slothy

Super-easy lazy importing in Python.

Intended to be used as a guard for expensive or type-checking imports.

[!tip] In case you're just looking around, feel free to install the latest beta version of slothy from PyPI and have some fun experimenting.
Don't forget to share your feedback in the issue tracker!

Usage

>>> from slothy import lazy_importing
>>> 
>>> with lazy_importing():
...     from asyncio import get_event_loop, run, erroneous_import
...     print(get_event_loop)
...     print(run)
...     print(erroneous_import)
... 
<from asyncio import get_event_loop, ... ("<stdin>", line 2)>
<from asyncio import ..., run, ... ("<stdin>", line 2)>
<from asyncio import ..., erroneous_import ("<stdin>", line 2)>
>>>
>>> get_event_loop
<built-in function get_event_loop>
>>>
>>> globals()["run"]
<function run at 0xdead1337beef>
>>>
>>> erroneous_import
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "./slothy/_importing.py", line 423, in __eq__
    self._import(their_import)
  File "./slothy/_importing.py", line 304, in __import
    raise exc from None
  File "./slothy/_importing.py", line 286, in __import
    obj = _import_item_from_list(
  File "./slothy/_importing.py", line 203, in _import_item_from_list
    raise ImportError(msg) from None
ImportError: cannot import name 'erroneous_import' from 'asyncio'
(caused by delayed execution of "<stdin>", line 2)

By default, with lazy_importing() statements fail immediately on unsupported Python implementations, i.e. those that don't define sys._getframe. To disable this behavior, which might be particularly useful in libraries, use with lazy_importing(prevent_eager=False).

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.

Kudos 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 significantly helped me.

I'm very grateful to @jimfulton for making the library possible in the first place almost 30 years ago.

Special thanks 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 Rye, simply run:

   rye toolchain fetch 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.