feat(bigquery): add description for routine entities (#9785)

* feat(bigquery): add description for routine entities

* feat(bigquery): use the Optional shorthand instead of a Union with None

bigquery/google/cloud/bigquery/dataset.py

@@ -509,7 +509,7 @@ def default_table_expiration_ms(self, value):
 
     @property
     def description(self):
-        """Union[str, None]: Description of the dataset as set by the user
+        """Optional[str]: Description of the dataset as set by the user
         (defaults to :data:`None`).
 
         Raises:

bigquery/google/cloud/bigquery/model.py

@@ -217,7 +217,7 @@ def expires(self, value):
 
     @property
     def description(self):
-        """Union[str, None]: Description of the model (defaults to
+        """Optional[str]: Description of the model (defaults to
         :data:`None`).
         """
         return self._properties.get("description")

bigquery/google/cloud/bigquery/routine.py

@@ -50,6 +50,7 @@ class Routine(object):
         "reference": "routineReference",
         "return_type": "returnType",
         "type_": "routineType",
+        "description": "description",
     }
 
     def __init__(self, routine_ref, **kwargs):
@@ -239,6 +240,17 @@ def body(self):
     def body(self, value):
         self._properties[self._PROPERTY_TO_API_FIELD["body"]] = value
 
+    @property
+    def description(self):
+        """Optional[str]: Description of the routine (defaults to
+        :data:`None`).
+        """
+        return self._properties.get(self._PROPERTY_TO_API_FIELD["description"])
+
+    @description.setter
+    def description(self, value):
+        self._properties[self._PROPERTY_TO_API_FIELD["description"]] = value
+
     @classmethod
     def from_api_repr(cls, resource):
         """Factory: construct a routine given its API representation.

bigquery/tests/unit/routine/test_routine.py

@@ -73,6 +73,7 @@ def test_ctor_w_properties(target_class):
         type_kind=bigquery_v2.enums.StandardSqlDataType.TypeKind.INT64
     )
     type_ = "SCALAR_FUNCTION"
+    description = "A routine description."
 
     actual_routine = target_class(
         routine_id,
@@ -81,6 +82,7 @@ def test_ctor_w_properties(target_class):
         language=language,
         return_type=return_type,
         type_=type_,
+        description=description,
     )
 
     ref = RoutineReference.from_string(routine_id)
@@ -90,6 +92,7 @@ def test_ctor_w_properties(target_class):
     assert actual_routine.language == language
     assert actual_routine.return_type == return_type
     assert actual_routine.type_ == type_
+    assert actual_routine.description == description
 
 
 def test_from_api_repr(target_class):
@@ -117,6 +120,7 @@ def test_from_api_repr(target_class):
         "returnType": {"typeKind": "INT64"},
         "routineType": "SCALAR_FUNCTION",
         "someNewField": "someValue",
+        "description": "A routine description.",
     }
     actual_routine = target_class.from_api_repr(resource)
 
@@ -148,6 +152,7 @@ def test_from_api_repr(target_class):
     )
     assert actual_routine.type_ == "SCALAR_FUNCTION"
     assert actual_routine._properties["someNewField"] == "someValue"
+    assert actual_routine.description == "A routine description."
 
 
 def test_from_api_repr_w_minimal_resource(target_class):
@@ -172,6 +177,7 @@ def test_from_api_repr_w_minimal_resource(target_class):
     assert actual_routine.language is None
     assert actual_routine.return_type is None
     assert actual_routine.type_ is None
+    assert actual_routine.description is None
 
 
 def test_from_api_repr_w_unknown_fields(target_class):
@@ -202,6 +208,7 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "language": "SQL",
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
+                "description": "A routine description.",
             },
             ["arguments"],
             {"arguments": [{"name": "x", "dataType": {"typeKind": "INT64"}}]},
@@ -213,6 +220,7 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "language": "SQL",
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
+                "description": "A routine description.",
             },
             ["body"],
             {"definitionBody": "x * 3"},
@@ -224,6 +232,7 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "language": "SQL",
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
+                "description": "A routine description.",
             },
             ["language"],
             {"language": "SQL"},
@@ -235,6 +244,7 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "language": "SQL",
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
+                "description": "A routine description.",
             },
             ["return_type"],
             {"returnType": {"typeKind": "INT64"}},
@@ -246,19 +256,33 @@ def test_from_api_repr_w_unknown_fields(target_class):
                 "language": "SQL",
                 "returnType": {"typeKind": "INT64"},
                 "routineType": "SCALAR_FUNCTION",
+                "description": "A routine description.",
             },
             ["type_"],
             {"routineType": "SCALAR_FUNCTION"},
         ),
+        (
+            {
+                "arguments": [{"name": "x", "dataType": {"typeKind": "INT64"}}],
+                "definitionBody": "x * 3",
+                "language": "SQL",
+                "returnType": {"typeKind": "INT64"},
+                "routineType": "SCALAR_FUNCTION",
+                "description": "A routine description.",
+            },
+            ["description"],
+            {"description": "A routine description."},
+        ),
         (
             {},
-            ["arguments", "language", "body", "type_", "return_type"],
+            ["arguments", "language", "body", "type_", "return_type", "description"],
             {
                 "arguments": None,
                 "definitionBody": None,
                 "language": None,
                 "returnType": None,
                 "routineType": None,
+                "description": None,
             },
         ),
         (
@@ -299,6 +323,12 @@ def test_set_return_type_w_none(object_under_test):
     assert object_under_test._properties["returnType"] is None
 
 
+def test_set_description_w_none(object_under_test):
+    object_under_test.description = None
+    assert object_under_test.description is None
+    assert object_under_test._properties["description"] is None
+
+
 def test_repr(target_class):
     model = target_class("my-proj.my_dset.my_routine")
     actual_routine = repr(model)