Skip to content

API Reference

SLOTHY_ENABLED: bool = not getenv('SLOTHY_DISABLE')

Whether slothy is enabled.

lazy_importing(*, prevent_eager=True, stack_offset=1, _fallback=MISSING)

Use slothy imports in a with statement.

Parameters:

  • prevent_eager (bool, default: True ) –

    If True, will raise a RuntimeError if slothy cannot guarantee to not fall back to eager imports on unsupported Python implementation. On supported Python implementations this parameter doesn't change the behavior. A general recommendation is to set this to True in applications and False in libraries.

  • stack_offset (int, default: 1 ) –

    The stack offset to use.

Returns:

  • Iterator[None] –

    Context manager's underlying generator.

Source code in slothy/_importing.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
@contextmanager
def lazy_importing(
    *,
    prevent_eager: bool = True,  # noqa: ARG001
    stack_offset: int = 1,
    _fallback: object = MISSING,
) -> Iterator[None]:
    """
    Use slothy imports in a `with` statement.

    Parameters
    ----------
    prevent_eager
        If True, will raise a `RuntimeError` if slothy cannot guarantee
        to not fall back to eager imports on unsupported Python implementation.
        On supported Python implementations this parameter doesn't change the behavior.
        A general recommendation is to set this to `True` in applications
        and `False` in libraries.
    stack_offset
        The stack offset to use.

    Returns
    -------
    Iterator[None]
        Context manager's underlying generator.

    """
    frame = get_frame(stack_offset + 1)  # +1 from @contextmanager
    builtin_import = _get_builtin_import(frame.f_builtins)

    import_wrapper = partial(
        _slothy_import_locally,
        _target=frame.f_globals["__name__"],
        _builtin_import=builtin_import,
    )
    import_wrapper.__slothy__ = True  # type: ignore[attr-defined]

    frame.f_builtins["__import__"] = import_wrapper
    try:
        yield
    finally:
        _process_slothy_objects(frame.f_locals, fallback=_fallback)
        frame.f_builtins["__import__"] = builtin_import

lazy_importing_if(condition, *, prevent_eager=True, stack_offset=1)

Use slothy imports only if condition evaluates to truth.

Parameters:

  • condition (object) –

    The condition to evaluate.

  • prevent_eager (bool, default: True ) –

    If True, will raise a RuntimeError if slothy cannot guarantee to not fall back to eager imports on unsupported Python implementation. On supported Python implementations this parameter doesn't change the behavior. A general recommendation is to set this to True in applications and False in libraries.

  • stack_offset (int, default: 1 ) –

    The stack offset to use.

Returns:

Source code in slothy/_importing.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def lazy_importing_if(
    condition: object,
    *,
    prevent_eager: bool = True,
    stack_offset: int = 1,
) -> AbstractContextManager[None]:
    """
    Use slothy imports only if condition evaluates to truth.

    Parameters
    ----------
    condition
        The condition to evaluate.
    prevent_eager
        If True, will raise a `RuntimeError` if slothy cannot guarantee
        to not fall back to eager imports on unsupported Python implementation.
        On supported Python implementations this parameter doesn't change the behavior.
        A general recommendation is to set this to `True` in applications
        and `False` in libraries.
    stack_offset
        The stack offset to use.

    Returns
    -------
    AbstractContextManager[None]
        The context manager.

    """
    return (
        lazy_importing(prevent_eager=prevent_eager, stack_offset=stack_offset)
        if condition
        else nullcontext()
    )

type_importing(*, default_type=Any, stack_offset=1)

Use this to import symbols recognized by type checkers that do not exist at runtime.

This function should generally be considered a runtime-friendly alternative to using if typing.TYPE_CHECKING.

Parameters:

  • default_type (object, default: Any ) –

    The item to import in case of a failure. Defaults to typing.Any

  • stack_offset (int, default: 1 ) –

    The stack offset to use.

Returns:

Source code in slothy/_importing.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def type_importing(
    *,
    default_type: object = Any,
    stack_offset: int = 1,
) -> AbstractContextManager[None]:
    """
    Use this to import symbols recognized by type checkers that do not exist at runtime.

    This function should generally be considered a runtime-friendly alternative to
    using `if typing.TYPE_CHECKING`.

    Parameters
    ----------
    default_type
        The item to import in case of a failure. Defaults to [`typing.Any`][]
    stack_offset
        The stack offset to use.

    Returns
    -------
    AbstractContextManager[None]
        The context manager.

    """
    return lazy_importing(
        prevent_eager=True,
        stack_offset=stack_offset,
        _fallback=default_type,
    )