slothy 0.1.0b0

Super-easy lazy importing in Python.

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.

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.