deprecate(bigquery): deprecate client.dataset() in favor of DatasetReference

Now that all client methods that take a `DatasetReference` or
`TableReference` also take a string, the `client.dataset()` method is
unnecessary and confusing.

Author: tswast

bigquery/google/cloud/bigquery/client.py

@@ -32,6 +32,7 @@
 import math
 import os
 import tempfile
+import textwrap
 import uuid
 import warnings
 
@@ -354,7 +355,18 @@ def list_datasets(
         )
 
     def dataset(self, dataset_id, project=None):
-        """Construct a reference to a dataset.
+        """Deprecated: Construct a reference to a dataset.
+
+        This method is deprecated. Construct a
+        :class:`~google.cloud.bigquery.dataset.DatasetReference` using its
+        constructor or use a string where previously a reference object was
+        used.
+
+        As ``google-cloud-bigquery`` version 1.7.0, all client methods that
+        take a :class:`~google.cloud.bigquery.dataset.DatasetReference` or
+        :class:`~google.cloud.bigquery.table.TableReference` also take a
+        string in standard SQL format, e.g. ``project.dataset_id`` or
+        ``project.dataset_id.table_id``.
 
         Args:
             dataset_id (str): ID of the dataset.
@@ -370,6 +382,15 @@ def dataset(self, dataset_id, project=None):
         if project is None:
             project = self.project
 
+        warnings.warn(
+            textwrap.fill(
+                "Client.dataset is deprecated and will be removed in a future version. "
+                "Use a string like 'my_project.my_dataset' or a "
+                "cloud.google.bigquery.DatasetReference object, instead."
+            ),
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         return DatasetReference(project, dataset_id)
 
     def _create_bqstorage_client(self):
@@ -419,7 +440,7 @@ def create_dataset(
 
             >>> from google.cloud import bigquery
             >>> client = bigquery.Client()
-            >>> dataset = bigquery.Dataset(client.dataset('my_dataset'))
+            >>> dataset = bigquery.Dataset('my_project.my_dataset')
             >>> dataset = client.create_dataset(dataset)
 
         """
@@ -2584,7 +2605,7 @@ def list_partitions(self, table, retry=DEFAULT_RETRY, timeout=None):
         ) as guard:
             meta_table = self.get_table(
                 TableReference(
-                    self.dataset(table.dataset_id, project=table.project),
+                    DatasetReference(table.project, table.dataset_id),
                     "%s$__PARTITIONS_SUMMARY__" % table.table_id,
                 ),
                 retry=retry,

bigquery/google/cloud/bigquery/magics.py

@@ -153,6 +153,7 @@
 from google.api_core.exceptions import NotFound
 import google.auth
 from google.cloud import bigquery
+import google.cloud.bigquery.dataset
 from google.cloud.bigquery.dbapi import _helpers
 import six
 
@@ -534,7 +535,7 @@ def _cell_magic(line, query):
                 )
             dataset_id, table_id = split
             job_config.allow_large_results = True
-            dataset_ref = client.dataset(dataset_id)
+            dataset_ref = bigquery.dataset.DatasetReference(client.project, dataset_id)
             destination_table_ref = dataset_ref.table(table_id)
             job_config.destination = destination_table_ref
             job_config.create_disposition = "CREATE_IF_NEEDED"