Updates enums, schema, and tests, plus linting

chalmerlowe · chalmerlowe · commit 907b77c38153 · 2024-11-26T17:05:10.000Z
diff --git a/google/cloud/bigquery/enums.py b/google/cloud/bigquery/enums.py
@@ -248,9 +248,9 @@ class KeyResultStatementKind:
 class StandardSqlTypeNames(str, enum.Enum):
     """Enum of allowed SQL type names in schema.SchemaField.
 
-    Datatype used in GoogleSQL. 
+    Datatype used in GoogleSQL.
     """
-    
+
     def _generate_next_value_(name, start, count, last_values):
         return name
 
@@ -273,7 +273,7 @@ def _generate_next_value_(name, start, count, last_values):
     STRUCT = enum.auto()
     RANGE = enum.auto()
     FOREIGN = enum.auto()  # NOTE: FOREIGN acts as a wrapper for data types
-                           # not natively understood by BigQuery unless translated
+    # not natively understood by BigQuery unless translated
 
 
 class EntityTypes(str, enum.Enum):
@@ -317,7 +317,7 @@ class SqlTypeNames(str, enum.Enum):
     INTERVAL = "INTERVAL"  # NOTE: not available in legacy types
     RANGE = "RANGE"  # NOTE: not available in legacy types
     FOREIGN = "FOREIGN"  # NOTE: FOREIGN acts as a wrapper for data types
-                           # not natively understood by BigQuery unless translated
+    # not natively understood by BigQuery unless translated
 
 
 class WriteDisposition(object):
diff --git a/google/cloud/bigquery/schema.py b/google/cloud/bigquery/schema.py
@@ -171,7 +171,34 @@ class SchemaField(object):
             the type is RANGE, this field is required. Possible values for the
             field element type of a RANGE include `DATE`, `DATETIME` and
             `TIMESTAMP`.
-        TODO: add docstring here.
+
+        rounding_mode: Union[RoundingMode, str, None]
+            Specifies the rounding mode to be used when storing values of
+            NUMERIC and BIGNUMERIC type.
+
+            Unspecified will default to using ROUND_HALF_AWAY_FROM_ZERO.
+
+            ROUND_HALF_AWAY_FROM_ZERO rounds half values away from zero
+            when applying precision and scale upon writing of NUMERIC and BIGNUMERIC
+            values.
+            For Scale: 0
+            1.1, 1.2, 1.3, 1.4 => 1
+            1.5, 1.6, 1.7, 1.8, 1.9 => 2
+
+            ROUND_HALF_EVEN rounds half values to the nearest even value
+            when applying precision and scale upon writing of NUMERIC and BIGNUMERIC
+            values.
+            For Scale: 0
+            1.1, 1.2, 1.3, 1.4 => 1
+            1.5 => 2
+            1.6, 1.7, 1.8, 1.9 => 2
+            2.5 => 2
+
+        foreign_type_definition: Optional[str]
+            Definition of the foreign data type.
+
+            Only valid for top-level schema fields (not nested fields).
+            If the type is FOREIGN, this field is required.
     """
 
     def __init__(
@@ -191,7 +218,7 @@ def __init__(
         foreign_type_definition: Optional[str] = None,
     ):
         self._properties: Dict[str, Any] = {}
-        
+
         self._properties["name"] = name
         if mode is not None:
             self._properties["mode"] = mode.upper()
@@ -219,16 +246,18 @@ def __init__(
             self._properties["roundingMode"] = rounding_mode
         if isinstance(foreign_type_definition, str):
             self._properties["foreignTypeDefinition"] = foreign_type_definition
-        
-        # The order of operations is important: 
+
+        # The order of operations is important:
         # If field_type is FOREIGN, then foreign_type_definition must be set.
         if field_type != "FOREIGN":
             self._properties["type"] = field_type
         else:
             if self._properties.get("foreignTypeDefinition") is None:
-                raise ValueError("If the 'field_type' is 'FOREIGN', then 'foreign_type_definition' is required.")
+                raise ValueError(
+                    "If the 'field_type' is 'FOREIGN', then 'foreign_type_definition' is required."
+                )
             self._properties["type"] = field_type
-        
+
         self._fields = tuple(fields)
 
     @staticmethod
@@ -355,26 +384,8 @@ def range_element_type(self):
 
     @property
     def rounding_mode(self):
-        """Specifies the rounding mode to be used when storing values of
+        """Enum that specifies the rounding mode to be used when storing values of
         NUMERIC and BIGNUMERIC type.
-
-        Unspecified will default to using ROUND_HALF_AWAY_FROM_ZERO.
-
-        ROUND_HALF_AWAY_FROM_ZERO rounds half values away from zero
-        when applying precision and scale upon writing of NUMERIC and BIGNUMERIC
-        values.
-        For Scale: 0
-        1.1, 1.2, 1.3, 1.4 => 1
-        1.5, 1.6, 1.7, 1.8, 1.9 => 2
-
-        ROUND_HALF_EVEN rounds half values to the nearest even value
-        when applying precision and scale upon writing of NUMERIC and BIGNUMERIC
-        values.
-        For Scale: 0
-        1.1, 1.2, 1.3, 1.4 => 1
-        1.5 => 2
-        1.6, 1.7, 1.8, 1.9 => 2
-        2.5 => 2
         """
         return self._properties.get("roundingMode")
 
diff --git a/tests/unit/test_schema.py b/tests/unit/test_schema.py
@@ -326,8 +326,7 @@ def test_to_standard_sql_simple_type(self):
             ("GEOGRAPHY", bigquery.StandardSqlTypeNames.GEOGRAPHY),
         )
         for legacy_type, standard_type in examples:
-            
-            field = self._make_one("some_field", legacy_type)            
+            field = self._make_one("some_field", legacy_type)
             standard_field = field.to_standard_sql()
             self.assertEqual(standard_field.name, "some_field")
             self.assertEqual(standard_field.type.type_kind, standard_type)
@@ -487,15 +486,31 @@ def test_to_standard_sql_unknown_type(self):
             bigquery.StandardSqlTypeNames.TYPE_KIND_UNSPECIFIED,
         )
 
-    def test_to_standard_sql_foreign_type(self):
-        examples = (
-            ("FOREIGN", bigquery.StandardSqlTypeNames.FOREIGN, "INTEGER"),            
+    def test_to_standard_sql_foreign_type_valid(self):
+        legacy_type = "FOREIGN"
+        standard_type = bigquery.StandardSqlTypeNames.FOREIGN
+        foreign_type_definition = "INTEGER"
+
+        field = self._make_one(
+            "some_field",
+            field_type=legacy_type,
+            foreign_type_definition=foreign_type_definition,
         )
-        for legacy_type, standard_type, foreign_type_definition in examples:
-            field = self._make_one("some_field", legacy_type, foreign_type_definition=foreign_type_definition)            
-            standard_field = field.to_standard_sql()
-            self.assertEqual(standard_field.name, "some_field")
-            self.assertEqual(standard_field.type.type_kind, standard_type)
+        standard_field = field.to_standard_sql()
+        self.assertEqual(standard_field.name, "some_field")
+        self.assertEqual(standard_field.type.type_kind, standard_type)
+
+    def test_to_standard_sql_foreign_type_invalid(self):
+        legacy_type = "FOREIGN"
+        foreign_type_definition = None
+
+        with self.assertRaises(ValueError) as context:
+            self._make_one(
+                "some_field",
+                field_type=legacy_type,
+                foreign_type_definition=foreign_type_definition,
+            )
+        self.assertTrue("If the 'field_type'" in context.exception.args[0])
 
     def test___eq___wrong_type(self):
         field = self._make_one("test", "STRING")
diff --git a/tests/unit/test_table.py b/tests/unit/test_table.py
@@ -5928,6 +5928,7 @@ def test_external_catalog_table_options_setter(
         result = table.to_api_repr()
         assert result == expected
 
+
 @pytest.mark.parametrize("preserve_order", [True, False])
 def test_to_arrow_iterable_w_bqstorage_max_stream_count(preserve_order):
     pytest.importorskip("pandas")
