BigQuery: deprecate client.dataset() part 1 (#9032)

Deprecate `client.dataset()` part 1

Author: emar-kar

bigquery/docs/snippets.py

@@ -125,133 +125,6 @@ def test_create_client_default_credentials():
     assert client is not None
 
 
-def test_list_datasets_by_label(client, to_delete):
-    dataset_id = "list_datasets_by_label_{}".format(_millis())
-    dataset = bigquery.Dataset(client.dataset(dataset_id))
-    dataset.labels = {"color": "green"}
-    dataset = client.create_dataset(dataset)  # API request
-    to_delete.append(dataset)
-
-    # [START bigquery_list_datasets_by_label]
-    # from google.cloud import bigquery
-    # client = bigquery.Client()
-
-    # The following label filter example will find datasets with an
-    # arbitrary 'color' label set to 'green'
-    label_filter = "labels.color:green"
-    datasets = list(client.list_datasets(filter=label_filter))
-
-    if datasets:
-        print("Datasets filtered by {}:".format(label_filter))
-        for dataset in datasets:  # API request(s)
-            print("\t{}".format(dataset.dataset_id))
-    else:
-        print("No datasets found with this filter.")
-    # [END bigquery_list_datasets_by_label]
-    found = set([dataset.dataset_id for dataset in datasets])
-    assert dataset_id in found
-
-
-# [START bigquery_dataset_exists]
-def dataset_exists(client, dataset_reference):
-    """Return if a dataset exists.
-
-    Args:
-        client (google.cloud.bigquery.client.Client):
-            A client to connect to the BigQuery API.
-        dataset_reference (google.cloud.bigquery.dataset.DatasetReference):
-            A reference to the dataset to look for.
-
-    Returns:
-        bool: ``True`` if the dataset exists, ``False`` otherwise.
-    """
-    from google.cloud.exceptions import NotFound
-
-    try:
-        client.get_dataset(dataset_reference)
-        return True
-    except NotFound:
-        return False
-
-
-# [END bigquery_dataset_exists]
-
-
-def test_dataset_exists(client, to_delete):
-    """Determine if a dataset exists."""
-    DATASET_ID = "get_table_dataset_{}".format(_millis())
-    dataset_ref = client.dataset(DATASET_ID)
-    dataset = bigquery.Dataset(dataset_ref)
-    dataset = client.create_dataset(dataset)
-    to_delete.append(dataset)
-
-    assert dataset_exists(client, dataset_ref)
-    assert not dataset_exists(client, client.dataset("i_dont_exist"))
-
-
-@pytest.mark.skip(
-    reason=(
-        "update_dataset() is flaky "
-        "https://github.com/GoogleCloudPlatform/google-cloud-python/issues/5588"
-    )
-)
-def test_manage_dataset_labels(client, to_delete):
-    dataset_id = "label_dataset_{}".format(_millis())
-    dataset = bigquery.Dataset(client.dataset(dataset_id))
-    dataset = client.create_dataset(dataset)
-    to_delete.append(dataset)
-
-    # [START bigquery_label_dataset]
-    # from google.cloud import bigquery
-    # client = bigquery.Client()
-    # dataset_ref = client.dataset('my_dataset')
-    # dataset = client.get_dataset(dataset_ref)  # API request
-
-    assert dataset.labels == {}
-    labels = {"color": "green"}
-    dataset.labels = labels
-
-    dataset = client.update_dataset(dataset, ["labels"])  # API request
-
-    assert dataset.labels == labels
-    # [END bigquery_label_dataset]
-
-    # [START bigquery_get_dataset_labels]
-    # from google.cloud import bigquery
-    # client = bigquery.Client()
-    # dataset_id = 'my_dataset'
-
-    dataset_ref = client.dataset(dataset_id)
-    dataset = client.get_dataset(dataset_ref)  # API request
-
-    # View dataset labels
-    print("Dataset ID: {}".format(dataset_id))
-    print("Labels:")
-    if dataset.labels:
-        for label, value in dataset.labels.items():
-            print("\t{}: {}".format(label, value))
-    else:
-        print("\tDataset has no labels defined.")
-    # [END bigquery_get_dataset_labels]
-    assert dataset.labels == labels
-
-    # [START bigquery_delete_label_dataset]
-    # from google.cloud import bigquery
-    # client = bigquery.Client()
-    # dataset_ref = client.dataset('my_dataset')
-    # dataset = client.get_dataset(dataset_ref)  # API request
-
-    # This example dataset starts with one label
-    assert dataset.labels == {"color": "green"}
-    # To delete a label from a dataset, set its value to None
-    dataset.labels["color"] = None
-
-    dataset = client.update_dataset(dataset, ["labels"])  # API request
-
-    assert dataset.labels == {}
-    # [END bigquery_delete_label_dataset]
-
-
 def test_create_table_nested_repeated_schema(client, to_delete):
     dataset_id = "create_table_nested_repeated_{}".format(_millis())
     dataset_ref = client.dataset(dataset_id)
@@ -612,43 +485,6 @@ def test_update_table_expiration(client, to_delete):
     # [END bigquery_update_table_expiration]
 
 
-@pytest.mark.skip(
-    reason=(
-        "update_table() is flaky "
-        "https://github.com/GoogleCloudPlatform/google-cloud-python/issues/5589"
-    )
-)
-def test_add_empty_column(client, to_delete):
-    """Adds an empty column to an existing table."""
-    dataset_id = "add_empty_column_dataset_{}".format(_millis())
-    table_id = "add_empty_column_table_{}".format(_millis())
-    dataset = bigquery.Dataset(client.dataset(dataset_id))
-    dataset = client.create_dataset(dataset)
-    to_delete.append(dataset)
-
-    table = bigquery.Table(dataset.table(table_id), schema=SCHEMA)
-    table = client.create_table(table)
-
-    # [START bigquery_add_empty_column]
-    # from google.cloud import bigquery
-    # client = bigquery.Client()
-    # dataset_id = 'my_dataset'
-    # table_id = 'my_table'
-
-    table_ref = client.dataset(dataset_id).table(table_id)
-    table = client.get_table(table_ref)  # API request
-
-    original_schema = table.schema
-    new_schema = original_schema[:]  # creates a copy of the schema
-    new_schema.append(bigquery.SchemaField("phone", "STRING"))
-
-    table.schema = new_schema
-    table = client.update_table(table, ["schema"])  # API request
-
-    assert len(table.schema) == len(original_schema) + 1 == len(new_schema)
-    # [END bigquery_add_empty_column]
-
-
 @pytest.mark.skip(
     reason=(
         "update_table() is flaky "
@@ -737,47 +573,6 @@ def test_update_table_cmek(client, to_delete):
     # [END bigquery_update_table_cmek]
 
 
-def test_browse_table_data(client, to_delete, capsys):
-    """Retreive selected row data from a table."""
-
-    # [START bigquery_browse_table]
-    # from google.cloud import bigquery
-    # client = bigquery.Client()
-
-    dataset_ref = client.dataset("samples", project="bigquery-public-data")
-    table_ref = dataset_ref.table("shakespeare")
-    table = client.get_table(table_ref)  # API call
-
-    # Load all rows from a table
-    rows = client.list_rows(table)
-    assert len(list(rows)) == table.num_rows
-
-    # Load the first 10 rows
-    rows = client.list_rows(table, max_results=10)
-    assert len(list(rows)) == 10
-
-    # Specify selected fields to limit the results to certain columns
-    fields = table.schema[:2]  # first two columns
-    rows = client.list_rows(table, selected_fields=fields, max_results=10)
-    assert len(rows.schema) == 2
-    assert len(list(rows)) == 10
-
-    # Use the start index to load an arbitrary portion of the table
-    rows = client.list_rows(table, start_index=10, max_results=10)
-
-    # Print row data in tabular format
-    format_string = "{!s:<16} " * len(rows.schema)
-    field_names = [field.name for field in rows.schema]
-    print(format_string.format(*field_names))  # prints column headers
-    for row in rows:
-        print(format_string.format(*row))  # prints row data
-    # [END bigquery_browse_table]
-
-    out, err = capsys.readouterr()
-    out = list(filter(bool, out.split("\n")))  # list of non-blank lines
-    assert len(out) == 11
-
-
 @pytest.mark.skip(
     reason=(
         "update_table() is flaky "

bigquery/docs/usage/datasets.rst

@@ -25,6 +25,15 @@ List datasets for a project with the
    :start-after: [START bigquery_list_datasets]
    :end-before: [END bigquery_list_datasets]
 
+List datasets by label for a project with the
+:func:`~google.cloud.bigquery.client.Client.list_datasets` method:
+
+.. literalinclude:: ../samples/list_datasets_by_label.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_list_datasets_by_label]
+   :end-before: [END bigquery_list_datasets_by_label]
+
 Getting a Dataset
 ^^^^^^^^^^^^^^^^^
 
@@ -37,6 +46,15 @@ Get a dataset resource (to pick up changes made by another client) with the
    :start-after: [START bigquery_get_dataset]
    :end-before: [END bigquery_get_dataset]
 
+Determine if a dataset exists with the
+:func:`~google.cloud.bigquery.client.Client.get_dataset` method:
+
+.. literalinclude:: ../samples/dataset_exists.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_dataset_exists]
+   :end-before: [END bigquery_dataset_exists]
+
 Creating a Dataset
 ^^^^^^^^^^^^^^^^^^
 
@@ -70,6 +88,36 @@ Modify user permissions on a dataset with the
    :start-after: [START bigquery_update_dataset_access]
    :end-before: [END bigquery_update_dataset_access]
 
+Manage Dataset labels
+^^^^^^^^^^^^^^^^^^^^^
+
+Add labels to a dataset with the
+:func:`~google.cloud.bigquery.client.Client.update_dataset` method:
+
+.. literalinclude:: ../samples/label_dataset.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_label_dataset]
+   :end-before: [END bigquery_label_dataset]
+
+Get dataset's labels with the
+:func:`~google.cloud.bigquery.client.Client.get_dataset` method:
+
+.. literalinclude:: ../samples/get_dataset_labels.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_get_dataset_labels]
+   :end-before: [END bigquery_get_dataset_labels]
+   
+Delete dataset's labels with the
+:func:`~google.cloud.bigquery.client.Client.update_dataset` method:
+
+.. literalinclude:: ../samples/delete_dataset_labels.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_delete_label_dataset]
+   :end-before: [END bigquery_delete_label_dataset]
+
 Deleting a Dataset
 ^^^^^^^^^^^^^^^^^^
 

bigquery/docs/usage/tables.rst

@@ -31,7 +31,7 @@ Get a table resource with the
 Browse data rows in a table with the
 :func:`~google.cloud.bigquery.client.Client.list_rows` method:
 
-.. literalinclude:: ../snippets.py
+.. literalinclude:: ../samples/browse_table_data.py
    :language: python
    :dedent: 4
    :start-after: [START bigquery_browse_table]
@@ -113,6 +113,15 @@ Insert rows into a table's data with the
    :start-after: [START bigquery_table_insert_rows]
    :end-before: [END bigquery_table_insert_rows]
 
+Add an empty column to the existing table with the
+:func:`~google.cloud.bigquery.update_table` method:
+
+.. literalinclude:: ../samples/add_empty_column.py
+   :language: python
+   :dedent: 4
+   :start-after: [START bigquery_add_empty_column]
+   :end-before: [END bigquery_add_empty_column]
+
 Copying a Table
 ^^^^^^^^^^^^^^^
 

bigquery/samples/add_empty_column.py

@@ -0,0 +1,40 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def add_empty_column(client, table_id):
+
+    # [START bigquery_add_empty_column]
+    from google.cloud import bigquery
+
+    # TODO(developer): Construct a BigQuery client object.
+    # client = bigquery.Client()
+
+    # TODO(developer): Set table_id to the ID of the table to add an empty column.
+    # table_id = "your-project.your_dataset.your_table_name"
+
+    table = client.get_table(table_id)
+
+    original_schema = table.schema
+    new_schema = original_schema[:]  # creates a copy of the schema
+    new_schema.append(bigquery.SchemaField("phone", "STRING"))
+
+    table.schema = new_schema
+    table = client.update_table(table, ["schema"])  # API request
+
+    if len(table.schema) == len(original_schema) + 1 == len(new_schema):
+        print("A new column has been added.")
+    else:
+        print("The column has not been added.")
+    # [END bigquery_add_empty_column]