Metadata-Version: 2.1
Name: nti.transactions
Version: 2.0.1
Summary: NTI Transactions Utility
Home-page: https://github.com/NextThought/nti.transactions
Author: Jason Madden
Author-email: jason@nextthought.com
License: Apache
Keywords: ZODB transaction
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Framework :: ZODB
Requires-Dist: setuptools
Requires-Dist: dm.transaction.aborthook
Requires-Dist: perfmetrics
Requires-Dist: transaction (>=2.2.1)
Requires-Dist: zope.exceptions
Requires-Dist: zope.interface
Provides-Extra: gevent
Requires-Dist: gevent ; extra == 'gevent'
Provides-Extra: test
Requires-Dist: zope.testrunner ; extra == 'test'
Requires-Dist: nti.testing ; extra == 'test'
Requires-Dist: fudge ; extra == 'test'

==================
 nti.transactions
==================


.. _transaction: https://pypi.python.org/pypi/transaction

.. image:: https://coveralls.io/repos/github/NextThought/nti.transactions/badge.svg?branch=master
	:target: https://coveralls.io/github/NextThought/nti.transactions?branch=master

.. image:: https://travis-ci.org/NextThought/nti.transactions.svg?branch=master
    :target: https://travis-ci.org/NextThought/nti.transactions

Extensions to the `transaction`_ package.

Transaction Manager
===================

``nti.transactions.transactions.TransactionsLoop`` is a retryable
transaction manager. It is conceptually similar to the `attempts`_
context manager provided by the transaction package itself, but much
more powerful and extensible via subclasses. Features include:

- Configurable commit vetos.
- Extensible tests for which exceptions should be retried.
- The ability to abort the transaction and bypass a potentially
  expensive commit when there are expected to be no side-effects.
- Sleeping between retries.
- Extensive logging and timing.

The TransactionLoop can be used as-is, or it can be subclassed for
customization. For use in a Pyramid tween, for example, a minimal
subclass might look like this::

  >>> class PyramidTransactionLoop(TransactionLoop):
  ...    def prep_for_retry(self, number, request):
  ...        request.make_body_seekable()
  ...    def describe_transaction(self, request):
  ...        return request.url

Data Managers
=============

A few `data managers`_ are provided for convenience.

The first data manager is used to put an object in a ``queue``
(something with the ``full`` and ``put_nowait`` methods) when a
transaction succeeds. If the queue is full, then the transaction will
not be allowed to commit::

  >>> from nti.transactions.transactions import put_nowait
  >>> put_nowait(queue, object)

This is a special case of the ``ObjectDataManager``, which will call
one method with any arguments when a transaction commits. It can be
configured to vote on whether the transaction should be allowed to commit.
or not. This is useful for, say, putting an item in a Redis queue when
the transaction is successful. It can be constructed directly, but the
``do`` function is a shorthand way of joining one to the current
transaction::

  >>> from nti.transactions.transactions import do
  >>> do(print, args=("Committed"))

.. caution:: See the documentation of this object for numerous
			 warnings about side-effects and its interaction with the
			 transaction machinery. Use it with care!

.. _attempts: http://zodb.readthedocs.io/en/latest/transactions.html#retrying-transactions
.. _data managers: http://zodb.readthedocs.io/en/latest/transactions.html#data-managers

Changes
========

2.0.1 (2019-09-03)
------------------

- Fix compatibility with perfmetrics 3.0: drop ``from __future__
  import unicode_literals``.


2.0.0 (2018-07-20)
------------------

- Use the new public ``isRetryableError`` in transaction 2.2. The
  interface for this package is unchanged, but a major version bump of
  a dependency necessitates a major bump here. See `issue 12
  <https://github.com/NextThought/nti.transactions/issues/12>`_.

- Test support for Python 3.7; remove test support for Python 3.4.

- ``TransactionLoop`` is more careful to not keep traceback objects
  around, especially on Python 2.

1.1.1 (2018-07-19)
------------------

- When the ``TransactionLoop`` raises a ``CommitFailedError`` from a
  ``TypeError``, it preserves the original message.

- Test support for Python 3.6.

1.1.0 (2017-04-17)
------------------

- Add a new ObjectDataManager that will attempt to execute after
  other ObjectDataManagers.


1.0.0 (2016-07-28)
------------------

- Add support for Python 3.
- Eliminate ZODB dependency. Instead of raising a
  ``ZODB.POSException.StorageError`` for unexpected ``TypeErrors``
  during commit, the new class
  ``nti.transactions.interfaces.CommitFailedError`` is raised.
- Introduce a new subclass of ``TransactionError``,
  ``AbortFailedError`` that is raised when an abort fails due to a
  system error.


