Add 'ExternalSourceFormat' enum. (googleapis#5674)

tseaver · web-flow · commit 13bbcdc11158 · 2018-07-25T14:09:48.000-04:00
Closes googleapis#5499.
diff --git a/bigquery/google/cloud/bigquery/__init__.py b/bigquery/google/cloud/bigquery/__init__.py
@@ -35,6 +35,13 @@
 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.external_config import ExternalConfig
+from google.cloud.bigquery.external_config import BigtableOptions
+from google.cloud.bigquery.external_config import BigtableColumnFamily
+from google.cloud.bigquery.external_config import BigtableColumn
+from google.cloud.bigquery.external_config import CSVOptions
+from google.cloud.bigquery.external_config import GoogleSheetsOptions
+from google.cloud.bigquery.external_config import ExternalSourceFormat
 from google.cloud.bigquery.job import Compression
 from google.cloud.bigquery.job import CopyJob
 from google.cloud.bigquery.job import CopyJobConfig
@@ -64,12 +71,6 @@
 from google.cloud.bigquery.table import Row
 from google.cloud.bigquery.table import TimePartitioningType
 from google.cloud.bigquery.table import TimePartitioning
-from google.cloud.bigquery.external_config import ExternalConfig
-from google.cloud.bigquery.external_config import BigtableOptions
-from google.cloud.bigquery.external_config import BigtableColumnFamily
-from google.cloud.bigquery.external_config import BigtableColumn
-from google.cloud.bigquery.external_config import CSVOptions
-from google.cloud.bigquery.external_config import GoogleSheetsOptions
 
 __all__ = [
     '__version__',
@@ -112,6 +113,7 @@
     'Compression',
     'CreateDisposition',
     'DestinationFormat',
+    'ExternalSourceFormat',
     'Encoding',
     'QueryPriority',
     'SchemaUpdateOption',
diff --git a/bigquery/google/cloud/bigquery/external_config.py b/bigquery/google/cloud/bigquery/external_config.py
@@ -29,6 +29,33 @@
 from google.cloud.bigquery.schema import SchemaField
 
 
+class ExternalSourceFormat(object):
+    """The format for external data files..
+
+    Note that the set of allowed values for external data sources is different
+    than the set used for loading data (see
+    :class:`~google.cloud.bigquery.job.SourceFormat`).
+    """
+
+    CSV = 'CSV'
+    """Specifies CSV format."""
+
+    GOOGLE_SHEETS = 'GOOGLE_SHEETS'
+    """Specifies Google Sheets format."""
+
+    NEWLINE_DELIMITED_JSON = 'NEWLINE_DELIMITED_JSON'
+    """Specifies newline delimited JSON format."""
+
+    AVRO = 'AVRO'
+    """Specifies Avro format."""
+
+    DATASTORE_BACKUP = 'DATASTORE_BACKUP'
+    """Specifies datastore backup format"""
+
+    BIGTABLE = 'BIGTABLE'
+    """Specifies Bigtable format."""
+
+
 class BigtableColumn(object):
     """Options for a Bigtable column."""
 
@@ -516,9 +543,9 @@ def from_api_repr(cls, resource):
 class ExternalConfig(object):
     """Description of an external data source.
 
-    :type source_format: str
-    :param source_format: the format of the external data. See
-                          the ``source_format`` property on this class.
+    Args:
+        source_format :class:`ExternalSourceFormat`:
+            See :attr:`source_format`.
     """
 
     def __init__(self, source_format):
@@ -531,8 +558,9 @@ def __init__(self, source_format):
 
     @property
     def source_format(self):
-        """See
-        https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query.tableDefinitions.(key).sourceFormat
+        """:class:`ExternalSourceFormat`: Format of external source.
+
+        See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#externalDataConfiguration.sourceFormat
         """
         return self._properties['sourceFormat']
diff --git a/bigquery/google/cloud/bigquery/job.py b/bigquery/google/cloud/bigquery/job.py
@@ -166,7 +166,12 @@ class QueryPriority(object):
 
 
 class SourceFormat(object):
-    """The format of the data files. The default value is :attr:`CSV`."""
+    """The format of the data files. The default value is :attr:`CSV`.
+
+    Note that the set of allowed values for loading data is different
+    than the set used for external data sources (see
+    :class:`~google.cloud.bigquery.external_config.ExternalSourceFormat`).
+    """
 
     CSV = 'CSV'
     """Specifies CSV format."""
diff --git a/docs/bigquery/reference.rst b/docs/bigquery/reference.rst
@@ -129,6 +129,7 @@ External Configuration
 .. autosummary::
     :toctree: generated
 
+    external_config.ExternalSourceFormat
     external_config.ExternalConfig
     external_config.BigtableOptions
     external_config.BigtableColumnFamily
