Metadata-Version: 1.1
Name: zc.extrinsicreference
Version: 0.3.0
Summary: Extrinsic reference registries
Home-page: http://pypi.python.org/pypi/zc.extrinsicreference
Author: Zope Corporation and Contributors
Author-email: zope-dev@zope.org
License: ZPL 2.1
Description: ========================
        Extrinsic Key References
        ========================
        
        See ``src/zc/extrinsicreference/README.txt`` for details.
        
        
        Detailed Documentation
        ----------------------
        
        ====================
        Extrinsic References
        ====================
        
        Extrinsic reference registries record a key and one or more values to which
        they refer.  The key and all values must be adaptable to
        zope.app.keyreference.interfaces.IKeyReference.
        
            >>> import zc.extrinsicreference
            >>> references = zc.extrinsicreference.ExtrinsicReferences()
            >>> references.add(1, 2)
            Traceback (most recent call last):
            ...
            TypeError: ('Could not adapt', 1...
            >>> from zope import interface, component
            >>> from zope.app.keyreference.interfaces import IKeyReference
            >>> class IMyObject(interface.Interface):
            ...     "An interface for which we register an IKeyReference adapter"
            ...     id = interface.Attribute("An id unique to IMyObject instances")
            ...
            >>> class MyObject(object):
            ...     interface.implements(IMyObject)
            ...     _id_counter  = 0
            ...     @classmethod
            ...     def _getId(cls):
            ...         val = cls._id_counter
            ...         cls._id_counter += 1
            ...         return val
            ...     def __init__(self):
            ...         self.id = self._getId()
            ...
            >>> class DummyKeyReference(object):
            ...     interface.implements(IKeyReference)
            ...     component.adapts(IMyObject)
            ...     key_type_id = 'zc.extrinsicreference.doctest'
            ...     def __init__(self, obj):
            ...         self.object = obj
            ...     def __call__(self):
            ...         """Get the object this reference is linking to.
            ...         """
            ...         return self.object
            ...     def __hash__(self):
            ...         """Get a unique identifier of the referenced object.
            ...         """
            ...         return hash(self.object.id)
            ...     def __cmp__(self, other):
            ...         """Compare the reference to another reference.
            ...         """
            ...         if self.key_type_id == other.key_type_id:
            ...             return cmp(self.object.id, other.object.id)
            ...         return cmp(self.key_type_id, other.key_type_id)
            ...
            >>> component.provideAdapter(DummyKeyReference)
            >>> object1 = MyObject()
            >>> references.add(object1, 2)
            Traceback (most recent call last):
            ...
            TypeError: ('Could not adapt', 2...
            >>> value1 = MyObject()
            >>> value2 = MyObject()
            >>> references.add(object1, value1)
            >>> references.add(object1, value2)
        
        Values can be retrieved by their key:
        
            >>> set(references.get(object1)) == set((value1, value2))
            True
        
        References can be removed:
        
            >>> references.remove(object1, value1)
            >>> list(references.get(object1)) == [value2]
            True
        
        But if the reference is not registered, removing it raises a KeyError.
        
            >>> references.remove(object1, value1)
            Traceback (most recent call last):
            ...
            KeyError:...
            >>> object2 = MyObject()
            >>> references.remove(object2, value2)
            Traceback (most recent call last):
            ...
            KeyError:...
        
        If you prefer to silently ignore these errors, use `discard`.
        
            >>> references.discard(object1, value1)
            >>> references.discard(object2, value2)
        
        Otherwise, you can use `contains` to determine if the reference exists:
        
            >>> references.contains(object1, value1)
            False
            >>> references.contains(object2, value2)
            False
            >>> references.contains(object1, value2)
            True
        
        If a key has no associated values, an empty iterable is returned:
        
            >>> references.discard(object1, value2)
            >>> list(references.get(object1))
            []
        
        Adding a value more than once does not cause the value to be included
        in the result sequence more than once:
        
            >>> references.add(object1, value1)
            >>> references.add(object1, value1)
            >>> list(references.get(object1)) == [value1]
            True
        
        The `set` method destructively sets the given values for the object.  Repeated
        objects are collapsed to a single instance.
        
            >>> references.set(object1, (value2, object2, value2, value2, object2))
            >>> references.contains(object1, value1)
            False
            >>> len(list(references.get(object1)))
            2
            >>> set(references.get(object1)) == set((value2, object2))
            True
            >>> references.set(object1, ())
            >>> len(list(references.get(object1)))
            0
        
        The `update` method adds values to the previous values, non-destructively.
        
            >>> references.add(object1, value1)
            >>> references.update(object1, (value2, object2, value2))
            >>> len(list(references.get(object1)))
            3
            >>> set(references.get(object1)) == set((value1, value2, object2))
            True
        
        
        =======
        CHANGES
        =======
        
        0.3.0 (2009-08-27)
        ------------------
        
        - Fix errors introduced in 0.2.0 refactoring:
        
          1. Stop referring to extrinsicreference module from ZCML.
             The code is now in ``__init__.py``.
        
          2. Revert `registerShortcut` and `unregisterShortcut` changes.
             These two functions are handlers in ``track_shortcuts.zcml``.
        
          3. Add more package infrastructure, such as this file.
        
        
        0.2.0 (2009-08-26)
        ------------------
        
        - Refactored an existing stable code.
        - Initial release as an egg.
        
Keywords: extrinsic key reference zope zope3
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Zope3
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
