Update external_config docstrings to google style and fixes typos (googleapis#5713)

alixhami · web-flow · commit 38080c8920d2 · 2018-08-06T11:21:47.000-07:00
diff --git a/bigquery/google/cloud/bigquery/external_config.py b/bigquery/google/cloud/bigquery/external_config.py
@@ -30,7 +30,7 @@
 
 
 class ExternalSourceFormat(object):
-    """The format for external data files..
+    """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
@@ -157,21 +157,26 @@ def type_(self, value):
     def to_api_repr(self):
         """Build an API representation of this object.
 
-        :rtype: dict
-        :returns: A dictionary in the format used by the BigQuery API.
+        Returns:
+            Dict[str, Any]:
+                A dictionary in the format used by the BigQuery API.
         """
         return copy.deepcopy(self._properties)
 
     @classmethod
     def from_api_repr(cls, resource):
-        """Factory: construct a BigtableColumn given its API representation
+        """Factory: construct a :class:`~.external_config.BigtableColumn`
+        instance given its API representation.
 
-        :type resource: dict
-        :param resource:
-            A column in the same representation as is returned from the API.
+        Args:
+            resource (Dict[str, Any]):
+                Definition of a :class:`~.external_config.BigtableColumn`
+                instance in the same representation as is returned from the
+                API.
 
-        :rtype: :class:`~google.cloud.bigquery.BigtableColumn`
-        :returns: Configuration parsed from ``resource``.
+        Returns:
+            :class:`~.external_config.BigtableColumn`:
+                Configuration parsed from ``resource``.
         """
         config = cls()
         config._properties = copy.deepcopy(resource)
@@ -243,8 +248,8 @@ def type_(self, value):
 
     @property
     def columns(self):
-        """List[google.cloud.bigquery.external_config.BigtableColumn]: Lists of
-        columns that should be exposed as individual fields
+        """List[:class:`~.external_config.BigtableColumn`]: Lists of columns
+        that should be exposed as individual fields.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query.tableDefinitions.(key).bigtableOptions.columnFamilies.columns
@@ -260,33 +265,35 @@ def columns(self, value):
     def to_api_repr(self):
         """Build an API representation of this object.
 
-        :rtype: dict
-        :returns: A dictionary in the format used by the BigQuery API.
+        Returns:
+            Dict[str, Any]:
+                A dictionary in the format used by the BigQuery API.
         """
         return copy.deepcopy(self._properties)
 
     @classmethod
     def from_api_repr(cls, resource):
-        """Factory: construct a BigtableColumnFamily given its
-           API representation
+        """Factory: construct a :class:`~.external_config.BigtableColumnFamily`
+        instance given its API representation.
 
-        :type resource: dict
-        :param resource:
-            A column family in the same representation as is returned
-            from the API.
+        Args:
+            resource (Dict[str, Any]):
+                Definition of a :class:`~.external_config.BigtableColumnFamily`
+                instance in the same representation as is returned from the
+                API.
 
-        :rtype:
-            :class:`~google.cloud.bigquery.external_config.BigtableColumnFamily`
-        :returns: Configuration parsed from ``resource``.
+        Returns:
+            :class:`~.external_config.BigtableColumnFamily`:
+                Configuration parsed from ``resource``.
         """
         config = cls()
         config._properties = copy.deepcopy(resource)
         return config
 
 
 class BigtableOptions(object):
-    """Options that describe how to treat Bigtable tables
-       as BigQuery tables."""
+    """Options that describe how to treat Bigtable tables as BigQuery tables.
+    """
 
     _SOURCE_FORMAT = 'BIGTABLE'
     _RESOURCE_NAME = 'bigtableOptions'
@@ -296,8 +303,8 @@ def __init__(self):
 
     @property
     def ignore_unspecified_column_families(self):
-        """bool: If `True`, ignore columns not specified in columnFamilies
-        list. Defaults to `False`.
+        """bool: If :data:`True`, ignore columns not specified in
+        :attr:`column_families` list. Defaults to :data:`False`.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query.tableDefinitions.(key).bigtableOptions.ignoreUnspecifiedColumnFamilies
@@ -311,8 +318,8 @@ def ignore_unspecified_column_families(self, value):
 
     @property
     def read_rowkey_as_string(self):
-        """bool: If `True`, rowkey column families will be read and converted
-        to string. Defaults to `False`.
+        """bool: If :data:`True`, rowkey column families will be read and
+        converted to string. Defaults to :data:`False`.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query.tableDefinitions.(key).bigtableOptions.readRowkeyAsString
@@ -326,9 +333,8 @@ def read_rowkey_as_string(self, value):
 
     @property
     def column_families(self):
-        """List[google.cloud.bigquery.external_config.BigtableColumnFamily]:
-        List of column families to expose in the table schema along with their
-        types.
+        """List[:class:`~.external_config.BigtableColumnFamily`]: List of
+        column families to expose in the table schema along with their types.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query.tableDefinitions.(key).bigtableOptions.columnFamilies
@@ -344,23 +350,26 @@ def column_families(self, value):
     def to_api_repr(self):
         """Build an API representation of this object.
 
-        :rtype: dict
-        :returns: A dictionary in the format used by the BigQuery API.
+        Returns:
+            Dict[str, Any]:
+                A dictionary in the format used by the BigQuery API.
         """
         return copy.deepcopy(self._properties)
 
     @classmethod
     def from_api_repr(cls, resource):
-        """Factory: construct a BigtableOptions given its API representation
+        """Factory: construct a :class:`~.external_config.BigtableOptions`
+        instance given its API representation.
 
-        :type resource: dict
-        :param resource:
-            A BigtableOptions in the same representation as is returned
-            from the API.
+        Args:
+            resource (Dict[str, Any]):
+                Definition of a :class:`~.external_config.BigtableOptions`
+                instance in the same representation as is returned from the
+                API.
 
-        :rtype:
-            :class:`~google.cloud.bigquery.external_config.BigtableOptions`
-        :returns: Configuration parsed from ``resource``.
+        Returns:
+            :class:`~.external_config.BigtableOptions`:
+                Configuration parsed from ``resource``.
         """
         config = cls()
         config._properties = copy.deepcopy(resource)
@@ -378,8 +387,8 @@ def __init__(self):
 
     @property
     def allow_jagged_rows(self):
-        """bool: If `True`, BigQuery treats missing trailing columns as null
-        values. Defaults to `False`.
+        """bool: If :data:`True`, BigQuery treats missing trailing columns as
+        null values. Defaults to :data:`False`.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query.tableDefinitions.(key).csvOptions.allowJaggedRows
@@ -393,8 +402,8 @@ def allow_jagged_rows(self, value):
 
     @property
     def allow_quoted_newlines(self):
-        """bool: If `True`, quoted data sections that contain newline
-        characters in a CSV file are allowed. Defaults to `False`.
+        """bool: If :data:`True`, quoted data sections that contain newline
+        characters in a CSV file are allowed. Defaults to :data:`False`.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query.tableDefinitions.(key).csvOptions.allowQuotedNewlines
@@ -422,7 +431,7 @@ def encoding(self, value):
 
     @property
     def field_delimiter(self):
-        """str: The separator for fields in a CSV file. Defaults a comma (',').
+        """str: The separator for fields in a CSV file. Defaults to comma (',').
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query.tableDefinitions.(key).csvOptions.fieldDelimiter
@@ -465,22 +474,26 @@ def skip_leading_rows(self, value):
     def to_api_repr(self):
         """Build an API representation of this object.
 
-        :rtype: dict
-        :returns: A dictionary in the format used by the BigQuery API.
+        Returns:
+            Dict[str, Any]:
+                A dictionary in the format used by the BigQuery API.
         """
         return copy.deepcopy(self._properties)
 
     @classmethod
     def from_api_repr(cls, resource):
-        """Factory: construct a CSVOptions given its API representation
+        """Factory: construct a :class:`~.external_config.CSVOptions` instance
+        given its API representation.
 
-        :type resource: dict
-        :param resource:
-            A CSVOptions in the same representation as is
-            returned from the API.
+        Args:
+            resource (Dict[str, Any]):
+                Definition of a :class:`~.external_config.CSVOptions`
+                instance in the same representation as is returned from the
+                API.
 
-        :rtype: :class:`~google.cloud.bigquery.external_config.CSVOptions`
-        :returns: Configuration parsed from ``resource``.
+        Returns:
+            :class:`~.external_config.CSVOptions`:
+                Configuration parsed from ``resource``.
         """
         config = cls()
         config._properties = copy.deepcopy(resource)
@@ -514,23 +527,26 @@ def skip_leading_rows(self, value):
     def to_api_repr(self):
         """Build an API representation of this object.
 
-        :rtype: dict
-        :returns: A dictionary in the format used by the BigQuery API.
+        Returns:
+            Dict[str, Any]:
+                A dictionary in the format used by the BigQuery API.
         """
         return copy.deepcopy(self._properties)
 
     @classmethod
     def from_api_repr(cls, resource):
-        """Factory: construct a GoogleSheetsOptions given its API representation
+        """Factory: construct a :class:`~.external_config.GoogleSheetsOptions`
+        instance given its API representation.
 
-        :type resource: dict
-        :param resource:
-            An GoogleSheetsOptions in the same representation as is
-            returned from the API.
+        Args:
+            resource (Dict[str, Any]):
+                Definition of a :class:`~.external_config.GoogleSheetsOptions`
+                instance in the same representation as is returned from the
+                API.
 
-        :rtype:
-            :class:`~google.cloud.bigquery.external_config.GoogleSheetsOptions`
-        :returns: Configuration parsed from ``resource``.
+        Returns:
+            :class:`~.external_config.GoogleSheetsOptions`:
+                Configuration parsed from ``resource``.
         """
         config = cls()
         config._properties = copy.deepcopy(resource)
@@ -544,7 +560,7 @@ class ExternalConfig(object):
     """Description of an external data source.
 
     Args:
-        source_format :class:`ExternalSourceFormat`:
+        source_format (:class:`~.external_config.ExternalSourceFormat`):
             See :attr:`source_format`.
     """
 
@@ -558,7 +574,8 @@ def __init__(self, source_format):
 
     @property
     def source_format(self):
-        """:class:`ExternalSourceFormat`: Format of external source.
+        """:class:`~.external_config.ExternalSourceFormat`:
+        Format of external source.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#externalDataConfiguration.sourceFormat
@@ -567,12 +584,12 @@ def source_format(self):
 
     @property
     def options(self):
-        """Source-specific options."""
+        """Dict[str, Any]: Source-specific options."""
         return self._options
 
     @property
     def autodetect(self):
-        """bool: If `True`, try to detect schema and format options
+        """bool: If :data:`True`, try to detect schema and format options
         automatically.
 
         See
@@ -601,8 +618,8 @@ def compression(self, value):
 
     @property
     def ignore_unknown_values(self):
-        """bool: If `True`, extra values that are not represented in the table
-        schema are ignored. Defaults to `False`.
+        """bool: If :data:`True`, extra values that are not represented in the
+        table schema are ignored. Defaults to :data:`False`.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query.tableDefinitions.(key).ignoreUnknownValues
@@ -645,8 +662,8 @@ def source_uris(self, value):
 
     @property
     def schema(self):
-        """List[google.cloud.bigquery.schema.SchemaField]: The schema for the
-        data.
+        """List[:class:`~google.cloud.bigquery.schema.SchemaField`]: The schema
+        for the data.
 
         See
         https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs#configuration.query.tableDefinitions.(key).schema
@@ -666,8 +683,9 @@ def schema(self, value):
     def to_api_repr(self):
         """Build an API representation of this object.
 
-        :rtype: dict
-        :returns: A dictionary in the format used by the BigQuery API.
+        Returns:
+            Dict[str, Any]:
+                A dictionary in the format used by the BigQuery API.
         """
         config = copy.deepcopy(self._properties)
         if self.options is not None:
@@ -678,15 +696,18 @@ def to_api_repr(self):
 
     @classmethod
     def from_api_repr(cls, resource):
-        """Factory: construct a CSVOptions given its API representation
-
-        :type resource: dict
-        :param resource:
-            An extract job configuration in the same representation as is
-            returned from the API.
-
-        :rtype: :class:`~google.cloud.bigquery.external_config.CSVOptions`
-        :returns: Configuration parsed from ``resource``.
+        """Factory: construct an :class:`~.external_config.ExternalConfig`
+        instance given its API representation.
+
+        Args:
+            resource (Dict[str, Any]):
+                Definition of an :class:`~.external_config.ExternalConfig`
+                instance in the same representation as is returned from the
+                API.
+
+        Returns:
+            :class:`~.external_config.ExternalConfig`:
+                Configuration parsed from ``resource``.
         """
         config = cls(resource['sourceFormat'])
         for optcls in _OPTION_CLASSES:
