Commits

Jean-Tiare Le Bigot committed 602c95d

transaction hight level doc

Comments (0)

Files changed (2)

docs/api/transaction.rst

 transaction. Amazon's DynamoDB has no "out of the box" transaction engines but
 provides this parameter as an elementary block for this purpose.
 
+Transaction concepts
+====================
+
+In Dynamodb-mapper, transactions *are* plain ``DynamoDBModel`` thus allowing
+them to persist their state.
+
+Transactions operates on a list of 'targets'. For each target, it needs list of
+``transactors``. ``transactors`` are tuples of ``(getter, setter)``. The getter
+is responsible of getting a fresh copy of the target from the target while setter
+performs the modifications. The call to save is handled by the engine itself.
+
+For each target, the transaction engine will successively call ``getter`` and
+``setter`` until ``save()`` succeeds. ``save()`` will succeed if and only if
+the target has not been altered by another thread in the mean time thus avoiding
+the lost update syndrome.
+
+Optionally, transactions may define a :py:meth:`~.Transactions._setup` method
+which will be called before any transactors.
+
+Unless the transaction is explicitely marked ``transient``, its state will be
+persisted to a dedicated table. ``Transaction`` base class embeds a minimal
+schema that should suit most applications but may be overloaded as long as a
+``datetime`` ``range_key`` is preserved along with a ``unicode`` ``status``
+field.
+
+Using the transaction engine
+============================
+
+To use the transaction engine, all you have to do is to define `__table__` and
+overload ``_get_transactors()``. Of course the transactors will themselves will
+need to be implemented. Optionally, you may overload the whole schema or set
+``transient=True``. A ``_setup()`` method may also be implemented.
 
 
 Related exceptions

docs/pages/overview.rst

 
 .. TODO: add links to related documentation
 
+Logging
+=======
+
+Dynamodb-mapper uses 3 "logging" loggers:
+
+- model
+- model.database-access
+- transactions
+
+.. example de parametrage de la sortie
+
 Known limitations
 =================
 
-- Dates nested in a dict or set can not be saved as ``datetime`` does not support
-    JSON serialization. (issue #7)
+- Dates nested in a dict or set can not be saved as ``datetime`` does not support JSON serialization. (issue #7)