{"id":22845242,"url":"https://github.com/zopefoundation/acquisition","last_synced_at":"2025-10-27T16:04:52.714Z","repository":{"id":7117243,"uuid":"8411282","full_name":"zopefoundation/Acquisition","owner":"zopefoundation","description":"Acquisition is a mechanism that allows objects to obtain attributes from the containment hierarchy they're in.","archived":false,"fork":false,"pushed_at":"2025-02-17T08:16:54.000Z","size":1365,"stargazers_count":12,"open_issues_count":3,"forks_count":12,"subscribers_count":61,"default_branch":"master","last_synced_at":"2025-04-06T23:16:12.853Z","etag":null,"topics":["python","zope"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zopefoundation.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-02-25T15:00:25.000Z","updated_at":"2025-02-17T08:16:58.000Z","dependencies_parsed_at":"2023-01-13T14:16:39.662Z","dependency_job_id":"59fcf95a-5a09-4bf9-ba47-f9f0ee4599dd","html_url":"https://github.com/zopefoundation/Acquisition","commit_stats":{"total_commits":295,"total_committers":35,"mean_commits":8.428571428571429,"dds":0.6677966101694915,"last_synced_commit":"fa72b954acb795ccf52d9c06f29cd3423f1aa103"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zopefoundation%2FAcquisition","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zopefoundation%2FAcquisition/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zopefoundation%2FAcquisition/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zopefoundation%2FAcquisition/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zopefoundation","download_url":"https://codeload.github.com/zopefoundation/Acquisition/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247563936,"owners_count":20958971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["python","zope"],"created_at":"2024-12-13T03:16:27.937Z","updated_at":"2025-10-27T16:04:52.619Z","avatar_url":"https://github.com/zopefoundation.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Environmental Acquisiton\n========================\n\nThis package implements \"environmental acquisiton\" for Python, as\nproposed in the OOPSLA96_ paper by Joseph Gil and David H. Lorenz:\n\n    We propose a new programming paradigm, environmental acquisition in\n    the context of object aggregation, in which objects acquire\n    behaviour from their current containers at runtime. The key idea is\n    that the behaviour of a component may depend upon its enclosing\n    composite(s). In particular, we propose a form of feature sharing in\n    which an object \"inherits\" features from the classes of objects in\n    its environment.  By examining the declaration of classes, it is\n    possible to determine which kinds of classes may contain a\n    component, and which components must be contained in a given kind of\n    composite. These relationships are the basis for language constructs\n    that supports acquisition.\n\n.. _OOPSLA96: http://www.cs.virginia.edu/~lorenz/papers/oopsla96/\u003e`_:\n\n.. contents::\n\nIntroductory Example\n--------------------\n\nZope implements acquisition with \"Extension Class\" mix-in classes. To\nuse acquisition your classes must inherit from an acquisition base\nclass. For example::\n\n  \u003e\u003e\u003e import ExtensionClass, Acquisition\n\n  \u003e\u003e\u003e class C(ExtensionClass.Base):\n  ...     color = 'red'\n\n  \u003e\u003e\u003e class A(Acquisition.Implicit):\n  ...     def report(self):\n  ...         print(self.color)\n  ...\n  \u003e\u003e\u003e a = A()\n  \u003e\u003e\u003e c = C()\n  \u003e\u003e\u003e c.a = a\n\n  \u003e\u003e\u003e c.a.report()\n  red\n\n  \u003e\u003e\u003e d = C()\n  \u003e\u003e\u003e d.color = 'green'\n  \u003e\u003e\u003e d.a = a\n\n  \u003e\u003e\u003e d.a.report()\n  green\n\n  \u003e\u003e\u003e try:\n  ...     a.report()\n  ... except AttributeError:\n  ...     pass\n  ... else:\n  ...     raise AssertionError('AttributeError not raised.')\n\nThe class ``A`` inherits acquisition behavior from\n``Acquisition.Implicit``. The object, ``a``, \"has\" the color of\nobjects ``c`` and d when it is accessed through them, but it has no\ncolor by itself. The object ``a`` obtains attributes from its\nenvironment, where its environment is defined by the access path used\nto reach ``a``.\n\nAcquisition Wrappers\n--------------------\n\nWhen an object that supports acquisition is accessed through an\nextension class instance, a special object, called an acquisition\nwrapper, is returned. In the example above, the expression ``c.a``\nreturns an acquisition wrapper that contains references to both ``c``\nand ``a``. It is this wrapper that performs attribute lookup in ``c``\nwhen an attribute cannot be found in ``a``.\n\nAcquisition wrappers provide access to the wrapped objects through the\nattributes ``aq_parent``, ``aq_self``, ``aq_base``.  Continue the\nexample from above::\n\n  \u003e\u003e\u003e c.a.aq_parent is c\n  True\n  \u003e\u003e\u003e c.a.aq_self is a\n  True\n\nExplicit and Implicit Acquisition\n---------------------------------\n\nTwo styles of acquisition are supported: implicit and explicit\nacquisition.\n\nImplicit acquisition\n--------------------\n\nImplicit acquisition is so named because it searches for attributes\nfrom the environment automatically whenever an attribute cannot be\nobtained directly from an object or through inheritance.\n\nAn attribute can be implicitly acquired if its name does not begin\nwith an underscore.\n\nTo support implicit acquisition, your class should inherit from the\nmix-in class ``Acquisition.Implicit``.\n\nExplicit Acquisition\n--------------------\n\nWhen explicit acquisition is used, attributes are not automatically\nobtained from the environment. Instead, the method aq_acquire must be\nused. For example::\n\n  \u003e\u003e\u003e print(c.a.aq_acquire('color'))\n  red\n\nTo support explicit acquisition, your class should inherit from the\nmix-in class ``Acquisition.Explicit``.\n\nControlling Acquisition\n-----------------------\n\nA class (or instance) can provide attribute by attribute control over\nacquisition. You should subclass from ``Acquisition.Explicit``, and set\nall attributes that should be acquired to the special value\n``Acquisition.Acquired``. Setting an attribute to this value also allows\ninherited attributes to be overridden with acquired ones. For example::\n\n  \u003e\u003e\u003e class C(Acquisition.Explicit):\n  ...     id = 1\n  ...     secret = 2\n  ...     color = Acquisition.Acquired\n  ...     __roles__ = Acquisition.Acquired\n\nThe only attributes that are automatically acquired from containing\nobjects are color, and ``__roles__``. Note that the ``__roles__``\nattribute is acquired even though its name begins with an\nunderscore. In fact, the special ``Acquisition.Acquired`` value can be\nused in ``Acquisition.Implicit`` objects to implicitly acquire\nselected objects that smell like private objects.\n\nSometimes, you want to dynamically make an implicitly acquiring object\nacquire explicitly. You can do this by getting the object's\naq_explicit attribute. This attribute provides the object with an\nexplicit wrapper that replaces the original implicit wrapper.\n\nFiltered Acquisition\n--------------------\n\nThe acquisition method, ``aq_acquire``, accepts two optional\narguments. The first of the additional arguments is a \"filtering\"\nfunction that is used when considering whether to acquire an\nobject. The second of the additional arguments is an object that is\npassed as extra data when calling the filtering function and which\ndefaults to ``None``. The filter function is called with five\narguments:\n\n* The object that the aq_acquire method was called on,\n\n* The object where an object was found,\n\n* The name of the object, as passed to aq_acquire,\n\n* The object found, and\n\n* The extra data passed to aq_acquire.\n\nIf the filter returns a true object that the object found is returned,\notherwise, the acquisition search continues.\n\nHere's an example::\n\n  \u003e\u003e\u003e from Acquisition import Explicit\n\n  \u003e\u003e\u003e class HandyForTesting(object):\n  ...     def __init__(self, name):\n  ...         self.name = name\n  ...     def __str__(self):\n  ...         return \"%s(%s)\" % (self.name, self.__class__.__name__)\n  ...     __repr__=__str__\n  ...\n  \u003e\u003e\u003e class E(Explicit, HandyForTesting): pass\n  ...\n  \u003e\u003e\u003e class Nice(HandyForTesting):\n  ...     isNice = 1\n  ...     def __str__(self):\n  ...         return HandyForTesting.__str__(self)+' and I am nice!'\n  ...     __repr__ = __str__\n  ...\n  \u003e\u003e\u003e a = E('a')\n  \u003e\u003e\u003e a.b = E('b')\n  \u003e\u003e\u003e a.b.c = E('c')\n  \u003e\u003e\u003e a.p = Nice('spam')\n  \u003e\u003e\u003e a.b.p = E('p')\n\n  \u003e\u003e\u003e def find_nice(self, ancestor, name, object, extra):\n  ...     return hasattr(object,'isNice') and object.isNice\n\n  \u003e\u003e\u003e print(a.b.c.aq_acquire('p', find_nice))\n  spam(Nice) and I am nice!\n\nThe filtered acquisition in the last line skips over the first\nattribute it finds with the name ``p``, because the attribute doesn't\nsatisfy the condition given in the filter.\n\nFiltered acquisition is rarely used in Zope.\n\nAcquiring from Context\n----------------------\n\nNormally acquisition allows objects to acquire data from their\ncontainers. However an object can acquire from objects that aren't its\ncontainers.\n\nMost of the examples we've seen so far show establishing of an\nacquisition context using getattr semantics. For example, ``a.b`` is a\nreference to ``b`` in the context of ``a``.\n\nYou can also manually set acquisition context using the ``__of__``\nmethod. For example::\n\n  \u003e\u003e\u003e from Acquisition import Implicit\n  \u003e\u003e\u003e class C(Implicit): pass\n  ...\n  \u003e\u003e\u003e a = C()\n  \u003e\u003e\u003e b = C()\n  \u003e\u003e\u003e a.color = \"red\"\n  \u003e\u003e\u003e print(b.__of__(a).color)\n  red\n\nIn this case, ``a`` does not contain ``b``, but it is put in ``b``'s\ncontext using the ``__of__`` method.\n\nHere's another subtler example that shows how you can construct an\nacquisition context that includes non-container objects::\n\n  \u003e\u003e\u003e from Acquisition import Implicit\n\n  \u003e\u003e\u003e class C(Implicit):\n  ...     def __init__(self, name):\n  ...         self.name = name\n\n  \u003e\u003e\u003e a = C(\"a\")\n  \u003e\u003e\u003e a.b = C(\"b\")\n  \u003e\u003e\u003e a.b.color = \"red\"\n  \u003e\u003e\u003e a.x = C(\"x\")\n\n  \u003e\u003e\u003e print(a.b.x.color)\n  red\n\nEven though ``b`` does not contain ``x``, ``x`` can acquire the color\nattribute from ``b``. This works because in this case, ``x`` is accessed\nin the context of ``b`` even though it is not contained by ``b``.\n\nHere acquisition context is defined by the objects used to access\nanother object.\n\nContainment Before Context\n--------------------------\n\nIf in the example above suppose both a and b have an color attribute::\n\n  \u003e\u003e\u003e a = C(\"a\")\n  \u003e\u003e\u003e a.color = \"green\"\n  \u003e\u003e\u003e a.b = C(\"b\")\n  \u003e\u003e\u003e a.b.color = \"red\"\n  \u003e\u003e\u003e a.x = C(\"x\")\n\n  \u003e\u003e\u003e print(a.b.x.color)\n  green\n\nWhy does ``a.b.x.color`` acquire color from ``a`` and not from ``b``?\nThe answer is that an object acquires from its containers before\nnon-containers in its context.\n\nTo see why consider this example in terms of expressions using the\n``__of__`` method::\n\n  a.x -\u003e x.__of__(a)\n\n  a.b -\u003e b.__of__(a)\n\n  a.b.x -\u003e x.__of__(a).__of__(b.__of__(a))\n\nKeep in mind that attribute lookup in a wrapper is done by trying to\nlook up the attribute in the wrapped object first and then in the\nparent object. So in the expressions above proceeds from left to\nright.\n\nThe upshot of these rules is that attributes are looked up by\ncontainment before context.\n\nThis rule holds true also for more complex examples. For example,\n``a.b.c.d.e.f.g.attribute`` would search for attribute in ``g`` and\nall its containers first. (Containers are searched in order from the\ninnermost parent to the outermost container.) If the attribute is not\nfound in ``g`` or any of its containers, then the search moves to\n``f`` and all its containers, and so on.\n\nAdditional Attributes and Methods\n---------------------------------\n\nYou can use the special method ``aq_inner`` to access an object\nwrapped only by containment. So in the example above,\n``a.b.x.aq_inner`` is equivalent to ``a.x``.\n\nYou can find out the acquisition context of an object using the\naq_chain method like so:\n\n  \u003e\u003e\u003e [obj.name for obj in a.b.x.aq_chain]\n  ['x', 'b', 'a']\n\nYou can find out if an object is in the containment context of another\nobject using the ``aq_inContextOf`` method. For example:\n\n  \u003e\u003e\u003e a.b.aq_inContextOf(a)\n  True\n\n.. Note: as of this writing the aq_inContextOf examples don't work the\n   way they should be working. According to Jim, this is because\n   aq_inContextOf works by comparing object pointer addresses, which\n   (because they are actually different wrapper objects) doesn't give\n   you the expected results. He acknowledges that this behavior is\n   controversial, and says that there is a collector entry to change\n   it so that you would get the answer you expect in the above. (We\n   just need to get to it).\n\nAcquisition Module Functions\n----------------------------\n\nIn addition to using acquisition attributes and methods directly on\nobjects you can use similar functions defined in the ``Acquisition``\nmodule. These functions have the advantage that you don't need to\ncheck to make sure that the object has the method or attribute before\ncalling it.\n\n``aq_acquire(object, name [, filter, extra, explicit, default, containment])``\n    Acquires an object with the given name.\n\n    This function can be used to explictly acquire when using explicit\n    acquisition and to acquire names that wouldn't normally be\n    acquired.\n\n    The function accepts a number of optional arguments:\n\n    ``filter``\n        A callable filter object that is used to decide if an object\n        should be acquired.\n\n        The filter is called with five arguments:\n\n        * The object that the aq_acquire method was called on,\n\n        * The object where an object was found,\n\n        * The name of the object, as passed to aq_acquire,\n\n        * The object found, and\n\n        * The extra argument passed to aq_acquire.\n\n        If the filter returns a true object that the object found is\n        returned, otherwise, the acquisition search continues.\n\n    ``extra``\n        Extra data to be passed as the last argument to the filter.\n\n    ``explicit``\n        A flag (boolean value) indicating whether explicit acquisition\n        should be used. The default value is true. If the flag is\n        true, then acquisition will proceed regardless of whether\n        wrappers encountered in the search of the acquisition\n        hierarchy are explicit or implicit wrappers. If the flag is\n        false, then parents of explicit wrappers are not searched.\n\n        This argument is useful if you want to apply a filter without\n        overriding explicit wrappers.\n\n    ``default``\n        A default value to return if no value can be acquired.\n\n    ``containment``\n        A flag indicating whether the search should be limited to the\n        containment hierarchy.\n\n    In addition, arguments can be provided as keywords.\n\n``aq_base(object)``\n    Return the object with all wrapping removed.\n\n``aq_chain(object [, containment])``\n    Return a list containing the object and it's acquisition\n    parents. The optional argument, containment, controls whether the\n    containment or access hierarchy is used.\n\n``aq_get(object, name [, default, containment])``\n    Acquire an attribute, name. A default value can be provided, as\n    can a flag that limits search to the containment hierarchy.\n\n``aq_inner(object)``\n    Return the object with all but the innermost layer of wrapping\n    removed.\n\n``aq_parent(object)``\n    Return the acquisition parent of the object or None if the object\n    is unwrapped.\n\n``aq_self(object)``\n    Return the object with one layer of wrapping removed, unless the\n    object is unwrapped, in which case the object is returned.\n\nIn most cases it is more convenient to use these module functions\ninstead of the acquisition attributes and methods directly.\n\nAcquisition and Methods\n-----------------------\n\nPython methods of objects that support acquisition can use acquired\nattributes. When a Python method is called on an object that is\nwrapped by an acquisition wrapper, the wrapper is passed to the method\nas the first argument. This rule also applies to user-defined method\ntypes and to C methods defined in pure mix-in classes.\n\nUnfortunately, C methods defined in extension base classes that define\ntheir own data structures, cannot use aquired attributes at this\ntime. This is because wrapper objects do not conform to the data\nstructures expected by these methods. In practice, you will seldom\nfind this a problem.\n\nConclusion\n----------\n\nAcquisition provides a powerful way to dynamically share information\nbetween objects. Zope uses acquisition for a number of its key\nfeatures including security, object publishing, and DTML variable\nlookup. Acquisition also provides an elegant solution to the problem\nof circular references for many classes of problems. While acquisition\nis powerful, you should take care when using acquisition in your\napplications. The details can get complex, especially with the\ndifferences between acquiring from context and acquiring from\ncontainment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzopefoundation%2Facquisition","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzopefoundation%2Facquisition","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzopefoundation%2Facquisition/lists"}