Source code for osprey_connectors.control_system.write_door
"""The write door: marks a put as made by a connector, not by a raw client.
A connector opens the door around its own call into a control-system client
library; the raw-client guard asks :func:`door_is_open` and lets a put through
only when the answer is yes. A put made from user code that reached for the
client directly finds the door closed.
**Contract.** A connector makes its client put in the context that opened
the door, inside ``asyncio.to_thread`` started from that context, or in a
coroutine handed to another loop with ``asyncio.run_coroutine_threadsafe``
from that context. The flag is a context variable, so it reaches exactly the
code that shares that context: ``asyncio.to_thread`` and
``run_coroutine_threadsafe`` both run the work in a copy of it and carry the
open door with it, as does every task created while the door is open.
``loop.run_in_executor``, a raw executor ``submit`` and a bare
``threading.Thread`` start from a fresh context and see the door closed, so a
connector that puts behind one of those hops is refused.
**Cooperative bypasses.** The door records attribution, not permission, and
some paths open it for code that is not a connector's own put. These are
accepted, because attribution is not a boundary:
- Anything a connector's put coroutine starts on the CA loop while it runs
(``ca_loop``) inherits the door with it. libca's own callback threads start
from a fresh context and never carry it.
- ``ControlSystemConnector`` wraps every subclass's ``write_channel`` and
``write_multiple_channels``, including those of a user-defined connector
subclass, so a user-defined connector puts inside an open door.
This module is stdlib-only: the guard that reads it runs in executor sandboxes
and notebook kernels where ``osprey`` is not importable.
"""
from __future__ import annotations
import contextvars
from collections.abc import Iterator
from contextlib import contextmanager
__all__ = ["door_is_open", "open_door"]
#: Whether the current context is inside a connector's write.
#:
#: Set and reset by token in :func:`open_door`, so a nested exit restores the
#: enclosing value rather than closing the outer door, and an exception leaves
#: the prior value in place.
_DOOR: contextvars.ContextVar[bool] = contextvars.ContextVar(
"osprey_connector_write_door", default=False
)
[docs]
@contextmanager
def open_door() -> Iterator[None]:
"""Open the write door for the body of the ``with`` block."""
token = _DOOR.set(True)
try:
yield
finally:
_DOOR.reset(token)
[docs]
def door_is_open() -> bool:
"""Whether the calling context is inside :func:`open_door`."""
return _DOOR.get()