Fixing various docstrings
diff --git a/google/auth/exceptions.py b/google/auth/exceptions.py
index dedde9e..2be9fd6 100644
--- a/google/auth/exceptions.py
+++ b/google/auth/exceptions.py
@@ -19,7 +19,7 @@
"""Base class for all google.auth errors."""
-class TransportError(Exception):
+class TransportError(GoogleAuthError):
"""Used to indicate an error occurred during an HTTP request."""
diff --git a/google/auth/jwt.py b/google/auth/jwt.py
index 5349e29..f68fc4b 100644
--- a/google/auth/jwt.py
+++ b/google/auth/jwt.py
@@ -19,7 +19,7 @@
See `rfc7519`_ for more details on JWTs.
-To encode a JWT::
+To encode a JWT use :func:`encode`::
from google.auth import crypto
from google.auth import jwt
@@ -28,7 +28,7 @@
payload = {'some': 'payload'}
encoded = jwt.encode(signer, payload)
-To decode a JWT and verify claims::
+To decode a JWT and verify claims use :func:`decode`::
claims = jwt.decode(encoded, certs=public_certs)
@@ -57,8 +57,8 @@
Args:
signer (google.auth.crypt.Signer): The signer used to sign the JWT.
- payload (Mapping): The JWT payload.
- header (Mapping): Additional JWT header payload.
+ payload (Mapping[str, str]): The JWT payload.
+ header (Mapping[str, str]): Additional JWT header payload.
key_id (str): The key id to add to the JWT header. If the
signer has a key id it will be used as the default. If this is
specified it will override the signer's key id.
@@ -146,11 +146,11 @@
def _verify_iat_and_exp(payload):
- """Verifies the iat (Issued At) and exp (Expires) claims in a token
+ """Verifies the ``iat`` (Issued At) and ``exp`` (Expires) claims in a token
payload.
Args:
- payload (mapping): The JWT payload.
+ payload (Mapping[str, str]): The JWT payload.
Raises:
ValueError: if any checks failed.
@@ -180,19 +180,20 @@
"""Decode and verify a JWT.
Args:
- token (string): The encoded JWT.
- certs (Union[str, bytes, Mapping]): The certificate used to
- validate. If bytes or string, it must the the public key
- certificate in PEM format. If a mapping, it must be a mapping of
- key IDs to public key certificates in PEM format. The mapping must
- contain the same key ID that's specified in the token's header.
+ token (str): The encoded JWT.
+ certs (Union[str, bytes, Mapping[str, Union[str, bytes]]]): The
+ certificate used to validate the JWT signatyre. If bytes or string,
+ it must the the public key certificate in PEM format. If a mapping,
+ it must be a mapping of key IDs to public key certificates in PEM
+ format. The mapping must contain the same key ID that's specified
+ in the token's header.
verify (bool): Whether to perform signature and claim validation.
Verification is done by default.
audience (str): The audience claim, 'aud', that this JWT should
contain. If None then the JWT's 'aud' parameter is not verified.
Returns:
- Mapping: The deserialized JSON payload in the JWT.
+ Mapping[str, str]: The deserialized JSON payload in the JWT.
Raises:
ValueError: if any verification checks failed.
diff --git a/google/auth/transport/__init__.py b/google/auth/transport/__init__.py
index 32de8f1..50b1c43 100644
--- a/google/auth/transport/__init__.py
+++ b/google/auth/transport/__init__.py
@@ -40,7 +40,7 @@
@abc.abstractproperty
def headers(self):
- """Mapping: The HTTP response headers."""
+ """Mapping[str, str]: The HTTP response headers."""
raise NotImplementedError('headers must be implemented.')
@abc.abstractproperty
@@ -55,6 +55,8 @@
Specific transport implementations should provide an implementation of
this that adapts their specific request / response API.
+
+ .. automethod:: __call__
"""
@abc.abstractmethod
@@ -67,8 +69,8 @@
method (str): The HTTP method to use for the request. Defaults
to 'GET'.
body (bytes): The payload / body in HTTP request.
- headers (Mapping): Request headers.
- timeout (Optional(int)): The number of seconds to wait for a
+ 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
transport-specific default timeout will be used.
kwargs: Additionally arguments passed on to the transport's
diff --git a/google/auth/transport/urllib3.py b/google/auth/transport/urllib3.py
index 9fc58f3..be6e55b 100644
--- a/google/auth/transport/urllib3.py
+++ b/google/auth/transport/urllib3.py
@@ -53,9 +53,11 @@
"""urllib3 request adapter
Args:
- http (urllib3.requests.RequestMethods): An instance of any urllib3
- class that implements :class:`~urllib3.requests.RequestMethods`,
+ http (urllib3.request.RequestMethods): An instance of any urllib3
+ class that implements :class:`~urllib3.request.RequestMethods`,
usually :class:`urllib3.PoolManager`.
+
+ .. automethod:: __call__
"""
def __init__(self, http):
self.http = http
@@ -69,8 +71,8 @@
method (str): The HTTP method to use for the request. Defaults
to 'GET'.
body (bytes): The payload / body in HTTP request.
- headers (Mapping): Request headers.
- timeout (Optional(int)): The number of seconds to wait for a
+ 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
urllib3 default timeout will be used.
kwargs: Additional arguments passed throught to the underlying