Skip to content

omnipy.util.contexts

Context managers and context helper utilities used across Omnipy.

CLASS DESCRIPTION
LastErrorHolder

Context manager that stores the latest suppressed exception for later chaining.
PrintExceptionContext

Context manager that prints and suppresses the first line of an exception.
FUNCTION DESCRIPTION
hold_and_reset_prev_attrib_value

Restore an object's attribute to its previous value when the context exits.
nothing

Yield a no-op context value.
setup_and_teardown_callback_context

Run optional setup, exception, and teardown callbacks around a context block.
ATTRIBUTE DESCRIPTION
print_exception

Context manager instance that prints and suppresses the first line of an exception.

print_exception module-attribute 

print_exception = PrintExceptionContext()

Context manager instance that prints and suppresses the first line of an exception.

LastErrorHolder

Bases: AbstractContextManager


              flowchart BT
              omnipy.util.contexts.LastErrorHolder[LastErrorHolder]

              

              click omnipy.util.contexts.LastErrorHolder href "" "omnipy.util.contexts.LastErrorHolder"

Context manager that stores the latest suppressed exception for later chaining.

METHOD DESCRIPTION
__init__
raise_derived

Raise an exception, chained from the last captured one when available.
Source code in src/omnipy/util/contexts.py 
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
class LastErrorHolder(AbstractContextManager):
    """Context manager that stores the latest suppressed exception for later chaining."""
    def __init__(self):
        self._last_error = None

    def __enter__(self):
        ...

    def __exit__(self, exc_type, exc_val, exc_tb):
        if exc_val is not None:
            self._last_error = exc_val
        return True

    def raise_derived(self, exc: Exception):
        """Raise an exception, chained from the last captured one when available.

        Args:
            exc: Exception to raise.

        Raises:
            Exception: ``exc``, with ``__cause__`` set to the most recently
                captured exception when present.
        """
        if self._last_error is not None:
            raise exc from self._last_error
        else:
            raise exc

__init__ 

__init__()
Source code in src/omnipy/util/contexts.py 
61
62
def __init__(self):
    self._last_error = None

raise_derived 

raise_derived(exc: Exception)

Raise an exception, chained from the last captured one when available.

PARAMETER DESCRIPTION
exc

Exception to raise.

TYPE: Exception

RAISES DESCRIPTION
Exception

exc, with __cause__ set to the most recently captured exception when present.
Source code in src/omnipy/util/contexts.py 
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def raise_derived(self, exc: Exception):
    """Raise an exception, chained from the last captured one when available.

    Args:
        exc: Exception to raise.

    Raises:
        Exception: ``exc``, with ``__cause__`` set to the most recently
            captured exception when present.
    """
    if self._last_error is not None:
        raise exc from self._last_error
    else:
        raise exc

PrintExceptionContext

Bases: AbstractContextManager


              flowchart BT
              omnipy.util.contexts.PrintExceptionContext[PrintExceptionContext]

              

              click omnipy.util.contexts.PrintExceptionContext href "" "omnipy.util.contexts.PrintExceptionContext"

Context manager that prints and suppresses the first line of an exception.

Used by:
Source code in src/omnipy/util/contexts.py 
121
122
123
124
125
126
127
128
class PrintExceptionContext(AbstractContextManager):
    """Context manager that prints and suppresses the first line of an exception."""
    def __enter__(self):
        ...

    def __exit__(self, exc_type, exc_val, exc_tb):
        print(f'{exc_type.__name__}: {str(exc_val).splitlines()[0]}', end='')
        return True

hold_and_reset_prev_attrib_value 

hold_and_reset_prev_attrib_value(
    obj: object, attr_name: str, copy_attr: bool = False
) -> Iterator[None]

Restore an object's attribute to its previous value when the context exits.

PARAMETER DESCRIPTION
obj

Object whose attribute should be restored.

TYPE: object

attr_name

Name of the attribute to preserve and restore.

TYPE: str

copy_attr

Whether to deep-copy the original value before storing it.

TYPE: bool DEFAULT: False

YIELDS DESCRIPTION
None

None while the caller temporarily mutates the attribute.
Source code in src/omnipy/util/contexts.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
@contextmanager
def hold_and_reset_prev_attrib_value(
    obj: object,
    attr_name: str,
    copy_attr: bool = False,
) -> Iterator[None]:
    """Restore an object's attribute to its previous value when the context exits.

    Args:
        obj: Object whose attribute should be restored.
        attr_name: Name of the attribute to preserve and restore.
        copy_attr: Whether to deep-copy the original value before storing it.

    Yields:
        ``None`` while the caller temporarily mutates the attribute.
    """

    attr_value = getattr(obj, attr_name)
    prev_value = deepcopy(attr_value) if copy_attr else attr_value

    try:
        yield
    finally:
        setattr(obj, attr_name, prev_value)

nothing 

nothing(*args, **kwds) -> Iterator[None]

Yield a no-op context value.

Source code in src/omnipy/util/contexts.py 
114
115
116
117
118
@contextmanager
def nothing(*args, **kwds) -> Iterator[None]:
    """Yield a no-op context value."""

    yield None

setup_and_teardown_callback_context 

setup_and_teardown_callback_context(
    *,
    setup_func: Callable[..., _ValT] | None = None,
    setup_func_args: tuple[object, ...] = (),
    setup_func_kwargs: dict[str, object] = {},
    exception_func: Callable[..., None] | None = None,
    exception_func_args: tuple[object, ...] = (),
    exception_func_kwargs: dict[str, object] = {},
    teardown_func: Callable[..., None] | None = None,
    teardown_func_args: tuple[object, ...] = (),
    teardown_func_kwargs: dict[str, object] = {},
) -> Iterator[_ValT | None]

Run optional setup, exception, and teardown callbacks around a context block.

PARAMETER DESCRIPTION
setup_func

Optional callback invoked before entering the context.

TYPE: Callable[..., _ValT] | None DEFAULT: None

setup_func_args

Positional arguments passed to setup_func.

TYPE: tuple[object, ...] DEFAULT: ()

setup_func_kwargs

Keyword arguments passed to setup_func.

TYPE: dict[str, object] DEFAULT: {}

exception_func

Optional callback invoked if the context raises.

TYPE: Callable[..., None] | None DEFAULT: None

exception_func_args

Positional arguments passed to exception_func.

TYPE: tuple[object, ...] DEFAULT: ()

exception_func_kwargs

Keyword arguments passed to exception_func.

TYPE: dict[str, object] DEFAULT: {}

teardown_func

Optional callback invoked when leaving the context.

TYPE: Callable[..., None] | None DEFAULT: None

teardown_func_args

Positional arguments passed to teardown_func.

TYPE: tuple[object, ...] DEFAULT: ()

teardown_func_kwargs

Keyword arguments passed to teardown_func.

TYPE: dict[str, object] DEFAULT: {}

YIELDS DESCRIPTION
_ValT | None

The value returned by setup_func, if any.
Source code in src/omnipy/util/contexts.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
@contextmanager
def setup_and_teardown_callback_context(
    *,
    setup_func: Callable[..., _ValT] | None = None,
    setup_func_args: tuple[object, ...] = (),
    setup_func_kwargs: dict[str, object] = {},
    exception_func: Callable[..., None] | None = None,
    exception_func_args: tuple[object, ...] = (),
    exception_func_kwargs: dict[str, object] = {},
    teardown_func: Callable[..., None] | None = None,
    teardown_func_args: tuple[object, ...] = (),
    teardown_func_kwargs: dict[str, object] = {},
) -> Iterator[_ValT | None]:
    """Run optional setup, exception, and teardown callbacks around a context block.

    Args:
        setup_func: Optional callback invoked before entering the context.
        setup_func_args: Positional arguments passed to ``setup_func``.
        setup_func_kwargs: Keyword arguments passed to ``setup_func``.
        exception_func: Optional callback invoked if the context raises.
        exception_func_args: Positional arguments passed to ``exception_func``.
        exception_func_kwargs: Keyword arguments passed to ``exception_func``.
        teardown_func: Optional callback invoked when leaving the context.
        teardown_func_args: Positional arguments passed to ``teardown_func``.
        teardown_func_kwargs: Keyword arguments passed to ``teardown_func``.

    Yields:
        The value returned by ``setup_func``, if any.
    """

    setup_val: _ValT | None = None
    if setup_func is not None:
        setup_val = setup_func(*setup_func_args, **setup_func_kwargs)
    try:
        yield setup_val
    except Exception:
        if exception_func is not None:
            exception_func(*exception_func_args, **exception_func_kwargs)
        raise
    finally:
        if teardown_func is not None:
            teardown_func(*teardown_func_args, **teardown_func_kwargs)