Jean-Tiare Le Bigot avatar Jean-Tiare Le Bigot committed d77ecbd

Getting sarted guide

Comments (0)

Files changed (3)

 
 
     class DoomMap(DynamoDBModel):
-        __table__ = "doom_map"
-        __hash_key__ = "episode"
-        __range_key__ = "map"
+        __table__ = u"doom_map"
+        __hash_key__ = u"episode"
+        __range_key__ = u"map"
         __schema__ = {
-            "episode": int,
-            "map": int,
-            "name": unicode,
-            "cheats": set,
+            u"episode": int,
+            u"map": int,
+            u"name": unicode,
+            u"cheats": set,
         }
         __defaults__ = {
-            "cheats": set(['Konami']),
+            "cheats": set([u"Konami"]),
         }
 
 
     e1m1.episode = 1
     e1m1.map = 1
     e1m1.name = u"Hangar"
-    e1m1.cheats = set(["idkfa", "iddqd", "idclip"])
+    e1m1.cheats = set([u"idkfa", u"iddqd", u"idclip"])
     e1m1.save()
 
 
     # Later on, retrieve that same object from the DB...
     e1m1 = DoomMap.get((1, 1))
 
-    # query on hash+range-keyed tables
+    # query all maps of episode 1
     e1_maps = DoomMap.query(hash_key=1)
 
+    # query all maps of episode 1 with 'map' hash_key > 5
     from boto.dynamodb.condition import GT
     e1_maps_after_5 = DoomMap.query(
         hash_key=1,

docs/pages/getting_started.rst

 ####################################
 Getting started with Dynamodb-mapper
 ####################################
+
+Setup Dynamodb-mapper
+=====================
+
+Instalation
+-----------
+
+>>> pip install dynamodb-mapper
+
+Set you Amazon's API credential in ``~/.boto``
+----------------------------------------------
+
+.. code-block:: ini
+
+    [Credentials]
+    aws_access_key_id = <your access key>
+    aws_secret_access_key = <your secret key>
+
+For advance configuration, please see the `official Boto documentation <http://docs.pythonboto.org/en/latest/boto_config_tut.html>`_.
+
+
+Example data: DoomMap
+=====================
+
+We want a DoomMap to be part of an ``episode``. In our schema, the ``episodes``
+are identified by an integer ID, this is the ``hash_key``. We also want our
+episodes to have multiple maps also identified by an integer. This ``map`` id is
+the ``range_key``. ``range_key`` allows to logically group items that belongs to
+a same group.
+
+Our maps also have an ``name`` and a set of ``cheats`` codes. In DynamoDB, all strings
+are stored as ``unicode`` hence the type. Lastly, we want each maps to recognize
+by ``__defaults__`` the famous "Konami" cheat code.
+
+DoomMap Model
+-------------
+
+Start by defining the document structure.
+
+::
+
+    from dynamodb_mapper.model import DynamoDBModel
+
+
+    class DoomMap(DynamoDBModel):
+        __table__ = u"doom_map"
+        __hash_key__ = u"episode"
+        __range_key__ = u"map"
+        __schema__ = {
+            u"episode": int,
+            u"map": int,
+            u"name": unicode,
+            u"cheats": set,
+        }
+        __defaults__ = {
+            u"cheats": set([u"Konami"]),
+        }
+
+All class attributes of the form ``__attr__`` are used to configure the mapper.
+Note that they are defined on the class level. Any accidental override in the
+instances will be ignored.
+
+- ``__table__`` Table name in dynamoDB
+- ``__hash_key__`` Name of the the hash key field
+- ``__range_key__`` Name of the (optional) range key field
+- ``__schema__`` Dict mapping of ``{"field_name": type}``. Must at least contain
+    the keys
+- ``__defaults__`` Define an optional default value for each field used by ``__init__``
+
+.. TODO: link to more doc.
+.. TODO: + details sur defaults
+.. TODO: limitation de schema et pb d'export de date
+
+Initial Table creation
+----------------------
+
+Unlike MongoDB, table creation must be done explicitly. At the moment
+:py:meth:`~.ConnectionBorg.create_table`, is the only case where
+you'd want to directly use the :py:class:`~.ConnectionBorg` class.
+
+::
+
+    conn = ConnectionBorg()
+    conn.create_table(DoomMap, 10, 10, wait_for_active=True)
+
+When creating a table with, you must specify the model class and the desired R/W
+throughput that is to say the peek number of request per seconds you expect
+for you application. For more information, please see `Amazon's official
+documentation <http://aws.amazon.com/dynamodb/faqs/#What_is_provisioned_throughput>`_.
+
+Default behavior is to create the tables asynchronously but you may explicitly
+ask for synchronous creation with ``wait_for_active=True``. Please note that only
+10 tables may be in ``CREATING`` simultaneously.
+
+.. FIXME: limitation, can not update throughput there
+
+
+Example Usage
+-----------
+
+First, create and :py:meth:`~.DynamoDBModel.save` new map in episode 1 and call
+it "Hangar". Let's also register a couple a cheats.
+
+::
+
+    e1m1 = DoomMap()
+    e1m1.episode = 1
+    e1m1.map = 1
+    e1m1.name = u"Hangar"
+    e1m1.cheats = set([u"idkfa", u"iddqd", u"idclip"])
+    e1m1.save()
+
+It is now possible to :py:meth:`~.DynamoDBModel.get` it from the database using
+a conpound index that is to say, both a ``hash_key`` and a ``range_key``. By
+default, ``get`` uses "eventual consistence" for data access but it is possible
+to ask for strongly consistent data using ``consistent_read=True``.
+
+.. TODO: plus d'info sur eventually consistent
+
+::
+
+    # Later on, retrieve that same object from the DB...
+    e1m1 = DoomMap.get((1, 1))
+
+What if I want to get all the maps in a given episode? This is the purpose of the
+:py:meth:`~.DynamoDBModel.query` methode which also allows to filter the results
+based on the ``range_key`` value.
+
+::
+
+    # query all maps of episode 1
+    e1_maps = DoomMap.query(hash_key=1)
+
+    # query all maps of episode 1 with 'map' hash_key > 5
+    from boto.dynamodb.condition import GT
+    e1_maps_after_5 = DoomMap.query(
+        hash_key=1,
+        range_key_condition=GT(5))
+
+Dynamodb-mapper offers much more usage tools like :py:meth:`~.DynamoDBModel.scan`
+and :py:meth:`~.DynamoDBModel.delete`, :py:class:`~.Transaction` support...

docs/pages/overview.rst

 
 - Dates nested in a dict or set can not be saved as ``datetime`` does not support
     JSON serialization. (issue #7)
-
-Quick example
-=============
-
-Setup Dynamodb-mapper
----------------------
-
-Instalation
-
->>> pip install dynamodb-mapper
-
-Set you Amazon's API credential in ``~/.boto``
-
-.. code-block:: ini
-
-    [Credentials]
-    aws_access_key_id = <your access key>
-    aws_secret_access_key = <your secret key>
-
-For advance configuration, please see the `official Boto documentation <http://docs.pythonboto.org/en/latest/boto_config_tut.html>`_.
-
-
-Example model: DoomMap
-----------------------
-
-::
-
-    from dynamodb_mapper.model import DynamoDBModel
-
-
-    class DoomMap(DynamoDBModel):
-        __table__ = "doom_map"
-        __hash_key__ = "episode"
-        __range_key__ = "map"
-        __schema__ = {
-            "episode": int,
-            "map": int,
-            "name": unicode,
-            "cheats": set,
-        }
-        __defaults__ = {
-            "cheats": set(['Konami']),
-        }
-
-
-Initial Table creation
-----------------------
-::
-
-    conn = ConnectionBorg()
-    conn.create_table(DoomMap, 10, 10, wait_for_active=True)
-
-
-Model Usage
------------
-
-::
-
-    e1m1 = DoomMap()
-    e1m1.episode = 1
-    e1m1.map = 1
-    e1m1.name = u"Hangar"
-    e1m1.cheats = set(["idkfa", "iddqd", "idclip"])
-    e1m1.save()
-
-
-    # Later on, retrieve that same object from the DB...
-    e1m1 = DoomMap.get((1, 1))
-
-    # query on hash+range-keyed tables
-    e1_maps = DoomMap.query(hash_key=1)
-
-    from boto.dynamodb.condition import GT
-    e1_maps_after_5 = DoomMap.query(
-        hash_key=1,
-        range_key_condition=GT(5))
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.