Commits

Jean-Tiare LE BIGOT  committed 64304f4

add ItemSize documentation

  • Participants
  • Parent commits d79d007

Comments (0)

Files changed (5)

 
  - Add documentation for ``Table`` internal API
  - Add documentation for ``DynamoDB`` (database) internal API
+ - Add documentation for ``Key`` internal API
+ - Add documentation for ``Item`` and ``ItemSize`` internal API
 
 Changes
 -------

File ddbmock/database/item.py

 
 
 def _decode_field(field):
+    """
+    Read a field's type and value
+
+    :param field: Raw DynamoDB request field of the form ``{'typename':'value'}``
+
+    :return: (typename, value) string tuple
+    """
     return field.items()[0]
 
 class ItemSize(int):
+    """
+    Utility class to represent an :py:class:`Item` size as bytes or capacity units
+    """
     def __add__(self, value):
+        """
+        Transparently allow addition of ``ItemSize`` values. This is useful for
+        all batch requests as ``Scan``, ``Query``, ``BatchWriteItem`` and
+        ``BatchReadItem``
+
+        :param value: foreign int compatible value to add
+
+        :return: new :py:class:`ItemSize` value
+
+        :raises: ``TypeError`` if ``value`` is not int compatible
+        """
         return ItemSize(int.__add__(self, value))
 
     def as_units(self):
-        """Get item size in terms of capacity units. This does *not* include the
-        index overhead. Units can *not* be bellow 1 ie: a "delete" on a non
+        """
+        Get item size in terms of capacity units. This does *not* include the
+        index overhead. Units can *not* be bellow 1 ie: a ``DeleteItem`` on a non
         existing item is *not* free
+
+        :return: number of capacity unit consummed by any operation on this ``ItemSize``
         """
         return max(1, int(ceil((self) / 1024.0)))
 
     def with_indexing_overhead(self):
-        """Take the indexing overhead into account. this is especially usefull
+        """
+        Take the indexing overhead into account. this is especially usefull
         to compute the table disk size as DynamoDB would but it's not included
         in the capacity unit calculation.
+
+        :return: ``ItemSize`` + :py:const:`ddbmock.config.INDEX_OVERHEAD`
         """
         return self + config.INDEX_OVERHEAD
 

File ddbmock/database/key.py

 from ddbmock.errors import ValidationException
 
 class Key(object):
+    """
+    Abstraction layer over DynamoDB Keys in :py:class:`ddbmock.databas.item.Item`
+    """
     def __init__(self, name, typename):
+        """
+        High level Python constructor
+
+        :param name: Valid key name. No further checks are performed.
+        :param typename: Valid key typename. No further checks are performed.
+        """
         self.name = name
         self.typename = typename
 
     def read(self, key):
-        """Parse a key as specified by DynamoDB API and return its value as long as
-            its typename matches self.typename
+        """
+        Parse a key as specified by DynamoDB API and return its value as long as
+        its typename matches :py:attr:`typename`
+
+        :param key: Raw DynamoDB request key.
+
+        :return: the value of the key
         """
         typename, value = key.items()[0]
         if self.typename != typename:
         return value
 
     def to_dict(self):
-        """Return the a dict form of the key, suitable for DynamoDb API
+        """
+        Return the key as a Python dict.
+
+        :return: Serialized version of the key definition metadata compatible with DynamoDB API syntax.
         """
         return {
             "AttributeName": self.name,
 
     @classmethod
     def from_dict(cls, data):
+        """
+        Alternate constructor which deciphers raw DynamoDB request data before
+        ultimately calling regular ``__init__`` method.
+
+        See :py:meth:`__init__` for more insight.
+
+        :param data: raw DynamoDB request data.
+
+        :return: fully initialized :py:class:`Key` instance
+        """
         return cls(data[u'AttributeName'], data[u'AttributeType'])
 
 class PrimaryKey(Key):
+    """Special marker to provide distinction between regulat Keys and PrimaryKey"""
     pass

File docs/api/database/itemsize.rst

+##############
+ItemSize class
+##############
+
+.. currentmodule:: ddbmock.database.item
+
+.. autoclass:: ItemSize
+
+ItemSize manipulations
+======================
+
+__add__
+-------
+
+.. automethod:: ItemSize.__add__
+
+as_units
+--------
+
+.. automethod:: ItemSize.as_units
+
+with_indexing_overhead
+----------------------
+
+.. automethod:: ItemSize.with_indexing_overhead
+

File docs/api/database/key.rst

+##########
+Key class
+##########
+
+.. currentmodule:: ddbmock.database.key
+
+.. autoclass:: Key
+
+Constructors
+============
+
+__init__
+--------
+
+.. automethod:: Key.__init__
+
+from_dict
+---------
+
+.. automethod:: Key.from_dict
+
+Key manipulations
+=================
+
+read
+----
+
+.. automethod:: Key.read
+
+to_dict
+-------
+
+.. automethod:: Key.to_dict
+
+PrimaryKey
+==========
+
+.. autoclass:: PrimaryKey