deprecate(bigquery): deprecate client.dataset() in favor of DatasetReference (#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>

Author: tswast

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"