zope.locking

HomePage: UNKNOWN

Author: Zope Project

Download: https://pypi.python.org/packages/source/z/zope.locking/zope.locking-1.2.2.tar.gz

        =======
Changes
=======


------------------
1.2.2 (2011-01-31)
------------------

- Consolidate duplicate evolution code.

- Split generations config into its own zcml file.


------------------
1.2.1 (2010-01-20)
------------------

- Bug fix: the generation added in 1.2 did not properly clean up
  expired tokens, and could leave the token utility in an inconsistent
  state.


----------------
1.2 (2009-11-23)
----------------

- Bug fix: tokens were stored in a manner that prevented them from
  being cleaned up properly in the utility's _principal_ids mapping.
  Make zope.locking.tokens.Token orderable to fix this, as tokens
  are stored as keys in BTrees.

- Add a zope.app.generations Schema Manager to clean up any lingering
  tokens due to this bug.  Token utilities not accessible through the
  component registry can be cleaned up manually with
  zope.locking.generations.fix_token_utility.

- TokenUtility's register method will now add the token to the utility's
  database connection if the token provides IPersistent.

- Clean up the tests and docs and move some common code to testing.py.

- Fix some missing imports.

---
1.1
---

(series for Zope 3.4; eggs)

1.1b
----

- converted to use eggs

---
1.0
---

(series for Zope 3.3; no dependencies on Zope eggs)

1.0b
----

Initial non-dev release


============
Introduction
============

The zope.locking package provides three main features:

- advisory exclusive locks for individual objects;

- advisory shared locks for individual objects; and

- frozen objects (locked to no one).

Locks and freezes by themselves are advisory tokens and inherently
meaningless.  They must be given meaning by other software, such as a security
policy.

This package approaches these features primarily from the perspective of a
system API, largely free of policy; and then provides a set of adapters for
more common interaction with users, with some access policy.  We will first
look at the system API, and then explain the policy and suggested use of the
provided adapters.

==========
System API
==========

The central approach for the package is that locks and freeze tokens must be
created and then registered by a token utility.  The tokens will not work
until they have been registered.  This gives the ability to definitively know,
and thus manipulate, all active tokens in a system.

The first object we'll introduce, then, is the TokenUtility: the utility that
is responsible for the registration and the retrieving of tokens.

    >>> from zope import component, interface
    >>> from zope.locking import interfaces, utility, tokens
    >>> util = utility.TokenUtility()
    >>> from zope.interface.verify import verifyObject
    >>> verifyObject(interfaces.ITokenUtility, util)
    True

The utility only has a few methods--`get`, `iterForPrincipalId`,
`__iter__`, and `register`--which we will look at below.  It is expected to be
persistent, and the included implementation is in fact persistent.Persistent,
and expects to be installed as a local utility.  The utility needs a
connection to the database before it can register persistent tokens.

    >>> lock = tokens.ExclusiveLock(Demo(), 'Fantomas')
    >>> util.register(lock)
    Traceback (most recent call last):
    ...
    AttributeError: 'NoneType' object has no attribute 'add'

    >>> conn.add(util)

If the token provides IPersistent, the utility will add it to its connection.

    >>> lock._p_jar is None
    True

    >>> lock = util.register(lock)
    >>> lock._p_jar is util._p_jar
    True

    >>> lock.end()
    >>> lock = util.register(lock)


The standard token utility can accept tokens for any object that is adaptable
to IKeyReference.

    >>> import datetime
    >>> import pytz
    >>> before_creation = datetime.datetime.now(pytz.utc)
    >>> demo = Demo()

Now, with an instance of the demo class, it is possible to register lock and
freeze tokens for demo instances with the token utility.

As mentioned above, the general pattern for making a lock or freeze token is
to create it--at which point most of its methods and attributes a