slothy

¶

Super-easy lazy importing in Python.

Important

Only CPython is supported.

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 SLOTHY

with SLOTHY:
    from pandas import DataFrame

# pandas.DataFrame not imported

def main() -> None:
    # pandas.DataFrame not imported
    print(DataFrame)  # <class 'pandas.core.frame.DataFrame'>
    # pandas.DataFrame imported just before print() called; from now on,
    # available everywhere in the module.


if __name__ == "__main__":
    main()

Caveats¶

Python <3.10 Boilerplate¶

On Python 3.8-3.9, every function accessing a lazily-imported object must be decorated with supports_slothy:

from slothy import SLOTHY, supports_slothy

with SLOTHY:
    from pandas import DataFrame

# pandas.DataFrame not imported

@supports_slothy
def main() -> None:
    # pandas.DataFrame not imported
    print(DataFrame)  # <class 'pandas.core.frame.DataFrame'>
    # pandas.DataFrame imported just before print() called; from now on,
    # available everywhere in the module.


if __name__ == "__main__":
    main()

Deleted References¶

Importing symbols with SLOTHY will make them intentionally unavailable in your namespace after the with SLOTHY block finishes.

Consequently,

from slothy import SLOTHY

with SLOTHY:
    from pandas import DataFrame

try:
    DataFrame
except NameError:
    print("DataFrame undefined")

outputs DataFrame undefined. This is caused by the fact that there must be at least 1 frame between "declared import" and usage. More in-depth technical explanation will be provided soon.

Credits¶

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.

Fork the slothy repository on GitHub.
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
```

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! ❤️

slothy ¶