[Checkins] SVN: Acquisition/trunk/ README.txt is now in the
ACquisition package.
Philipp von Weitershausen
philikon at philikon.de
Fri Jul 27 14:09:29 EDT 2007
Log message for revision 78386:
README.txt is now in the ACquisition package.
Changed:
D Acquisition/trunk/README.txt
A Acquisition/trunk/README.txt
U Acquisition/trunk/setup.py
-=-
Deleted: Acquisition/trunk/README.txt
===================================================================
--- Acquisition/trunk/README.txt 2007-07-27 18:07:04 UTC (rev 78385)
+++ Acquisition/trunk/README.txt 2007-07-27 18:09:23 UTC (rev 78386)
@@ -1,417 +0,0 @@
-.. contents::
-
-Introductory Example
-====================
-
-Zope implements acquisition with "Extension Class" mix-in classes. To
-use acquisition your classes must inherit from an acquisition base
-class. For example::
-
- >>> import ExtensionClass, Acquisition
-
- >>> class C(ExtensionClass.Base):
- ... color='red'
-
- >>> class A(Acquisition.Implicit):
- ... def report(self):
- ... print self.color
- ...
- >>> a = A()
- >>> c = C()
- >>> c.a = a
-
- >>> c.a.report()
- red
-
- >>> d = C()
- >>> d.color = 'green'
- >>> d.a = a
-
- >>> d.a.report()
- green
-
- >>> a.report() # raises an attribute error
- Traceback (most recent call last):
- ...
- AttributeError: color
-
-The class ``A`` inherits acquisition behavior from
-``Acquisition.Implicit``. The object, ``a``, "has" the color of
-objects ``c`` and d when it is accessed through them, but it has no
-color by itself. The object ``a`` obtains attributes from its
-environment, where its environment is defined by the access path used
-to reach ``a``.
-
-Acquisition Wrappers
-====================
-
-When an object that supports acquisition is accessed through an
-extension class instance, a special object, called an acquisition
-wrapper, is returned. In the example above, the expression ``c.a``
-returns an acquisition wrapper that contains references to both ``c``
-and ``a``. It is this wrapper that performs attribute lookup in ``c``
-when an attribute cannot be found in ``a``.
-
-Acquisition wrappers provide access to the wrapped objects through the
-attributes ``aq_parent``, ``aq_self``, ``aq_base``. Continue the
-example from above::
-
- >>> c.a.aq_parent is c
- True
- >>> c.a.aq_self is a
- True
-
-Explicit and Implicit Acquisition
-=================================
-
-Two styles of acquisition are supported: implicit and explicit
-acquisition.
-
-Implicit acquisition
---------------------
-
-Implicit acquisition is so named because it searches for attributes
-from the environment automatically whenever an attribute cannot be
-obtained directly from an object or through inheritance.
-
-An attribute can be implicitly acquired if its name does not begin
-with an underscore.
-
-To support implicit acquisition, your class should inherit from the
-mix-in class ``Acquisition.Implicit``.
-
-Explicit Acquisition
---------------------
-
-When explicit acquisition is used, attributes are not automatically
-obtained from the environment. Instead, the method aq_acquire must be
-used. For example::
-
- >>> print c.a.aq_acquire('color')
- red
-
-To support explicit acquisition, your class should inherit from the
-mix-in class ``Acquisition.Explicit``.
-
-Controlling Acquisition
------------------------
-
-A class (or instance) can provide attribute by attribute control over
-acquisition. Your should subclass from ``Acquisition.Explicit``, and set
-all attributes that should be acquired to the special value
-``Acquisition.Acquired``. Setting an attribute to this value also allows
-inherited attributes to be overridden with acquired ones. For example::
-
- >>> class C(Acquisition.Explicit):
- ... id=1
- ... secret=2
- ... color=Acquisition.Acquired
- ... __roles__=Acquisition.Acquired
-
-The only attributes that are automatically acquired from containing
-objects are color, and ``__roles__``. Note that the ``__roles__``
-attribute is acquired even though its name begins with an
-underscore. In fact, the special ``Acquisition.Acquired`` value can be
-used in ``Acquisition.Implicit`` objects to implicitly acquire
-selected objects that smell like private objects.
-
-Sometimes, you want to dynamically make an implicitly acquiring object
-acquire explicitly. You can do this by getting the object's
-aq_explicit attribute. This attribute provides the object with an
-explicit wrapper that places the original implicit wrapper.
-
-Filtered Acquisition
-====================
-
-The acquisition method, ``aq_acquire``, accepts two optional
-arguments. The first of the additional arguments is a "filtering"
-function that is used when considering whether to acquire an
-object. The second of the additional arguments is an object that is
-passed as extra data when calling the filtering function and which
-defaults to ``None``. The filter function is called with five
-arguments:
-
-* The object that the aq_acquire method was called on,
-
-* The object where an object was found,
-
-* The name of the object, as passed to aq_acquire,
-
-* The object found, and
-
-* The extra data passed to aq_acquire.
-
-If the filter returns a true object that the object found is returned,
-otherwise, the acquisition search continues.
-
-Here's an example::
-
- >>> from Acquisition import Explicit
-
- >>> class HandyForTesting:
- ... def __init__(self, name):
- ... self.name = name
- ... def __str__(self):
- ... return "%s(%s)" % (self.name, self.__class__.__name__)
- ... __repr__=__str__
- ...
- >>> class E(Explicit, HandyForTesting): pass
- ...
- >>> class Nice(HandyForTesting):
- ... isNice= 1
- ... def __str__(self):
- ... return HandyForTesting.__str__(self)+' and I am nice!'
- ... __repr__=__str__
- ...
- >>> a = E('a')
- >>> a.b = E('b')
- >>> a.b.c = E('c')
- >>> a.p = Nice('spam')
- >>> a.b.p = E('p')
-
- >>> def find_nice(self, ancestor, name, object, extra):
- ... return hasattr(object,'isNice') and object.isNice
-
- >>> print a.b.c.aq_acquire('p', find_nice)
- spam(Nice) and I am nice!
-
-The filtered acquisition in the last line skips over the first
-attribute it finds with the name ``p``, because the attribute doesn't
-satisfy the condition given in the filter.
-
-Filtered acquisition is rarely used in Zope.
-
-Acquiring from Context
-======================
-
-Normally acquisition allows objects to acquire data from their
-containers. However an object can acquire from objects that aren't its
-containers.
-
-Most of the examples we've seen so far show establishing of an
-acquisition context using getattr semantics. For example, ``a.b`` is a
-reference to ``b`` in the context of ``a``.
-
-You can also manually set acquisition context using the ``__of__``
-method. For example::
-
- >>> from Acquisition import Implicit
- >>> class C(Implicit): pass
- ...
- >>> a = C()
- >>> b = C()
- >>> a.color = "red"
- >>> print b.__of__(a).color
- red
-
-In this case, ``a`` does not contain ``b``, but it is put in ``b``'s
-context using the ``__of__`` method.
-
-Here's another subtler example that shows how you can construct an
-acquisition context that includes non-container objects::
-
- >>> from Acquisition import Implicit
-
- >>> class C(Implicit):
- ... def __init__(self, name):
- ... self.name = name
-
- >>> a = C("a")
- >>> a.b = C("b")
- >>> a.b.color = "red"
- >>> a.x = C("x")
-
- >>> print a.b.x.color
- red
-
-Even though ``b`` does not contain ``x``, ``x`` can acquire the color
-attribute from ``b``. This works because in this case, ``x`` is accessed
-in the context of ``b`` even though it is not contained by ``b``.
-
-Here acquisition context is defined by the objects used to access
-another object.
-
-Containment Before Context
-==========================
-
-If in the example above suppose both a and b have an color attribute::
-
- >>> a = C("a")
- >>> a.color = "green"
- >>> a.b = C("b")
- >>> a.b.color = "red"
- >>> a.x = C("x")
-
- >>> print a.b.x.color
- green
-
-Why does ``a.b.x.color`` acquire color from ``a`` and not from ``b``?
-The answer is that an object acquires from its containers before
-non-containers in its context.
-
-To see why consider this example in terms of expressions using the
-``__of__`` method::
-
- a.x -> x.__of__(a)
-
- a.b -> b.__of__(a)
-
- a.b.x -> x.__of__(a).__of__(b.__of__(a))
-
-Keep in mind that attribute lookup in a wrapper is done by trying to
-look up the attribute in the wrapped object first and then in the
-parent object. So in the expressions above proceeds from left to
-right.
-
-The upshot of these rules is that attributes are looked up by
-containment before context.
-
-This rule holds true also for more complex examples. For example,
-``a.b.c.d.e.f.g.attribute`` would search for attribute in ``g`` and
-all its containers first. (Containers are searched in order from the
-innermost parent to the outermost container.) If the attribute is not
-found in ``g`` or any of its containers, then the search moves to
-``f`` and all its containers, and so on.
-
-Additional Attributes and Methods
-=================================
-
-You can use the special method ``aq_inner`` to access an object
-wrapped only by containment. So in the example above,
-``a.b.x.aq_inner`` is equivalent to ``a.x``.
-
-You can find out the acquisition context of an object using the
-aq_chain method like so:
-
- >>> [obj.name for obj in a.b.x.aq_chain]
- ['x', 'b', 'a']
-
-You can find out if an object is in the containment context of another
-object using the ``aq_inContextOf`` method. For example:
-
- >>> a.b.aq_inContextOf(a)
- 1
-
-.. Note: as of this writing the aq_inContextOf examples don't work the
- way they should be working. According to Jim, this is because
- aq_inContextOf works by comparing object pointer addresses, which
- (because they are actually different wrapper objects) doesn't give
- you the expected results. He acknowledges that this behavior is
- controversial, and says that there is a collector entry to change
- it so that you would get the answer you expect in the above. (We
- just need to get to it).
-
-Acquisition Module Functions
-============================
-
-In addition to using acquisition attributes and methods directly on
-objects you can use similar functions defined in the ``Acquisition``
-module. These functions have the advantage that you don't need to
-check to make sure that the object has the method or attribute before
-calling it.
-
-``aq_acquire(object, name [, filter, extra, explicit, default, containment])``
- Acquires an object with the given name.
-
- This function can be used to explictly acquire when using explicit
- acquisition and to acquire names that wouldn't normally be
- acquired.
-
- The function accepts a number of optional arguments:
-
- ``filter``
- A callable filter object that is used to decide if an object
- should be acquired.
-
- The filter is called with five arguments:
-
- * The object that the aq_acquire method was called on,
-
- * The object where an object was found,
-
- * The name of the object, as passed to aq_acquire,
-
- * The object found, and
-
- * The extra argument passed to aq_acquire.
-
- If the filter returns a true object that the object found is
- returned, otherwise, the acquisition search continues.
-
- ``extra``
- Extra data to be passed as the last argument to the filter.
-
- ``explicit``
- A flag (boolean value) indicating whether explicit acquisition
- should be used. The default value is true. If the flag is
- true, then acquisition will proceed regardless of whether
- wrappers encountered in the search of the acquisition
- hierarchy are explicit or implicit wrappers. If the flag is
- false, then parents of explicit wrappers are not searched.
-
- This argument is useful if you want to apply a filter without
- overriding explicit wrappers.
-
- ``default``
- A default value to return if no value can be acquired.
-
- ``containment``
- A flag indicating whether the search should be limited to the
- containment hierarchy.
-
- In addition, arguments can be provided as keywords.
-
-``aq_base(object)``
- Return the object with all wrapping removed.
-
-``aq_chain(object [, containment])``
- Return a list containing the object and it's acquisition
- parents. The optional argument, containment, controls whether the
- containment or access hierarchy is used.
-
-``aq_get(object, name [, default, containment])``
- Acquire an attribute, name. A default value can be provided, as
- can a flag that limits search to the containment hierarchy.
-
-``aq_inner(object)``
- Return the object with all but the innermost layer of wrapping
- removed.
-
-``aq_parent(object)``
- Return the acquisition parent of the object or None if the object
- is unwrapped.
-
-``aq_self(object)``
- Return the object with one layer of wrapping removed, unless the
- object is unwrapped, in which case the object is returned.
-
-In most cases it is more convenient to use these module functions
-instead of the acquisition attributes and methods directly.
-
-Acquisition and Methods
-=======================
-
-Python methods of objects that support acquisition can use acquired
-attributes. When a Python method is called on an object that is
-wrapped by an acquisition wrapper, the wrapper is passed to the method
-as the first argument. This rule also applies to user-defined method
-types and to C methods defined in pure mix-in classes.
-
-Unfortunately, C methods defined in extension base classes that define
-their own data structures, cannot use aquired attributes at this
-time. This is because wrapper objects do not conform to the data
-structures expected by these methods. In practice, you will seldom
-find this a problem.
-
-Conclusion
-==========
-
-Acquisition provides a powerful way to dynamically share information
-between objects. Zope 2 uses acquisition for a number of its key
-features including security, object publishing, and DTML variable
-lookup. Acquisition also provides an elegant solution to the problem
-of circular references for many classes of problems. While acquisition
-is powerful, you should take care when using acquisition in your
-applications. The details can get complex, especially with the
-differences between acquiring from context and acquiring from
-containment.
Added: Acquisition/trunk/README.txt
===================================================================
--- Acquisition/trunk/README.txt (rev 0)
+++ Acquisition/trunk/README.txt 2007-07-27 18:09:23 UTC (rev 78386)
@@ -0,0 +1 @@
+Please refer to src/Acquisition/README.txt.
Modified: Acquisition/trunk/setup.py
===================================================================
--- Acquisition/trunk/setup.py 2007-07-27 18:07:04 UTC (rev 78385)
+++ Acquisition/trunk/setup.py 2007-07-27 18:09:23 UTC (rev 78386)
@@ -24,7 +24,8 @@
"attributes from the containment hierarchy they're in.",
author='Zope Corporation and Contributors',
author_email='zope-dev at zope.org',
- long_description=open('README.txt').read(),
+ long_description=open(
+ os.path.join('src', 'Acquisition', 'README.txt')).read(),
packages=find_packages('src'),
package_dir={'': 'src'},
More information about the Checkins
mailing list