================
DynamoDB Mapping
================
.. image:: https://img.shields.io/pypi/v/dynamodb_mapping.svg
:target: https://pypi.python.org/pypi/dynamodb_mapping
.. image:: https://codecov.io/gh/mrtj/dynamodb-mapping/branch/main/graph/badge.svg?token=Y44R08UKEG
:target: https://codecov.io/gh/mrtj/dynamodb-mapping
.. image:: https://readthedocs.org/projects/dynamodb-mapping/badge/?version=latest
:target: https://dynamodb-mapping.readthedocs.io/en/latest/?version=latest
:alt: Documentation Status
A Python dictionary-like interface for an Amazon DynamoDB table.
DynamoDBMapping is an alternative API for `Amazon DynamoDB`_ that implements the Python
``collections.abc.MutableMapping`` abstract base class, effectively allowing you to use a DynamoDB
table as if it were a Python dictionary.
* Free software: MIT license
* Documentation: https://dynamodb-mapping.readthedocs.io.
.. _Amazon DynamoDB: https://aws.amazon.com/dynamodb/
Getting started
---------------
To do anything useful with this module you need an Amazon Web Services account and an Amazon
DynamoDB table. In every AWS account several DynamoDB tables can be created for free. Open
an `AWS account`_ and `create a DynamoDB table`_. You also need to create a IAM user and configure
the access keys on your workstation. The easiest way to do so is to install and configure the
`AWS Command Line Interface`_. Once the AWS CLI works correctly, the AWS Python libraries (boto3)
will correctly pick up the credentials.
.. _AWS account: https://aws.amazon.com/free/
.. _create a DynamoDB table: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-1.html
.. _AWS Command Line Interface: https://docs.aws.amazon.com/cli/index.html
Installation
------------
Stable release
~~~~~~~~~~~~~~
To install DynamoDB Mapping, run this command in your terminal:
.. code-block:: console
$ pip install dynamodb_mapping
This is the preferred method to install DynamoDB Mapping, as it will always install the most recent stable release.
If you don't have `pip`_ installed, this `Python installation guide`_ can guide
you through the process.
.. _pip: https://pip.pypa.io
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
From sources
~~~~~~~~~~~~
The sources for DynamoDB Mapping can be downloaded from the `Github repo`_.
You can either clone the public repository:
.. code-block:: console
$ git clone git://github.com/mrtj/dynamodb_mapping
Or download the `tarball`_:
.. code-block:: console
$ curl -OJL https://github.com/mrtj/dynamodb_mapping/tarball/master
Once you have a copy of the source, you can install it with:
.. code-block:: console
$ python setup.py install
.. _Github repo: https://github.com/mrtj/dynamodb_mapping
.. _tarball: https://github.com/mrtj/dynamodb_mapping/tarball/master
Usage
-----
Once the credentials are correctly configured, you can start reading and writing to your DynamoDB
table with DynamoDBMapping as it was an ordinal Python dictionary::
from dynamodb_mapping import DynamoDBMapping
mapping = DynamoDBMapping(table_name="my_table")
# Create or modify an item:
mapping["my_item"] = {"description": "foo", "price": 123}
mapping["my_item"]["price"] = 456
# Iterate over all items:
for key, value in mapping.items():
print(key, value)
# Get a single item:
print(mapping["my_item"])
# Number of items in table:
# (read bellow on how to get the estimated vs precise number of items)
print(len(mapping))
# Delete an item:
del mapping["my_item"]
All methods that iterate over the elements of the table do so in a lazy manner, in that the
successive pages of the scan operation are queried only on demand. Examples of such operations
include scan, iteration over keys, iteration over values, and iteration over items (key-value
tuples). You should pay particular attention to certain patterns that fetch all items in the table,
for example, calling ``list(mapping.values())``. This call will execute an exhaustive scan on your
table, which can be costly, and attempt to load all items into memory, which can be
resource-demanding if your table is particularly large.
The ``__len__`` implementation of this class returns a best-effort estimate of the number of items
in the table using the TableDescription DynamoDB API. The number of items are updated at DynamoDB
service side approximately once in every 6 hours. If you need the exact number of items currently in
the table, you can use ``len(list(mapping.keys()))``. Note however that this will cause to run an
exhaustive scan operation on your table.
Advanced configuration
----------------------
You have the following options to configure the underlying boto3 session:
- Automatic configuration: pass nothing to DynamoDBMapping initializer. This will prompt
DynamoDBMapping to load the default ``boto3.Session`` object, which in turn will use the
standard boto3 credentials chain to find AWS credentials (e.g., the ``~/.aws/credentials``
file, environment variables, etc.).
- Pass a preconfigured ``boto3.Session`` object
- Pass ``aws_access_key_id`` and ``aws_secret_access_key`` as keyword arguments. Additionally,
the optional ``aws_region`` and ``aws_profile`` arguments are also considered.
=======
History
=======
0.1.0 (2023-07-28)
------------------
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/mrtj/dynamodb_mapping",
"name": "dynamodb-mapping",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "dynamodb_mapping",
"author": "Janos Tolgyesi",
"author_email": "janos.tolgyesi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/be/f2/66c637c71e9a8e82866052cc14bde171a4b3bbe33afc90d947b7c333fbc1/dynamodb_mapping-0.1.2.tar.gz",
"platform": null,
"description": "================\nDynamoDB Mapping\n================\n\n\n.. image:: https://img.shields.io/pypi/v/dynamodb_mapping.svg\n :target: https://pypi.python.org/pypi/dynamodb_mapping\n\n.. image:: https://codecov.io/gh/mrtj/dynamodb-mapping/branch/main/graph/badge.svg?token=Y44R08UKEG\n :target: https://codecov.io/gh/mrtj/dynamodb-mapping\n\n.. image:: https://readthedocs.org/projects/dynamodb-mapping/badge/?version=latest\n :target: https://dynamodb-mapping.readthedocs.io/en/latest/?version=latest\n :alt: Documentation Status\n\n\n\nA Python dictionary-like interface for an Amazon DynamoDB table.\n\nDynamoDBMapping is an alternative API for `Amazon DynamoDB`_ that implements the Python\n``collections.abc.MutableMapping`` abstract base class, effectively allowing you to use a DynamoDB\ntable as if it were a Python dictionary.\n\n* Free software: MIT license\n* Documentation: https://dynamodb-mapping.readthedocs.io.\n\n.. _Amazon DynamoDB: https://aws.amazon.com/dynamodb/\n\n\nGetting started\n---------------\n\nTo do anything useful with this module you need an Amazon Web Services account and an Amazon\nDynamoDB table. In every AWS account several DynamoDB tables can be created for free. Open\nan `AWS account`_ and `create a DynamoDB table`_. You also need to create a IAM user and configure\nthe access keys on your workstation. The easiest way to do so is to install and configure the\n`AWS Command Line Interface`_. Once the AWS CLI works correctly, the AWS Python libraries (boto3)\nwill correctly pick up the credentials.\n\n.. _AWS account: https://aws.amazon.com/free/\n.. _create a DynamoDB table: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-1.html\n.. _AWS Command Line Interface: https://docs.aws.amazon.com/cli/index.html\n\n\nInstallation\n------------\n\nStable release\n~~~~~~~~~~~~~~\n\nTo install DynamoDB Mapping, run this command in your terminal:\n\n.. code-block:: console\n\n $ pip install dynamodb_mapping\n\nThis is the preferred method to install DynamoDB Mapping, as it will always install the most recent stable release.\n\nIf you don't have `pip`_ installed, this `Python installation guide`_ can guide\nyou through the process.\n\n.. _pip: https://pip.pypa.io\n.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/\n\n\nFrom sources\n~~~~~~~~~~~~\n\nThe sources for DynamoDB Mapping can be downloaded from the `Github repo`_.\n\nYou can either clone the public repository:\n\n.. code-block:: console\n\n $ git clone git://github.com/mrtj/dynamodb_mapping\n\nOr download the `tarball`_:\n\n.. code-block:: console\n\n $ curl -OJL https://github.com/mrtj/dynamodb_mapping/tarball/master\n\nOnce you have a copy of the source, you can install it with:\n\n.. code-block:: console\n\n $ python setup.py install\n\n\n.. _Github repo: https://github.com/mrtj/dynamodb_mapping\n.. _tarball: https://github.com/mrtj/dynamodb_mapping/tarball/master\n\n\nUsage\n-----\n\nOnce the credentials are correctly configured, you can start reading and writing to your DynamoDB\ntable with DynamoDBMapping as it was an ordinal Python dictionary::\n\n from dynamodb_mapping import DynamoDBMapping\n\n mapping = DynamoDBMapping(table_name=\"my_table\")\n\n # Create or modify an item:\n mapping[\"my_item\"] = {\"description\": \"foo\", \"price\": 123}\n mapping[\"my_item\"][\"price\"] = 456\n\n # Iterate over all items:\n for key, value in mapping.items():\n print(key, value)\n\n # Get a single item:\n print(mapping[\"my_item\"])\n\n # Number of items in table:\n # (read bellow on how to get the estimated vs precise number of items)\n print(len(mapping))\n\n # Delete an item:\n del mapping[\"my_item\"]\n\n\nAll methods that iterate over the elements of the table do so in a lazy manner, in that the\nsuccessive pages of the scan operation are queried only on demand. Examples of such operations\ninclude scan, iteration over keys, iteration over values, and iteration over items (key-value\ntuples). You should pay particular attention to certain patterns that fetch all items in the table,\nfor example, calling ``list(mapping.values())``. This call will execute an exhaustive scan on your\ntable, which can be costly, and attempt to load all items into memory, which can be\nresource-demanding if your table is particularly large.\n\nThe ``__len__`` implementation of this class returns a best-effort estimate of the number of items\nin the table using the TableDescription DynamoDB API. The number of items are updated at DynamoDB\nservice side approximately once in every 6 hours. If you need the exact number of items currently in\nthe table, you can use ``len(list(mapping.keys()))``. Note however that this will cause to run an\nexhaustive scan operation on your table.\n\n\nAdvanced configuration\n----------------------\n\nYou have the following options to configure the underlying boto3 session:\n\n- Automatic configuration: pass nothing to DynamoDBMapping initializer. This will prompt\n DynamoDBMapping to load the default ``boto3.Session`` object, which in turn will use the\n standard boto3 credentials chain to find AWS credentials (e.g., the ``~/.aws/credentials``\n file, environment variables, etc.).\n- Pass a preconfigured ``boto3.Session`` object\n- Pass ``aws_access_key_id`` and ``aws_secret_access_key`` as keyword arguments. Additionally,\n the optional ``aws_region`` and ``aws_profile`` arguments are also considered.\n\n\n\n=======\nHistory\n=======\n\n0.1.0 (2023-07-28)\n------------------\n\n* First release on PyPI.\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "A Python dictionary-like interface for an Amazon DynamoDB table.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/mrtj/dynamodb_mapping"
},
"split_keywords": [
"dynamodb_mapping"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "958ade67659a1b726ab6149fb5a5bd17024b1cc199358afca4afe6d23a8dfcd9",
"md5": "61d198a3de420f487e3632dcad345d7a",
"sha256": "e185a3414934d284245a4a7224de0afa2cbd2b3da4dd131462912b5436b7d5ed"
},
"downloads": -1,
"filename": "dynamodb_mapping-0.1.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "61d198a3de420f487e3632dcad345d7a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 11389,
"upload_time": "2023-09-05T16:31:59",
"upload_time_iso_8601": "2023-09-05T16:31:59.463210Z",
"url": "https://files.pythonhosted.org/packages/95/8a/de67659a1b726ab6149fb5a5bd17024b1cc199358afca4afe6d23a8dfcd9/dynamodb_mapping-0.1.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bef266c637c71e9a8e82866052cc14bde171a4b3bbe33afc90d947b7c333fbc1",
"md5": "4fd1bfd9eee610fa3039d7d102a7d2b9",
"sha256": "46ff3e141c15a19a63c43601929b4f939bbe2f5ef774c5d626985e31a904b650"
},
"downloads": -1,
"filename": "dynamodb_mapping-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "4fd1bfd9eee610fa3039d7d102a7d2b9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 19754,
"upload_time": "2023-09-05T16:32:01",
"upload_time_iso_8601": "2023-09-05T16:32:01.109141Z",
"url": "https://files.pythonhosted.org/packages/be/f2/66c637c71e9a8e82866052cc14bde171a4b3bbe33afc90d947b7c333fbc1/dynamodb_mapping-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-05 16:32:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mrtj",
"github_project": "dynamodb_mapping",
"github_not_found": true,
"lcname": "dynamodb-mapping"
}
JSON
