slothy

Super-easy lazy importing in Python.

Intended to be used as a drop-in replacement for if typing.TYPE_CHECKING blocks as well as a convenient guard against expensive imports.

Usage

>>> from slothy import lazy_importing
>>>
>>> with lazy_importing(prevent_eager=False):
...     from functools import partial, reduce
...     print(partial)  # <from functools import partial, ...>
...     print(reduce)  # <from functools import ..., reduce>
>>>
>>> # First time imported items are referenced, they're imported.
... # If a declared item is never referenced, the module containing it is never
... # imported too, provided it was not imported by some external instruction.
... partial, reduce
(<class 'functools.partial'>, <built-in function reduce>)

lazy_importing() will default to eager imports on unsupported Python implementations, i.e. those that don't define sys._getframe. While this library is 3.8+ and that eliminates the risk of running slothy in most of these implementations now, future versions of them can finally support 3.8.

To prevent eager imports in with lazy_importing() statements and instead fail immediately on unsupported Python implementations, use with lazy_importing(prevent_eager=True). Preventing eager imports might be useful in type-checking sections, where eager imports could cause cycles resulting in less readable tracebacks.

Credits

Many thanks to Jelle Zijlstra @JelleZijlstra who wrote a basic dict key lookup-based lazy importing implementation that is now the core solution of slothy.

Special thanks to Carl Meyer @carljm who willingly sacrificed his time to consult the project with me and share his deep knowledge of the problem at the bigger picture. His experience with PEP 690 as a Meta software engineer helped me grasp the topic in the context of real production. I find it delightful!

Kudos to Alex Waygood @AlexWaygood who made this project possible by sharing his knowledge of CPython implementation details regarding name lookup behavior.

Shoutout to Will McGugan @willmcgugan who supported the idea of slothy from the very beginning and promoted the project on Twitter.

Installation

You might simply install it with pip:

pip install slothy

If you use Poetry, then you might want to run:

poetry add slothy

For Contributors

[!Note] If you use Windows, it is highly recommended to complete the installation in the way presented below through WSL2.

1. Fork the slothy repository on GitHub.

2. Install Poetry.
   Poetry is an amazing tool for managing dependencies & virtual environments, building packages and publishing them. You might use pipx to install it globally (recommended):

   pipx install poetry
   

   _{If you encounter any problems, refer to the official documentation for the most up-to-date installation instructions.}

   Be sure to have Python 3.8 installed—if you use pyenv, simply run:

   pyenv install 3.8
   

3. Clone your fork locally and install dependencies.

   git clone https://github.com/your-username/slothy path/to/slothy
   cd path/to/slothy
   poetry env use $(cat .python-version)
   poetry install
   

   Next up, simply activate the virtual environment and install pre-commit hooks:

   poetry shell
   pre-commit install
   

For more information on how to contribute, check out CONTRIBUTING.md.
Always happy to accept contributions! ❤️

Legal Info

© Copyright by Bartosz Sławecki (@bswck).
This software is licensed under the terms of MIT License.