Repository: googleapis/google-cloud-python

Issue:
BigQuery: Document constants for things like NEWLINE_DELIMITED_JSON and move to bigquery module
See: https://github.com/GoogleCloudPlatform/google-cloud-python/pull/4790#discussion_r164172094

I think we used to have constants / enum-like classes for some of these things, but maybe they got lost in the rewrite. I can't find NEWLINE_DELIMITED_JSON in the [reference docs for the BigQuery client](https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/reference.html
).

**Feature request:** Add constants for commonly-used strings such as the source formats.


Discussion:
There are three actions left over from #4833:

- [ ] import the classes that hold constants into the [bigquery module](https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/bigquery/google/cloud/bigquery/__init__.py)
- [ ] use the constant classes (via the `bigquery` module) in the [documentation snippets](https://github.com/GoogleCloudPlatform/google-cloud-python/blob/master/docs/bigquery/snippets.py)
- [ ] ensure the constant strings appear in the API reference docs. The docs do not include the possible values. See: https://googlecloudplatform.github.io/google-cloud-python/latest/bigquery/reference.html#google.cloud.bigquery.job.WriteDisposition It defines the class, but none of the values are shown.


Resolving patch:
diff --git a/bigquery/google/cloud/bigquery/__init__.py b/bigquery/google/cloud/bigquery/__init__.py
--- a/bigquery/google/cloud/bigquery/__init__.py
+++ b/bigquery/google/cloud/bigquery/__init__.py
@@ -36,14 +36,21 @@
 from google.cloud.bigquery.dataset import AccessEntry
 from google.cloud.bigquery.dataset import Dataset
 from google.cloud.bigquery.dataset import DatasetReference
+from google.cloud.bigquery.job import Compression
 from google.cloud.bigquery.job import CopyJob
 from google.cloud.bigquery.job import CopyJobConfig
+from google.cloud.bigquery.job import CreateDisposition
+from google.cloud.bigquery.job import DestinationFormat
+from google.cloud.bigquery.job import Encoding
 from google.cloud.bigquery.job import ExtractJob
 from google.cloud.bigquery.job import ExtractJobConfig
-from google.cloud.bigquery.job import QueryJob
-from google.cloud.bigquery.job import QueryJobConfig
 from google.cloud.bigquery.job import LoadJob
 from google.cloud.bigquery.job import LoadJobConfig
+from google.cloud.bigquery.job import QueryJob
+from google.cloud.bigquery.job import QueryJobConfig
+from google.cloud.bigquery.job import QueryPriority
+from google.cloud.bigquery.job import SourceFormat
+from google.cloud.bigquery.job import WriteDisposition
 from google.cloud.bigquery.query import ArrayQueryParameter
 from google.cloud.bigquery.query import ScalarQueryParameter
 from google.cloud.bigquery.query import StructQueryParameter
@@ -94,4 +101,12 @@
     'CSVOptions',
     'GoogleSheetsOptions',
     'DEFAULT_RETRY',
+    # Enum Constants
+    'Compression',
+    'CreateDisposition',
+    'DestinationFormat',
+    'Encoding',
+    'QueryPriority',
+    'SourceFormat',
+    'WriteDisposition'
 ]
diff --git a/bigquery/google/cloud/bigquery/job.py b/bigquery/google/cloud/bigquery/job.py
--- a/bigquery/google/cloud/bigquery/job.py
+++ b/bigquery/google/cloud/bigquery/job.py
@@ -90,38 +90,72 @@ def _error_result_to_exception(error_result):
 
 
 class Compression(_EnumApiResourceProperty):
-    """Pseudo-enum for ``compression`` properties."""
+    """The compression type to use for exported files.
+
+    Possible values include `GZIP` and `NONE`. The default value is `NONE`.
+    """
     GZIP = 'GZIP'
     NONE = 'NONE'
 
 
 class CreateDisposition(_EnumApiResourceProperty):
-    """Pseudo-enum for ``create_disposition`` properties."""
+    """Specifies whether the job is allowed to create new tables.
+
+    The following values are supported:
+    `CREATE_IF_NEEDED`: If the table does not exist, BigQuery creates
+    the table.
+    `CREATE_NEVER`: The table must already exist. If it does not,
+    a 'notFound' error is returned in the job result.
+    The default value is `CREATE_IF_NEEDED`.
+
+    Creation, truncation and append actions occur as one atomic update
+    upon job completion.
+    """
     CREATE_IF_NEEDED = 'CREATE_IF_NEEDED'
     CREATE_NEVER = 'CREATE_NEVER'
 
 
 class DestinationFormat(_EnumApiResourceProperty):
-    """Pseudo-enum for ``destination_format`` properties."""
+    """The exported file format.
+
+    Possible values include `CSV`, `NEWLINE_DELIMITED_JSON` and `AVRO`.
+    The default value is `CSV`. Tables with nested or repeated fields
+    cannot be exported as CSV.
+    """
     CSV = 'CSV'
     NEWLINE_DELIMITED_JSON = 'NEWLINE_DELIMITED_JSON'
     AVRO = 'AVRO'
 
 
 class Encoding(_EnumApiResourceProperty):
-    """Pseudo-enum for ``encoding`` properties."""
+    """The character encoding of the data. The supported values
+    are `UTF-8` or `ISO-8859-1`. The default value is `UTF-8`.
+
+    BigQuery decodes the data after the raw, binary data has been
+    split using the values of the quote and fieldDelimiter properties.
+    """
     UTF_8 = 'UTF-8'
     ISO_8559_1 = 'ISO-8559-1'
 
 
 class QueryPriority(_EnumApiResourceProperty):
-    """Pseudo-enum for ``QueryJob.priority`` property."""
+    """Specifies a priority for the query.
+
+    Possible values include `INTERACTIVE` and `BATCH`. The default value
+    is `INTERACTIVE`.
+    """
     INTERACTIVE = 'INTERACTIVE'
     BATCH = 'BATCH'
 
 
 class SourceFormat(_EnumApiResourceProperty):
-    """Pseudo-enum for ``source_format`` properties."""
+    """The format of the data files.
+
+    For CSV files, specify `CSV`. For datastore backups, specify
+    `DATASTORE_BACKUP`. For newline-delimited json, specify
+    `NEWLINE_DELIMITED_JSON`. For Avro, specify `AVRO`. The default
+    value is `CSV`.
+    """
     CSV = 'CSV'
     DATASTORE_BACKUP = 'DATASTORE_BACKUP'
     NEWLINE_DELIMITED_JSON = 'NEWLINE_DELIMITED_JSON'
@@ -129,7 +163,21 @@ class SourceFormat(_EnumApiResourceProperty):
 
 
 class WriteDisposition(_EnumApiResourceProperty):
-    """Pseudo-enum for ``write_disposition`` properties."""
+    """Specifies the action that occurs if destination table already exists.
+
+    The following values are supported:
+    `WRITE_TRUNCATE`: If the table already exists, BigQuery overwrites the
+    table data.
+    `WRITE_APPEND`: If the table already exists, BigQuery appends the data
+    to the table.
+    `WRITE_EMPTY`: If the table already exists and contains data, a 'duplicate'
+    error is returned in the job result.
+    The default value is `WRITE_APPEND`.
+
+    Each action is atomic and only occurs if BigQuery is able to complete
+    the job successfully. Creation, truncation and append actions occur as one
+    atomic update upon job completion.
+    """
     WRITE_APPEND = 'WRITE_APPEND'
     WRITE_TRUNCATE = 'WRITE_TRUNCATE'
     WRITE_EMPTY = 'WRITE_EMPTY'
diff --git a/docs/bigquery/snippets.py b/docs/bigquery/snippets.py
--- a/docs/bigquery/snippets.py
+++ b/docs/bigquery/snippets.py
@@ -567,7 +567,7 @@ def test_load_table_from_uri(client, to_delete):
         bigquery.SchemaField('name', 'STRING'),
         bigquery.SchemaField('post_abbr', 'STRING')
     ]
-    job_config.source_format = 'NEWLINE_DELIMITED_JSON'
+    job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
 
     load_job = client.load_table_from_uri(
         'gs://cloud-samples-data/bigquery/us-states/us-states.json',
@@ -594,7 +594,7 @@ def test_load_table_from_uri_cmek(client, to_delete):
     dataset_ref = client.dataset(dataset_id)
     job_config = bigquery.LoadJobConfig()
     job_config.autodetect = True
-    job_config.source_format = 'NEWLINE_DELIMITED_JSON'
+    job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
 
     # Set the encryption key to use for the destination.
     # TODO: Replace this key with a key you have created in KMS.
@@ -630,7 +630,7 @@ def test_load_table_from_uri_autodetect(client, to_delete):
     dataset_ref = client.dataset(dataset_id)
     job_config = bigquery.LoadJobConfig()
     job_config.autodetect = True
-    job_config.source_format = 'NEWLINE_DELIMITED_JSON'
+    job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
 
     load_job = client.load_table_from_uri(
         'gs://cloud-samples-data/bigquery/us-states/us-states.json',
@@ -666,8 +666,8 @@ def test_load_table_from_uri_append(client, to_delete):
     # table_ref = client.dataset('my_dataset').table('existing_table')
     previous_rows = client.get_table(table_ref).num_rows
     job_config = bigquery.LoadJobConfig()
-    job_config.source_format = 'NEWLINE_DELIMITED_JSON'
-    job_config.write_disposition = 'WRITE_APPEND'
+    job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
+    job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
 
     load_job = client.load_table_from_uri(
         'gs://cloud-samples-data/bigquery/us-states/us-states.json',
@@ -705,8 +705,8 @@ def test_load_table_from_uri_truncate(client, to_delete):
     assert previous_rows > 0
 
     job_config = bigquery.LoadJobConfig()
-    job_config.source_format = 'NEWLINE_DELIMITED_JSON'
-    job_config.write_disposition = 'WRITE_TRUNCATE'
+    job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
+    job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
 
     load_job = client.load_table_from_uri(
         'gs://cloud-samples-data/bigquery/us-states/us-states.json',
@@ -822,8 +822,8 @@ def test_extract_table(client, to_delete):
     rows = [json.dumps(row) for row in to_insert]
     body = six.StringIO('{}\n'.format('\n'.join(rows)))
     job_config = bigquery.LoadJobConfig()
-    job_config.write_disposition = 'WRITE_TRUNCATE'
-    job_config.source_format = 'NEWLINE_DELIMITED_JSON'
+    job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
+    job_config.source_format = bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
     job_config.schema = SCHEMA
     to_delete.insert(0, table_ref)
     # Load a table using a local JSON file from memory.


Test patch: