Refactor examples into sub-module (#163)

This lets us use the examples during release validation -- simply update
the dynamodb-encryption-sdk dependency to point to the specific version we
want to validate.

Author: farleyb-amazon

examples/README.md

@@ -0,0 +1,33 @@
+# AWS DynamoDB Encryption Client Examples
+
+This section features examples that show you
+how to use the AWS DynamoDB Encryption Client.
+We demonstrate how to use the encryption and decryption APIs
+and how to set up some common configuration patterns.
+
+## APIs
+
+The AWS DynamoDB Encryption Client provides four high-level APIs: `EncryptedClient`, `EncryptedItem`,
+`EncryptedResource`, and `EncryptedTable`.
+
+You can find examples that demonstrate these APIs
+in the [`examples/src/dynamodb_encryption_sdk_examples`](./src/dynamodb_encryption_sdk_examples) directory. 
+Each of these examples uses AWS KMS as the materials provider.
+
+* [How to use the EncryptedClient API](./src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_client.py)
+* [How to use the EncryptedItem API](./src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_item.py)
+* [How to use the EncryptedResource API](./src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_resource.py)
+* [How to use the EncryptedTable API](./src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_table.py)
+
+## Material Providers
+
+To use the encryption and decryption APIs, you need to describe how you want the library to protect your data keys.
+You can do this by configuring material providers. AWS KMS is the most common material provider used with the AWS DynamoDB Encryption
+SDK, and each of the API examples above uses AWS KMS. This section describes the other providers that come bundled
+with this library.
+
+* [How to use the CachingMostRecentProvider](./src/dynamodb_encryption_sdk_examples/most_recent_provider_encrypted_table.py)
+* [How to use raw symmetric wrapping keys](./src/dynamodb_encryption_sdk_examples/wrapped_symmetric_encrypted_table.py)
+* [How to use raw asymmetric wrapping keys](./src/dynamodb_encryption_sdk_examples/wrapped_rsa_encrypted_table.py)
+
+For more details on the different type of material providers, see [How to choose a cryptographic materials provider](https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/crypto-materials-providers.html).

examples/requirements.txt

@@ -0,0 +1 @@
+dynamodb-encryption-sdk

examples/setup.py

@@ -0,0 +1,62 @@
+"""DynamoDB Encryption Client for Python examples."""
+import io
+import os
+import re
+
+from setuptools import find_packages, setup
+
+VERSION_RE = re.compile(r"""__version__ = ['"]([0-9.]+)['"]""")
+HERE = os.path.abspath(os.path.dirname(__file__))
+
+
+def read(*args):
+    """Reads complete file contents."""
+    return io.open(os.path.join(HERE, *args), encoding="utf-8").read()
+
+
+def get_version():
+    """Reads the version from this module."""
+    init = read("src", "dynamodb_encryption_sdk_examples", "__init__.py")
+    return VERSION_RE.search(init).group(1)
+
+
+def get_requirements():
+    """Reads the requirements file."""
+    requirements = read("requirements.txt")
+    return requirements.strip().splitlines()
+
+
+setup(
+    name="dynamodb-encryption-sdk-examples",
+    version=get_version(),
+    packages=find_packages("src"),
+    package_dir={"": "src"},
+    url="https://github.com/aws/aws-dynamodb-encryption-python",
+    author="Amazon Web Services",
+    author_email="[email protected]",
+    maintainer="Amazon Web Services",
+    description="DynamoDB Encryption Client for Python examples",
+    long_description=read("README.rst"),
+    keywords="dynamodb-encryption-sdk aws kms encryption dynamodb",
+    data_files=["requirements.txt"],
+    license="Apache License 2.0",
+    install_requires=get_requirements(),
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "Natural Language :: English",
+        "License :: OSI Approved :: Apache Software License",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 2",
+        "Programming Language :: Python :: 2.7",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.5",
+        "Programming Language :: Python :: 3.6",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: Implementation :: CPython",
+        "Topic :: Security",
+        "Topic :: Security :: Cryptography",
+    ],
+)

examples/src/__init__.py renamed to examples/src/dynamodb_encryption_sdk_examples/__init__.py

@@ -11,3 +11,4 @@
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
 """Stub module indicator to make linter configuration simpler."""
+__version__ = "1.0.0"