docs(bigquery): standardize comments and formatting in existing code samples (#9212)

* update samples

* comments rephrasing

* docs: comments rephrasing

Author: emar-kar

bigquery/samples/add_empty_column.py

@@ -21,17 +21,18 @@ def add_empty_column(client, table_id):
     # 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.
+    # 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)
+    table = client.get_table(table_id)  # Make an 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
+    table = client.update_table(table, ["schema"])  # Make an API request.
 
     if len(table.schema) == len(original_schema) + 1 == len(new_schema):
         print("A new column has been added.")

bigquery/samples/browse_table_data.py

@@ -26,7 +26,7 @@ def browse_table_data(client, table_id):
     # table_id = "your-project.your_dataset.your_table_name"
 
     # Download all rows from a table.
-    rows_iter = client.list_rows(table_id)
+    rows_iter = client.list_rows(table_id)  # Make an API request.
 
     # Iterate over rows to make the API requests to fetch row data.
     rows = list(rows_iter)
@@ -38,10 +38,18 @@ def browse_table_data(client, table_id):
     print("Downloaded {} rows from table {}".format(len(rows), table_id))
 
     # Specify selected fields to limit the results to certain columns.
-    table = client.get_table(table_id)
+    table = client.get_table(table_id)  # Make an API request.
     fields = table.schema[:2]  # first two columns
     rows_iter = client.list_rows(table_id, selected_fields=fields, max_results=10)
     rows = list(rows_iter)
     print("Selected {} columns from table {}.".format(len(rows_iter.schema), table_id))
     print("Downloaded {} rows from table {}".format(len(rows), table_id))
+
+    # Print row data in tabular format.
+    rows = client.list_rows(table, max_results=10)
+    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]

bigquery/samples/create_dataset.py

@@ -33,6 +33,6 @@ def create_dataset(client, dataset_id):
     # Send the dataset to the API for creation.
     # Raises google.api_core.exceptions.Conflict if the Dataset already
     # exists within the project.
-    dataset = client.create_dataset(dataset)  # API request
+    dataset = client.create_dataset(dataset)  # Make an API request.
     print("Created dataset {}.{}".format(client.project, dataset.dataset_id))
     # [END bigquery_create_dataset]

bigquery/samples/create_job.py

@@ -33,7 +33,7 @@ def create_job(client):
         # The client libraries automatically generate a job ID. Override the
         # generated ID with either the job_id_prefix or job_id parameters.
         job_id_prefix="code_sample_",
-    )  # API request
+    )  # Make an API request.
 
     print("Started job: {}".format(query_job.job_id))
     # [END bigquery_create_job]

bigquery/samples/create_routine.py

@@ -40,7 +40,7 @@ def create_routine(client, routine_id):
         ],
     )
 
-    routine = client.create_routine(routine)
+    routine = client.create_routine(routine)  # Make an API request.
 
     print("Created routine {}".format(routine.reference))
     # [END bigquery_create_routine]

bigquery/samples/create_routine_ddl.py

@@ -36,10 +36,10 @@ def create_routine_ddl(client, routine_id):
     )
 
     # Initiate the query to create the routine.
-    query_job = client.query(sql)
+    query_job = client.query(sql)  # Make an API request.
 
     # Wait for the query to complete.
-    query_job.result()
+    query_job.result()  # Waits for the job to complete.
 
     print("Created routine {}".format(query_job.ddl_target_routine))
     # [END bigquery_create_routine_ddl]

bigquery/samples/create_table.py

@@ -30,7 +30,7 @@ def create_table(client, table_id):
     ]
 
     table = bigquery.Table(table_id, schema=schema)
-    table = client.create_table(table)  # API request
+    table = client.create_table(table)  # Make an API request.
     print(
         "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
     )

bigquery/samples/dataset_exists.py

@@ -22,7 +22,7 @@ def dataset_exists(client, dataset_id):
     # dataset_id = "your-project.your_dataset"
 
     try:
-        client.get_dataset(dataset_id)
+        client.get_dataset(dataset_id)  # Make an API request.
         print("Dataset {} already exists".format(dataset_id))
     except NotFound:
         print("Dataset {} is not found".format(dataset_id))

bigquery/samples/delete_dataset.py

@@ -27,7 +27,9 @@ def delete_dataset(client, dataset_id):
 
     # Use the delete_contents parameter to delete a dataset and its contents
     # Use the not_found_ok parameter to not receive an error if the dataset has already been deleted.
-    client.delete_dataset(dataset_id, delete_contents=True, not_found_ok=True)
+    client.delete_dataset(
+        dataset_id, delete_contents=True, not_found_ok=True
+    )  # Make an API request.
 
     print("Deleted dataset '{}'.".format(dataset_id))
     # [END bigquery_delete_dataset]

bigquery/samples/delete_dataset_labels.py

@@ -25,12 +25,12 @@ def delete_dataset_labels(client, dataset_id):
     # TODO(developer): Set dataset_id to the ID of the dataset to fetch.
     # dataset_id = "your-project.your_dataset"
 
-    dataset = client.get_dataset(dataset_id)
+    dataset = client.get_dataset(dataset_id)  # Make an API request.
 
     # To delete a label from a dataset, set its value to None
     dataset.labels["color"] = None
 
-    dataset = client.update_dataset(dataset, ["labels"])
+    dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.
     print("Labels deleted from {}".format(dataset_id))
     # [END bigquery_delete_label_dataset]
     return dataset

bigquery/samples/delete_model.py

@@ -26,7 +26,7 @@ def delete_model(client, model_id):
     # TODO(developer): Set model_id to the ID of the model to fetch.
     # model_id = 'your-project.your_dataset.your_model'
 
-    client.delete_model(model_id)
+    client.delete_model(model_id)  # Make an API request.
 
     print("Deleted model '{}'.".format(model_id))
     # [END bigquery_delete_model]

bigquery/samples/delete_routine.py

@@ -25,7 +25,7 @@ def delete_routine(client, routine_id):
     # TODO(developer): Set the fully-qualified ID for the routine.
     # routine_id = "my-project.my_dataset.my_routine"
 
-    client.delete_routine(routine_id)
+    client.delete_routine(routine_id)  # Make an API request.
 
     print("Deleted routine {}.".format(routine_id))
     # [END bigquery_delete_routine]

bigquery/samples/delete_table.py

@@ -27,6 +27,6 @@ def delete_table(client, table_id):
 
     # If the table does not exist, delete_table raises
     # google.api_core.exceptions.NotFound unless not_found_ok is True
-    client.delete_table(table_id, not_found_ok=True)
+    client.delete_table(table_id, not_found_ok=True)  # Make an API request.
     print("Deleted table '{}'.".format(table_id))
     # [END bigquery_delete_table]

bigquery/samples/get_dataset.py

@@ -25,7 +25,7 @@ def get_dataset(client, dataset_id):
     # TODO(developer): Set dataset_id to the ID of the dataset to fetch.
     # dataset_id = 'your-project.your_dataset'
 
-    dataset = client.get_dataset(dataset_id)
+    dataset = client.get_dataset(dataset_id)  # Make an API request.
 
     full_dataset_id = "{}.{}".format(dataset.project, dataset.dataset_id)
     friendly_name = dataset.friendly_name

bigquery/samples/get_dataset_labels.py

@@ -25,7 +25,7 @@ def get_dataset_labels(client, dataset_id):
     # TODO(developer): Set dataset_id to the ID of the dataset to fetch.
     # dataset_id = "your-project.your_dataset"
 
-    dataset = client.get_dataset(dataset_id)
+    dataset = client.get_dataset(dataset_id)  # Make an API request.
 
     # View dataset labels
     print("Dataset ID: {}".format(dataset_id))

bigquery/samples/get_model.py

@@ -26,7 +26,7 @@ def get_model(client, model_id):
     # TODO(developer): Set model_id to the ID of the model to fetch.
     # model_id = 'your-project.your_dataset.your_model'
 
-    model = client.get_model(model_id)
+    model = client.get_model(model_id)  # Make an API request.
 
     full_model_id = "{}.{}.{}".format(model.project, model.dataset_id, model.model_id)
     friendly_name = model.friendly_name

bigquery/samples/get_routine.py

@@ -25,15 +25,15 @@ def get_routine(client, routine_id):
     # TODO(developer): Set the fully-qualified ID for the routine.
     # routine_id = "my-project.my_dataset.my_routine"
 
-    routine = client.get_routine(routine_id)
+    routine = client.get_routine(routine_id)  # Make an API request.
 
-    print("Routine `{}`:".format(routine.reference))
-    print("  Type: '{}'".format(routine.type_))
-    print("  Language: '{}'".format(routine.language))
-    print("  Arguments:")
+    print("Routine '{}':".format(routine.reference))
+    print("\tType: '{}'".format(routine.type_))
+    print("\tLanguage: '{}'".format(routine.language))
+    print("\tArguments:")
 
     for argument in routine.arguments:
-        print("    Name: '{}'".format(argument.name))
-        print("    Type: '{}'".format(argument.type_))
+        print("\t\tName: '{}'".format(argument.name))
+        print("\t\tType: '{}'".format(argument.data_type))
     # [END bigquery_get_routine]
     return routine

bigquery/samples/get_table.py

@@ -25,13 +25,12 @@ def get_table(client, table_id):
     # TODO(developer): Set table_id to the ID of the model to fetch.
     # table_id = 'your-project.your_dataset.your_table'
 
-    table = client.get_table(table_id)
+    table = client.get_table(table_id)  # Make an API request.
 
+    # View table properties
     print(
         "Got table '{}.{}.{}'.".format(table.project, table.dataset_id, table.table_id)
     )
-
-    # View table properties
     print("Table schema: {}".format(table.schema))
     print("Table description: {}".format(table.description))
     print("Table has {} rows".format(table.num_rows))

bigquery/samples/label_dataset.py

@@ -25,9 +25,9 @@ def label_dataset(client, dataset_id):
     # TODO(developer): Set dataset_id to the ID of the dataset to fetch.
     # dataset_id = "your-project.your_dataset"
 
-    dataset = client.get_dataset(dataset_id)
+    dataset = client.get_dataset(dataset_id)  # Make an API request.
     dataset.labels = {"color": "green"}
-    dataset = client.update_dataset(dataset, ["labels"])
+    dataset = client.update_dataset(dataset, ["labels"])  # Make an API request.
 
     print("Labels added to {}".format(dataset_id))
     # [END bigquery_label_dataset]

bigquery/samples/list_datasets.py

@@ -22,12 +22,12 @@ def list_datasets(client):
     # TODO(developer): Construct a BigQuery client object.
     # client = bigquery.Client()
 
-    datasets = list(client.list_datasets())
+    datasets = list(client.list_datasets())  # Make an API request.
     project = client.project
 
     if datasets:
         print("Datasets in project {}:".format(project))
-        for dataset in datasets:  # API request(s)
+        for dataset in datasets:
             print("\t{}".format(dataset.dataset_id))
     else:
         print("{} project does not contain any datasets.".format(project))

bigquery/samples/list_datasets_by_label.py

@@ -23,7 +23,7 @@ def list_datasets_by_label(client):
     # client = bigquery.Client()
 
     label_filter = "labels.color:green"
-    datasets = list(client.list_datasets(filter=label_filter))
+    datasets = list(client.list_datasets(filter=label_filter))  # Make an API request.
 
     if datasets:
         print("Datasets filtered by {}:".format(label_filter))

bigquery/samples/list_models.py

@@ -27,7 +27,7 @@ def list_models(client, dataset_id):
     #                  the models you are listing.
     # dataset_id = 'your-project.your_dataset'
 
-    models = client.list_models(dataset_id)
+    models = client.list_models(dataset_id)  # Make an API request.
 
     print("Models contained in '{}':".format(dataset_id))
     for model in models:

bigquery/samples/list_routines.py

@@ -26,7 +26,7 @@ def list_routines(client, dataset_id):
     #                  the routines you are listing.
     # dataset_id = 'your-project.your_dataset'
 
-    routines = client.list_routines(dataset_id)
+    routines = client.list_routines(dataset_id)  # Make an API request.
 
     print("Routines contained in dataset {}:".format(dataset_id))
     for routine in routines:

bigquery/samples/list_tables.py

@@ -26,7 +26,7 @@ def list_tables(client, dataset_id):
     #                  the tables you are listing.
     # dataset_id = 'your-project.your_dataset'
 
-    tables = client.list_tables(dataset_id)
+    tables = client.list_tables(dataset_id)  # Make an API request.
 
     print("Tables contained in '{}':".format(dataset_id))
     for table in tables:

bigquery/samples/load_table_dataframe.py

@@ -14,8 +14,10 @@
 
 
 def load_table_dataframe(client, table_id):
+
     # [START bigquery_load_table_dataframe]
     from google.cloud import bigquery
+
     import pandas
 
     # TODO(developer): Construct a BigQuery client object.
@@ -59,11 +61,14 @@ def load_table_dataframe(client, table_id):
     )
 
     job = client.load_table_from_dataframe(
-        dataframe, table_id, job_config=job_config, location="US"
-    )
-    job.result()  # Waits for table load to complete.
+        dataframe,
+        table_id,
+        job_config=job_config,
+        location="US",  # Must match the destination dataset location.
+    )  # Make an API request.
+    job.result()  # Waits for the job to complete.
 
-    table = client.get_table(table_id)
+    table = client.get_table(table_id)  # Make an API request.
     print(
         "Loaded {} rows and {} columns to {}".format(
             table.num_rows, len(table.schema), table_id

bigquery/samples/query_to_arrow.py

@@ -41,7 +41,7 @@ def query_to_arrow(client):
     CROSS JOIN UNNEST(r.participants) as participant;
     """
     query_job = client.query(sql)
-    arrow_table = query_job.to_arrow()
+    arrow_table = query_job.to_arrow()  # Make an API request.
 
     print(
         "Downloaded {} rows, {} columns.".format(

bigquery/samples/tests/test_browse_table_data.py

@@ -24,3 +24,5 @@ def test_browse_table_data(capsys, client, table_with_data_id):
     assert "Downloaded 10 rows from table {}".format(table_with_data_id) in out
     assert "Selected 2 columns from table {}".format(table_with_data_id) in out
     assert "Downloaded 10 rows from table {}".format(table_with_data_id) in out
+    assert "word" in out
+    assert "LVII" in out

bigquery/samples/tests/test_create_routine.py

@@ -0,0 +1,23 @@
+# 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.
+
+
+from .. import create_routine
+
+
+def test_create_routine(capsys, client, random_routine_id):
+
+    create_routine.create_routine(client, random_routine_id)
+    out, err = capsys.readouterr()
+    assert "Created routine {}".format(random_routine_id) in out