Merge pull request #1280 from tseaver/1267-document_cloud_storage_uri_format

Document URI format for loading/extracting Cloud Storage objects.

Author: dhermes

gcloud/bigquery/client.py

@@ -105,14 +105,18 @@ 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.
 
  :type destination: :class:`gcloud.bigquery.table.Table`
  :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.
 

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