nirs4all.core.logging.context module

Run context management for nirs4all logging.

This module provides context managers for tracking run state, phases, branches, sources, and stacking operations in the logging system.

class nirs4all.core.logging.context.BranchContext(name: str, path: list[str] = <factory>, index: int | None = None, total: int | None = None, parent: str | None = None, depth: int = 0)[source]

Bases: object

Context for a branch in the pipeline.

name

Branch name.

Type:: str

path

Full branch path (for nested branches).

Type:: list[str]

index

Branch index (0-based).

Type:: int | None

total

Total number of branches at this level.

Type:: int | None

parent

Parent branch name (for nested branches).

Type:: str | None

depth

Nesting depth (0 for top-level).

Type:: int

depth: int = 0

index: int | None = None

name: str

parent: str | None = None

path: list[str]

total: int | None = None

class nirs4all.core.logging.context.LogContext(run_id: str | None = None, run_name: str | None = None, project: str | None = None, **extra: Any)[source]

Bases: object

Context manager for run-level logging context.

Provides a context manager that sets up run state and can be used to track the current run, phase, branches, sources, etc.

Example

>>> with LogContext(run_id="my-experiment", project="protein"):
...     logger.info("Starting analysis")
...     with LogContext.branch("snv", index=0, total=4):
...         logger.info("Processing SNV branch")

__enter__() → LogContext[source]: Enter the context, setting up run state.

__exit__(exc_type: Any, exc_val: Any, exc_tb: Any) → None[source]: Exit the context, restoring previous state.

static branch(name: str, index: int | None = None, total: int | None = None, parent: str | None = None) → Generator[BranchContext, None, None][source]

Context manager for tracking branch execution.

Parameters:

name – Branch name.
index – Branch index (0-based).
total – Total number of branches at this level.
parent – Parent branch name (for nested branches).

Yields:

BranchContext for the current branch.

static phase(phase: Phase) → Generator[None, None, None][source]

Context manager for tracking the current phase.

Parameters:: phase – The phase being entered.
Yields:: None

static source(name: str, index: int | None = None, total: int | None = None) → Generator[SourceContext, None, None][source]

Context manager for tracking source processing in multi-source pipelines.

Parameters:

name – Source name.
index – Source index (0-based).
total – Total number of sources.

Yields:

SourceContext for the current source.

static stack(n_branches: int, meta_model: str | None = None, branch_sources: list[str] | None = None) → Generator[StackContext, None, None][source]

Context manager for tracking stacking operations.

Parameters:

n_branches – Number of branches being stacked.
meta_model – Meta-model name/description.
branch_sources – List of branch names being stacked.

Yields:

StackContext for the stacking operation.

class nirs4all.core.logging.context.RunState(run_id: str, run_name: str | None = None, project: str | None = None, start_time: ~datetime.datetime = <factory>, current_phase: ~nirs4all.core.logging.events.Phase | None = None, branch_stack: list[~nirs4all.core.logging.context.BranchContext] = <factory>, source_context: ~nirs4all.core.logging.context.SourceContext | None = None, stack_context: ~nirs4all.core.logging.context.StackContext | None = None, extra: dict[str, ~typing.Any] = <factory>)[source]

Bases: object

State for a single run.

run_id

Unique run identifier.

Type:: str

run_name

Human-readable run name.

Type:: str | None

project

Project name (optional).

Type:: str | None

start_time

Run start timestamp.

Type:: datetime.datetime

current_phase

Current workflow phase.

Type:: nirs4all.core.logging.events.Phase | None

branch_stack

Stack of branch contexts (for nesting).

Type:: list[nirs4all.core.logging.context.BranchContext]

source_context

Current source context (if any).

Type:: nirs4all.core.logging.context.SourceContext | None

stack_context

Current stacking context (if any).

Type:: nirs4all.core.logging.context.StackContext | None

extra

Additional run-level metadata.

Type:: dict[str, Any]

property branch_depth: int: Get the current branch nesting depth.

property branch_path: list[str]: Get the full branch path.

branch_stack: list[BranchContext]

property current_branch: BranchContext | None: Get the current (innermost) branch context.

current_phase: Phase | None = None

extra: dict[str, Any]

project: str | None = None

run_id: str

run_name: str | None = None

source_context: SourceContext | None = None

stack_context: StackContext | None = None

start_time: datetime

class nirs4all.core.logging.context.SourceContext(name: str, index: int | None = None, total: int | None = None)[source]

Bases: object

Context for a source in multi-source pipelines.

name

Source name.

Type:: str

index

Source index (0-based).

Type:: int | None

total

Total number of sources.

Type:: int | None

index: int | None = None

name: str

total: int | None = None

class nirs4all.core.logging.context.StackContext(n_branches: int, meta_model: str | None = None, branch_sources: list[str] = <factory>)[source]

Bases: object

Context for stacking operations.

n_branches

Number of branches being stacked.

Type:: int

meta_model

Meta-model name/description.

Type:: str | None

branch_sources

List of branch names being stacked.

Type:: list[str]

branch_sources: list[str]

meta_model: str | None = None

n_branches: int

nirs4all.core.logging.context.get_current_state() → RunState | None[source]

Get the current run state.

Returns:: Current RunState or None if not in a run context.

nirs4all.core.logging.context.get_run_id() → str | None[source]

Get the current run ID.

Returns:: Current run ID or None if not in a run context.

nirs4all.core.logging.context.inject_context(record: LogRecord) → LogRecord[source]

Inject current context into a log record.

This is called by the logger to add context fields to each log record.

Parameters:: record – Log record to inject context into.
Returns:: Modified log record with context fields.