yera.apps.context

Per-invocation app context, accessible via a ContextVar.

The @app decorator pushes an AppContext onto a stack on entry and pops it on exit; user code reads the current context via get_app_context.

Symbols

class AppContext — Per-invocation runtime context for an executing app.
def get_app_context — Return the currently executing app's runtime context.
def no_active_app_context — Return whether no application context is currently active.

AppContext

Per-invocation runtime context for an executing app.

Pushed onto a ContextVar stack on entry and popped on exit. Tracks the app's metadata, an instance counter, and its position in the app stack (top-level vs. nested). Managed by the @app decorator; not constructed by user code.

Attributes

metadata

AppMetadata describing the app this context belongs to.

instance_number

Counter for this app's invocations within a single run.

Methods

__init__ — Initialize an inactive invocation context for an app.
__enter__ — Push this context onto the stack and return it.
__exit__ — Pop this context off the stack.
top_level — Return whether this context is the outermost app on the stack.

AppContext.__init__

__init__(
    metadata: AppMetadata,
)

Initialize an inactive invocation context for an app.

Parameters

metadata
type: AppMetadata

Metadata identifying the app represented by this context.

AppContext.__enter__

__enter__()

Push this context onto the stack and return it.

The outermost invocation creates a run-scoped set of counters. Every app identifier receives an independent sequence beginning at zero.

Raises

RuntimeError

If no run-scoped app-instance counters are available.

Returns

This active application context.

AppContext.__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
)

Pop this context off the stack.

Parameters

exc_type
type: type[BaseException] | None

Type of exception leaving the context, if any.

exc_val
type: BaseException | None

Exception leaving the context, if any.

exc_tb
type: TracebackType | None

Traceback associated with the exception, if any.

Raises

RuntimeError

If the context was not previously entered.

AppContext.top_level

top_level() → bool

Return whether this context is the outermost app on the stack.

Returns

type: bool

Whether this is the outermost active application context.

Raises

RuntimeError

If called before the context has been entered.

get_app_context

get_app_context() → AppContext

Return the currently executing app's runtime context.

For framework code that needs to inspect the running app (e.g. its metadata or position in the app stack). User code in an app's body rarely needs this.

Returns

type: AppContext

The active AppContext.

Raises

RuntimeError

If called outside an active app invocation.

no_active_app_context

no_active_app_context() → bool

Return whether no application context is currently active.

Returns

type: bool

Whether execution is currently outside an application invocation.