deprecate(bigquery): deprecate client.dataset() in favor of `Datase…

…tReference` (#7753)

* 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.

* fix: remove unnecessary textwrap

* Update bigquery/google/cloud/bigquery/client.py

Co-Authored-By: Peter Lamut <plamut@users.noreply.github.com>

* docs: use sphinx deprecation directive

Co-authored-by: Peter Lamut <plamut@users.noreply.github.com>

bigquery/google/cloud/bigquery/client.py

@@ -354,7 +354,20 @@ def list_datasets(
         )
 
     def dataset(self, dataset_id, project=None):
-        """Construct a reference to a dataset.
+        """Deprecated: Construct a reference to a dataset.
+
+        .. deprecated:: 1.24.0
+           Construct a
+           :class:`~google.cloud.bigquery.dataset.DatasetReference` using its
+           constructor or use a string where previously a reference object
+           was used.
+
+           As of ``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 +383,13 @@ def dataset(self, dataset_id, project=None):
         if project is None:
             project = self.project
 
+        warnings.warn(
+            "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 +439,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 +2604,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"