docstring cleanup and class reference simplification (#52)

Author: mattsb42-aws

doc/conf.py

@@ -64,7 +64,7 @@ def get_version():
 htmlhelp_basename = '%sdoc' % project
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+intersphinx_mapping = {'python': ('http://docs.python.org/', None)}
 
 # autosummary
 autosummary_generate = True

doc/index.rst

@@ -12,6 +12,7 @@ Modules
     dynamodb_encryption_sdk.exceptions
     dynamodb_encryption_sdk.identifiers
     dynamodb_encryption_sdk.structures
+    dynamodb_encryption_sdk.transform
     dynamodb_encryption_sdk.delegated_keys
     dynamodb_encryption_sdk.delegated_keys.jce
     dynamodb_encryption_sdk.encrypted
@@ -44,7 +45,6 @@ Modules
     dynamodb_encryption_sdk.internal.crypto.jce_bridge.primitives
     dynamodb_encryption_sdk.internal.formatting
     dynamodb_encryption_sdk.internal.formatting.material_description
-    dynamodb_encryption_sdk.internal.formatting.transform
     dynamodb_encryption_sdk.internal.formatting.deserialize
     dynamodb_encryption_sdk.internal.formatting.deserialize.attribute
     dynamodb_encryption_sdk.internal.formatting.serialize

src/dynamodb_encryption_sdk/delegated_keys/__init__.py

@@ -26,7 +26,7 @@
 
 
 def _raise_not_implemented(method_name):
-    """Raises a standardized ``NotImplementedError`` to report that the specified method
+    """Raises a standardized :class:`NotImplementedError` to report that the specified method
     is not supported.
 
     :raises NotImplementedError: when called
@@ -40,7 +40,7 @@ class DelegatedKey(object):
     and unwrap keys. Not all delegated keys implement all methods.
 
     Unless overridden by a subclass, any method that a delegated key does not implement raises
-    a ``NotImplementedError`` detailing this.
+    a :class:`NotImplementedError` detailing this.
     """
 
     @abc.abstractproperty
@@ -51,7 +51,8 @@ def algorithm(self):
     @property
     def allowed_for_raw_materials(self):
         # type: () -> bool
-        """Most delegated keys should not be used with RawCryptographicMaterials.
+        """Most delegated keys should not be used with :class:`RawDecryptionMaterials` or
+        :class:`RawEncryptionMaterials`.
 
         :returns: False
         :rtype: bool
@@ -62,12 +63,12 @@ def allowed_for_raw_materials(self):
     def generate(cls, algorithm, key_length):  # type: ignore
         # type: (Text, int) -> DelegatedKey
         # pylint: disable=unused-argument,no-self-use
-        """Generate an instance of this DelegatedKey using the specified algorithm and key length.
+        """Generate an instance of this :class:`DelegatedKey` using the specified algorithm and key length.
 
         :param str algorithm: Text description of algorithm to be used
         :param int key_length: Size of key to generate
         :returns: Generated delegated key
-        :rtype: dynamodb_encryption_sdk.delegated_keys.DelegatedKey
+        :rtype: DelegatedKey
         """
         _raise_not_implemented('generate')
 
@@ -130,12 +131,11 @@ def unwrap(  # type: ignore
         :param str algorithm: Text description of algorithm to use to unwrap key
         :param bytes content_key: Raw content key to wrap
         :param str wrapped_key_algorithm: Text description of algorithm for unwrapped key to use
-        :param wrapped_key_type: Type of key to treat key as once unwrapped
-        :type wrapped_key_type: dynamodb_encryption_sdk.identifiers.EncryptionKeyType
+        :param EncryptionKeyType wrapped_key_type: Type of key to treat key as once unwrapped
         :param dict additional_associated_data: Not used by all delegated keys, but if it
             is, then if it is provided on wrap it must be required on unwrap.
         :returns: Delegated key using unwrapped key
-        :rtype: dynamodb_encryption_sdk.delegated_keys.DelegatedKey
+        :rtype: DelegatedKey
         """
         _raise_not_implemented('unwrap')
 
@@ -166,9 +166,9 @@ def signing_algorithm(self):  # type: ignore
         # type: () -> Text
         # pylint: disable=no-self-use
         """Provide a description that can inform an appropriate cryptographic materials
-        provider about how to build a DelegatedKey for signature verification. If implemented,
-        the return value of this method is included in the material description written to
-        the encrypted item.
+        provider about how to build a :class:`DelegatedKey` for signature verification.
+        If implemented, the return value of this method is included in the material description
+        written to the encrypted item.
 
         :returns: Signing algorithm identifier
         :rtype: str

src/dynamodb_encryption_sdk/delegated_keys/jce.py

@@ -42,7 +42,7 @@ def _generate_symmetric_key(key_length):
 
     :param int key_length: Required key length in bits
     :returns: raw key, symmetric key identifier, and RAW encoding identifier
-    :rtype: tuple of bytes, EncryptionKeyType, and KeyEncodingType
+    :rtype: tuple(bytes, :class:`EncryptionKeyType`, :class:`KeyEncodingType`)
     """
     return os.urandom(key_length // 8), EncryptionKeyType.SYMMETRIC, KeyEncodingType.RAW
 
@@ -52,7 +52,7 @@ def _generate_rsa_key(key_length):
 
     :param int key_length: Required key length in bits
     :returns: DER-encoded private key, private key identifier, and DER encoding identifier
-    :rtype: tuple of bytes, EncryptionKeyType, and KeyEncodingType
+    :rtype: tuple(bytes, :class:`EncryptionKeyType`, :class:`KeyEncodingType`)
     """
     private_key = rsa.generate_private_key(
         public_exponent=65537,
@@ -109,10 +109,8 @@ class JceNameLocalDelegatedKey(DelegatedKey):
 
     :param bytes key: Raw key bytes
     :param str algorithm: JCE Standard Algorithm Name
-    :param key_type: Identifies what type of key is being provided
-    :type key_type: dynamodb_encryption_sdk.identifiers.EncryptionKeyType
-    :param key_encoding: Identifies how the provided key is encoded
-    :type key_encoding: dynamodb_encryption_sdk.identifiers.KeyEncodingTypes
+    :param EncryptionKeyType key_type: Identifies what type of key is being provided
+    :param KeyEncodingType key_encoding: Identifies how the provided key is encoded
     """
 
     key = attr.ib(validator=attr.validators.instance_of(bytes), repr=False)
@@ -204,12 +202,13 @@ def __attrs_post_init__(self):
     @classmethod
     def generate(cls, algorithm, key_length=None):
         # type: (Text, Optional[int]) -> JceNameLocalDelegatedKey
-        """Generate an instance of this DelegatedKey using the specified algorithm and key length.
+        """Generate an instance of this :class:`DelegatedKey` using the specified algorithm
+        and key length.
 
         :param str algorithm: Text description of algorithm to be used
         :param int key_length: Size in bits of key to generate
         :returns: Generated delegated key
-        :rtype: dynamodb_encryption_sdk.delegated_keys.DelegatedKey
+        :rtype: DelegatedKey
         """
         # Normalize to allow generating both encryption and signing keys
         algorithm_lookup = algorithm.upper()
@@ -229,8 +228,8 @@ def generate(cls, algorithm, key_length=None):
     @property
     def allowed_for_raw_materials(self):
         # type: () -> bool
-        """Only ``JceNameLocalDelegatedKey`` backed by AES keys are allowed to be used with
-        ``RawCryptographicMaterials``.
+        """Only :class:`JceNameLocalDelegatedKey` backed by AES keys are allowed to be used
+        with :class:`RawDecryptionMaterials` or :class:`RawEncryptionMaterials`.
 
         :returns: decision
         :rtype: bool
@@ -264,7 +263,7 @@ def _decrypt(self, algorithm, name, ciphertext, additional_associated_data=None)
             https://docs.oracle.com/javase/8/docs/api/javax/crypto/Cipher.html
         :param str name: Name associated with ciphertext data
         :param bytes ciphertext: Ciphertext data to decrypt
-        :param dict additional_associated_data: Not used by ``JceNameLocalDelegatedKey``
+        :param dict additional_associated_data: Not used by :class:`JceNameLocalDelegatedKey`
         :returns: Decrypted plaintext
         :rtype: bytes
         """
@@ -278,7 +277,7 @@ def _wrap(self, algorithm, content_key, additional_associated_data=None):
 
         :param str algorithm: Text description of algorithm to use to wrap key
         :param bytes content_key: Raw content key to wrap
-        :param dict additional_associated_data: Not used by ``JceNameLocalDelegatedKey``
+        :param dict additional_associated_data: Not used by :class:`JceNameLocalDelegatedKey`
         :returns: Wrapped key
         :rtype: bytes
         """
@@ -296,11 +295,10 @@ def _unwrap(self, algorithm, wrapped_key, wrapped_key_algorithm, wrapped_key_typ
         :param str algorithm: Text description of algorithm to use to unwrap key
         :param bytes content_key: Raw content key to wrap
         :param str wrapped_key_algorithm: Text description of algorithm for unwrapped key to use
-        :param wrapped_key_type: Type of key to treat key as once unwrapped
-        :type wrapped_key_type: dynamodb_encryption_sdk.identifiers.EncryptionKeyType
-        :param dict additional_associated_data: Not used by ``JceNameLocalDelegatedKey``
+        :param EncryptionKeyType wrapped_key_type: Type of key to treat key as once unwrapped
+        :param dict additional_associated_data: Not used by :class:`JceNameLocalDelegatedKey`
         :returns: Delegated key using unwrapped key
-        :rtype: dynamodb_encryption_sdk.delegated_keys.DelegatedKey
+        :rtype: DelegatedKey
         """
         if wrapped_key_type is not EncryptionKeyType.SYMMETRIC:
             raise UnwrappingError('Unsupported wrapped key type: "{}"'.format(wrapped_key_type))

src/dynamodb_encryption_sdk/encrypted/__init__.py

@@ -24,7 +24,7 @@
 from dynamodb_encryption_sdk.exceptions import InvalidArgumentError
 from dynamodb_encryption_sdk.identifiers import CryptoAction
 from dynamodb_encryption_sdk.material_providers import CryptographicMaterialsProvider
-from dynamodb_encryption_sdk.materials import DecryptionMaterials, EncryptionMaterials  # noqa pylint: disable=unused-import
+from dynamodb_encryption_sdk.materials import CryptographicMaterials  # noqa pylint: disable=unused-import
 from dynamodb_encryption_sdk.structures import AttributeActions, EncryptionContext
 
 __all__ = ('CryptoConfig',)
@@ -34,12 +34,12 @@
 class CryptoConfig(object):
     """Container for all configuration needed to encrypt or decrypt an item.
 
-    :param materials_provider: Cryptographic materials provider to use
-    :type materials_provider: dynamodb_encryption_sdk.material_providers.CryptographicMaterialsProvider
-    :param encryption_context: Context data describing what is being encrypted or decrypted.
-    :type encryption_context: dynamodb_encryption_sdk.structures.EncryptionContext
-    :param attribute_actions: Description of what action should be taken for each attribute
-    :type attribute_actions: dynamodb_encryption_sdk.structures.AttributeActions
+    :param CryptographicMaterialsProvider materials_provider: Cryptographic materials provider
+        to use
+    :param EncryptionContext encryption_context: Context data describing what is being encrypted
+        or decrypted
+    :param AttributeActions attribute_actions: Description of what action should be taken
+        for each attribute
     """
 
     materials_provider = attr.ib(validator=attr.validators.instance_of(CryptographicMaterialsProvider))
@@ -75,28 +75,28 @@ def __attrs_post_init__(self):
                 raise InvalidArgumentError('Cannot encrypt sort key')
 
     def decryption_materials(self):
-        # type: () -> DecryptionMaterials
+        # type: () -> CryptographicMaterials
         """Load decryption materials from instance resources.
 
         :returns: Decryption materials
-        :rtype: dynamodb_encryption_sdk.materials.DecryptionMaterials
+        :rtype: CryptographicMaterials
         """
         return self.materials_provider.decryption_materials(self.encryption_context)
 
     def encryption_materials(self):
-        # type: () -> EncryptionMaterials
+        # type: () -> CryptographicMaterials
         """Load encryption materials from instance resources.
 
         :returns: Encryption materials
-        :rtype: dynamodb_encryption_sdk.materials.EncryptionMaterials
+        :rtype: CryptographicMaterials
         """
         return self.materials_provider.encryption_materials(self.encryption_context)
 
     def copy(self):
         # type: () -> CryptoConfig
         """Return a copy of this instance with a copied instance of its encryption context.
 
-        :returns: New CryptoConfig identical to this one
+        :returns: New :class:`CryptoConfig` identical to this one
         :rtype: CryptoConfig
         """
         return CryptoConfig(

src/dynamodb_encryption_sdk/encrypted/client.py

@@ -33,7 +33,7 @@
 from dynamodb_encryption_sdk.structures import AttributeActions
 from .item import decrypt_dynamodb_item, decrypt_python_item, encrypt_dynamodb_item, encrypt_python_item
 
-__all__ = ('EncryptedClient',)
+__all__ = ('EncryptedClient', 'EncryptedPaginator')
 
 
 @attr.s(init=False)
@@ -42,8 +42,8 @@ class EncryptedPaginator(object):
 
     :param paginator: Pre-configured boto3 DynamoDB paginator object
     :type paginator: botocore.paginate.Paginator
-    :param decrypt_method: Item decryptor method from ``dynamodb_encryption_sdk.encrypted.item``
-    :param callable crypto_config_method: Callable that returns a crypto config
+    :param decrypt_method: Item decryptor method from :mod:`dynamodb_encryption_sdk.encrypted.item`
+    :param callable crypto_config_method: Callable that returns a :class:`CryptoConfig`
     """
 
     _paginator = attr.ib(validator=attr.validators.instance_of(botocore.paginate.Paginator))
@@ -130,7 +130,7 @@ class EncryptedClient(object):
 
         If you want to provide per-request cryptographic details, the ``put_item``, ``get_item``,
         ``query``, ``scan``, ``batch_write_item``, and ``batch_get_item`` methods will also
-        accept a ``crypto_config`` parameter, defining a custom ``CryptoConfig`` instance
+        accept a ``crypto_config`` parameter, defining a custom :class:`CryptoConfig` instance
         for this request.
 
     .. warning::
@@ -139,10 +139,10 @@ class EncryptedClient(object):
 
     :param table: Pre-configured boto3 DynamoDB client object
     :type table: boto3.resources.base.BaseClient
-    :param materials_provider: Cryptographic materials provider to use
-    :type materials_provider: dynamodb_encryption_sdk.material_providers.CryptographicMaterialsProvider
-    :param attribute_actions: Table-level configuration of how to encrypt/sign attributes
-    :type attribute_actions: dynamodb_encryption_sdk.structures.AttributeActions
+    :param CryptographicMaterialsProvider materials_provider: Cryptographic materials provider
+        to use
+    :param AttributeActions attribute_actions: Table-level configuration of how to encrypt/sign
+        attributes
     :param bool auto_refresh_table_indexes: Should we attempt to refresh information about table indexes?
         Requires ``dynamodb:DescribeTable`` permissions on each table. (default: True)
     :param bool expect_standard_dictionaries: Should we expect items to be standard Python
@@ -259,7 +259,10 @@ def __getattr__(self, name):
         return getattr(self._client, name)
 
     def update_item(self, **kwargs):
-        """Update item is not yet supported."""
+        """Update item is not yet supported.
+
+        :raises NotImplementedError: if called
+        """
         raise NotImplementedError('"update_item" is not yet implemented')
 
     def get_paginator(self, operation_name):
@@ -268,7 +271,7 @@ def get_paginator(self, operation_name):
 
         :param str operation_name: Name of operation for which to get paginator
         :returns: Paginator for name
-        :rtype: Paginator or EncryptedPaginator
+        :rtype: :class:`botocore.paginate.Paginator` or :class:`EncryptedPaginator`
         """
         paginator = self._client.get_paginator(operation_name)
 

src/dynamodb_encryption_sdk/encrypted/item.py

@@ -42,8 +42,7 @@ def encrypt_dynamodb_item(item, crypto_config):
         This handles DynamoDB-formatted items and is for use with the boto3 DynamoDB client.
 
     :param dict item: Plaintext DynamoDB item
-    :param crypto_config: Cryptographic configuration
-    :type crypto_config: dynamodb_encryption_sdk.encrypted.CryptoConfig
+    :param CryptoConfig crypto_config: Cryptographic configuration
     :returns: Encrypted and signed DynamoDB item
     :rtype: dict
     """
@@ -118,8 +117,7 @@ def encrypt_python_item(item, crypto_config):
         This handles human-friendly dictionaries and is for use with the boto3 DynamoDB service or table resource.
 
     :param dict item: Plaintext dictionary
-    :param crypto_config: Cryptographic configuration
-    :type crypto_config: dynamodb_encryption_sdk.encrypted.CryptoConfig
+    :param CryptoConfig crypto_config: Cryptographic configuration
     :returns: Encrypted and signed dictionary
     :rtype: dict
     """
@@ -137,8 +135,7 @@ def decrypt_dynamodb_item(item, crypto_config):
         This handles DynamoDB-formatted items and is for use with the boto3 DynamoDB client.
 
     :param dict item: Encrypted and signed DynamoDB item
-    :param crypto_config: Cryptographic configuration
-    :type crypto_config: dynamodb_encryption_sdk.encrypted.CryptoConfig
+    :param CryptoConfig crypto_config: Cryptographic configuration
     :returns: Plaintext DynamoDB item
     :rtype: dict
     """
@@ -212,8 +209,7 @@ def decrypt_python_item(item, crypto_config):
         This handles human-friendly dictionaries and is for use with the boto3 DynamoDB service or table resource.
 
     :param dict item: Encrypted and signed dictionary
-    :param crypto_config: Cryptographic configuration
-    :type crypto_config: dynamodb_encryption_sdk.encrypted.CryptoConfig
+    :param CryptoConfig crypto_config: Cryptographic configuration
     :returns: Plaintext dictionary
     :rtype: dict
     """