build: fix warnings in docgen (#711)
Resolved all the outstanding warnings from sphinx.
Going forward, warnings will be treated as errors since the `-W` flag is being used with `sphinx-build`
diff --git a/google/auth/crypt/_python_rsa.py b/google/auth/crypt/_python_rsa.py
index e288c50..ec30dd0 100644
--- a/google/auth/crypt/_python_rsa.py
+++ b/google/auth/crypt/_python_rsa.py
@@ -88,7 +88,7 @@
x509 public key certificate.
Returns:
- Verifier: The constructed verifier.
+ google.auth.crypt._python_rsa.RSAVerifier: The constructed verifier.
Raises:
ValueError: If the public_key can't be parsed.
diff --git a/google/auth/transport/_aiohttp_requests.py b/google/auth/transport/_aiohttp_requests.py
index aaf4e2c..4293810 100644
--- a/google/auth/transport/_aiohttp_requests.py
+++ b/google/auth/transport/_aiohttp_requests.py
@@ -131,7 +131,7 @@
credentials.refresh(request)
Args:
- session (aiohttp.ClientSession): An instance :class: aiohttp.ClientSession used
+ session (aiohttp.ClientSession): An instance :class:`aiohttp.ClientSession` used
to make HTTP requests. If not specified, a session will be created.
.. automethod:: __call__
@@ -154,15 +154,17 @@
Args:
url (str): The URL to be requested.
- method (str): The HTTP method to use for the request. Defaults
- to 'GET'.
- body (bytes): The payload / body in HTTP request.
- headers (Mapping[str, str]): Request headers.
+ method (Optional[str]):
+ The HTTP method to use for the request. Defaults to 'GET'.
+ body (Optional[bytes]):
+ The payload or body in HTTP request.
+ headers (Optional[Mapping[str, str]]):
+ Request headers.
timeout (Optional[int]): The number of seconds to wait for a
response from the server. If not specified or if None, the
requests default timeout will be used.
kwargs: Additional arguments passed through to the underlying
- requests :meth:`~requests.Session.request` method.
+ requests :meth:`requests.Session.request` method.
Returns:
google.auth.transport.Response: The HTTP response.
@@ -211,8 +213,8 @@
credentials' headers to the request and refreshing credentials as needed.
Args:
- credentials (google.auth._credentials_async.Credentials): The credentials to
- add to the request.
+ credentials (google.auth._credentials_async.Credentials):
+ The credentials to add to the request.
refresh_status_codes (Sequence[int]): Which HTTP status codes indicate
that credentials should be refreshed and the request should be
retried.
@@ -264,29 +266,26 @@
"""Implementation of Authorized Session aiohttp request.
Args:
- method: The http request method used (e.g. GET, PUT, DELETE)
-
- url: The url at which the http request is sent.
-
- data, headers: These fields parallel the associated data and headers
- fields of a regular http request. Using the aiohttp client session to
- send the http request allows us to use this parallel corresponding structure
- in our Authorized Session class.
-
+ method (str):
+ The http request method used (e.g. GET, PUT, DELETE)
+ url (str):
+ The url at which the http request is sent.
+ data (Optional[dict]): Dictionary, list of tuples, bytes, or file-like
+ object to send in the body of the Request.
+ headers (Optional[dict]): Dictionary of HTTP Headers to send with the
+ Request.
timeout (Optional[Union[float, aiohttp.ClientTimeout]]):
The amount of time in seconds to wait for the server response
- with each individual request.
-
- Can also be passed as an `aiohttp.ClientTimeout` object.
-
+ with each individual request. Can also be passed as an
+ ``aiohttp.ClientTimeout`` object.
max_allowed_time (Optional[float]):
If the method runs longer than this, a ``Timeout`` exception is
- automatically raised. Unlike the ``timeout` parameter, this
+ automatically raised. Unlike the ``timeout`` parameter, this
value applies to the total method execution time, even if
multiple requests are made under the hood.
Mind that it is not guaranteed that the timeout error is raised
- at ``max_allowed_time`. It might take longer, for example, if
+ at ``max_allowed_time``. It might take longer, for example, if
an underlying request takes a lot of time, but the request
itself does not timeout, e.g. if a large file is being
transmitted. The timout error will be raised after such
diff --git a/google/auth/transport/requests.py b/google/auth/transport/requests.py
index ef973fc..d317544 100644
--- a/google/auth/transport/requests.py
+++ b/google/auth/transport/requests.py
@@ -79,7 +79,7 @@
"""A context manager raising an error if the suite execution took too long.
Args:
- timeout ([Union[None, float, Tuple[float, float]]]):
+ timeout (Union[None, Union[float, Tuple[float, float]]]):
The maximum number of seconds a suite can run without the context
manager raising a timeout exception on exit. If passed as a tuple,
the smaller of the values is taken as a timeout. If ``None``, a
@@ -164,7 +164,7 @@
url (str): The URI to be requested.
method (str): The HTTP method to use for the request. Defaults
to 'GET'.
- body (bytes): The payload / body in HTTP request.
+ body (bytes): The payload or body in HTTP request.
headers (Mapping[str, str]): Request headers.
timeout (Optional[int]): The number of seconds to wait for a
response from the server. If not specified or if None, the
@@ -248,21 +248,23 @@
response = authed_session.request(
'GET', 'https://www.googleapis.com/storage/v1/b')
+
The underlying :meth:`request` implementation handles adding the
credentials' headers to the request and refreshing credentials as needed.
This class also supports mutual TLS via :meth:`configure_mtls_channel`
method. In order to use this method, the `GOOGLE_API_USE_CLIENT_CERTIFICATE`
- environment variable must be explicitly set to `true`, otherwise it does
- nothing. Assume the environment is set to `true`, the method behaves in the
+ environment variable must be explicitly set to ``true``, otherwise it does
+ nothing. Assume the environment is set to ``true``, the method behaves in the
following manner:
+
If client_cert_callback is provided, client certificate and private
key are loaded using the callback; if client_cert_callback is None,
application default SSL credentials will be used. Exceptions are raised if
there are problems with the certificate, private key, or the loading process,
so it should be called within a try/except block.
- First we set the environment variable to `true`, then create an :class:`AuthorizedSession`
+ First we set the environment variable to ``true``, then create an :class:`AuthorizedSession`
instance and specify the endpoints::
regular_endpoint = 'https://pubsub.googleapis.com/v1/projects/{my_project_id}/topics'
@@ -291,6 +293,7 @@
else:
response = authed_session.request('GET', regular_endpoint)
+
You can alternatively use application default SSL credentials like this::
try:
@@ -432,19 +435,17 @@
Args:
timeout (Optional[Union[float, Tuple[float, float]]]):
The amount of time in seconds to wait for the server response
- with each individual request.
-
- Can also be passed as a tuple (connect_timeout, read_timeout).
- See :meth:`requests.Session.request` documentation for details.
-
+ with each individual request. Can also be passed as a tuple
+ ``(connect_timeout, read_timeout)``. See :meth:`requests.Session.request`
+ documentation for details.
max_allowed_time (Optional[float]):
If the method runs longer than this, a ``Timeout`` exception is
- automatically raised. Unlike the ``timeout` parameter, this
+ automatically raised. Unlike the ``timeout`` parameter, this
value applies to the total method execution time, even if
multiple requests are made under the hood.
Mind that it is not guaranteed that the timeout error is raised
- at ``max_allowed_time`. It might take longer, for example, if
+ at ``max_allowed_time``. It might take longer, for example, if
an underlying request takes a lot of time, but the request
itself does not timeout, e.g. if a large file is being
transmitted. The timout error will be raised after such
diff --git a/google/oauth2/_service_account_async.py b/google/oauth2/_service_account_async.py
index 0a4e724..cfd315a 100644
--- a/google/oauth2/_service_account_async.py
+++ b/google/oauth2/_service_account_async.py
@@ -112,7 +112,7 @@
'service-account.json',
scopes=['email'],
subject='user@example.com'))
-`
+
The credentials are considered immutable. If you want to modify the scopes
or the subject used for delegation, use :meth:`with_scopes` or
:meth:`with_subject`::
diff --git a/google/oauth2/id_token.py b/google/oauth2/id_token.py
index d70782b..5e36260 100644
--- a/google/oauth2/id_token.py
+++ b/google/oauth2/id_token.py
@@ -50,7 +50,7 @@
cached_session = cachecontrol.CacheControl(session)
request = google.auth.transport.requests.Request(session=cached_session)
-.. _OpenID Connect ID Token:
+.. _OpenID Connect ID Tokens:
http://openid.net/specs/openid-connect-core-1_0.html#IDToken
.. _CacheControl: https://cachecontrol.readthedocs.io
"""
diff --git a/google/oauth2/service_account.py b/google/oauth2/service_account.py
index ed91011..1ccfa19 100644
--- a/google/oauth2/service_account.py
+++ b/google/oauth2/service_account.py
@@ -424,6 +424,7 @@
service_account.IDTokenCredentials.from_service_account_file(
'service-account.json'))
+
Or if you already have the service account file loaded::
service_account_info = json.load(open('service_account.json'))
@@ -431,6 +432,7 @@
service_account.IDTokenCredentials.from_service_account_info(
service_account_info))
+
Both helper methods pass on arguments to the constructor, so you can
specify additional scopes and a subject if necessary::
@@ -439,7 +441,8 @@
'service-account.json',
scopes=['email'],
subject='user@example.com'))
-`
+
+
The credentials are considered immutable. If you want to modify the scopes
or the subject used for delegation, use :meth:`with_scopes` or
:meth:`with_subject`::
diff --git a/google/oauth2/utils.py b/google/oauth2/utils.py
index efda796..593f032 100644
--- a/google/oauth2/utils.py
+++ b/google/oauth2/utils.py
@@ -101,7 +101,7 @@
Args:
headers (Mapping[str, str]): The HTTP request header.
- request_body (Optional[Mapping[str, str]): The HTTP request body
+ request_body (Optional[Mapping[str, str]]): The HTTP request body
dictionary. For requests that do not support request body, this
is None and will be ignored.
bearer_token (Optional[str]): The optional bearer token.