feat: support ScalarQueryParameterType for type_ argument in `Sca…

…larQueryParameter` constructor (#850)

Follow-up to https://github.com/googleapis/python-bigquery/pull/840/files#r679880582

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:
- [ ] Make sure to open an issue as a [bug/issue](https://github.com/googleapis/python-bigquery/issues/new/choose) before writing your code!  That way we can discuss the change, evaluate designs, and agree on the general idea
- [ ] Ensure the tests and linter pass
- [ ] Code coverage does not decrease (if any source code was changed)
- [ ] Appropriate docs were updated (if necessary)

docs/conf.py

@@ -110,6 +110,7 @@
 # directories to ignore when looking for source files.
 exclude_patterns = [
     "_build",
+    "**/.nox/**/*",
     "samples/AUTHORING_GUIDE.md",
     "samples/CONTRIBUTING.md",
     "samples/snippets/README.rst",

docs/reference.rst

@@ -138,6 +138,7 @@ Query
 
     query.ArrayQueryParameter
     query.ScalarQueryParameter
+    query.ScalarQueryParameterType
     query.StructQueryParameter
     query.UDFResource
 

google/cloud/bigquery/enums.py

@@ -259,23 +259,23 @@ class SqlTypeNames(str, enum.Enum):
 class SqlParameterScalarTypes:
     """Supported scalar SQL query parameter types as type objects."""
 
-    STRING = ScalarQueryParameterType("STRING")
+    BOOL = ScalarQueryParameterType("BOOL")
+    BOOLEAN = ScalarQueryParameterType("BOOL")
+    BIGDECIMAL = ScalarQueryParameterType("BIGNUMERIC")
+    BIGNUMERIC = ScalarQueryParameterType("BIGNUMERIC")
     BYTES = ScalarQueryParameterType("BYTES")
-    INTEGER = ScalarQueryParameterType("INT64")
-    INT64 = ScalarQueryParameterType("INT64")
+    DATE = ScalarQueryParameterType("DATE")
+    DATETIME = ScalarQueryParameterType("DATETIME")
+    DECIMAL = ScalarQueryParameterType("NUMERIC")
     FLOAT = ScalarQueryParameterType("FLOAT64")
     FLOAT64 = ScalarQueryParameterType("FLOAT64")
-    NUMERIC = ScalarQueryParameterType("NUMERIC")
-    BIGNUMERIC = ScalarQueryParameterType("BIGNUMERIC")
-    DECIMAL = ScalarQueryParameterType("NUMERIC")
-    BIGDECIMAL = ScalarQueryParameterType("BIGNUMERIC")
-    BOOLEAN = ScalarQueryParameterType("BOOL")
-    BOOL = ScalarQueryParameterType("BOOL")
     GEOGRAPHY = ScalarQueryParameterType("GEOGRAPHY")
-    TIMESTAMP = ScalarQueryParameterType("TIMESTAMP")
-    DATE = ScalarQueryParameterType("DATE")
+    INT64 = ScalarQueryParameterType("INT64")
+    INTEGER = ScalarQueryParameterType("INT64")
+    NUMERIC = ScalarQueryParameterType("NUMERIC")
+    STRING = ScalarQueryParameterType("STRING")
     TIME = ScalarQueryParameterType("TIME")
-    DATETIME = ScalarQueryParameterType("DATETIME")
+    TIMESTAMP = ScalarQueryParameterType("TIMESTAMP")
 
 
 class WriteDisposition(object):

google/cloud/bigquery/query.py

@@ -16,14 +16,21 @@
 
 from collections import OrderedDict
 import copy
-from typing import Union
+import datetime
+import decimal
+from typing import Optional, Union
 
 from google.cloud.bigquery.table import _parse_schema_resource
 from google.cloud.bigquery._helpers import _rows_from_json
 from google.cloud.bigquery._helpers import _QUERY_PARAMS_FROM_JSON
 from google.cloud.bigquery._helpers import _SCALAR_VALUE_TO_JSON_PARAM
 
 
+_SCALAR_VALUE_TYPE = Optional[
+    Union[str, int, float, decimal.Decimal, bool, datetime.datetime, datetime.date]
+]
+
+
 class UDFResource(object):
     """Describe a single user-defined function (UDF) resource.
 
@@ -325,35 +332,46 @@ class ScalarQueryParameter(_AbstractQueryParameter):
     """Named / positional query parameters for scalar values.
 
     Args:
-        name (Optional[str]):
+        name:
             Parameter name, used via ``@foo`` syntax.  If None, the
             parameter can only be addressed via position (``?``).
 
-        type_ (str):
-            Name of parameter type.  One of 'STRING', 'INT64',
-            'FLOAT64', 'NUMERIC', 'BIGNUMERIC', 'BOOL', 'TIMESTAMP', 'DATETIME', or
-            'DATE'.
+        type_:
+            Name of parameter type. See
+            :class:`google.cloud.bigquery.enums.SqlTypeNames` and
+            :class:`google.cloud.bigquery.enums.SqlParameterScalarTypes` for
+            supported types.
 
-        value (Union[str, int, float, decimal.Decimal, bool, datetime.datetime, datetime.date]):
+        value:
             The scalar parameter value.
     """
 
-    def __init__(self, name, type_, value):
+    def __init__(
+        self,
+        name: Optional[str],
+        type_: Optional[Union[str, ScalarQueryParameterType]],
+        value: _SCALAR_VALUE_TYPE,
+    ):
         self.name = name
-        self.type_ = type_
+        if isinstance(type_, ScalarQueryParameterType):
+            self.type_ = type_._type
+        else:
+            self.type_ = type_
         self.value = value
 
     @classmethod
-    def positional(cls, type_: str, value) -> "ScalarQueryParameter":
+    def positional(
+        cls, type_: Union[str, ScalarQueryParameterType], value: _SCALAR_VALUE_TYPE
+    ) -> "ScalarQueryParameter":
         """Factory for positional paramater.
 
         Args:
-            type_ (str):
+            type_:
                 Name of parameter type.  One of 'STRING', 'INT64',
                 'FLOAT64', 'NUMERIC', 'BIGNUMERIC', 'BOOL', 'TIMESTAMP', 'DATETIME', or
                 'DATE'.
 
-            value (Union[str, int, float, decimal.Decimal, bool, datetime.datetime, datetime.date]):
+            value:
                 The scalar parameter value.
 
         Returns:

tests/unit/test_query.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 import datetime
+import decimal
 import unittest
 
 import mock
@@ -430,6 +431,18 @@ def test_positional(self):
         self.assertEqual(param.type_, "INT64")
         self.assertEqual(param.value, 123)
 
+    def test_ctor_w_scalar_query_parameter_type(self):
+        from google.cloud.bigquery import enums
+
+        param = self._make_one(
+            name="foo",
+            type_=enums.SqlParameterScalarTypes.BIGNUMERIC,
+            value=decimal.Decimal("123.456"),
+        )
+        self.assertEqual(param.name, "foo")
+        self.assertEqual(param.type_, "BIGNUMERIC")
+        self.assertEqual(param.value, decimal.Decimal("123.456"))
+
     def test_from_api_repr_w_name(self):
         RESOURCE = {
             "name": "foo",