Add documentation for google.api.core modules (#4203)

Author: Jon Wayne Parrott

core/google/api/core/exceptions.py

@@ -150,8 +150,8 @@ class TemporaryRedirect(Redirection):
 class ResumeIncomplete(Redirection):
     """Exception mapping a ``308 Resume Incomplete`` response.
 
-    .. note:: :ref:`http_client.PERMANENT_REDIRECT` is ``308``, but Google APIs
-        differ in their use of this status code.
+    .. note:: :attr:`http_client.PERMANENT_REDIRECT` is ``308``, but Google
+        APIs differ in their use of this status code.
     """
     code = 308
 
@@ -166,20 +166,20 @@ class BadRequest(ClientError):
 
 
 class InvalidArgument(BadRequest):
-    """Exception mapping a :prop:`grpc.StatusCode.INVALID_ARGUMENT` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.INVALID_ARGUMENT` error."""
     grpc_status_code = (
         grpc.StatusCode.INVALID_ARGUMENT if grpc is not None else None)
 
 
 class FailedPrecondition(BadRequest):
-    """Exception mapping a :prop:`grpc.StatusCode.FAILED_PRECONDITION`
+    """Exception mapping a :attr:`grpc.StatusCode.FAILED_PRECONDITION`
     error."""
     grpc_status_code = (
         grpc.StatusCode.FAILED_PRECONDITION if grpc is not None else None)
 
 
 class OutOfRange(BadRequest):
-    """Exception mapping a :prop:`grpc.StatusCode.OUT_OF_RANGE` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.OUT_OF_RANGE` error."""
     grpc_status_code = (
         grpc.StatusCode.OUT_OF_RANGE if grpc is not None else None)
 
@@ -190,7 +190,7 @@ class Unauthorized(ClientError):
 
 
 class Unauthenticated(Unauthorized):
-    """Exception mapping a :prop:`grpc.StatusCode.UNAUTHENTICATED` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.UNAUTHENTICATED` error."""
     grpc_status_code = (
         grpc.StatusCode.UNAUTHENTICATED if grpc is not None else None)
 
@@ -201,14 +201,14 @@ class Forbidden(ClientError):
 
 
 class PermissionDenied(Forbidden):
-    """Exception mapping a :prop:`grpc.StatusCode.PERMISSION_DENIED` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.PERMISSION_DENIED` error."""
     grpc_status_code = (
         grpc.StatusCode.PERMISSION_DENIED if grpc is not None else None)
 
 
 class NotFound(ClientError):
     """Exception mapping a ``404 Not Found`` response or a
-    :prop:`grpc.StatusCode.NOT_FOUND` error."""
+    :attr:`grpc.StatusCode.NOT_FOUND` error."""
     code = http_client.NOT_FOUND
     grpc_status_code = (
         grpc.StatusCode.NOT_FOUND if grpc is not None else None)
@@ -225,13 +225,13 @@ class Conflict(ClientError):
 
 
 class AlreadyExists(Conflict):
-    """Exception mapping a :prop:`grpc.StatusCode.ALREADY_EXISTS` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.ALREADY_EXISTS` error."""
     grpc_status_code = (
         grpc.StatusCode.ALREADY_EXISTS if grpc is not None else None)
 
 
 class Aborted(Conflict):
-    """Exception mapping a :prop:`grpc.StatusCode.ABORTED` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.ABORTED` error."""
     grpc_status_code = (
         grpc.StatusCode.ABORTED if grpc is not None else None)
 
@@ -258,13 +258,13 @@ class TooManyRequests(ClientError):
 
 
 class ResourceExhausted(TooManyRequests):
-    """Exception mapping a :prop:`grpc.StatusCode.RESOURCE_EXHAUSTED` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.RESOURCE_EXHAUSTED` error."""
     grpc_status_code = (
         grpc.StatusCode.RESOURCE_EXHAUSTED if grpc is not None else None)
 
 
 class Cancelled(ClientError):
-    """Exception mapping a :prop:`grpc.StatusCode.CANCELLED` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.CANCELLED` error."""
     # This maps to HTTP status code 499. See
     # https://github.com/googleapis/googleapis/blob/master/google/rpc\
     # /code.proto
@@ -278,24 +278,24 @@ class ServerError(GoogleAPICallError):
 
 class InternalServerError(ServerError):
     """Exception mapping a ``500 Internal Server Error`` response. or a
-    :prop:`grpc.StatusCode.INTERNAL` error."""
+    :attr:`grpc.StatusCode.INTERNAL` error."""
     code = http_client.INTERNAL_SERVER_ERROR
     grpc_status_code = grpc.StatusCode.INTERNAL if grpc is not None else None
 
 
 class Unknown(ServerError):
-    """Exception mapping a :prop:`grpc.StatusCode.UNKNOWN` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.UNKNOWN` error."""
     grpc_status_code = grpc.StatusCode.UNKNOWN if grpc is not None else None
 
 
 class DataLoss(ServerError):
-    """Exception mapping a :prop:`grpc.StatusCode.DATA_LOSS` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.DATA_LOSS` error."""
     grpc_status_code = grpc.StatusCode.DATA_LOSS if grpc is not None else None
 
 
 class MethodNotImplemented(ServerError):
     """Exception mapping a ``501 Not Implemented`` response or a
-    :prop:`grpc.StatusCode.UNIMPLEMENTED` error."""
+    :attr:`grpc.StatusCode.UNIMPLEMENTED` error."""
     code = http_client.NOT_IMPLEMENTED
     grpc_status_code = (
         grpc.StatusCode.UNIMPLEMENTED if grpc is not None else None)
@@ -308,7 +308,7 @@ class BadGateway(ServerError):
 
 class ServiceUnavailable(ServerError):
     """Exception mapping a ``503 Service Unavailable`` response or a
-    :prop:`grpc.StatusCode.UNAVAILABLE` error."""
+    :attr:`grpc.StatusCode.UNAVAILABLE` error."""
     code = http_client.SERVICE_UNAVAILABLE
     grpc_status_code = (
         grpc.StatusCode.UNAVAILABLE if grpc is not None else None)
@@ -320,7 +320,7 @@ class GatewayTimeout(ServerError):
 
 
 class DeadlineExceeded(GatewayTimeout):
-    """Exception mapping a :prop:`grpc.StatusCode.DEADLINE_EXCEEDED` error."""
+    """Exception mapping a :attr:`grpc.StatusCode.DEADLINE_EXCEEDED` error."""
     grpc_status_code = (
         grpc.StatusCode.DEADLINE_EXCEEDED if grpc is not None else None)
 
@@ -332,7 +332,7 @@ def exception_class_for_http_status(status_code):
         status_code (int): The HTTP status code.
 
     Returns:
-        type: the appropriate subclass of :class:`GoogleAPICallError`.
+        :func:`type`: the appropriate subclass of :class:`GoogleAPICallError`.
     """
     return _HTTP_CODE_TO_EXCEPTION.get(status_code, GoogleAPICallError)
 
@@ -395,7 +395,7 @@ def exception_class_for_grpc_status(status_code):
         status_code (grpc.StatusCode): The gRPC status code.
 
     Returns:
-        type: the appropriate subclass of :class:`GoogleAPICallError`.
+        :func:`type`: the appropriate subclass of :class:`GoogleAPICallError`.
     """
     return _GRPC_CODE_TO_EXCEPTION.get(status_code, GoogleAPICallError)
 

core/google/api/core/gapic_v1/config.py

@@ -39,7 +39,7 @@ def _exception_class_for_grpc_status_name(name):
             ``UNAVAILABLE``.
 
     Returns:
-        type: The appropriate subclass of
+        :func:`type`: The appropriate subclass of
             :class:`google.api.core.exceptions.GoogleAPICallError`.
     """
     return exceptions.exception_class_for_grpc_status(

core/google/api/core/operation.py

@@ -57,8 +57,9 @@ class Operation(polling.PollingFuture):
             latest state of the operation.
         cancel (Callable[[], None]): A callable that tries to cancel
             the operation.
-        result_type (type): The protobuf type for the operation's result.
-        metadata_type (type): The protobuf type for the operation's
+        result_type (func:`type`): The protobuf type for the operation's
+            result.
+        metadata_type (func:`type`): The protobuf type for the operation's
             metadata.
     """
 
@@ -200,7 +201,7 @@ def from_http_json(operation, api_request, result_type, **kwargs):
         api_request (Callable): A callable used to make an API request. This
             should generally be
             :meth:`google.cloud._http.Connection.api_request`.
-        result_type (type): The protobuf result type.
+        result_type (:func:`type`): The protobuf result type.
         kwargs: Keyword args passed into the :class:`Operation` constructor.
 
     Returns:
@@ -256,7 +257,7 @@ def from_grpc(operation, operations_stub, result_type, **kwargs):
         operation (google.longrunning.operations_pb2.Operation): The operation.
         operations_stub (google.longrunning.operations_pb2.OperationsStub):
             The operations stub.
-        result_type (type): The protobuf result type.
+        result_type (:func:`type`): The protobuf result type.
         kwargs: Keyword args passed into the :class:`Operation` constructor.
 
     Returns:
@@ -283,7 +284,7 @@ def from_gapic(operation, operations_client, result_type, **kwargs):
         operation (google.longrunning.operations_pb2.Operation): The operation.
         operations_client (google.api.core.operations_v1.OperationsClient):
             The operations client.
-        result_type (type): The protobuf result type.
+        result_type (:func:`type`): The protobuf result type.
         kwargs: Keyword args passed into the :class:`Operation` constructor.
 
     Returns:

core/google/api/core/page_iterator.py

@@ -23,7 +23,7 @@
     https://cloud.google.com/apis/design/design_patterns#list_pagination
 
 API clients that have methods that follow the list pagination pattern can
-return an :class:`Iterator`. You can use this iterator to get **all** of
+return an :class:`.Iterator`. You can use this iterator to get **all** of
 the results across all pages::
 
     >>> results_iterator = client.list_resources()
@@ -88,12 +88,14 @@ class Page(object):
     """Single page of results in an iterator.
 
     Args:
-        parent (Iterator): The iterator that owns the current page.
+        parent (google.api.core.page_iterator.Iterator): The iterator that owns
+            the current page.
         items (Sequence[Any]): An iterable (that also defines __len__) of items
             from a raw API response.
-        item_to_value (Callable[Iterator, Any]): Callable to convert an item
-            from the type in the raw API response into the native object. Will
-            be called with the iterator and a single item.
+        item_to_value (Callable[google.api.core.page_iterator.Iterator, Any]):
+            Callable to convert an item from the type in the raw API response
+            into the native object. Will be called with the iterator and a
+            single item.
     """
 
     def __init__(self, parent, items, item_to_value):
@@ -143,9 +145,10 @@ class Iterator(object):
 
     Args:
         client(google.cloud.client.Client): The API client.
-        item_to_value (Callable[Iterator, Any]): Callable to convert an item
-            from the type in the raw API response into the native object. Will
-            be called with the iterator and a single item.
+        item_to_value (Callable[google.api.core.page_iterator.Iterator, Any]):
+            Callable to convert an item from the type in the raw API response
+            into the native object. Will be called with the iterator and a
+            single item.
         page_token (str): A token identifying a page in a result set to start
             fetching results from.
         max_results (int): The maximum number of results to fetch.
@@ -167,7 +170,8 @@ def pages(self):
         """Iterator of pages in the response.
 
         returns:
-            types.GeneratorType[Page]: A generator of :class:`Page` instances.
+            types.GeneratorType[google.api.core.page_iterator.Page]: A
+                generator of page instances.
 
         raises:
             ValueError: If the iterator has already been started.
@@ -260,20 +264,23 @@ class HTTPIterator(Iterator):
             Generally, this will be
             :meth:`google.cloud._http.JSONConnection.api_request`.
         path (str): The method path to query for the list of items.
-        item_to_value (Callable[Iterator, Any]): Callable to convert an item
-            from the type in the JSON response into a native object. Will
-            be called with the iterator and a single item.
+        item_to_value (Callable[google.api.core.page_iterator.Iterator, Any]):
+            Callable to convert an item from the type in the JSON response into
+            a native object. Will be called with the iterator and a single
+            item.
         items_key (str): The key in the API response where the list of items
             can be found.
         page_token (str): A token identifying a page in a result set to start
             fetching results from.
         max_results (int): The maximum number of results to fetch.
         extra_params (dict): Extra query string parameters for the
             API call.
-        page_start (Callable[Iterator, Page, dict]):  Callable to provide any
-            special behavior after a new page has been created. Assumed
-            signature takes the :class:`Iterator` that started the page,
-            the :class:`Page` that was started and the dictionary containing
+        page_start (Callable[
+            google.api.core.page_iterator.Iterator,
+            google.api.core.page_iterator.Page, dict]): Callable to provide
+            any special behavior after a new page has been created. Assumed
+            signature takes the :class:`.Iterator` that started the page,
+            the :class:`.Page` that was started and the dictionary containing
             the page response.
         next_token (str): The name of the field used in the response for page
             tokens.
@@ -442,8 +449,8 @@ class GRPCIterator(Iterator):
         request (protobuf.Message): The request message.
         items_field (str): The field in the response message that has the
             items for the page.
-        item_to_value (Callable[Iterator, Any]): Callable to convert an item
-            from the type in the JSON response into a native object. Will
+        item_to_value (Callable[GRPCIterator, Any]): Callable to convert an
+            item from the type in the JSON response into a native object. Will
             be called with the iterator and a single item.
         request_token_field (str): The field in the request message used to
             specify the page token.
@@ -479,8 +486,8 @@ def _next_page(self):
         """Get the next page in the iterator.
 
         Returns:
-            Page: The next page in the iterator or :data:`None` if there are no
-                pages left.
+            Page: The next page in the iterator or :data:`None` if
+                there are no pages left.
         """
         if not self._has_next_page():
             return None

core/google/api/core/retry.py

@@ -14,10 +14,10 @@
 
 """Helpers for retrying functions with exponential back-off.
 
-The :cls:`Retry` decorator can be used to retry functions that raise exceptions
-using exponential backoff. Because a exponential sleep algorithm is used,
-the retry is limited by a `deadline`. The deadline is the maxmimum amount of
-time a method can block. This is used instead of total number of retries
+The :class:`Retry` decorator can be used to retry functions that raise
+exceptions using exponential backoff. Because a exponential sleep algorithm is
+used, the retry is limited by a `deadline`. The deadline is the maxmimum amount
+of time a method can block. This is used instead of total number of retries
 because it is difficult to ascertain the amount of time a function can block
 when using total number of retries and exponential backoff.
 
@@ -79,7 +79,8 @@ def if_exception_type(*exception_types):
     """Creates a predicate to check if the exception is of a given type.
 
     Args:
-        exception_types (Sequence[type]): The exception types to check for.
+        exception_types (Sequence[:func:`type`]): The exception types to check
+            for.
 
     Returns:
         Callable[Exception]: A predicate that returns True if the provided
@@ -148,7 +149,7 @@ def retry_target(target, predicate, sleep_generator, deadline, on_error=None):
         predicate (Callable[Exception]): A callable used to determine if an
             exception raised by the target should be considered retryable.
             It should return True to retry or False otherwise.
-        sleep_generator (Iterator[float]): An infinite iterator that determines
+        sleep_generator (Iterable[float]): An infinite iterator that determines
             how long to sleep between retries.
         deadline (float): How long to keep retrying the target.
         on_error (Callable): A function to call while processing a retryable

docs/core/client.rst

@@ -0,0 +1,6 @@
+Base Client
+===========
+
+.. automodule:: google.cloud.client
+  :members:
+  :show-inheritance:

docs/core/config.rst

@@ -58,3 +58,11 @@ using the ``gcloud`` CLI tool to change the configuration.
 .. code-block:: bash
 
     $ gcloud config set project my-new-default-project
+
+
+Environment Variables
+=====================
+
+.. automodule:: google.cloud.environment_vars
+  :members:
+  :show-inheritance:

docs/core/exceptions.rst

@@ -0,0 +1,6 @@
+Exceptions
+==========
+
+.. automodule:: google.api.core.exceptions
+  :members:
+  :show-inheritance:

docs/core/helpers.rst

@@ -0,0 +1,26 @@
+Helpers
+=======
+
+
+General Helpers
+---------------
+
+.. automodule:: google.api.core.general_helpers
+  :members:
+  :show-inheritance:
+
+
+Datetime Helpers
+----------------
+
+.. automodule:: google.api.core.datetime_helpers
+  :members:
+  :show-inheritance:
+
+
+gRPC Helpers
+------------
+
+.. automodule:: google.api.core.grpc_helpers
+  :members:
+  :show-inheritance: