Repository: googleapis/google-cloud-python

Issue:
Document format for Cloud Storage URIs used in BigQuery
BigQuery APIs which load table data from (or extract it to) Cloud Storage blobs take URIs of the format, `gs://<bucket-name>/<object-name-or-glob>`.  Ensure that the docstrings for those methods document the expected URI format.



Discussion:
:+1: Thanks


Resolving patch:
diff --git a/gcloud/bigquery/client.py b/gcloud/bigquery/client.py
--- a/gcloud/bigquery/client.py
+++ b/gcloud/bigquery/client.py
@@ -105,6 +105,9 @@ def dataset(self, dataset_name):
     def load_table_from_storage(self, job_name, destination, *source_uris):
         """Construct a job for loading data into a table from CloudStorage.
 
+        See:
+        https://cloud.google.com/bigquery/docs/reference/v2/jobs#configuration.load
+
         :type job_name: string
         :param job_name: Name of the job.
 
@@ -112,7 +115,8 @@ def load_table_from_storage(self, job_name, destination, *source_uris):
         :param destination: Table into which data is to be loaded.
 
         :type source_uris: sequence of string
-        :param source_uris: URIs of data files to be loaded.
+        :param source_uris: URIs of data files to be loaded; in format
+                            ``gs://<bucket_name>/<object_name_or_glob>``.
 
         :rtype: :class:`gcloud.bigquery.job.LoadTableFromStorageJob`
         :returns: a new ``LoadTableFromStorageJob`` instance
@@ -123,6 +127,9 @@ def load_table_from_storage(self, job_name, destination, *source_uris):
     def copy_table(self, job_name, destination, *sources):
         """Construct a job for copying one or more tables into another table.
 
+        See:
+        https://cloud.google.com/bigquery/docs/reference/v2/jobs#configuration.copy
+
         :type job_name: string
         :param job_name: Name of the job.
 
@@ -140,6 +147,9 @@ def copy_table(self, job_name, destination, *sources):
     def extract_table_to_storage(self, job_name, source, *destination_uris):
         """Construct a job for extracting a table into Cloud Storage files.
 
+        See:
+        https://cloud.google.com/bigquery/docs/reference/v2/jobs#configuration.extract
+
         :type job_name: string
         :param job_name: Name of the job.
 
@@ -148,7 +158,8 @@ def extract_table_to_storage(self, job_name, source, *destination_uris):
 
         :type destination_uris: sequence of string
         :param destination_uris: URIs of CloudStorage file(s) into which
-                                 table data is to be extracted.
+                                 table data is to be extracted; in format
+                                 ``gs://<bucket_name>/<object_name_or_glob>``.
 
         :rtype: :class:`gcloud.bigquery.job.ExtractTableToStorageJob`
         :returns: a new ``ExtractTableToStorageJob`` instance
@@ -159,6 +170,9 @@ def extract_table_to_storage(self, job_name, source, *destination_uris):
     def run_async_query(self, job_name, query):
         """Construct a job for running a SQL query asynchronously.
 
+        See:
+        https://cloud.google.com/bigquery/docs/reference/v2/jobs#configuration.query
+
         :type job_name: string
         :param job_name: Name of the job.
 
diff --git a/gcloud/bigquery/job.py b/gcloud/bigquery/job.py
--- a/gcloud/bigquery/job.py
+++ b/gcloud/bigquery/job.py
@@ -435,7 +435,8 @@ class LoadTableFromStorageJob(_AsyncJob):
     :param destination: Table into which data is to be loaded.
 
     :type source_uris: sequence of string
-    :param source_uris: URIs of data files to be loaded.
+    :param source_uris: URIs of one or more data files to be loaded, in
+                        format ``gs://<bucket_name>/<object_name_or_glob>``.
 
     :type client: :class:`gcloud.bigquery.client.Client`
     :param client: A client which holds credentials and project configuration
@@ -736,7 +737,8 @@ class ExtractTableToStorageJob(_AsyncJob):
 
     :type destination_uris: list of string
     :param destination_uris: URIs describing Cloud Storage blobs into which
-                             extracted data will be written.
+                             extracted data will be written, in format
+                             ``gs://<bucket_name>/<object_name_or_glob>``.
 
     :type client: :class:`gcloud.bigquery.client.Client`
     :param client: A client which holds credentials and project configuration


Test patch: