{"id":19146423,"url":"https://github.com/kushagraindurkhya/dynabridge","last_synced_at":"2025-08-04T12:39:33.418Z","repository":{"id":203072972,"uuid":"708714890","full_name":"KushagraIndurkhya/DynaBridge","owner":"KushagraIndurkhya","description":"An elegant DynamoDB Object-Relational Mapping (ORM) library for Python, simplifying database interactions and data modeling.","archived":false,"fork":false,"pushed_at":"2023-11-03T06:54:50.000Z","size":32,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-22T19:49:40.901Z","etag":null,"topics":["dynamod","library","mapping","orm","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/DynaBridge/#description","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KushagraIndurkhya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-23T08:38:29.000Z","updated_at":"2023-11-26T10:57:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"bd5728d7-857c-4f0d-b6e3-534c32ced646","html_url":"https://github.com/KushagraIndurkhya/DynaBridge","commit_stats":null,"previous_names":["kushagraindurkhya/dynabridge"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/KushagraIndurkhya/DynaBridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KushagraIndurkhya%2FDynaBridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KushagraIndurkhya%2FDynaBridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KushagraIndurkhya%2FDynaBridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KushagraIndurkhya%2FDynaBridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KushagraIndurkhya","download_url":"https://codeload.github.com/KushagraIndurkhya/DynaBridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KushagraIndurkhya%2FDynaBridge/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268697065,"owners_count":24292391,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-04T02:00:09.867Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dynamod","library","mapping","orm","python"],"created_at":"2024-11-09T07:44:05.985Z","updated_at":"2025-08-04T12:39:33.374Z","avatar_url":"https://github.com/KushagraIndurkhya.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DynaBridge\n\nDynaBridge is a Python library that simplifies interactions with Amazon DynamoDB, a fast and flexible NoSQL database service provided by AWS. This library provides an easy-to-use interface for creating, querying, and managing tables and items in DynamoDB.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n- [DynamoTable](#dynamotable)\n- [DynamoModel](#dynamomodel)\n- [DynamoSchema and DynamoAttribute](#dynamoschema-and-dynamoattribute)\n- [Examples](#examples)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\nYou can install DynaBridge using pip:\n\n```bash\npip install dynabridge\n```\n\n## Getting Started\n\nBefore you can start using DynaBridge, you'll need to set up your AWS credentials. You can do this by configuring your AWS credentials using the AWS Command Line Interface (CLI) or by setting the environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. Make sure that your IAM user or role has the necessary permissions to create and manage DynamoDB tables.\n\nHere's a simple example of how to get started with DynaBridge:\n\n```python\nfrom dynabridge import DynamoTable, DynamoModel\n\n# Initialize DynamoTable with your AWS resource and table details\ndynamo_table = DynamoTable(\n    table_name='MyTable',\n    db_resource=your_db_resource,  # Replace with your DynamoDB resource\n    primary_key='your_primary_key',\n    sort_key='your_sort_key'  # Optional\n)\n\n# Set the DynamoTable instance for your DynamoModel\nDynamoModel.set_dynamo_table(dynamo_table)\n\n# Create a DynamoModel instance and save it to the table\nmodel_instance = DynamoModel()\nmodel_instance.your_attribute = 'your_value'\nmodel_instance.create()\n```\n\nNow let's dive into the details of DynamoTable and DynamoModel.\n\n## DynamoTable\n\nThe `DynamoTable` class provides methods to interact with DynamoDB tables. It includes functions for creating, retrieving, updating, and deleting items. Here are some of the key methods and their descriptions:\n\n- `_create_table`: Creates a new DynamoDB table.\n- `create_table_if_not_exists`: Checks if a table exists and creates it if not.\n- `save`: Saves an item to the table.\n- `get`: Retrieves an item from the table.\n- `scan`: Retrieves items based on a filter expression.\n- `delete`: Deletes an item from the table.\n\nYou can also use `DynamoTable` to handle versioning, schema validation, and transactional updates in DynamoDB.\n\n## DynamoModel\n\nThe `DynamoModel` class is designed to simplify the interaction with DynamoDB tables using a model-like approach. You can use `DynamoModel` to define and manipulate items within a table. Here are some of the key methods and their descriptions:\n\n- `create`: Creates and saves an item to the associated table.\n- `get`: Retrieves an item from the table based on the primary key.\n- `get_all`: Retrieves all items from the associated table.\n- `delete_by_primary_key`: Deletes an item based on the primary key.\n- `get_all_by_attribute`: Retrieves items based on a specific attribute and its value.\n- `transactional_lock`: Provides a mechanism for transactional operations on items in the table.\n\n`DynamoModel` is a convenient way to work with DynamoDB tables, allowing you to define models that correspond to your data and perform operations on them with ease.\n\n## DynamoSchema and DynamoAttribute\n\nDynaBridge also provides the `DynamoSchema` and `DynamoAttribute` classes for more fine-grained control over attribute management within DynamoDB schemas. Here's how you can use them:\n\n### Creating a DynamoSchema and DynamoAttribute\n\n```python\nfrom DynaBridge.attribute import DynamoAttribute\nfrom DynaBridge.exceptions import DynamoAttributeError, DynamoTypeError, DynamoValueError\n\n# Create a DynamoAttribute\nattribute = DynamoAttribute(\n    attribute_name='example_attribute',\n    data_type='str',\n    attribute_default='default_value',\n    attribute_required=True,\n    attribute_immutable=False,\n    attribute_validator=None\n)\n\n# Create a DynamoSchema\nschema = DynamoSchema()\nschema.add_attributes([attribute])\n```\n\n- `DynamoAttribute` allows you to specify attributes with detailed information, including name, data type, default value, required flag, immutability flag, and a validation function.\n\n- `DynamoSchema` is used to store and manage attributes within a DynamoDB schema.\n\n### Using DynamoSchema to Validate and Fill Defaults\n\n```python\n# Validate an item against the schema\nitem = {'example_attribute': 'item_value'}\nschema.validate(item)\n\n# Fill in defaults for an item\nitem = {}\nitem = schema.fill_defaults(item)\n```\n\n`DynamoSchema` can validate whether an item contains all required attributes, whether attribute types match expected types, and whether attribute values pass validation functions. It can also fill in missing attributes with their default values.\n\n## Examples\n\nHere are some examples of how to use DynaBridge for common DynamoDB operations:\n\n### Creating a DynamoTable and Saving an Item\n\n```python\nfrom dynabridge import DynamoTable, DynamoModel\n\n# Initialize DynamoTable\ndynamo_table = DynamoTable(\n    table_name='MyTable',\n    db_resource=your_db_resource,\n    primary_key='your_primary_key',\n    sort_key='your_sort_key'  # Optional\n)\n\n# Set the DynamoTable instance for your DynamoModel\nDynamoModel.set_dynamo_table(dynamo_table)\n\n# Create a DynamoModel instance and save it to the table\nmodel_instance = DynamoModel()\nmodel_instance.your_attribute = 'your_value'\nmodel_instance.create()\n```\n\n### Retrieving an Item by Primary Key\n\n```python\n# Get an item by its primary key\nkey = {'your_primary_key': 'key_value'}\nretrieved_item = DynamoModel.get_by_primary_key(key)\n```\n\n### Retrieving All Items\n\n```python\n# Get all items from the table\nall_items = DynamoModel.get_all()\n```\n\n### Deleting an Item by Primary Key\n\n```python\n# Delete an item by its primary key\nkey = {'your_primary_key': 'key_value'}\nDynamoModel.delete_by_primary_key(key)\n```\n\n## Sample App\n\nHere is an example app that defines a User model using DynamoModel and performs basic operations on it using DynamoBridge:\n```python\nfrom DynaBridge.table import DynamoTable\nfrom DynaBridge.models import DynamoModel\nfrom DynaBridge.exceptions import *\nfrom DynaBridge.attribute import *\nfrom DynaBridge.schema import *\nimport boto3\n\n# Create a DynamoTable\nUserTable = DynamoTable(table_name='User', db_resource=boto3.resource('dynamodb'), primary_key='UserId')\n\n# Define a DynamoSchema with attributes\nUserSchema = DynamoSchema().add_attributes([\n    DynamoAttribute(attribute_name='UserId', data_type='uuid', attribute_required=True),\n    DynamoAttribute(attribute_name='Name', data_type='str', attribute_required=True),\n    DynamoAttribute(attribute_name='Country', data_type='str', attribute_required=True, attribute_default='India'),\n    DynamoAttribute(attribute_name='Email', data_type='str', attribute_required=False,\n                    attribute_validator=lambda x: '@' in x, attribute_default=\"admin+missing@test.com\"),\n    DynamoAttribute(attribute_name='Status', data_type='str', attribute_required=True)\n])\n\n# Register the schema with the table\nUserTable.register_schema(UserSchema)\n\n# Define a User model class\nclass User(DynamoModel):\n    def __init__(self, **kwargs):\n        super().__init__()\n        if \"UserId\" in kwargs:\n            self.UserId = kwargs['UserId']\n        if \"Name\" in kwargs:\n            self.Name = kwargs['Name']\n        if \"Country\" in kwargs:\n            self.Country = kwargs['Country']\n        if \"Email\" in kwargs:\n            self.Email = kwargs['Email']\n        if \"Status\" in kwargs:\n            self.Status = kwargs['Status']\n\n    def update_status(self, new_status):\n        self.Status = new_status\n        self.save()\n\n# Associate the User model with the UserTable\nUser.set_dynamo_table(UserTable)\n\n# Create and save a user\nuser = User(Name='John', Country='India', Email='john@example.com', Status='Active').save()\nprint(f\"User created: {user.get_self_json()}\")\n\n# Retrieve the user by primary key\nretrieved_user = User.get_by_primary_key(key={'UserId': user.UserId})\nprint(f\"Retrieved user: {retrieved_user.get_self_json()}\")\n\n# Retrieve all users with a specific attribute value\nusers_in_india = User.get_all_by_attribute(attribute='Country', value='India')\nprint(\"Users in India:\")\nfor user in users_in_india:\n    print(user.get_self_json())\n\n# Update the user\nuser.Name = 'Updated John'\nuser.save()\nprint(f\"User updated: {user.get_self_json()}\")\n\nuser.update_status(new_status='Inactive')\n\n# Additional feature: Conditional updates\nuser.Status = 'Suspended'\nuser.save_if(lambda obj: obj.Status == 'Active')\nprint(f\"User updated with condition: {user.get_self_json()}\")\n\n# Delete the user\nuser.delete()\nprint(\"User deleted\")\n\n# Check if the user exists\nif User.exists(key={'UserId': user.UserId}):\n    print(\"User exists\")\nelse:\n    print(\"User does not exist\")\n\n```\n\n## Limitations\n\nWhile DynaBridge is a powerful library for DynamoDB interactions, it has some limitations:\n\n- **Complex Queries**: Complex queries and joins are not supported out of the box, as DynamoDB is designed for high-performance and scalability rather than complex querying.\n\n- **Scaling and Throughput**: You need to carefully manage and provision your DynamoDB throughput to ensure optimal performance.\n\n- **No Support for Nested Data Structures**: DynaBridge does not support nested dictionaries and lists as custom attributes or within schemas. DynamoDB is optimized for simple data structures, so storing complex nested data may require flattening or other strategies.\n\n- **No Support for Enums in Custom Attributes**: While you can specify data types like 'str' or 'int' for custom attributes using `DynamoAttribute`, there's no built-in support for enums. You would need to handle enum-like behavior at the application level.\n\nPlease be aware of these limitations when designing your DynamoDB schemas and working with custom attributes in DynaBridge.\n\n## Contributing\n\nIf you'd like to contribute to DynaBridge, please see our [contributing guidelines](CONTRIBUTING.md).\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkushagraindurkhya%2Fdynabridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkushagraindurkhya%2Fdynabridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkushagraindurkhya%2Fdynabridge/lists"}