DynamoDB JSON Conversion Utility

Common errors

• ImportError: cannot import name 'json_util' from 'dynamo_json' (or similar ImportError)

  cause The `dynamo-json` package was either not installed, installed in a different Python environment, or there's a typo in the import statement.
  fix Ensure the package is installed: `pip install dynamo-json`. Verify the import statement: `from dynamo_json import json_util as json`.

• TypeError: Object of type Decimal is not JSON serializable (or datetime, UUID, etc.)

  cause You are attempting to use Python's built-in `json` module (or another standard JSON library) to serialize objects containing types like `Decimal`, `datetime`, or `UUID` without a custom encoder. The `dynamo-json` library is specifically designed to handle these for DynamoDB compatibility.
  fix Always use `dynamo_json.json_util.dumps()` and `dynamo_json.json_util.loads()` when working with data intended for or retrieved from DynamoDB, as these functions include the necessary custom encoders/decoders.

• Data appears incorrectly formatted or unreadable in the AWS DynamoDB Console's 'JSON' view.

  cause The AWS DynamoDB Console's 'JSON' tab sometimes has limitations when displaying or converting complex DynamoDB JSON (with type descriptors) into a more human-readable 'plain JSON' format, especially for items with very large numbers or deeply nested structures. This is a display limitation of the console, not an issue with the data serialized by `dynamo-json`.
  fix Trust that `dynamo-json` correctly formats the data for DynamoDB. If you need to inspect the exact Python object, retrieve the item programmatically and use `dynamo_json.json_util.loads()` to deserialize it into a Python object.

Warnings

• gotcha There is a similarly named but distinct library called `dynamodb-json` (with 'db') developed by Alonreznik, which also provides DynamoDB JSON conversion functionalities and uses a very similar import pattern (`from dynamodb_json import json_util as json`). Ensure you install `dynamo-json` (`pip install dynamo-json`) if you intend to use this specific library by adilosa, to avoid unexpected behavior or missing features from the wrong package.
  Fix: Always explicitly install `dynamo-json` if this specific library is desired, and verify the package source if encountering unexpected behavior.
• gotcha DynamoDB has a strict item size limit of 400KB. While `dynamo-json` handles the format conversion, it does not bypass this underlying DynamoDB constraint. Attempting to serialize very large Python objects will result in DynamoDB errors when `put_item` is called.
  Fix: For items exceeding 400KB, consider storing large attributes in Amazon S3 and referencing them in DynamoDB, or restructure your data model to break down large items into smaller ones.
• gotcha DynamoDB supports high-precision numbers (up to 38 digits) which are typically represented as strings in DynamoDB JSON (`{'N': '123.45'}`). This library correctly handles `Decimal` objects. If you process data outside of `dynamo-json`'s `dumps`/`loads` using standard JSON libraries, you might lose precision for large numbers or encounter `TypeError` for `Decimal` objects.
  Fix: Consistently use `dynamo_json.json_util.dumps()` and `loads()` for all DynamoDB-related JSON serialization/deserialization to ensure proper handling of numerical precision and other complex types like `datetime` and `UUID`.

Install

• pip install dynamo-json Install with pip

Imports

• json_util
  wrong:

  import json_util

  correct:

  from dynamo_json import json_util as json

  The library is typically imported with an alias to mimic the standard 'json' module.

Quickstart

Demonstrates converting a complex Python dictionary containing Decimals, datetimes, and UUIDs to DynamoDB-compatible JSON and back. The `json_util` module handles the necessary type marshalling and unmarshalling.

import time
import uuid
from datetime import datetime
from decimal import Decimal
from dynamo_json import json_util as json

# Python object with various types, including those requiring special handling by DynamoDB
json_ = {
    "MyString": "a",
    "num": 4,
    "MyBool": False,
    "my_dict": {"my_date": datetime.now(), "my_uuid": uuid.uuid4()},
    "MyList": [Decimal('1.23'), 2, 3],
    "MyNull": None
}

# Convert Python object to DynamoDB JSON format
dynamo_json_data = json.dumps(json_)
print("DynamoDB JSON:\n", dynamo_json_data)

# Convert DynamoDB JSON format back to a Python object
python_object = json.loads(dynamo_json_data)
print("Python object:\n", python_object)