[Checkins] SVN: zope.location/trunk/src/zope/location/location. added method quite like in zope.app.container.contained

[Christian Zagrodnick]

Log message for revision 78902:
  added  method quite like  in zope.app.container.contained

Changed:
  U   zope.location/trunk/src/zope/location/location.py
  U   zope.location/trunk/src/zope/location/location.txt

-=-
Modified: zope.location/trunk/src/zope/location/location.py
===================================================================
--- zope.location/trunk/src/zope/location/location.py	2007-08-17 11:48:10 UTC (rev 78901)
+++ zope.location/trunk/src/zope/location/location.py	2007-08-17 11:57:04 UTC (rev 78902)
@@ -44,6 +44,18 @@
     object.__name__ = name
 
 
+def located(object, parent, name=None):
+    """Locate an object in another and return it.
+
+    If the object does not provide ILocation a LocationProxy is returned.
+
+    """
+    if ILocation.providedBy(object):
+        locate(object, parent, name)
+        return object
+    return LocationProxy(object, parent, name)
+
+
 def LocationIterator(object):
     while object is not None:
         yield object

Modified: zope.location/trunk/src/zope/location/location.txt
===================================================================
--- zope.location/trunk/src/zope/location/location.txt	2007-08-17 11:48:10 UTC (rev 78901)
+++ zope.location/trunk/src/zope/location/location.txt	2007-08-17 11:57:04 UTC (rev 78902)
@@ -75,9 +75,13 @@
 
 >>> 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__
@@ -94,3 +98,36 @@
 >>> p.__doc__ == l.__doc__
 True
 
+
+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 the object does not provide ILocation a LocationProxy is returned:
+
+>>> l = [1, 2, 3]
+>>> parent = Location()
+>>> l_located = located(l, parent, 'l')
+>>> l_located
+[1, 2, 3]
+>>> l_located.__parent__ is parent
+True
+>>> l_located.__name__
+'l'
+>>> l_located is l
+False
+>>> type(l_located)
+<class 'zope.location.location.LocationProxy'>