BigQuery: deprecate list_dataset_tables in favor of list_tables (#4653)

* BigQuery: deprecate list_dataset_tables in favor of list_tables

* Update changelog for this change and already-merged changes.

* Make 0.29 changelog headers consistent with previous versions.

Author: tswast

bigquery/CHANGELOG.md

@@ -4,6 +4,39 @@
 
 [1]: https://pypi.org/project/google-cloud-bigquery/#history
 
+## 0.29.0 (unreleased)
+
+## Interface changes / additions
+
+-   Add `to_dataframe()` method to row iterators. When Pandas is installed this
+    method returns a `DataFrame` containing the query's or table's rows.
+    ([#4354](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4354))
+-   Iterate over a `QueryJob` to wait for and get the query results.
+    ([#4350](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4350))
+-   Add `Table.reference` and `Dataset.reference` properties to get the
+    `TableReference` or `DatasetReference` corresponding to that `Table` or
+    `Dataset`, respectively.
+    ([#4405](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4405))
+-   Add `Row.keys()`, `Row.items()`, and `Row.get()`. This makes `Row` act
+    more like a built-in dictionary.
+    ([#4393](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4393),
+    [#4413](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4413))
+
+## Interface changes / breaking changes
+
+-   Add `Client.list_tables`, deprecate `Client.list_dataset_tables`.
+    ([#4653](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4653))
+-   `Client.list_tables` returns an iterators of `TableListItem`. The API
+    only returns a subset of properties of a table when listing.
+    ([#4427](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4427))
+-   Remove `QueryJob.query_results()`. Use `QueryJob.result()` instead.
+    ([#4652](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4652))
+-   Remove `Client.query_rows()`. Use `Client.query()` instead.
+    ([#4429](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4429))
+-   `Client.list_datasets` returns an iterator of `DatasetListItem`. The API
+    only returns a subset of properties of a dataset when listing.
+    ([#4439](https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4439))
+
 ## 0.28.0
 
 **0.28.0 significantly changes the interface for this package.** For examples

bigquery/google/cloud/bigquery/client.py

@@ -20,6 +20,7 @@
 import functools
 import os
 import uuid
+import warnings
 
 import six
 
@@ -389,8 +390,8 @@ def update_table(self, table, fields, retry=DEFAULT_RETRY):
             method='PATCH', path=table.path, data=partial, headers=headers)
         return Table.from_api_repr(api_response)
 
-    def list_dataset_tables(self, dataset, max_results=None, page_token=None,
-                            retry=DEFAULT_RETRY):
+    def list_tables(self, dataset, max_results=None, page_token=None,
+                    retry=DEFAULT_RETRY):
         """List tables in the dataset.
 
         See
@@ -432,6 +433,16 @@ def list_dataset_tables(self, dataset, max_results=None, page_token=None,
         result.dataset = dataset
         return result
 
+    def list_dataset_tables(self, *args, **kwargs):
+        """DEPRECATED: List tables in the dataset.
+
+        Use :func:`~google.cloud.bigquery.client.Client.list_tables` instead.
+        """
+        warnings.warn(
+            'list_dataset_tables is deprecated, use list_tables instead.',
+            DeprecationWarning)
+        return self.list_tables(*args, **kwargs)
+
     def delete_dataset(self, dataset, retry=DEFAULT_RETRY):
         """Delete a dataset.
 

bigquery/tests/system.py

@@ -230,11 +230,11 @@ def test_get_table_w_public_dataset(self):
         self.assertEqual(
             schema_names, ['word', 'word_count', 'corpus', 'corpus_date'])
 
-    def test_list_dataset_tables(self):
+    def test_list_tables(self):
         DATASET_ID = _make_dataset_id('list_tables')
         dataset = self.temp_dataset(DATASET_ID)
         # Retrieve tables before any are created for the dataset.
-        iterator = Config.CLIENT.list_dataset_tables(dataset)
+        iterator = Config.CLIENT.list_tables(dataset)
         all_tables = list(iterator)
         self.assertEqual(all_tables, [])
         self.assertIsNone(iterator.next_page_token)
@@ -251,7 +251,7 @@ def test_list_dataset_tables(self):
             self.to_delete.insert(0, created_table)
 
         # Retrieve the tables.
-        iterator = Config.CLIENT.list_dataset_tables(dataset)
+        iterator = Config.CLIENT.list_tables(dataset)
         all_tables = list(iterator)
         self.assertIsNone(iterator.next_page_token)
         created = [table for table in all_tables

docs/bigquery/snippets.py

@@ -247,26 +247,26 @@ def test_delete_dataset(client):
     # [END delete_dataset]
 
 
-def test_list_dataset_tables(client, to_delete):
+def test_list_tables(client, to_delete):
     """List tables within a dataset."""
-    DATASET_ID = 'list_dataset_tables_dataset_{}'.format(_millis())
+    DATASET_ID = 'list_tables_dataset_{}'.format(_millis())
     dataset = bigquery.Dataset(client.dataset(DATASET_ID))
     dataset = client.create_dataset(dataset)
     to_delete.append(dataset)
 
-    # [START list_dataset_tables]
-    tables = list(client.list_dataset_tables(dataset))  # API request(s)
+    # [START list_tables]
+    tables = list(client.list_tables(dataset))  # API request(s)
     assert len(tables) == 0
 
     table_ref = dataset.table('my_table')
     table = bigquery.Table(table_ref)
     table.view_query = QUERY
     client.create_table(table)                          # API request
-    tables = list(client.list_dataset_tables(dataset))  # API request(s)
+    tables = list(client.list_tables(dataset))  # API request(s)
 
     assert len(tables) == 1
     assert tables[0].table_id == 'my_table'
-    # [END list_dataset_tables]
+    # [END list_tables]
 
     to_delete.insert(0, table)
 

docs/bigquery/usage.rst

@@ -134,8 +134,8 @@ Table operations
 List tables for the dataset:
 
 .. literalinclude:: snippets.py
-   :start-after: [START list_dataset_tables]
-   :end-before: [END list_dataset_tables]
+   :start-after: [START list_tables]
+   :end-before: [END list_tables]
 
 Create a table: