{"id":10115,"library":"pynamodb-attributes","title":"PynamoDB Attributes","description":"pynamodb-attributes provides common custom attribute types for PynamoDB models, extending the built-in attributes with specialized types like Timestamp, Timedelta, and Protobuf Enum attributes. It aims to simplify handling complex data types in DynamoDB. The current version is 0.5.1 and it generally follows the release cadence of its upstream dependency, PynamoDB.","status":"active","version":"0.5.1","language":"en","source_language":"en","source_url":"https://github.com/lyft/pynamodb-attributes","tags":["database","dynamodb","pynamodb","attributes","aws","data-types"],"install":[{"cmd":"pip install pynamodb-attributes","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This library provides custom attributes for PynamoDB models and requires PynamoDB to function.","package":"pynamodb","optional":false}],"imports":[{"note":"Custom attributes from this library are imported directly from `pynamodb_attributes`, not from PynamoDB's built-in attributes.","wrong":"from pynamodb.attributes import TimestampAttribute","symbol":"TimestampAttribute","correct":"from pynamodb_attributes import TimestampAttribute"},{"note":"Used for serializing Python `timedelta` objects to milliseconds.","symbol":"TimedeltaMsAttribute","correct":"from pynamodb_attributes import TimedeltaMsAttribute"},{"note":"Allows storing a set of integers, providing stronger type guarantees than `NumberSetAttribute`.","symbol":"IntegerSetAttribute","correct":"from pynamodb_attributes import IntegerSetAttribute"},{"note":"Serializes Python Enums to DynamoDB strings, compatible with Protobuf enum definitions.","symbol":"UnicodeProtobufEnumAttribute","correct":"from pynamodb_attributes import UnicodeProtobufEnumAttribute"}],"quickstart":{"code":"from pynamodb.models import Model\nfrom pynamodb.attributes import UnicodeAttribute\nfrom pynamodb_attributes import TimestampAttribute, TimedeltaMsAttribute, IntegerSetAttribute\nimport datetime\n\n# Configure PynamoDB (for local DynamoDB for example)\n# from pynamodb.connection import Connection\n# Connection.tables = {}\n\nclass MyModel(Model):\n    class Meta:\n        table_name = 'my_test_model_table'\n        region = 'us-east-1'\n        # host = 'http://localhost:8000' # Uncomment for local DynamoDB\n        read_capacity_units = 1\n        write_capacity_units = 1\n\n    id = UnicodeAttribute(hash_key=True)\n    created_at = TimestampAttribute(null=True)\n    processing_time = TimedeltaMsAttribute(null=True)\n    favorite_numbers = IntegerSetAttribute(null=True)\n\n# Example Usage:\nif __name__ == '__main__':\n    # MyModel.create_table(wait=True) # Uncomment to create table\n    \n    item = MyModel(\n        id='item-123',\n        created_at=datetime.datetime.now(datetime.timezone.utc),\n        processing_time=datetime.timedelta(seconds=5, milliseconds=250),\n        favorite_numbers={1, 5, 10}\n    )\n    # item.save() # Uncomment to save item\n    \n    # retrieved_item = MyModel.get('item-123') # Uncomment to retrieve item\n    # print(f\"Retrieved: {retrieved_item.id}, Created: {retrieved_item.created_at}, \"\n    #       f\"Processed in: {retrieved_item.processing_time}, Favorites: {retrieved_item.favorite_numbers}\")\n","lang":"python","description":"This quickstart demonstrates how to define a PynamoDB model using custom attributes like `TimestampAttribute`, `TimedeltaMsAttribute`, and `IntegerSetAttribute`. It shows how to initialize an item with these types and how they would be stored and retrieved (commented out save/get operations requiring a running DynamoDB instance)."},"warnings":[{"fix":"Always check the `pynamodb-attributes` release notes for PynamoDB compatibility when upgrading PynamoDB. Upgrade `pynamodb-attributes` to the version compatible with your PynamoDB installation.","message":"PynamoDB-attributes versions are tied to PynamoDB major versions. For instance, `pynamodb-attributes==0.3.0` introduced compatibility with `pynamodb==5.0.0`. Upgrading PynamoDB might require upgrading `pynamodb-attributes` to a compatible version.","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Understand that the attribute serializes complex Python types into DynamoDB numbers. If string-based ISO 8601 timestamps are desired, use `UnicodeAttribute` with manual serialization or a different library.","message":"Be aware of the underlying storage format for custom attributes. For example, `TimestampAttribute` stores `datetime` objects as Unix timestamps (numbers), and `TimedeltaAttribute` variants store `timedelta` objects as integers (seconds, milliseconds, or microseconds). These are not stored as ISO 8601 strings.","severity":"gotcha","affected_versions":"All"},{"fix":"Always pass Python `int` types to `IntegerSetAttribute`. If you need to store mixed integer/float numbers, consider `pynamodb.attributes.NumberSetAttribute` instead, or explicitly cast to `int` before assigning.","message":"When working with `IntegerSetAttribute`, ensure all values are integers. PynamoDB's built-in `NumberSetAttribute` allows floats, but `IntegerSetAttribute` strictly enforces integers, which can lead to `TypeError` if floats are accidentally used.","severity":"gotcha","affected_versions":"All"},{"fix":"No direct fix needed if you're using `prefix` as before, but be aware that it's now optional. New implementations can omit `prefix` if not required for their use case.","message":"The `prefix` argument for `UnicodeProtobufEnumAttribute` was made optional in version 0.5.1. While still functional, relying on it being mandatory might lead to confusion if new code omits it.","severity":"deprecated","affected_versions":"<0.5.1"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Change your import statement from `from pynamodb.attributes import TimestampAttribute` to `from pynamodb_attributes import TimestampAttribute`.","cause":"Attempting to import custom attributes from `pynamodb.attributes` instead of `pynamodb_attributes`.","error":"AttributeError: module 'pynamodb.attributes' has no attribute 'TimestampAttribute'"},{"fix":"Ensure all values passed to `IntegerSetAttribute` or `IntegerAttribute` are Python `int` types. Explicitly cast floats to integers if needed (e.g., `int(value)`).","cause":"Attempting to assign a float value or a set containing floats to an `IntegerSetAttribute` or `IntegerAttribute` which expects strict integer types.","error":"TypeError: argument of type 'float' is not iterable (for IntegerSetAttribute) or TypeError: 'float' object cannot be interpreted as an integer (for IntegerAttribute)"},{"fix":"Ensure you are passing a Python `datetime.datetime` object to `TimestampAttribute` or a `datetime.timedelta` object to `TimedeltaAttribute`. These attributes handle the conversion to a numeric type automatically.","cause":"You are attempting to store a non-numeric type (e.g., a string) into an attribute that expects a Number type in DynamoDB, such as `TimestampAttribute` or `TimedeltaAttribute`.","error":"pynamodb.exceptions.PynamoDBException: The provided attribute value is not of type N (for attribute: 'created_at')"}]}