sync

Author: Lucas McDonald

DynamoDbEncryption/runtimes/python/src/aws_dbesdk_dynamodb/encrypted/client.py

@@ -44,23 +44,25 @@ class EncryptedClient(EncryptedBotoInterface):
     drop-in replacement that transparently handles encryption and decryption of items.
 
     The API matches the standard boto3 DynamoDB client interface:
+
     https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#client
 
     This class will encrypt/decrypt items for the following operations:
-        * put_item
-        * get_item
-        * query
-        * scan
-        * batch_write_item
-        * batch_get_item
-        * transact_get_items
-        * transact_write_items
 
-    The update_item operation is not currently supported. Calling this operation will raise NotImplementedError.
+        * ``put_item``
+        * ``get_item``
+        * ``query``
+        * ``scan``
+        * ``batch_write_item``
+        * ``batch_get_item``
+        * ``transact_get_items``
+        * ``transact_write_items``
+
+    The ``update_item`` operation is not currently supported. Calling this operation will raise ``NotImplementedError``.
 
     Any other operations on this class will defer to the underlying boto3 DynamoDB client's implementation.
 
-    EncryptedClient can also return an EncryptedPaginator for transparent decryption of paginated results.
+    ``EncryptedClient`` can also return an ``EncryptedPaginator`` for transparent decryption of paginated results.
     """
 
     _client: botocore.client.BaseClient
@@ -76,15 +78,15 @@ def __init__(
         expect_standard_dictionaries: bool | None = False,
     ):
         """
-        Create an EncryptedClient object.
+        Create an ``EncryptedClient`` object.
 
         Args:
             client (botocore.client.BaseClient): Initialized boto3 DynamoDB client
             encryption_config (DynamoDbTablesEncryptionConfig): Initialized DynamoDbTablesEncryptionConfig
             expect_standard_dictionaries (Optional[bool]): Does the underlying boto3 client expect items
                 to be standard Python dictionaries? This should only be set to True if you are using a
-                client obtained from a service resource or table resource (ex: `table.meta.client`).
-                If this is True, EncryptedClient will expect item-like shapes to be
+                client obtained from a service resource or table resource (ex: ``table.meta.client``).
+                If this is True, ``EncryptedClient`` will expect item-like shapes to be
                 standard Python dictionaries (default: False).
 
         """
@@ -99,15 +101,16 @@ def put_item(self, **kwargs) -> dict[str, Any]:
         """
         Put a single item to a table. Encrypts the item before writing to DynamoDB.
 
-        The parameters and return value match the boto3 DynamoDB put_item API:
+        The input and output syntaxes match those for the boto3 DynamoDB ``put_item`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/put_item.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 put_item API parameters.
-                The "Item" argument will be encrypted locally before being written to DynamoDB.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 ``put_item`` request syntax.
+                The value in ``"Item"`` will be encrypted locally before being written to DynamoDB.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 put_item API response.
+            dict: The response from DynamoDB. This matches the boto3 ``put_item`` response syntax.
 
         """
         return self._client_operation_logic(
@@ -127,15 +130,16 @@ def get_item(self, **kwargs) -> dict[str, Any]:
         """
         Get a single item from a table. Decrypts the item after reading from DynamoDB.
 
-        The parameters and return value match the boto3 DynamoDB get_item API:
+        The input and output syntaxes match those for the boto3 DynamoDB ``get_item`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/get_item.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 get_item API parameters.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 ``get_item`` request syntax.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 get_item API response.
-                The "Item" field will be decrypted locally after being read from DynamoDB.
+            dict: The response from DynamoDB. This matches the boto3 ``get_item`` response syntax.
+            The value in ``"Item"`` field be decrypted locally after being read from DynamoDB.
 
         """
         return self._client_operation_logic(
@@ -156,6 +160,7 @@ def query(self, **kwargs) -> dict[str, Any]:
         Query items from a table or index. Decrypts any returned items.
 
         The parameters and return value match the boto3 DynamoDB query API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/query.html
 
         Args:
@@ -183,15 +188,16 @@ def scan(self, **kwargs) -> dict[str, Any]:
         """
         Scan an entire table or index. Decrypts any returned items.
 
-        The parameters and return value match the boto3 DynamoDB scan API:
+        The input and output syntaxes match those for the boto3 DynamoDB ``scan`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/scan.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 scan API parameters.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 ``scan`` request syntax.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 scan API response.
-                The "Items" field will be decrypted locally after being read from DynamoDB.
+            dict: The response from DynamoDB. This matches the boto3 ``scan`` response syntax.
+            The values in ``"Items"`` will be decrypted locally after being read from DynamoDB.
 
         """
         return self._client_operation_logic(
@@ -213,16 +219,17 @@ def batch_write_item(self, **kwargs) -> dict[str, Any]:
 
         For put operations, encrypts items before writing.
 
-        The parameters and return value match the boto3 DynamoDB batch_write_item API:
+        The input and output syntaxes match those for the boto3 DynamoDB ``batch_write_item`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/batch_write_item.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 batch_write_item API parameters.
-                Any put operations in the "RequestItems" argument will be encrypted locally
-                before being written to DynamoDB.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 ``batch_write_item``
+                request syntax. Items in ``"PutRequest"`` values in the ``"RequestItems"`` argument will be encrypted
+                locally before being written to DynamoDB.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 batch_write_item API response.
+            dict: The response from DynamoDB. This matches the boto3 ``batch_write_item`` response syntax.
 
         """
         return self._client_operation_logic(
@@ -242,15 +249,17 @@ def batch_get_item(self, **kwargs) -> dict[str, Any]:
         """
         Get multiple items from one or more tables. Decrypts any returned items.
 
-        The parameters and return value match the boto3 DynamoDB batch_get_item API:
+        The input and output syntaxes match those for the boto3 DynamoDB ``batch_get_item`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/batch_get_item.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 batch_get_item API parameters.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 ``batch_get_item``
+                request syntax.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 batch_get_item API response.
-                The "Responses" field will be decrypted locally after being read from DynamoDB.
+            dict: The response from DynamoDB. This matches the boto3 ``batch_get_item`` response syntax.
+            The values in ``"Responses"`` will be decrypted locally after being read from DynamoDB.
 
         """
         return self._client_operation_logic(
@@ -270,15 +279,16 @@ def transact_get_items(self, **kwargs) -> dict[str, Any]:
         """
         Get multiple items in a single transaction. Decrypts any returned items.
 
-        The parameters and return value match the boto3 DynamoDB transact_get_items API:
+        The input and output syntaxes match those for the boto3 DynamoDB ``transact_get_items`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/transact_get_items.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 transact_get_items API
-                parameters.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 ``transact_get_items``
+                request syntax.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 transact_get_items API response.
+            dict: The response from DynamoDB. This matches the boto3 ``transact_get_items`` response syntax.
 
         """
         return self._client_operation_logic(
@@ -300,16 +310,17 @@ def transact_write_items(self, **kwargs) -> dict[str, Any]:
 
         For put operations, encrypts items before writing.
 
-        The parameters and return value match the boto3 DynamoDB transact_write_items API:
+        The input and output syntaxes match those for the boto3 DynamoDB ``transact_write_items`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/transact_write_items.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 transact_write_items API
-                parameters. Any put operations in the "TransactItems" argument will be encrypted locally
-                before being written to DynamoDB.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 ``transact_write_items``
+                request syntax. Any ``"PutRequest"`` values in the ``"TransactItems"`` argument will be encrypted
+                locally before being written to DynamoDB.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 transact_write_items API response.
+            dict: The response from DynamoDB. This matches the boto3 ``transact_write_items`` response syntax.
 
         """
         return self._client_operation_logic(
@@ -351,8 +362,8 @@ def get_paginator(self, operation_name: str) -> EncryptedPaginator | botocore.cl
             operation_name (str): Name of operation for which to get paginator
 
         Returns:
-            EncryptedPaginator | botocore.client.Paginator: A paginator that will transparently decrypt items
-                for scan/query operations, or the standard paginator for other operations.
+            EncryptedPaginator | botocore.client.Paginator: An EncryptedPaginator that will transparently decrypt items
+            for ``scan``/``query`` operations; for other operations, the standard paginator.
 
         """
         paginator = self._client.get_paginator(operation_name)

DynamoDbEncryption/runtimes/python/test/integ/encrypted/test_client.py

@@ -1,3 +1,5 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 import boto3
 import pytest
 from boto3.dynamodb.types import TypeDeserializer, TypeSerializer
@@ -41,11 +43,16 @@
     basic_transact_write_item_put_request_ddb,
     basic_transact_write_item_put_request_dict,
 )
+from . import sort_dynamodb_json_lists
 
 serializer = TypeSerializer()
 deserializer = TypeDeserializer()
 
 
+# Creates a matrix of tests for each value in param,
+# with a user-friendly string for test output:
+# expect_standard_dictionaries = True -> "standard_dicts"
+# expect_standard_dictionaries = False -> "ddb_json"
 @pytest.fixture(params=[True, False], ids=["standard_dicts", "ddb_json"])
 def expect_standard_dictionaries(request):
     return request.param
@@ -67,6 +74,10 @@ def plaintext_client(expect_standard_dictionaries):
     return client
 
 
+# Creates a matrix of tests for each value in param,
+# with a user-friendly string for test output:
+# encrypted = True -> "encrypted"
+# encrypted = False -> "plaintext"
 @pytest.fixture(params=[True, False], ids=["encrypted", "plaintext"])
 def encrypted(request):
     return request.param
@@ -80,6 +91,10 @@ def client(encrypted, expect_standard_dictionaries):
         return plaintext_client(expect_standard_dictionaries)
 
 
+# Creates a matrix of tests for each value in param,
+# with a user-friendly string for test output:
+# use_complex_item = True -> "complex_item"
+# use_complex_item = False -> "simple_item"
 @pytest.fixture(params=[True, False], ids=["complex_item", "simple_item"])
 def use_complex_item(request):
     return request.param
@@ -143,22 +158,6 @@ def get_item_request(expect_standard_dictionaries, test_item):
     return basic_get_item_request_ddb(test_item)
 
 
-def sort_dynamodb_json_lists(obj):
-    """
-    Utility that recursively sorts all lists in a DynamoDB JSON-like structure.
-    DynamoDB JSON uses lists to represent sets, so strict equality can fail.
-    Sort lists to ensure consistent ordering when comparing expected and actual items.
-    """
-    if isinstance(obj, dict):
-        return {k: sort_dynamodb_json_lists(v) for k, v in obj.items()}
-    elif isinstance(obj, list):
-        try:
-            return sorted(obj)  # Sort lists for consistent comparison
-        except TypeError:
-            return obj  # Not all lists are sortable; ex. complex_item_ddb's "list" attribute
-    return obj
-
-
 def test_GIVEN_valid_put_and_get_requests_WHEN_put_and_get_THEN_round_trip_passes(
     client, put_item_request, get_item_request
 ):

Examples/runtimes/python/DynamoDBEncryption/src/basic_put_get_example/with_encrypted_client.py

@@ -20,11 +20,11 @@
 )
 from aws_cryptographic_material_providers.mpl.references import IKeyring
 from aws_dbesdk_dynamodb.encrypted.client import EncryptedClient
-from aws_dbesdk_dynamodb.models.dynamodb import (
+from aws_dbesdk_dynamodb.structures.dynamodb import (
     DynamoDbTableEncryptionConfig,
     DynamoDbTablesEncryptionConfig,
 )
-from aws_dbesdk_dynamodb.models.structured_encryption import (
+from aws_dbesdk_dynamodb.structures.structured_encryption import (
     CryptoAction,
 )