m

Author: Lucas McDonald

DynamoDbEncryption/runtimes/python/test/unit/internal/README.md

@@ -1,35 +1,39 @@
-The test_client_to_resource.py and test_resource_to_client.py files
+The `test_client_to_resource.py` and `test_resource_to_client.py` files
 in this directory verify that DBESDK's boto3 resource/client conversion methods
 correctly convert between resource/client shapes for all operations
 supported by DBESDK.
 
 The only shapes that require conversion are
-* AttributeValues (DDB items or keys)
-  * Client shape ex.: `{"S": "some string"}`
-  * Resource shape ex.: `"some string"`
-* ConditionExpressions (KeyConditionExpression or FilterExpression; only resource-to-client)
+* `AttributeValue`s (DDB items or keys)
+  * Client format example: `{"S": "some string"}`
+  * Resource format example: `"some string"`
+* ConditionExpressions (`KeyConditionExpression` or `FilterExpression`; only resource-to-client)
   * Client shape ex.:
     * KeyConditionExpression: `"attr : :value"`
     * ExpressionAttributeValues: `{":value" : {"S" : "some value}}`
   * Resource shape ex.:
-    * KeyConditionExpression: `Attr("attr").eq("some value")` (also supports the client shape)
+    * KeyConditionExpression: `Attr("attr").eq("some value")`
+    * (Resources also support the client-style string expression)
 
-and recursive traversals from the input/output shape to those shapes.
-(i.e. for boto3 Table [put_item](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/table/put_item.html)),
-the following kwargs MUST be converted from resource shapes to client shapes:
+The conversion logic will recursively traverse inpuyt/output shapes to find shapes that require conversion, then convert them.
+(ex. for boto3 Table [put_item](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/table/put_item.html)),
+the following kwargs MUST be converted from resource to client format:
 * `["Item"]`
 * `["Expected"][<table_name>]["Value"]`
 * `["Expected"][<table_name>]["AttributeValueList"]`
 * `["ConditionExpression"]`
 * `["ExpressionAttributeValues"]`
 
 The requests, responses, and items in the parent directory are shared between the integ tests and these unit tests.
-The integ tests assert that the basic forms of these requests, responses, and items are authoritative; i.e. DynamoDB will receive/send these structures.
-These tests assert
+The integ tests send the exact request that whose client/resource conversion is tested in the unit tests,
+and the integ tests receive the exact response whose conversion is tested in the unit tests.
+
+The integration tests verify that the basic forms of these requests and responses are authoritative. The unit tests verify that DBESDK’s conversion logic exactly transforms one shape format into the other.
 
 Note: The conversion logic is generated by Smithy-Dafny Python
 and the shape traversals are derived from the MPL's DynamoDB Smithy model.
-As a result, the correctness of this conversion logic is largely defined by the correctness of the Smithy codegen logic and the correctness of the DynamoDB Smithy model.
-As a result, the amount of testing needed by these files *should* only need to be smoke testing, 
-but it is more exhaustive than that
-because the conversion logic was manually written at first.
+As a result, the correctness of this conversion logic is primarily depends on the correctness of the Smithy codegen logic and the correctness of the DynamoDB Smithy model.
+
+Originally, the conversion logic was hand-written,
+so these tests go beyond smoke testing to provide extra guarantees,
+even though basic smoke testing should suffice now that the logic is machine-generated.