Merge pull request #44 from GoogleCloudPlatform/docstrings

Added doc strings to functions with ambiguous args

bigquery/samples/export_data_to_cloud_storage.py

@@ -21,6 +21,19 @@
 def export_table(service, cloud_storage_path,
  projectId, datasetId, tableId,
  num_retries=5):
+ """
+ Starts an export job
+
+ Args:
+ service: initialized and authorized bigquery
+ google-api-client object,
+ cloud_storage_path: fully qualified
+ path to a Google Cloud Storage location,
+ e.g. gs://mybucket/myfolder/
+
+ Returns: an extract job resource representing the
+ job, see https://cloud.google.com/bigquery/docs/reference/v2/jobs
+ """
  # Generate a unique job_id so retries
  # don't accidentally duplicate export
  job_data = {

bigquery/samples/load_data_by_post.py

@@ -22,6 +22,18 @@
 
 # [START make_post]
 def make_post(http, schema, data, projectId, datasetId, tableId):
+ """
+ Creates an http POST request for loading data into
+ a bigquery table
+
+ Args:
+ http: an authorized httplib2 client,
+ schema: a valid bigquery schema,
+ see https://cloud.google.com/bigquery/docs/reference/v2/tables,
+ data: valid JSON to insert into the table
+
+ Returns: an http.request object
+ """
  url = ('https://www.googleapis.com/upload/bigquery/v2/projects/' +
  projectId + '/jobs')
  # Create the body of the request, separated by a boundary of xxx

bigquery/samples/load_data_from_csv.py

@@ -20,6 +20,21 @@
 # [START load_table]
 def load_table(service, source_schema, source_csv,
  projectId, datasetId, tableId, num_retries=5):
+ """
+ Starts a job to load a bigquery table from CSV
+
+ Args:
+ service: an initialized and authorized bigquery
+ google-api-client object
+ source_schema: a valid bigquery schema,
+ see https://cloud.google.com/bigquery/docs/reference/v2/tables
+ source_csv: the fully qualified Google Cloud Storage location of
+ the data to load into your table
+
+ Returns: a bigquery load job, see
+ https://cloud.google.com/bigquery/docs/reference/v2/jobs#configuration.load
+ """
+
  # Generate a unique job_id so retries
  # don't accidentally duplicate query
  job_data = {

bigquery/samples/utils.py

@@ -15,8 +15,11 @@
 
 # [START get_service]
 def get_service():
+ """returns an initialized and authorized bigquery client"""
+
  from googleapiclient.discovery import build
  from oauth2client.client import GoogleCredentials
+
  credentials = GoogleCredentials.get_application_default()
  if credentials.create_scoped_required():
  credentials = credentials.create_scoped(
@@ -27,6 +30,8 @@ def get_service():
 
 # [START poll_job]
 def poll_job(service, projectId, jobId, interval=5, num_retries=5):
+ """checks the status of a job every *interval* seconds"""
+
  import time
 
  job_get = service.jobs().get(projectId=projectId, jobId=jobId)
@@ -44,6 +49,8 @@ def poll_job(service, projectId, jobId, interval=5, num_retries=5):
 
 # [START paging]
 def paging(service, request_func, num_retries=5, **kwargs):
+ """pages though the results of an asynchronous job"""
+
  has_next = True
  while has_next:
  response = request_func(**kwargs).execute(num_retries=num_retries)