lazy-object-proxy

Concept

lazy-object-proxy is a fast and thorough lazy object proxy. It is designed for scenarios where the target object is only available or needed much later in the execution flow.

Comparison with wrapt.ObjectProxy

While both are proxies, they serve different primary purposes:

• Use lazy-object-proxy when you want to wrap a function that produces an object, and you want that function to be called only upon the first use of the proxy.
• Use wrapt.ObjectProxy when you want to override specific methods (via subclassing) and forward all other calls to an existing target object.

The project uses tox for testing and documentation building. You can run specific subsets of tests or run environments in parallel to speed up the process.

# Run a subset of tests using pytest markers
tox -e envname -- pytest -k test_myfeature

# Run all test environments in parallel
tox -p auto

When submitting a pull request for merging, ensure you follow these requirements:

1. Include passing tests (run tox).
2. Update documentation if there is new API or functionality.
3. Add a note about the changes to CHANGELOG.rst.
4. Add your name to AUTHORS.rst.

When reporting a bug via GitHub issues, please include:

• Your operating system name and version.
• Details about your local setup helpful for troubleshooting.
• Detailed steps to reproduce the bug.

Install the lazy-object-proxy package using pip from your command line.

pip install lazy-object-proxy

To use lazy-object-proxy in your Python project, ensure it is installed in your environment and then import the package.

Note: The package name for installation is typically lazy-object-proxy, but you import it as lazy_object_proxy in your code.

import lazy_object_proxy

You can install the stable version of lazy-object-proxy from PyPI using pip. If you need the latest in-development version, you can install it directly from the GitHub master branch.

# Install stable version
pip install lazy-object-proxy

# Install in-development version
pip install https://github.com/ionelmc/python-lazy-object-proxy/archive/master.zip

You can install the lazy-object-proxy package using pip.

pip install lazy-object-proxy

To develop locally, fork the repository, clone your fork, and create a new branch. Use tox to run all checks and the documentation builder.

# 1. Clone your fork
git clone git@github.com:YOURGITHUBNAME/python-lazy-object-proxy.git

# 2. Create a branch
git checkout -b name-of-your-bugfix-or-feature

# 3. Run all checks and docs builder
tox

# 4. Commit and push
git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

The Proxy class implements comprehensive delegation to the wrapped object:

• Attribute Access: __getattr__ and __setattr__ delegate to the wrapped object.
• Magic Methods: Supports arithmetic (__add__, __sub__, etc.), comparison (__eq__, __lt__, etc.), container operations (__len__, __getitem__, __contains__), and more.
• Context Managers: Supports __enter__ and __exit__.
• Async Support: Supports __await__, __aenter__, __aexit__, __aiter__, and __anext__ if the environment supports it.
• Metadata: Properties like __module__, __doc__, and __name__ are proxied to match the wrapped object.

The Proxy class manages the lifecycle of the wrapped object through several internal mechanisms:

1. __factory__: The callback function used to create the target object.
2. __target__: The storage for the materialized object once the factory has been executed.
3. __resolved__: A boolean flag that is True if __target__ is set, and False otherwise.
4. __wrapped__: The primary interface to the underlying object. When accessed, it checks if __target__ exists. If not, it calls __factory__, stores the result in __target__, and returns it.

The lazy_object_proxy.Proxy class creates a proxy object that wraps a function. The function is only executed the first time the proxy object is actually accessed or used. Subsequent accesses return the cached result of the function without re-executing it.

import lazy_object_proxy

def expensive_func():
    from time import sleep
    print('starting calculation')
    # just as example for a very slow computation
    sleep(2)
    print('finished calculation')
    # return the result of the calculation
    return 10

obj = lazy_object_proxy.Proxy(expensive_func)
# function is called only when object is actually used
print(obj)  # now expensive_func is called

print(obj)  # the result without calling the expensive_func