@@ -22,12 +22,134 @@ DynamoDB Mapping
2222
2323A Python dictionary-like interface for an Amazon DynamoDB table.
2424
25+ DynamoDBMapping is an alternative API for `Amazon DynamoDB `_ that implements the Python
26+ ``collections.abc.MutableMapping `` abstract base class, effectively allowing you to use a DynamoDB
27+ table as if it were a Python dictionary.
2528
2629* Free software: MIT license
2730* Documentation: https://dynamodb-mapping.readthedocs.io.
2831
32+ .. _Amazon DynamoDB : https://aws.amazon.com/dynamodb/
2933
30- Features
31- --------
3234
33- * A Python dictionary-like interface for an Amazon DynamoDB table.
35+ Getting started
36+ ---------------
37+
38+ To do anything useful with this module you need an Amazon Web Services account and an Amazon
39+ DynamoDB table. In every AWS account several DynamoDB tables can be created for free. Open
40+ an `AWS account `_ and `create a DynamoDB table `_. You also need to create a IAM user and configure
41+ the access keys on your workstation. The easiest way to do so is to install and configure the
42+ `AWS Command Line Interface `_. Once the AWS CLI works correctly, the AWS Python libraries (boto3)
43+ will correctly pick up the credentials.
44+
45+ .. _AWS account : https://aws.amazon.com/free/
46+ .. _create a DynamoDB table : https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/getting-started-step-1.html
47+ .. _AWS Command Line Interface : https://docs.aws.amazon.com/cli/index.html
48+
49+
50+ Installation
51+ ------------
52+
53+ Stable release
54+ ~~~~~~~~~~~~~~
55+
56+ To install DynamoDB Mapping, run this command in your terminal:
57+
58+ .. code-block :: console
59+
60+ $ pip install dynamodb_mapping
61+
62+
63+
64+ If you don't have `pip `_ installed, this `Python installation guide `_ can guide
65+ you through the process.
66+
67+ .. _pip : https://pip.pypa.io
68+ .. _Python installation guide : http://docs.python-guide.org/en/latest/starting/installation/
69+
70+
71+ From sources
72+ ~~~~~~~~~~~~
73+
74+ The sources for DynamoDB Mapping can be downloaded from the `Github repo `_.
75+
76+ You can either clone the public repository:
77+
78+ .. code-block :: console
79+
80+ $ git clone git://github.com/mrtj/dynamodb_mapping
81+
82+ tarball `_:
83+
84+ .. code-block :: console
85+
86+ $ curl -OJL https://github.com/mrtj/dynamodb_mapping/tarball/master
87+
88+
89+
90+ .. code-block :: console
91+
92+ $ python setup.py install
93+
94+
95+ Github repo : https://github.com/mrtj/dynamodb_mapping
96+ .. _tarball : https://github.com/mrtj/dynamodb_mapping/tarball/master
97+
98+
99+ Usage
100+ -----
101+
102+ Once the credentials are correctly configured, you can start reading and writing to your DynamoDB
103+ table with DynamoDBMapping as it was an ordinal Python dictionary::
104+
105+ from dynamodb_mapping import DynamoDBMapping
106+
107+ mapping = DynamoDBMapping(table_name="my_table")
108+
109+ # Create or modify an item:
110+ mapping["my_item"] = {"description": "foo", "price": 123}
111+ mapping["my_item"]["price"] = 456
112+
113+ # Iterate over all items:
114+ for key, value in mapping.items():
115+ print(key, value)
116+
117+ # Get a single item:
118+ print(mapping["my_item"])
119+
120+ # Number of items in table:
121+ # (read bellow on how to get the estimated vs precise number of items)
122+ print(len(mapping))
123+
124+ # Delete an item:
125+ del mapping["my_item"]
126+
127+
128+ All methods that iterate over the elements of the table do so in a lazy manner, in that the
129+ successive pages of the scan operation are queried only on demand. Examples of such operations
130+ include scan, iteration over keys, iteration over values, and iteration over items (key-value
131+ tuples). You should pay particular attention to certain patterns that fetch all items in the table,
132+ for example, calling ``list(mapping.values()) ``. This call will execute an exhaustive scan on your
133+ table, which can be costly, and attempt to load all items into memory, which can be
134+ resource-demanding if your table is particularly large.
135+
136+ The ``__len__ `` implementation of this class returns a best-effort estimate of the number of items
137+ in the table using the TableDescription DynamoDB API. The number of items are updated at DynamoDB
138+ service side approximately once in every 6 hours. If you need the exact number of items currently in
139+ the table, you can use ``len(list(mapping.keys())) ``. Note however that this will cause to run an
140+ exhaustive scan operation on your table.
141+
142+
143+ Advanced configuration
144+ ----------------------
145+
146+ You have the following options to configure the underlying boto3 session:
147+
148+ - Automatic configuration: pass nothing to DynamoDBMapping initializer. This will prompt
149+ DynamoDBMapping to load the default ``boto3.Session `` object, which in turn will use the
150+ standard boto3 credentials chain to find AWS credentials (e.g., the ``~/.aws/credentials ``
151+ file, environment variables, etc.).
152+ - Pass a preconfigured ``boto3.Session `` object
153+ - Pass ``aws_access_key_id `` and ``aws_secret_access_key `` as keyword arguments. Additionally,
154+ the optional ``aws_region `` and ``aws_profile `` arguments are also considered.
155+
0 commit comments