[Checkins] SVN: zope.location/trunk/ Move narrative doctest file into Sphinx docs.
Tres Seaver
cvs-admin at zope.org
Thu Jun 7 01:31:52 UTC 2012
Log message for revision 126642:
Move narrative doctest file into Sphinx docs.
Changed:
_U zope.location/trunk/
U zope.location/trunk/docs/index.rst
A zope.location/trunk/docs/narr.rst
D zope.location/trunk/src/zope/location/location.txt
-=-
Modified: zope.location/trunk/docs/index.rst
===================================================================
--- zope.location/trunk/docs/index.rst 2012-06-07 01:31:45 UTC (rev 126641)
+++ zope.location/trunk/docs/index.rst 2012-06-07 01:31:48 UTC (rev 126642)
@@ -6,6 +6,7 @@
.. toctree::
:maxdepth: 2
+ narr
Indices and tables
Copied: zope.location/trunk/docs/narr.rst (from rev 126641, zope.location/trunk/src/zope/location/location.txt)
===================================================================
--- zope.location/trunk/docs/narr.rst (rev 0)
+++ zope.location/trunk/docs/narr.rst 2012-06-07 01:31:48 UTC (rev 126642)
@@ -0,0 +1,210 @@
+Using :mod:`zope.location`
+==========================
+
+Location Base Class
+-------------------
+
+The `Location` base class is a mix-in that defines `__parent__` and
+`__name__` attributes.
+
+Usage within an Object field:
+
+.. doctest::
+
+ >>> from zope.interface import implementer, Interface
+ >>> from zope.schema import Object
+ >>> from zope.schema.fieldproperty import FieldProperty
+ >>> from zope.location.interfaces import ILocation
+ >>> from zope.location.location import Location
+
+ >>> class IA(Interface):
+ ... location = Object(schema=ILocation, required=False, default=None)
+ >>> @implementer(IA)
+ ... class A(object):
+ ... location = FieldProperty(IA['location'])
+
+ >>> a = A()
+ >>> a.location = Location()
+
+ >>> loc = Location(); loc.__name__ = u'foo'
+ >>> a.location = loc
+
+ >>> loc = Location(); loc.__name__ = None
+ >>> a.location = loc
+
+ >>> loc = Location(); loc.__name__ = 'foo'
+ >>> a.location = loc
+ Traceback (most recent call last):
+ ...
+ WrongContainedType: ([WrongType('foo', <type 'unicode'>, '__name__')], 'location')
+
+
+The func:`~zope.location.location.inside` Function
+--------------------------------------------------
+
+The `inside` function tells if l1 is inside l2. L1 is inside l2 if l2 is an
+ancestor of l1.
+
+.. doctest::
+
+ >>> o1 = Location()
+ >>> o2 = Location(); o2.__parent__ = o1
+ >>> o3 = Location(); o3.__parent__ = o2
+ >>> o4 = Location(); o4.__parent__ = o3
+
+ >>> from zope.location.location import inside
+
+ >>> inside(o1, o1)
+ True
+
+ >>> inside(o2, o1)
+ True
+
+ >>> inside(o3, o1)
+ True
+
+ >>> inside(o4, o1)
+ True
+
+ >>> inside(o1, o4)
+ False
+
+ >>> inside(o1, None)
+ False
+
+
+:class:`~zope.location.location.LocationProxy`
+----------------------------------------------
+
+`LocationProxy` is a non-picklable proxy that can be put around
+objects that don't implement `ILocation`.
+
+.. doctest::
+
+ >>> from zope.location.location import LocationProxy
+ >>> l = [1, 2, 3]
+ >>> ILocation.providedBy(l)
+ False
+ >>> p = LocationProxy(l, "Dad", "p")
+ >>> p
+ [1, 2, 3]
+ >>> ILocation.providedBy(p)
+ True
+ >>> p.__parent__
+ 'Dad'
+ >>> p.__name__
+ 'p'
+
+ >>> import pickle
+ >>> p2 = pickle.dumps(p)
+ Traceback (most recent call last):
+ ...
+ TypeError: Not picklable
+
+Proxies should get their doc strings from the object they proxy:
+
+.. doctest::
+
+ >>> p.__doc__ == l.__doc__
+ True
+
+If we get a "located class" somehow, its doc string well be available
+through proxy as well:
+
+.. doctest::
+
+ >>> class LocalClass(object):
+ ... """This is class that can be located"""
+
+ >>> p = LocationProxy(LocalClass)
+ >>> p.__doc__ == LocalClass.__doc__
+ True
+
+:func:`~zope.location.location.LocationInterator`
+-------------------------------------------------
+
+This function allows us to iterate over object and all its parents.
+
+.. doctest::
+
+ >>> from zope.location.location import LocationIterator
+
+ >>> o1 = Location()
+ >>> o2 = Location()
+ >>> o3 = Location()
+ >>> o3.__parent__ = o2
+ >>> o2.__parent__ = o1
+
+ >>> iter = LocationIterator(o3)
+ >>> iter.next() is o3
+ True
+ >>> iter.next() is o2
+ True
+ >>> iter.next() is o1
+ True
+ >>> iter.next()
+ Traceback (most recent call last):
+ ...
+ StopIteration
+
+
+The :func:`~zope.location.location.located` function
+----------------------------------------------------
+
+`located` locates an object in another and returns it:
+
+.. doctest::
+
+ >>> from zope.location.location import located
+ >>> a = Location()
+ >>> parent = Location()
+ >>> a_located = located(a, parent, 'a')
+ >>> a_located is a
+ True
+ >>> a_located.__parent__ is parent
+ True
+ >>> a_located.__name__
+ 'a'
+
+If we locate the object again, nothing special happens:
+
+.. doctest::
+
+ >>> a_located_2 = located(a_located, parent, 'a')
+ >>> a_located_2 is a_located
+ True
+
+If the object does not provide ILocation an adapter can be provided:
+
+.. doctest::
+
+ >>> import zope.interface
+ >>> import zope.component
+ >>> sm = zope.component.getGlobalSiteManager()
+ >>> sm.registerAdapter(LocationProxy, required=(zope.interface.Interface,))
+
+ >>> l = [1, 2, 3]
+ >>> parent = Location()
+ >>> l_located = located(l, parent, 'l')
+ >>> l_located.__parent__ is parent
+ True
+ >>> l_located.__name__
+ 'l'
+ >>> l_located is l
+ False
+ >>> type(l_located)
+ <class 'zope.location.location.LocationProxy'>
+ >>> l_located_2 = located(l_located, parent, 'l')
+ >>> l_located_2 is l_located
+ True
+
+When changing the name, we still do not get a different proxied object:
+
+.. doctest::
+
+ >>> l_located_3 = located(l_located, parent, 'new-name')
+ >>> l_located_3 is l_located_2
+ True
+
+ >>> sm.unregisterAdapter(LocationProxy, required=(zope.interface.Interface,))
+ True
Deleted: zope.location/trunk/src/zope/location/location.txt
===================================================================
--- zope.location/trunk/src/zope/location/location.txt 2012-06-07 01:31:45 UTC (rev 126641)
+++ zope.location/trunk/src/zope/location/location.txt 2012-06-07 01:31:48 UTC (rev 126642)
@@ -1,191 +0,0 @@
-========
-Location
-========
-
-Location Base Class
--------------------
-
-The `Location` base class is a stupid mix-in that defines `__parent__` and
-`__name__` attributes.
-
-Usage within an Object field:
-
- >>> from zope.interface import implementer, Interface
- >>> from zope.schema import Object
- >>> from zope.schema.fieldproperty import FieldProperty
- >>> from zope.location.interfaces import ILocation
- >>> from zope.location.location import Location
-
- >>> class IA(Interface):
- ... location = Object(schema=ILocation, required=False, default=None)
- >>> @implementer(IA)
- ... class A(object):
- ... location = FieldProperty(IA['location'])
-
- >>> a = A()
- >>> a.location = Location()
-
- >>> loc = Location(); loc.__name__ = u'foo'
- >>> a.location = loc
-
- >>> loc = Location(); loc.__name__ = None
- >>> a.location = loc
-
- >>> loc = Location(); loc.__name__ = 'foo'
- >>> a.location = loc
- Traceback (most recent call last):
- ...
- WrongContainedType: ([WrongType('foo', <type 'unicode'>, '__name__')], 'location')
-
-
-The `inside` Function
----------------------
-
-The `inside` function tells if l1 is inside l2. L1 is inside l2 if l2 is an
-ancestor of l1.
-
- >>> o1 = Location()
- >>> o2 = Location(); o2.__parent__ = o1
- >>> o3 = Location(); o3.__parent__ = o2
- >>> o4 = Location(); o4.__parent__ = o3
-
- >>> from zope.location.location import inside
-
- >>> inside(o1, o1)
- True
-
- >>> inside(o2, o1)
- True
-
- >>> inside(o3, o1)
- True
-
- >>> inside(o4, o1)
- True
-
- >>> inside(o1, o4)
- False
-
- >>> inside(o1, None)
- False
-
-
-LocationProxy
--------------
-
-The LocationProxy is a non-picklable proxy that can be put around
-objects that don't implement `ILocation`.
-
- >>> from zope.location.location import LocationProxy
- >>> l = [1, 2, 3]
- >>> ILocation.providedBy(l)
- False
- >>> p = LocationProxy(l, "Dad", "p")
- >>> p
- [1, 2, 3]
- >>> ILocation.providedBy(p)
- True
- >>> p.__parent__
- 'Dad'
- >>> p.__name__
- 'p'
-
- >>> import pickle
- >>> p2 = pickle.dumps(p)
- Traceback (most recent call last):
- ...
- TypeError: Not picklable
-
-Proxies should get their doc strings from the object they proxy:
-
- >>> p.__doc__ == l.__doc__
- True
-
-If we get a "located class" somehow, its doc string well be available
-through proxy as well:
-
- >>> class LocalClass(object):
- ... """This is class that can be located"""
-
- >>> p = LocationProxy(LocalClass)
- >>> p.__doc__ == LocalClass.__doc__
- True
-
-LocationInterator
------------------
-
-This function allows us to iterate over object and all its parents.
-
- >>> from zope.location.location import LocationIterator
-
- >>> o1 = Location()
- >>> o2 = Location()
- >>> o3 = Location()
- >>> o3.__parent__ = o2
- >>> o2.__parent__ = o1
-
- >>> iter = LocationIterator(o3)
- >>> iter.next() is o3
- True
- >>> iter.next() is o2
- True
- >>> iter.next() is o1
- True
- >>> iter.next()
- Traceback (most recent call last):
- ...
- StopIteration
-
-
-The `located` function
-----------------------
-
-`located` locates an object in another and returns it:
-
- >>> from zope.location.location import located
- >>> a = Location()
- >>> parent = Location()
- >>> a_located = located(a, parent, 'a')
- >>> a_located is a
- True
- >>> a_located.__parent__ is parent
- True
- >>> a_located.__name__
- 'a'
-
-If we locate the object again, nothing special happens:
-
- >>> a_located_2 = located(a_located, parent, 'a')
- >>> a_located_2 is a_located
- True
-
-If the object does not provide ILocation an adapter can be provided:
-
- >>> import zope.interface
- >>> import zope.component
- >>> sm = zope.component.getGlobalSiteManager()
- >>> sm.registerAdapter(LocationProxy, required=(zope.interface.Interface,))
-
- >>> l = [1, 2, 3]
- >>> parent = Location()
- >>> l_located = located(l, parent, 'l')
- >>> l_located.__parent__ is parent
- True
- >>> l_located.__name__
- 'l'
- >>> l_located is l
- False
- >>> type(l_located)
- <class 'zope.location.location.LocationProxy'>
- >>> l_located_2 = located(l_located, parent, 'l')
- >>> l_located_2 is l_located
- True
-
-When changing the name, we still do not get a different proxied object:
-
- >>> l_located_3 = located(l_located, parent, 'new-name')
- >>> l_located_3 is l_located_2
- True
-
- >>> sm.unregisterAdapter(LocationProxy, required=(zope.interface.Interface,))
- True
More information about the checkins
mailing list