bigquery: support table labels (#4207)

bigquery/google/cloud/bigquery/table.py

@@ -163,15 +163,15 @@ class Table(object):
     all_fields = [
         'description', 'friendly_name', 'expires', 'location',
         'partitioning_type', 'view_use_legacy_sql', 'view_query', 'schema',
-        'external_data_configuration',
+        'external_data_configuration', 'labels',
     ]
 
     def __init__(self, table_ref, schema=()):
         self._project = table_ref.project
         self._table_id = table_ref.table_id
         self._dataset_id = table_ref.dataset_id
         self._external_config = None
-        self._properties = {}
+        self._properties = {'labels': {}}
         # Let the @property do validation.
         self.schema = schema
 
@@ -238,6 +238,32 @@ def schema(self, value):
         else:
             self._schema = tuple(value)
 
+    @property
+    def labels(self):
+        """Labels for the table.
+
+        This method always returns a dict. To change a table's labels,
+        modify the dict, then call ``Client.update_table``. To delete a
+        label, set its value to ``None`` before updating.
+
+        :rtype: dict, {str -> str}
+        :returns: A dict of the the table's labels.
+        """
+        return self._properties['labels']
+
+    @labels.setter
+    def labels(self, value):
+        """Update labels for the table.
+
+        :type value: dict, {str -> str}
+        :param value: new labels
+
+        :raises: ValueError for invalid value types.
+        """
+        if not isinstance(value, dict):
+            raise ValueError("Pass a dict")
+        self._properties['labels'] = value
+
     @property
     def created(self):
         """Datetime at which the table was created.
@@ -620,6 +646,8 @@ def _set_properties(self, api_response):
             cleaned['lastModifiedTime'] = float(cleaned['lastModifiedTime'])
         if 'expirationTime' in cleaned:
             cleaned['expirationTime'] = float(cleaned['expirationTime'])
+        if 'labels' not in cleaned:
+            cleaned['labels'] = {}
         self._properties.update(cleaned)
 
     def _populate_expires_resource(self, resource):

bigquery/tests/system.py

@@ -265,18 +265,27 @@ def test_update_table(self):
         self.assertTrue(_table_exists(table))
         self.assertIsNone(table.friendly_name)
         self.assertIsNone(table.description)
+        self.assertEquals(table.labels, {})
         table.friendly_name = 'Friendly'
         table.description = 'Description'
+        table.labels = {'priority': 'high', 'color': 'blue'}
 
         table2 = Config.CLIENT.update_table(
-            table, ['friendly_name', 'description'])
+            table, ['friendly_name', 'description', 'labels'])
 
         self.assertEqual(table2.friendly_name, 'Friendly')
         self.assertEqual(table2.description, 'Description')
+        self.assertEqual(table2.labels, {'priority': 'high', 'color': 'blue'})
 
         table2.description = None
-        table3 = Config.CLIENT.update_table(table2, ['description'])
+        table2.labels = {
+            'color': 'green',   # change
+            'shape': 'circle',  # add
+            'priority': None,   # delete
+        }
+        table3 = Config.CLIENT.update_table(table2, ['description', 'labels'])
         self.assertIsNone(table3.description)
+        self.assertEqual(table3.labels, {'color': 'green', 'shape': 'circle'})
 
         # If we try to update using table2 again, it will fail because the
         # previous update changed the ETag.

bigquery/tests/unit/test_client.py

@@ -464,6 +464,7 @@ def test_create_table_w_day_partition(self):
                 'tableId': self.TABLE_ID
             },
             'timePartitioning': {'type': 'DAY'},
+            'labels': {},
         }
         self.assertEqual(req['data'], sent)
         self.assertEqual(table.partitioning_type, "DAY")
@@ -502,6 +503,7 @@ def test_create_table_w_day_partition_and_expire(self):
                 'tableId': self.TABLE_ID
             },
             'timePartitioning': {'type': 'DAY', 'expirationMs': 100},
+            'labels': {},
         }
         self.assertEqual(req['data'], sent)
         self.assertEqual(table.partitioning_type, "DAY")
@@ -554,6 +556,7 @@ def test_create_table_w_schema_and_query(self):
                 {'name': 'age', 'type': 'INTEGER', 'mode': 'REQUIRED'}]
             },
             'view': {'query': query, 'useLegacySql': False},
+            'labels': {},
         }
         self.assertEqual(req['data'], sent)
         self.assertEqual(got.table_id, self.TABLE_ID)
@@ -603,7 +606,8 @@ def test_create_table_w_external(self):
             'externalDataConfiguration': {
                 'sourceFormat': 'CSV',
                 'autodetect': True,
-            }
+            },
+            'labels': {},
         }
         self.assertEqual(req['data'], sent)
         self.assertEqual(got.table_id, self.TABLE_ID)
@@ -727,6 +731,7 @@ def test_update_table(self):
             'etag': 'etag',
             'description': description,
             'friendlyName': title,
+            'labels': {'x': 'y'},
         }
         schema = [
             SchemaField('full_name', 'STRING', mode='REQUIRED'),
@@ -738,9 +743,10 @@ def test_update_table(self):
         table = Table(self.TABLE_REF, schema=schema)
         table.description = description
         table.friendly_name = title
+        table.labels = {'x': 'y'}
 
         updated_table = client.update_table(
-            table, ['schema', 'description', 'friendly_name'])
+            table, ['schema', 'description', 'friendly_name', 'labels'])
 
         sent = {
             'tableReference': {
@@ -753,6 +759,7 @@ def test_update_table(self):
                 {'name': 'age', 'type': 'INTEGER', 'mode': 'REQUIRED'}]},
             'description': description,
             'friendlyName': title,
+            'labels': {'x': 'y'},
         }
         self.assertEqual(len(conn._requested), 1)
         req = conn._requested[0]
@@ -763,6 +770,7 @@ def test_update_table(self):
         self.assertEqual(updated_table.description, table.description)
         self.assertEqual(updated_table.friendly_name, table.friendly_name)
         self.assertEqual(updated_table.schema, table.schema)
+        self.assertEqual(updated_table.labels, table.labels)
 
         # ETag becomes If-Match header.
         table._properties['etag'] = 'etag'

bigquery/tests/unit/test_table.py

@@ -205,6 +205,7 @@ def _makeResource(self):
                 'csvOptions': {
                     'allowJaggedRows': True,
                     'encoding': 'encoding'}},
+            'labels': {'x': 'y'},
         }
 
     def _verifyReadonlyResourceProperties(self, table, resource):
@@ -279,6 +280,11 @@ def _verifyResourceProperties(self, table, resource):
             self.assertEqual(edc.source_format, 'CSV')
             self.assertEqual(edc.options.allow_jagged_rows, True)
 
+        if 'labels' in resource:
+            self.assertEqual(table.labels, {'x': 'y'})
+        else:
+            self.assertEqual(table.labels, {})
+
     def test_ctor(self):
         dataset = DatasetReference(self.PROJECT, self.DS_ID)
         table_ref = dataset.table(self.TABLE_NAME)
@@ -301,13 +307,14 @@ def test_ctor(self):
         self.assertIsNone(table.self_link)
         self.assertIsNone(table.full_table_id)
         self.assertIsNone(table.table_type)
-
         self.assertIsNone(table.description)
         self.assertIsNone(table.expires)
         self.assertIsNone(table.friendly_name)
         self.assertIsNone(table.location)
         self.assertIsNone(table.view_query)
         self.assertIsNone(table.view_use_legacy_sql)
+        self.assertIsNone(table.external_data_configuration)
+        self.assertEquals(table.labels, {})
 
     def test_ctor_w_schema(self):
         from google.cloud.bigquery.table import SchemaField
@@ -534,6 +541,13 @@ def test_external_data_configuration_setter_bad_value(self):
         with self.assertRaises(ValueError):
             table.external_data_configuration = 12345
 
+    def test_labels_setter_bad_value(self):
+        dataset = DatasetReference(self.PROJECT, self.DS_ID)
+        table_ref = dataset.table(self.TABLE_NAME)
+        table = self._make_one(table_ref)
+        with self.assertRaises(ValueError):
+            table.labels = 12345
+
     def test_from_api_repr_missing_identity(self):
         self._setUpConstants()
         RESOURCE = {}