Merge lp:~flacoste/lazr.lifecycle/devel into lp:~launchpad-pqm/lazr.lifecycle/trunk

[Francis J. Lacoste]

[Francis J. Lacoste (flacoste)]

Hi Gary,

Here is the initial version of lazr.lifecycle. It brings ObjectDelta, Snapshot and the SQLObject events which have been renamed to the more generic names.

[Gary Poster (gary)]

merge-conditional

Looks good. I have a few changes for readability, below. Other than that, ship it. :-)

Thanks

Gary

...

> === modified file 'src/lazr/lifecycle/README.txt'
> --- src/lazr/lifecycle/README.txt 2009-03-02 21:29:43 +0000
> +++ src/lazr/lifecycle/README.txt 2009-03-05 16:35:08 +0000
> @@ -15,8 +15,14 @@
> along with lazr.lifecycle. If not, see <http://www.gnu.org/licenses/>.
>
> LAZR lifecycle
> -***********
> -
> -This is a pure template for new lazr namespace packages. Whenever you want to
> -make a new lazr subpackage, just branch this code and change all occurrences
> -of 'lifecycle' with whatever your subpackage's name is.
> +**************
> +
> +This package defines three "lifecycle" events that notifies about object

...that notify...

> +creation, modification and deletion. The events include information about the
> +user responsible for the changes.
> +
> +The modification event also includes information about the state of the object
> +before the changes.
> +
> +The module also contains Snapshot support (to save the state of an object for
> +notification) and to compute deltas between version of objects.

Remove parens, add a comma:

The module also contains Snapshot support to save the state of an object for
notification, and to compute deltas between version of objects.

>
> === modified file 'src/lazr/lifecycle/docs/snapshot.txt'
> --- src/lazr/lifecycle/docs/snapshot.txt 2009-03-03 19:34:49 +0000
> +++ src/lazr/lifecycle/docs/snapshot.txt 2009-03-05 15:19:18 +0000
> @@ -117,50 +117,53 @@
> >>> IBar.providedBy(snapshot)
> True
>
> -Snapshots of Iterables
> -----------------------
> -
> -If your some fields is actually an iterable (but not a string), they will be
> -automatically converted to lists when attaching them to
> -the Snapshot object. The example below uses a property that returns
> -a generator for example.
> -
> - >>> class IterableFoo(Foo):
> - ... implements(IFoo)
> +
> +ISnapshotValueFactory
> +---------------------
> +
> +For some fields, assigning the existing value to the snapshot object
> +isn't appropriate. For these case, one can provide a factory registered
> +as an adapter for the value to ISnapshotValueFactory. The result of the
> +adaptation lookup will be stored in the snapshot attribute.
> +
> + >>> from zope.interface import implementer, Interface
> + >>> from zope.component import adapter, getSiteManager
> +
> + >>> class IIterable(Interface):
> + ... """Marker for a value that needs special snapshot need."""

"...that needs a special snapshot"?

> +
> + >>> class EvenOrOddIterable:
> + ... """An object that will be snapshotted specially."""
> + ... implements(IIterable)
> ...
> ... even = True
> ... max = 10
> ...
> - ... @property
> - ... def remotes(self):
> + ... def __iter__(self):
> ... for i in range(self.max):
> ... if i % 2 == 0 and self.even:
> - ... yield 1
> + ... yield i
> ... elif i % 2 == 1 and not self.even:
> - ... yield 1
> + ... ...

review: Approve

[lp:~flacoste/lazr.lifecycle/devel]

34. By Francis J. Lacoste on 2009-03-05

Make example clearer.

35. By Francis J. Lacoste on 2009-03-05

Updates based on Gary's review.

=== modified file 'README.txt'
--- README.txt	2009-03-02 21:29:43 +0000
+++ README.txt	2009-03-05 16:35:08 +0000
@@ -1,8 +1,6 @@
-This is a template for your lazr package.  To start your own lazr package,
-branch this code and change 'lifecycle' to your package's actual name in all
-files.
-
-
+Richer lifecycle events API.
+
+..
     This file is part of lazr.lifecycle.
 
     lazr.lifecycle is free software: you can redistribute it and/or modify it

=== modified file 'src/lazr/lifecycle/README.txt'
--- src/lazr/lifecycle/README.txt	2009-03-02 21:29:43 +0000
+++ src/lazr/lifecycle/README.txt	2009-03-05 16:35:08 +0000
@@ -15,8 +15,14 @@
     along with lazr.lifecycle.  If not, see <http://www.gnu.org/licenses/>.
 
 LAZR lifecycle
-***********
-
-This is a pure template for new lazr namespace packages.  Whenever you want to
-make a new lazr subpackage, just branch this code and change all occurrences
-of 'lifecycle' with whatever your subpackage's name is.
+**************
+
+This package defines three "lifecycle" events that notifies about object
+creation, modification and deletion. The events include information about the
+user responsible for the changes.
+
+The modification event also includes information about the state of the object
+before the changes.
+
+The module also contains Snapshot support (to save the state of an object for
+notification) and to compute deltas between version of objects.

=== modified file 'src/lazr/lifecycle/docs/snapshot.txt'
--- src/lazr/lifecycle/docs/snapshot.txt	2009-03-03 19:34:49 +0000
+++ src/lazr/lifecycle/docs/snapshot.txt	2009-03-05 15:19:18 +0000
@@ -117,50 +117,53 @@
     >>> IBar.providedBy(snapshot)
     True
 
-Snapshots of Iterables
-----------------------
-
-If your some fields is actually an iterable (but not a string), they will be
-automatically converted to lists when attaching them to
-the Snapshot object. The example below uses a property that returns
-a generator for example.
-
-    >>> class IterableFoo(Foo):
-    ...     implements(IFoo)
+
+ISnapshotValueFactory
+---------------------
+
+For some fields, assigning the existing value to the snapshot object
+isn't appropriate. For these case, one can provide a factory registered
+as an adapter for the value to ISnapshotValueFactory. The result of the
+adaptation lookup will be stored in the snapshot attribute.
+
+    >>> from zope.interface import implementer, Interface
+    >>> from zope.component import adapter, getSiteManager
+
+    >>> class IIterable(Interface):
+    ...     """Marker for a value that needs special snapshot need."""
+
+    >>> class EvenOrOddIterable:
+    ...     """An object that will be snapshotted specially."""
+    ...     implements(IIterable)
     ...
     ...     even = True
     ...     max = 10
     ...
-    ...     @property
-    ...     def remotes(self):
+    ...     def __iter__(self):
     ...         for i in range(self.max):
     ...             if i % 2  == 0 and self.even:
-    ...                 yield 1
+    ...                 yield i
     ...             elif i % 2  == 1 and not self.even:
-    ...                 yield 1
+    ...                 yield i
     ...             else:
     ...                 continue
-    >>> even_generator = IterableFoo()
+
+    >>> from lazr.lifecycle.interfaces import ISnapshotValueFactory
+    >>> @implementer(ISnapshotValueFactory)
+    ... @adapter(IIterable)
+    ... def snapshot_iterable(value):
+    ...     return list(value)
+    >>> getSiteManager().registerAdapter(snapshot_iterable)
+
+    >>> even_generator = Foo()
     >>> even_generator.title = 'Even'
     >>> even_generator.description = 'Generates even number below 10.'
+    >>> even_generator.remotes = EvenOrOddIterable()
 
     >>> snapshot = Snapshot(even_generator, providing=IFoo)
     >>> snapshot.remotes == list(even_generator.remotes)
     True
 
-shortlist is used under the hood to convert this, so a warning will be issued
-if the iterables has more than 100 items and an error will be raised if there
-are more than 1000.
-
-    >>> even_generator.max = 202
-    >>> snapshot = Snapshot(even_generator, providing=IFoo)
-    UserWarning: ...
-
-
-    >>> even_generator.max = 2002
-    >>> snapshot = Snapshot(even_generator, providing=IFoo)
-    Traceback (most recent call last):
-    ...
-    ShortListTooBigError: ...
-
+    >>> getSiteManager().unregisterAdapter(snapshot_iterable)
+    True
 

=== modified file 'src/lazr/lifecycle/interfaces.py'
--- src/lazr/lifecycle/interfaces.py	2009-03-03 20:38:02 +0000
+++ src/lazr/lifecycle/interfaces.py	2009-03-05 15:19:18 +0000
@@ -21,7 +21,8 @@
 __all__ = [
     'IObjectCreatedEvent',
     'IObjectDeletedEvent',
-    'IObjectModifiedEvent'
+    'IObjectModifiedEvent',
+    'ISnapshotValueFactory',
     ]
 
 import zope.lifecycleevent.interfaces as z3lifecycle
@@ -49,3 +50,13 @@
         "changed.")
     user = Attribute("The user who modified the object.")
 
+
+class ISnapshotValueFactory(Interface):
+    """This is a marker interface used to obtain snapshot of values.
+
+    The interface isn't meant to be provided, but is only used as a factory
+    lookup. The snapshot value is what should be returned from the adapter
+    lookup.
+    """
+
+

=== removed file 'src/lazr/lifecycle/shortlist.py'
--- src/lazr/lifecycle/shortlist.py	2009-03-03 23:12:10 +0000
+++ src/lazr/lifecycle/shortlist.py	1970-01-01 00:00:00 +0000
@@ -1,89 +0,0 @@
-# Copyright 2009 Canonical Ltd.  All rights reserved.
-#
-# This file is part of lazr.lifecycle
-#
-# lazr.lifecycle is free software: you can redistribute it and/or modify it
-# under the terms of the GNU Lesser General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or (at your
-# option) any later version.
-#
-# lazr.lifecycle is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
-# License for more details.
-#
-# You should have received a copy of the GNU Lesser General Public License
-# along with lazr.lifecycle.  If not, see <http://www.gnu.org/licenses/>.
-
-"""A function to listify iterables but with a maximum size."""
-
-# This should probably live in its own package as it is generally useful.
-# But since none of the other lazr libraries requires it, it's fine here for
-# the moment.
-
-__metaclass__ = type
-
-__all__ = [
-    'shortlist',
-    'ShortListTooBigError'
-    ]
-
-import warnings
-
-
-class ShortListTooBigError(Exception):
-    """This error is raised when the shortlist hardlimit is reached"""
-
-
-def shortlist(sequence, longest_expected=15, hardlimit=None):
-    """Return a listified version of sequence.
-
-    If <sequence> has more than <longest_expected> items, a warning is issued.
-
-    >>> shortlist([1, 2])
-    [1, 2]
-
-    >>> shortlist([1, 2, 3], 2)
-    UserWarning: shortlist() should not be used here. It's meant to listify sequences with no more than 2 items.  There were 3 items.
-    [1, 2, 3]
-
-    >>> shortlist([1, 2, 3, 4], hardlimit=2)
-    Traceback (most recent call last):
-    ...
-    ShortListTooBigError: Hard limit of 2 exceeded.
-
-    >>> shortlist([1, 2, 3, 4], 2, hardlimit=4)
-    UserWarning: shortlist() should not be used here. It's meant to listify sequences with no more than 2 items.  There were 4 items.
-    [1, 2, 3, 4]
-
-    It works on iterable also.
-
-    >>> shortlist(range(10), 5, hardlimit=8) #doctest: +ELLIPSIS
-    Traceback (most recent call last):
-    ...
-    ShortListTooBigError: ...
-
-    """
-    if hardlimit is not None:
-        last = hardlimit + 1
-    else:
-        last = longest_expected + 1
-    if getattr(sequence, '__getitem__', False):
-        results = list(sequence[:last])
-    else:
-        results = []
-        for idx, item in enumerate(sequence):
-            if hardlimit and idx > hardlimit:
-                break
-            results.append(item)
-
-    size = len(results)
-    if hardlimit and size > hardlimit:
-        raise ShortListTooBigError(
-           'Hard limit of %d exceeded.' % hardlimit)
-    elif size > longest_expected:
-        warnings.warn(
-            "shortlist() should not be used here. It's meant to listify"
-            " sequences with no more than %d items.  There were %s items."
-            % (longest_expected, size), stacklevel=2)
-    return results

=== modified file 'src/lazr/lifecycle/snapshot.py'
--- src/lazr/lifecycle/snapshot.py	2009-03-03 20:38:02 +0000
+++ src/lazr/lifecycle/snapshot.py	2009-03-05 15:19:18 +0000
@@ -26,13 +26,13 @@
            'Snapshot',
            ]
 
+from zope.component import queryAdapter
 from zope.interface.interfaces import IInterface
 from zope.interface import directlyProvides
 from zope.schema.interfaces import IField
 from zope.security.proxy import removeSecurityProxy
 
-from lazr.lifecycle.shortlist import shortlist
-
+from lazr.lifecycle.interfaces import ISnapshotValueFactory
 
 _marker = object()
 
@@ -48,6 +48,9 @@
     will also provide the interfaces listed in providing. If no names
     are supplied but an interface is provided, all Fields of that
     interface will be included in the snapshot.
+
+    The attributes are copied by passing them through a ISnapshotValueFactory.
+    The default implementation of that adapter just returns the value itself.
     """
     def __init__(self, ob, names=None, providing=None):
         ob = removeSecurityProxy(ob)
@@ -72,15 +75,11 @@
             if value is _marker:
                 raise AssertionError("Attribute %s not in object %r"
                                      % (name, ob))
-            def should_listify(value):
-                # We listify using shortlist any iterable that isn't one of
-                # the basic types.
-                return (
-                    not isinstance(value, (str, unicode, tuple, list))
-                    and getattr(value, '__iter__', False))
-            if should_listify(value):
-                value = shortlist(value, longest_expected=100, hardlimit=1000)
-            setattr(self, name, value)
+            snapshot_value = queryAdapter(
+                value, ISnapshotValueFactory, default=_marker)
+            if snapshot_value is _marker:
+                snapshot_value = value
+            setattr(self, name, snapshot_value)
 
         if providing is not None:
             directlyProvides(self, providing)

=== modified file 'src/lazr/lifecycle/tests/test_documentation.py'
--- src/lazr/lifecycle/tests/test_documentation.py	2009-03-03 19:29:52 +0000
+++ src/lazr/lifecycle/tests/test_documentation.py	2009-03-05 16:05:12 +0000
@@ -12,8 +12,6 @@
 import unittest
 import warnings
 
-import lazr.lifecycle.shortlist
-
 DOCTEST_FLAGS = (
     doctest.ELLIPSIS |
     doctest.NORMALIZE_WHITESPACE |
@@ -50,6 +48,4 @@
         optionflags=doctest.NORMALIZE_WHITESPACE|doctest.ELLIPSIS
         )
     return unittest.TestSuite((
-        doctest.DocFileSuite(*doctest_files, **options),
-        doctest.DocTestSuite(
-            lazr.lifecycle.shortlist, setUp=setUp, tearDown=tearDown)))
+        doctest.DocFileSuite(*doctest_files, **options)))