Fixing various docstrings

google/auth/exceptions.py

@@ -19,7 +19,7 @@ class GoogleAuthError(Exception):
     """Base class for all google.auth errors."""
 
 
-class TransportError(Exception):
+class TransportError(GoogleAuthError):
     """Used to indicate an error occurred during an HTTP request."""
 
 

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 @@ def encode(signer, payload, header=None, key_id=None):
 
     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 decode_header(token):
 
 
 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 @@ def decode(token, certs=None, verify=True, audience=None):
     """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.

google/auth/transport/__init__.py

@@ -40,7 +40,7 @@ def status(self):
 
     @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 @@ class Request(object):
 
     Specific transport implementations should provide an implementation of
     this that adapts their specific request / response API.
+
+    .. automethod:: __call__
     """
 
     @abc.abstractmethod
@@ -67,8 +69,8 @@ def __call__(self, url, method='GET', body=None, headers=None,
             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

google/auth/transport/urllib3.py

@@ -53,9 +53,11 @@ class Request(transport.Request):
     """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 @@ def __call__(self, url, method='GET', body=None, headers=None,
             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