Jean-Tiare Le Bigot avatar Jean-Tiare Le Bigot committed d79d007

add DynamoDB api documentation

Comments (0)

Files changed (5)

+=================
+ddbmock 1.0.0.dev
+=================
+
+This section documents all user visible changes included between ddbmock
+versions 0.4.1 and versions 1.0.0
+
+Additions
+---------
+
+ - Add documentation for ``Table`` internal API
+ - Add documentation for ``DynamoDB`` (database) internal API
+
+Changes
+-------
+
+  - Add a ``truncate`` method to the tables
+
+
 ==========================
 ddbmock 0.4.1 aka 1.0.0 RC
 ==========================

ddbmock/database/db.py

 # All validations are performed on *incomming* data => already done :)
 
 class DynamoDB(object):
+    """
+    Main database, behaves as a singleton in the sense that all instances share
+    the same data.
+
+    If underlying store supports it, all tables schema are persisted at creation
+    time to a special table ``~*schema*~`` which is an invalid DynamoDB table name
+    so no collisions are to be expected.
+    """
     _shared_data = {
         'data': {},
         'store': None,
     }
 
     def __init__(self):
+        """
+        When first instanciated, ``__init__`` checks the underlying store for
+        potentially persisted tables. If any, it reloads there schema to make
+        them available to the application.
+
+        In all other cases, ``__init__`` simply loads the shared state.
+        """
         cls = type(self)
         self.__dict__ = cls._shared_data
 
                 self.data[table.name] = table
 
     def hard_reset(self):
+        """
+        Reset and drop all tables. If any data was persisted, it will be completely
+        lost after a call to this method. I do use in ``tearDown`` of all ddbmock
+        tests to avaid any side effect.
+        """
         for table in self.data.values():
-            table.store.truncate() # FIXME: should be moved in table
+            table.truncate()
+
         self.data.clear()
         self.store.truncate()
 
     def list_tables(self):
+        """
+        Get a list of all table names.
+        """
         return self.data.keys()
 
     def get_table(self, name):
+        """
+        Get a handle to :py:class:`ddbmock.database.table.Table` '``name``' is it exists.
+
+        :param name: Name of the table to load.
+
+        :return: :py:class:`ddbmock.database.table.Table` with name '``name``'
+
+        :raises: :py:exc:`ddbmock.errors.ResourceNotFoundException` if the table does not exist.
+        """
         if name in self.data:
             return self.data[name]
         raise ResourceNotFoundException("Table {} does not exist".format(name))
 
     def create_table(self, name, data):
+        """
+        Create a :py:class:`ddbmock.database.table.Table` named '``name``'' using
+        parameters provided in ``data`` if it does not yet exist.
+
+        :param name: Valid table name. No further checks are performed.
+        :param data: raw DynamoDB request data.
+
+        :return: A reference to the newly created :py:class:`ddbmock.database.table.Table`
+
+        :raises: :py:exc:`ddbmock.errors.ResourceInUseException` if the table already exists.
+        :raises: :py:exc:`ddbmock.errors.LimitExceededException` if more than :py:const:`ddbmock.config.MAX_TABLES` already exist.
+        """
         if name in self.data:
             raise ResourceInUseException("Table {} already exists".format(name))
         if len(self.data) >= config.MAX_TABLES:
         self.store[name, False] = self.data[name]
         return self.data[name]
 
-    # FIXME: what if the table ref changed in the mean time ?
     def _internal_delete_table(self, table):
         """This is ran only after the timer is exhausted.
         Important note: this function is idempotent. If another table with the
         exist at that moment and possibly still handle pending requests. This also
         allows to safely return a handle to the table object.
 
-        :param name: Table name
-        :return: The :py:class:ddbmock.database.table.Table object referenced by ``name``
+        :param name: Valid table name.
+
+        :return: A reference to :py:class:`ddbmock.database.table.Table` named ``name``
         """
         if name not in self.data:
             raise ResourceNotFoundException("Table {} does not exist".format(name))
         return table
 
     def get_batch(self, batch):
+        """
+        Batch processor. Dispatches call to appropriate :py:class:`ddbmock.database.table.Table`
+        methods. This is the only low_level API that directly pushes throughput usage.
+
+        :param batch: raw DynamoDB request batch.
+
+        :returns: dict compatible with DynamoDB API
+
+        :raises: :py:exc:`ddbmock.errors.ValidationException` if a ``range_key`` was provided while table has none.
+        :raises: :py:exc:`ddbmock.errors.ResourceNotFoundException` if a table does not exist.
+        """
         ret = defaultdict(dict)
 
         for tablename, batch in batch.iteritems():
         return ret
 
     def write_batch(self, batch):
+        """
+        Batch processor. Dispatches call to appropriate :py:class:`ddbmock.database.table.Table`
+        methods. This is the only low_level API that directly pushes throughput usage.
+
+        :param batch: raw DynamoDB request batch.
+
+        :returns: dict compatible with DynamoDB API
+
+        :raises: :py:exc:`ddbmock.errors.ValidationException` if a ``range_key`` was provided while table has none.
+        :raises: :py:exc:`ddbmock.errors.ResourceNotFoundException` if a table does not exist.
+        """
         ret = defaultdict(dict)
 
         for tablename, operations in batch.iteritems():
 
         return ret
 
-# reference instance
 dynamodb = DynamoDB()
+"""Reference :py:class:`DynamoDB` instance. You should use it directly"""

ddbmock/database/table.py

         is updated to ``ACTIVE``, the table is immediately available. This is a
         slight difference with real DynamooDB to ease unit and functionnal tests.
 
-        :param name: Valid table name. No checks are performed.
+        :param name: Valid table name. No further checks are performed.
         :param rt: Provisioned read throughput.
         :param wt: Provisioned write throughput.
         :param hash_key: :py:class:`ddbmock.database.key.Key` instance describe the ``hash_key``
 
         schedule_action(config.DELAY_CREATING, self.activate)
 
+    def truncate(self):
+        """
+        Remove all Items from this table. This is like a reset. Might be very
+        usefull in unit and functional tests.
+        """
+        self.store.truncate()
+
     def delete(self):
         """
         If the table was ``ACTIVE``, update its state to ``DELETING``. This is
 
         See :py:meth:`__init__` for more insight.
 
-        :param data: raw DynamoDB request data
+        :param data: raw DynamoDB request data.
 
         :return: fully initialized :py:class:`Table` instance
         """

docs/api/database/db.rst

+##############
+DynamoDB class
+##############
+
+.. currentmodule:: ddbmock.database.db
+
+.. autoclass:: DynamoDB
+
+Constructors
+============
+
+__init__
+--------
+
+.. automethod:: DynamoDB.__init__
+
+Batch data manipulations
+========================
+
+get_batch
+---------
+
+.. automethod:: DynamoDB.get_batch
+
+write_batch
+-----------
+
+.. automethod:: DynamoDB.write_batch
+
+Database management
+===================
+
+list_tables
+-----------
+
+.. automethod:: DynamoDB.list_tables
+
+create_table
+------------
+
+.. automethod:: DynamoDB.create_table
+
+delete_table
+------------
+
+.. automethod:: DynamoDB.delete_table
+
+get_table
+---------
+
+.. automethod:: DynamoDB.get_table
+
+hard_reset
+----------
+
+.. automethod:: DynamoDB.hard_reset

docs/api/database/table.rst

+###########
+Table class
+###########
+
+.. currentmodule:: ddbmock.database.table
+
+.. autoclass:: Table
+
+Constructors
+============
+
+__init__
+--------
+
+.. automethod:: Table.__init__
+
+from_dict
+---------
+
+.. automethod:: Table.from_dict
+
+Table manipulations
+===================
+
+truncate
+--------
+
+.. automethod:: Table.truncate
+
+delete
+------
+
+.. automethod:: Table.delete
+
+activate
+--------
+
+.. automethod:: Table.activate
+
+update_throughput
+-----------------
+
+.. automethod:: Table.update_throughput
+
+get_size
+--------
+
+.. automethod:: Table.get_size
+
+to_dict
+-------
+
+.. automethod:: Table.to_dict
+
+Items manipulations
+===================
+
+delete_item
+-----------
+
+.. automethod:: Table.delete_item
+
+update_item
+-----------
+
+.. automethod:: Table.update_item
+
+put
+---
+
+.. automethod:: Table.put
+
+get
+---
+
+.. automethod:: Table.get
+
+query
+-----
+
+.. automethod:: Table.query
+
+scan
+----
+
+.. automethod:: Table.scan
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.