Acquisition 4.11

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

>>> try:
...     a.report()
... except AttributeError:
...     pass
... else:
...     raise AssertionError('AttributeError not raised.')

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. You 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 replaces 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(object):
...     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)
True

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 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.

4.11 (2022-09-16)

• Add support for Python 3.11 (as of 3.11.0rc1).

• Switch from -Ofast to -O3 when compiling code for Linux wheels. (#64)

4.10 (2021-12-07)

• Fix bug in the PURE_PYTHON version affecting aq_acquire applied to a class with a filter.

• Improve interface documentation.

• Add support for Python 3.10.

4.9 (2021-08-19)

• On CPython no longer omit compiling the C code when PURE_PYTHON is required. Just evaluate it at runtime. (#53)

4.8 (2021-07-20)

• Various fixes for the PURE_PYTHON version, e.g. make Acquired an str (as required by Zope), avoid infinite __cmp__ loop. (#51, #48)

• Create aarch64 wheels.

4.7 (2020-10-07)

• Add support for Python 3.8 and 3.9.

4.6 (2019-04-24)

• Drop support for Python 3.4.

• Add support for Python 3.8a3.

• Add support to call bytes() on an object wrapped by an ImplicitAcquisitionWrapper. (#38)

4.5 (2018-10-05)

• Avoid deprecation warnings by using current API.

• Add support for Python 3.7.

4.4.4 (2017-11-24)

• Add Appveyor configuration to automate building Windows eggs.

4.4.3 (2017-11-23)

• Fix the extremely rare potential for a crash when the C extensions are in use. See issue 21.

4.4.2 (2017-05-12)

• Fix C capsule name to fix import errors.

• Ensure our dependencies match our expactations about C extensions.

4.4.1 (2017-05-04)

• Fix C code under Python 3.4, with missing Py_XSETREF.

4.4.0 (2017-05-04)

• Enable the C extension under Python 3.

• Drop support for Python 3.3.

4.3.0 (2017-01-20)

• Make tests compatible with ExtensionClass 4.2.0.

• Drop support for Python 2.6 and 3.2.

• Add support for Python 3.5 and 3.6.

4.2.2 (2015-05-19)

• Make the pure-Python Acquirer objects cooperatively use the superclass __getattribute__ method, like the C implementation. See https://github.com/zopefoundation/Acquisition/issues/7.

• The pure-Python implicit acquisition wrapper allows wrapped objects to use object.__getattribute__(self, name). This differs from the C implementation, but is important for compatibility with the pure-Python versions of libraries like persistent. See https://github.com/zopefoundation/Acquisition/issues/9.

4.2.1 (2015-04-23)

• Correct several dangling pointer uses in the C extension, potentially fixing a few interpreter crashes. See https://github.com/zopefoundation/Acquisition/issues/5.

4.2 (2015-04-04)

• Add support for PyPy, PyPy3, and Python 3.2, 3.3, and 3.4.

4.1 (2014-12-18)

• Bump dependency on ExtensionClass to match current release.

4.0.3 (2014-11-02)

• Skip readme.rst tests when tests are run outside a source checkout.

4.0.2 (2014-11-02)

• Include *.rst files in the release.

4.0.1 (2014-10-30)

• Tolerate Unicode attribute names (ASCII only). LP #143358.

• Make module-level aq_acquire API respect the default parameter. LP #1387363.

• Don’t raise an attribute error for __iter__ if the fallback to __getitem__ succeeds. LP #1155760.

4.0 (2013-02-24)

• Added trove classifiers to project metadata.

4.0a1 (2011-12-13)

• Raise RuntimeError: Recursion detected in acquisition wrapper if an object with a __parent__ pointer points to a wrapper that in turn points to the original object.

• Prevent wrappers to be created while accessing __parent__ on types derived from Explicit or Implicit base classes.

2.13.9 (2015-02-17)

• Tolerate Unicode attribute names (ASCII only). LP #143358.

• Make module-level aq_acquire API respect the default parameter. LP #1387363.

• Don’t raise an attribute error for __iter__ if the fallback to __getitem__ succeeds. LP #1155760.

2.13.8 (2011-06-11)

• Fixed a segfault on 64bit platforms when providing the explicit argument to the aq_acquire method of an Acquisition wrapper. Thx to LP #675064 for the hint to the solution. The code passed an int instead of a pointer into a function.

2.13.7 (2011-03-02)

• Fixed bug: When an object did not implement __unicode__, calling unicode(wrapped) was calling __str__ with an unwrapped self.

2.13.6 (2011-02-19)

• Add aq_explicit to IAcquisitionWrapper.

• Fixed bug: unicode(wrapped) was not calling a __unicode__ method on wrapped objects.

2.13.5 (2010-09-29)

• Fixed unit tests that failed on 64bit Python on Windows machines.

2.13.4 (2010-08-31)

• LP 623665: Fixed typo in Acquisition.h.

2.13.3 (2010-04-19)

• Use the doctest module from the standard library and no longer depend on zope.testing.

2.13.2 (2010-04-04)

• Give both wrapper classes a __getnewargs__ method, which causes the ZODB optimization to fail and create persistent references using the _p_oid alone. This happens to be the persistent oid of the wrapped object. This lets these objects to be persisted correctly, even though they are passed to the ZODB in a wrapped state.

• Added failing tests for http://dev.plone.org/plone/ticket/10318. This shows an edge-case where AQ wrappers can be pickled using the specific combination of cPickle, pickle protocol one and a custom Pickler class with an inst_persistent_id hook. Unfortunately this is the exact combination used by ZODB3.

2.13.1 (2010-02-23)

• Update to include ExtensionClass 2.13.0.

• Fix the tp_name of the ImplicitAcquisitionWrapper and ExplicitAcquisitionWrapper to match their Python visible names and thus have a correct __name__.

• Expand the tp_name of our extension types to hold the fully qualified name. This ensures classes have their __module__ set correctly.

2.13.0 (2010-02-14)

• Added support for method cache in Acquisition. Patch contributed by Yoshinori K. Okuji. See https://bugs.launchpad.net/zope2/+bug/486182.

2.12.4 (2009-10-29)

• Fix iteration proxying to pass self acquisition-wrapped into both __iter__ as well as __getitem__ (this fixes https://bugs.launchpad.net/zope2/+bug/360761).

• Add tests for the __getslice__ proxying, including open-ended slicing.

2.12.3 (2009-08-08)

• More 64-bit fixes in Py_BuildValue calls.

• More 64-bit issues fixed: Use correct integer size for slice operations.

2.12.2 (2009-08-02)

• Fixed 64-bit compatibility issues for Python 2.5.x / 2.6.x. See http://www.python.org/dev/peps/pep-0353/ for details.

2.12.1 (2009-04-15)

• Update for iteration proxying: The proxy for __iter__ must not rely on the object to have an __iter__ itself, but also support fall-back iteration via __getitem__ (this fixes https://bugs.launchpad.net/zope2/+bug/360761).

2.12 (2009-01-25)

• Release as separate package.