"""Registered implementations for config-selected callbacks, separate from global attachment.
A registration makes a callback or tracer available by name to
``config.callbacks``; it never attaches anything to a simulation. There are two
families of registration functions:
- :func:`register_callback` and :func:`register_tracer`, the preferred
decorators, which register a callback function or a tracer class directly;
- :func:`register_callback_factory` and :func:`register_tracer_factory`, which
register a factory building a fresh callback from a validated options model,
and remain available unchanged.
"""
from __future__ import annotations
import copy
import inspect
import json
from collections.abc import Callable
from dataclasses import dataclass, field
from typing import Any, Literal, overload
from pydantic import BaseModel, ConfigDict, TypeAdapter, create_model
from ._signatures import read_signature, resolve_annotation
from .registry import (
DEFAULT_DAILY_PRIORITY,
HOOKS,
QUEUED_HOOKS,
SYNCHRONOUS_HOOKS,
Hook,
_as_whole_number,
check_daily_priority,
)
from .tracer import GenericTracer, tracer_hooks
_HOOKS = set(HOOKS)
DefinitionKind = Literal["factory", "callback", "tracer"]
"""How a definition was registered.
``"factory"`` is :func:`register_callback_factory` or
:func:`register_tracer_factory`; ``"callback"`` is :func:`register_callback`;
``"tracer"`` is :func:`register_tracer`.
"""
[docs]
@dataclass(frozen=True)
class CallbackDefinition:
"""Factory metadata used to validate and construct one callback per simulation."""
factory: Callable[[BaseModel], Any]
"""Construct a fresh callable from one validated options model."""
when: Hook | None
"""Lifecycle hook for the constructed callback.
None for a factory returning a tracer, which then runs on the hooks the
tracer itself declares (see :func:`~passengersim.callbacks.tracer.tracer_hooks`).
"""
parameters_model: type[BaseModel]
"""Schema used for runtime validation without changing explicit config."""
version: str
"""Implementation version checked against an explicit config requirement."""
output_name: str | None = None
"""Expected name of the tracer returned by the factory, or None for an ordinary callback."""
kind: DefinitionKind = "factory"
"""How this definition was registered; see :data:`DefinitionKind`."""
source: Any = field(default=None, compare=False, repr=False)
"""The function or class given to :func:`register_callback` or :func:`register_tracer`.
None for a factory registration. Used to decide whether a later
registration under the same name may replace this one.
"""
def __reduce__(self) -> tuple:
# Definitions are pickled to send them to spawned workers. A model built
# here with create_model cannot be pickled by reference, because it is
# not an attribute of any module. Its fields are sent instead, exactly as
# captured when it was built (resolved types, defaults, and constraints),
# and the worker builds an identical model from them. Nothing is read
# again from the registered function, whose module globals or defaults
# may differ in the worker or may have changed since registration.
model = self.parameters_model
if model.__dict__.get(_GENERATED_MODEL, False):
model = _model_fields_recipe(model)
return (
_restore_definition,
(self.factory, self.when, model, self.version, self.output_name, self.kind, self.source),
)
_GENERATED_MODEL = "__passengersim_generated_model__"
"""Class attribute marking an options model built here with ``create_model``."""
def _generated_model(name: str, config: ConfigDict, fields: dict[str, Any]) -> type[BaseModel]:
"""Build an options model with ``create_model``, marked so its definition can be pickled."""
model = create_model(name, __config__=config, **fields)
# type.__setattr__, so that Pydantic does not treat it as a private attribute.
type.__setattr__(model, _GENERATED_MODEL, True)
return model
def _model_fields_recipe(model: type[BaseModel]) -> tuple[str, dict[str, Any], dict[str, Any]]:
"""Capture a generated model's name, configuration, and fields, to rebuild it elsewhere."""
fields = {name: (field.annotation, field) for name, field in model.model_fields.items()}
return model.__name__, dict(model.model_config), fields
def _restore_definition(
factory: Callable[..., Any],
when: Hook | None,
model: type[BaseModel] | tuple,
version: str,
output_name: str | None,
kind: DefinitionKind,
source: Any,
) -> CallbackDefinition:
"""Rebuild a pickled :class:`CallbackDefinition`, rebuilding a generated options model from its fields."""
if isinstance(model, tuple):
name, config, fields = model
model = _generated_model(name, ConfigDict(**config), fields)
return CallbackDefinition(factory, when, model, version, output_name, kind=kind, source=source)
_DEFINITIONS: dict[str, CallbackDefinition] = {}
def _publish(name: str, definition: CallbackDefinition) -> None:
"""Store a fully validated definition.
A new object is always published, never an edit of the old one, so
definitions already handed to a running simulation or worker stay stable,
and validation cached against the old object is recognized as stale (see
:func:`_resolve`).
"""
_DEFINITIONS[name] = definition
def _check_definition_fields(
*,
factory: Callable[..., Any],
when: Hook | None,
parameters_model: type[BaseModel],
version: str,
output_name: str | None,
) -> None:
"""Validate the fields shared by every kind of definition, raising if any is invalid."""
if when is None:
if output_name is None:
raise ValueError("A callback factory without a hook must return a tracer, so it needs an output_name")
elif when not in _HOOKS:
raise ValueError(f"Invalid callback hook: {when!r}")
if output_name is not None and (not isinstance(output_name, str) or not output_name or output_name in _HOOKS):
raise ValueError(f"Reserved or empty callback output name: {output_name!r}")
if not callable(factory) or not isinstance(parameters_model, type) or not issubclass(parameters_model, BaseModel):
raise TypeError("A callable factory and BaseModel parameter class are required")
if not isinstance(version, str) or not version:
raise ValueError("Callback version must be a nonempty string")
def _check_factory_name(name: str) -> None:
if not isinstance(name, str) or not name or name in _DEFINITIONS:
raise ValueError(f"Callback registry name {name!r} is empty or already registered")
[docs]
def register_callback_factory(
name: str,
*,
factory: Callable[[BaseModel], Any],
when: Hook | None,
parameters_model: type[BaseModel],
version: str,
output_name: str | None = None,
) -> None:
"""Make a factory available to YAML declarations without attaching it.
For a plain callback, :func:`register_callback` is usually simpler: it
registers the callback function itself, with no factory.
Parameters
----------
name : str
Unique registry name. Duplicate registration is always an error.
factory : callable
Receives one validated parameter-model instance and returns a fresh
callback. Sample hooks receive a simulation; daily hooks also receive
days prior to departure.
when : {"initialize_sample", "begin_sample", "daily", "end_sample", "finalize_sample"} or None
Lifecycle hook at which the returned callback runs. None is allowed
only for a factory returning a tracer (so `output_name` is required);
the tracer then runs on every hook it declares.
parameters_model : type[pydantic.BaseModel]
Schema for factory options; preferably configured with extra="forbid".
version : str
Implementation version checked only when explicitly required in YAML.
output_name : str or None, optional
Required canonical result name for a factory returning a GenericTracer.
Raises
------
ValueError
If the name is duplicated, the hook is invalid, or the output is reserved.
TypeError
If the factory or parameter model is invalid.
"""
_check_factory_name(name)
_check_definition_fields(
factory=factory, when=when, parameters_model=parameters_model, version=version, output_name=output_name
)
_publish(name, CallbackDefinition(factory, when, parameters_model, version, output_name))
@dataclass(frozen=True)
class _TracerFactory:
"""Construct a registered tracer class from one validated options model."""
cls: type[GenericTracer]
def __call__(self, options: BaseModel) -> GenericTracer:
# Pass values as validated rather than dumped, as configured callbacks
# do, so a constructor parameter annotated with a model receives that
# model and not a dict. Extra fields, if the model allows them, follow.
kwargs = {name: getattr(options, name) for name in type(options).model_fields}
kwargs.update(options.model_extra or {})
return self.cls(**kwargs)
[docs]
def options_model_from_signature(cls: type) -> type[BaseModel]:
"""Build a configured-callback options model from a class's constructor.
Each keyword-capable constructor parameter becomes a field, with the
parameter's annotation as its type (or ``Any`` if there is none, or it
cannot be resolved) and its default, if any. A ``name`` parameter is left
out: a configured tracer uses its declaration ID as its result name. Unknown
options are rejected (``extra="forbid"``).
Parameters
----------
cls : type
The class whose ``__init__`` signature is read.
Returns
-------
type[pydantic.BaseModel]
A model named ``<ClassName>Options``.
Raises
------
TypeError
If the constructor takes positional-only parameters, ``*args``, or
``**kwargs``, which cannot be described by an options model, or a
parameter's annotation fails to evaluate for a reason other than an
undefined name, or names a type that Pydantic cannot validate.
"""
if cls.__init__ is object.__init__ and cls.__new__ is object.__new__:
# The class accepts no options despite object.__init__ exposing *args and **kwargs.
return _generated_model(f"{cls.__name__}Options", ConfigDict(extra="forbid"), {})
signature = read_signature(cls.__init__)
fields: dict[str, Any] = {}
for index, (param_name, param) in enumerate(signature.parameters.items()):
if index == 0 or param_name == "name":
continue # self, and the instance-level result name
if param.kind in (param.POSITIONAL_ONLY, param.VAR_POSITIONAL, param.VAR_KEYWORD):
raise TypeError(
f"{cls.__name__}.__init__ has parameter {param_name!r} that cannot be given by keyword; "
"declare options_model on the class instead"
)
annotation = Any
if param.annotation is not param.empty:
try:
annotation = resolve_annotation(cls.__init__, param.annotation)
except NameError:
# Type-checking-only names leave just this field unconstrained.
pass
except Exception as error:
# Anything else (a malformed string annotation, say) is a mistake
# in the class, reported here rather than as a bare error at import.
raise TypeError(
f"the annotation of {cls.__name__}.__init__ parameter {param_name!r} cannot be evaluated "
f"({type(error).__name__}: {error}); fix it, or declare options_model on the class"
) from error
try:
TypeAdapter(annotation)
except Exception as error:
raise TypeError(
f"{cls.__name__}.__init__ parameter {param_name!r} is annotated with {annotation!r}, which "
f"cannot be validated from configuration ({error}); use a JSON-compatible type, or declare "
"options_model on the class"
) from error
default = ... if param.default is param.empty else param.default
fields[param_name] = (annotation, default)
return _generated_model(f"{cls.__name__}Options", ConfigDict(extra="forbid"), fields)
def _tracer_definition(
cls: type[GenericTracer],
*,
parameters_model: type[BaseModel] | None,
version: str | None,
kind: DefinitionKind,
) -> CallbackDefinition:
"""Build (but do not publish) the definition registering a tracer class.
Raises
------
TypeError
If no options model is declared or given and none can be derived.
ValueError
If the class declares no hook, or an invalid hook or output.
"""
parameters_model = parameters_model or getattr(cls, "options_model", None)
if parameters_model is None:
parameters_model = options_model_from_signature(cls)
hooks = tracer_hooks(cls)
if not hooks:
raise ValueError(
f"{cls.__name__} declares no hook; override one or more on_<hook> methods, "
"or set the class attribute 'hook'"
)
factory = _TracerFactory(cls)
# A single-hook tracer keeps its hook on the definition, as before; a
# tracer with several hooks is attached to all of them at prepare.
when = hooks[0] if len(hooks) == 1 else None
version = version or getattr(cls, "options_version", "1")
_check_definition_fields(
factory=factory, when=when, parameters_model=parameters_model, version=version, output_name=cls.name
)
return CallbackDefinition(
factory,
when,
parameters_model,
version,
cls.name,
kind=kind,
source=cls if kind != "factory" else None,
)
[docs]
def register_tracer_factory(
cls: type[GenericTracer],
*,
parameters_model: type[BaseModel] | None = None,
version: str | None = None,
name: str | None = None,
) -> None:
"""Register a tracer using the configuration it declares on its class.
:func:`register_tracer` does the same and also works as a class
decorator; it is the preferred spelling.
The output name, options model, and version are read from the class
attributes ``name``, ``options_model``, and ``options_version``, and the
hooks from the ``on_<hook>`` methods the class overrides or, for a legacy
tracer, its ``hook`` attribute (see
:class:`~passengersim.callbacks.tracer.GenericTracer`). They are defined
once, beside the tracer's constructor.
Parameters
----------
cls : type[GenericTracer]
Tracer class declaring a canonical ``name``, and either hook methods
or a ``hook``.
parameters_model : type[pydantic.BaseModel] or None, optional
Overrides ``cls.options_model``. Fields map to constructor keyword
arguments. If neither is given, a model is derived from the
constructor's signature (see :func:`options_model_from_signature`).
version : str or None, optional
Overrides ``cls.options_version``, the implementation version checked
against explicit YAML requirements.
name : str or None, optional
Registry name or alias; defaults to ``cls.name``. The configuration's
declaration ID names each result table.
Raises
------
TypeError
If cls is not a GenericTracer subclass, or no options model is
declared or given and none can be derived from the constructor.
ValueError
If registration duplicates a name, the class declares no hook, or it
declares an invalid hook or output.
"""
if not isinstance(cls, type) or not issubclass(cls, GenericTracer):
raise TypeError("Expected a GenericTracer subclass")
definition = _tracer_definition(cls, parameters_model=parameters_model, version=version, kind="factory")
registry_name = name or cls.name
_check_factory_name(registry_name)
_publish(registry_name, definition)
# --------------------------------------------------------------------------
# register_callback and register_tracer
_RESERVED_PARAMETERS = frozenset({"priority", "skip_burn"})
"""Keyword-only parameter names refused by :func:`register_callback`.
They are registration options. A configuration parameter of either name would
look like one, but would never be applied as one.
"""
def _describe_origin(obj: Any) -> str:
"""Name a registered function or class by its module and qualified name."""
return f"{getattr(obj, '__module__', '?')}.{getattr(obj, '__qualname__', repr(obj))}"
def _is_local(obj: Any) -> bool:
"""Whether `obj` is a lambda or a local function or class.
Such objects can share a module and qualified name with others (every
closure made by one factory does), so those names do not identify them.
"""
qualname = getattr(obj, "__qualname__", "")
return "<locals>" in qualname or "<lambda>" in qualname
def _publish_new_style(name: str, definition: CallbackDefinition) -> None:
"""Publish a :func:`register_callback` or :func:`register_tracer` definition.
A definition may replace an existing one of the same kind from the same
origin, so that re-running a notebook cell or reloading a module works.
For a module-level function or class, the same origin means the same
module and qualified name. A lambda or local object can only replace
itself (the identical object). Every other duplicate is an error.
Raises
------
ValueError
If the name is used by a definition that this one may not replace.
"""
existing = _DEFINITIONS.get(name)
if existing is not None:
new = definition.source
old = existing.source
same_origin = existing.kind == definition.kind and (
old is new or (not _is_local(old) and not _is_local(new) and _describe_origin(old) == _describe_origin(new))
)
if not same_origin:
if existing.kind == "factory":
held_by = "a factory registration"
else:
held_by = f"{existing.kind} {_describe_origin(old)}"
raise ValueError(
f"Callback registry name {name!r} is already registered by {held_by}, so "
f"{definition.kind} {_describe_origin(new)} cannot use it; choose a different name="
)
_publish(name, definition)
def _registry_name(obj: Any, name: str | None) -> str:
"""Get the registry name for a function or class, validating an explicit one."""
if name is not None:
if not isinstance(name, str) or not name:
raise ValueError(f"Callback registry name {name!r} is empty or not a string")
return name
inferred = getattr(obj, "__name__", "")
if not isinstance(inferred, str) or not inferred.isidentifier():
raise ValueError(f"{obj!r} has no usable name to register under; pass name=...")
return inferred
def _is_async_or_generator(func: Callable[..., Any]) -> bool:
"""Whether `func`, or anything in its ``__wrapped__`` chain, is async or a generator."""
seen: set[int] = set()
current: Any = func
while current is not None and id(current) not in seen:
seen.add(id(current))
if (
inspect.iscoroutinefunction(current)
or inspect.isgeneratorfunction(current)
or inspect.isasyncgenfunction(current)
):
return True
current = getattr(current, "__wrapped__", None)
return False
def _check_callback_kind(obj: Any) -> None:
"""Refuse anything but a synchronous plain function, naming the right decorator."""
if isinstance(obj, GenericTracer):
raise TypeError(f"{obj!r} is a tracer instance; register its class with register_tracer, not register_callback")
if isinstance(obj, type):
if issubclass(obj, GenericTracer):
raise TypeError(
f"{obj.__name__} is a tracer class; register it with register_tracer, not register_callback"
)
raise TypeError(f"register_callback registers a function, not the class {obj.__name__}; decorate a function")
if not inspect.isfunction(obj):
raise TypeError(
f"register_callback registers a plain function, not {obj!r}; wrap it in a function. Callable "
"objects can carry state shared across simulations; a stateful collector belongs in a tracer"
)
if _is_async_or_generator(obj):
raise TypeError(
f"{obj.__qualname__} is a coroutine, generator, or async-generator function; callbacks must "
"execute synchronously and return their results directly"
)
def _check_tracer_kind(obj: Any) -> None:
"""Refuse anything but a GenericTracer subclass, naming the right decorator."""
if isinstance(obj, GenericTracer):
raise TypeError(f"{obj!r} is a tracer instance; with register_tracer, decorate the class, not an instance")
if isinstance(obj, type) and issubclass(obj, GenericTracer):
return
if inspect.isfunction(obj) and not _is_async_or_generator(obj):
raise TypeError(f"{obj.__qualname__} is a function; register it with register_callback, not register_tracer")
raise TypeError(f"register_tracer registers tracer classes, and {obj!r} is not a GenericTracer subclass")
def _configuration_parameters(func: Callable[..., Any], hook: str) -> list[inspect.Parameter]:
"""Check a callback's signature against its hook, and get its configuration parameters.
Returns
-------
list[inspect.Parameter]
The keyword-only parameters, in order.
Raises
------
TypeError
If the signature does not fit the hook.
"""
label = func.__qualname__
parameters = list(read_signature(func).parameters.values())
positional = [p for p in parameters if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
needed = 2 if hook == "daily" else 1
arguments = "(sim, days_prior)" if hook == "daily" else "(sim)"
for param in parameters:
if param.kind in (param.VAR_POSITIONAL, param.VAR_KEYWORD):
raise TypeError(
f"{label} takes {param}, which cannot be described by configuration; "
"declare each configuration parameter after * instead"
)
if positional and positional[0].name in ("self", "cls"):
raise TypeError(
f"{label} takes {positional[0].name!r} first, so it looks like a method; register a plain "
"function defined outside a class body"
)
if len(positional) < needed:
raise TypeError(f"a {hook} callback is called as {arguments}, but {label} takes too few positional parameters")
if len(positional) > needed:
extra = ", ".join(p.name for p in positional[needed:])
raise TypeError(
f"a {hook} callback is called as {arguments}, so {label}'s parameter(s) {extra} must be "
"keyword-only configuration parameters, declared after *"
)
configuration = [p for p in parameters if p.kind is p.KEYWORD_ONLY]
for param in configuration:
if param.name in _RESERVED_PARAMETERS:
raise TypeError(
f"{label} has a parameter named {param.name!r}, which is reserved for the registration "
f"option of that name; pass {param.name}=... to register_callback instead"
)
if param.name.startswith("_"):
raise TypeError(f"{label}'s configuration parameter {param.name!r} cannot start with an underscore")
return configuration
def _inferred_model(func: Callable[..., Any], model_name: str, parameters: list[inspect.Parameter]) -> type[BaseModel]:
"""Build an options model from a callback's keyword-only parameters.
Raises
------
TypeError
If a parameter has no annotation, an annotation that cannot be
resolved, or one that Pydantic cannot validate.
"""
label = func.__qualname__
fields: dict[str, Any] = {}
for param in parameters:
if param.annotation is param.empty:
raise TypeError(
f"{label}'s configuration parameter {param.name!r} needs a type annotation, used to validate "
"its configured value; annotate it with Any to accept anything"
)
try:
annotation = resolve_annotation(func, param.annotation)
except Exception as error:
raise TypeError(
f"the annotation of {label}'s configuration parameter {param.name!r} cannot be resolved at run "
f"time ({type(error).__name__}: {error}); import the type at module level, not only for type "
"checking, or pass parameters_model="
) from error
try:
TypeAdapter(annotation)
except Exception as error:
raise TypeError(
f"{label}'s configuration parameter {param.name!r} is annotated with {annotation!r}, which "
f"cannot be validated from configuration ({error}); use a JSON-compatible type, or pass "
"parameters_model="
) from error
fields[param.name] = (annotation, ... if param.default is param.empty else param.default)
return _generated_model(model_name, ConfigDict(extra="forbid"), fields)
def _check_explicit_model(func: Callable[..., Any], model: Any, parameters: list[inspect.Parameter]) -> None:
"""Check that an explicit ``parameters_model`` matches the callback, without changing it.
Raises
------
TypeError
If the model is not a Pydantic model class, does not forbid unknown
fields, or its fields do not match the keyword-only parameters.
"""
if not isinstance(model, type) or not issubclass(model, BaseModel):
raise TypeError(f"parameters_model must be a pydantic BaseModel subclass, not {model!r}")
if model.model_config.get("extra") != "forbid":
raise TypeError(
f"parameters_model {model.__name__} must reject unknown fields, so that misspelled configuration "
'options are caught; declare it with extra="forbid"'
)
fields = set(model.model_fields)
names = {p.name for p in parameters}
if fields != names:
problems = []
if missing := sorted(names - fields):
problems.append(f"no field for parameter(s) {', '.join(missing)}")
if extra := sorted(fields - names):
problems.append(f"field(s) {', '.join(extra)} with no matching keyword-only parameter")
raise TypeError(f"parameters_model {model.__name__} does not match {func.__qualname__}: {'; '.join(problems)}")
def _registration_options(
func: Callable[..., Any], hook: str, priority: Any, skip_burn: bool | None
) -> tuple[int | None, bool]:
"""Resolve and validate the priority and burn-in option captured at registration.
Returns
-------
tuple[int | None, bool]
The priority in whole seconds (None for a synchronous hook), and
whether burn-in samples are skipped.
Raises
------
ValueError
If a priority is given for a synchronous hook, or a queued hook's
priority is zero or not a whole number of seconds.
TypeError
If `skip_burn` is not a bool.
"""
if skip_burn is None:
resolved_skip = bool(getattr(func, "skip_burn", False))
elif isinstance(skip_burn, bool):
resolved_skip = skip_burn
else:
raise TypeError(f"skip_burn must be True or False, not {skip_burn!r}")
attribute = getattr(func, "priority", None)
if hook in SYNCHRONOUS_HOOKS:
if priority is not None or attribute is not None:
given = priority if priority is not None else attribute
raise ValueError(
f"a {hook} callback runs directly, not as a timed event, so it has no priority; "
f"remove the priority ({given!r}) from {func.__qualname__}"
)
return None, resolved_skip
chosen = priority if priority is not None else attribute if attribute is not None else DEFAULT_DAILY_PRIORITY
return check_daily_priority(chosen, f"{hook} callback {func.__qualname__!r}"), resolved_skip
class _BoundCallback:
"""A registered callback with one declaration's validated parameters bound to it.
This is what a simulation actually calls for a callback registered with
:func:`register_callback`. It is built fresh for every declaration and run,
and carries the options captured at registration, read by the scheduler
and dispatcher exactly as for a manual callback registered with options.
"""
def __init__(
self,
func: Callable[..., Any],
kwargs: dict[str, Any],
*,
priority: int | None,
skip_burn: bool,
result_name: str | None,
) -> None:
self.func = func
"""The registered function."""
self.kwargs = kwargs
"""Validated configuration parameters, passed by keyword on every call."""
self.skip_burn = skip_burn
"""Whether the dispatcher skips this callback during burn-in samples."""
self.result_name = result_name
"""Key under which returned dictionaries are stored: the declaration ID."""
if priority is not None:
# Set only for a queued hook; a synchronous one has no priority.
self.priority = priority
"""Offset in seconds from the DCP trigger time."""
# The signature check in prepare() reads __signature__, which takes
# precedence over __wrapped__, so it sees the bound parameters with
# their values as defaults rather than the function's required ones.
signature = read_signature(func)
self.__signature__ = signature.replace(
parameters=[
p.replace(default=kwargs[p.name]) if p.name in kwargs else p for p in signature.parameters.values()
]
)
# Lets remove_callback(func) recognize a configured callback, and
# explain that it must be disabled in the configuration instead.
self.__wrapped__ = func
def __call__(self, sim: Any, *args: Any) -> Any:
return self.func(sim, *args, **self.kwargs)
def __repr__(self) -> str:
return f"<configured {self.func.__qualname__} as {self.result_name!r}>"
@dataclass(frozen=True)
class _CallbackFactory:
"""Bind validated parameters to a function registered with :func:`register_callback`.
A module-level class rather than a closure, so that definitions holding it
can be sent to spawned workers.
"""
func: Callable[..., Any]
"""The registered function."""
priority: int | None
"""Captured queued-hook offset in seconds, or None for a synchronous hook."""
skip_burn: bool
"""Captured burn-in option."""
def build(self, options: BaseModel, result_name: str | None = None) -> _BoundCallback:
"""Bind one validated options model to the function.
Every field of the model is passed by its canonical name, including
fields left at their defaults, so the model's defaults (not the
function's) apply to configured runs. Values are passed as validated,
so nested models stay models.
Parameters
----------
options : pydantic.BaseModel
Validated options for one declaration. The caller passes a copy
that no other declaration shares.
result_name : str, optional
Key under which returned dictionaries are stored.
Returns
-------
_BoundCallback
"""
kwargs = {name: getattr(options, name) for name in type(options).model_fields}
return _BoundCallback(
self.func, kwargs, priority=self.priority, skip_burn=self.skip_burn, result_name=result_name
)
def __call__(self, options: BaseModel) -> _BoundCallback:
return self.build(options)
@overload
def register_callback[CallbackT: Callable[..., Any]](
func: CallbackT,
/,
*,
when: Hook,
name: str | None = None,
parameters_model: type[BaseModel] | None = None,
version: str = "1",
priority: int | None = None,
skip_burn: bool | None = None,
) -> CallbackT: ...
@overload
def register_callback[CallbackT: Callable[..., Any]](
*,
when: Hook,
name: str | None = None,
parameters_model: type[BaseModel] | None = None,
version: str = "1",
priority: int | None = None,
skip_burn: bool | None = None,
) -> Callable[[CallbackT], CallbackT]: ...
[docs]
def register_callback(
func: Any = None,
/,
*,
when: Hook | None = None,
name: str | None = None,
parameters_model: type[BaseModel] | None = None,
version: str = "1",
priority: Any = None,
skip_burn: bool | None = None,
) -> Any:
"""Make a callback function available to ``config.callbacks``, without attaching it.
Use it as a decorator, ``@register_callback(when="end_sample")``, or call
it directly, ``register_callback(func, when="end_sample")``. Either way the
function itself is returned unchanged, so it can still be called directly
or attached manually.
The function's leading positional parameters receive the hook's arguments:
``(sim)``, or ``(sim, days_prior)`` for the daily hook. Every other
parameter must be keyword-only (declared after ``*``); these are its
configuration parameters, given in a declaration's ``parameters``::
@register_callback(when="end_sample", skip_burn=True)
def carrier_revenue(
sim: Simulation, *, carriers: list[str] | None = None
) -> dict:
return {
c.name: c.revenue
for c in sim.eng.carriers
if carriers is None or c.name in carriers
}
Returned dictionaries are stored under the declaration's ID, so the same
function can be declared several times with different parameters.
Parameters
----------
func : Callable, optional
The callback: a plain, synchronous function. Omit it to get a decorator.
when : {"initialize_sample", "begin_sample", "daily", "end_sample", "finalize_sample"}
Hook at which the callback runs. Required; it is never inferred.
name : str, optional
Registry name; defaults to the function's name. Required for a lambda.
parameters_model : type[pydantic.BaseModel], optional
Options model for the configuration parameters. By default one is
built from the keyword-only parameters, whose type annotations are
then required. An explicit model must declare ``extra="forbid"`` and
exactly one field per keyword-only parameter. It decides the types,
defaults, and required fields of configured runs; the function's own
defaults apply only when it is called directly.
version : str, default "1"
Implementation version, checked when a configuration requires one.
priority : int, optional
Offset in seconds from the DCP trigger time, for a queued hook
(``begin_sample``, ``daily``, or ``end_sample``); see
:meth:`~passengersim.callbacks.CallbackMixin.daily_callback`. Defaults
to the function's own ``priority`` attribute, else 1. Not allowed for
a synchronous hook.
skip_burn : bool, optional
Whether burn-in samples are skipped. Defaults to the function's own
``skip_burn`` attribute, else False.
Returns
-------
Callable
`func`, unchanged; or, without `func`, a decorator that registers the
function it decorates and returns it unchanged.
Raises
------
TypeError
If `func` is not a plain synchronous function (a tracer class or
instance, another class, or a callable object), `when` is missing,
the signature does not fit the hook, or a configuration parameter's
annotation is missing or cannot be resolved.
ValueError
If the hook or name is invalid, the name is registered by something
else, or the priority is invalid.
Notes
-----
``priority`` and ``skip_burn`` are read once, at registration; changing
the function's attributes afterwards has no effect until it is registered
again. They apply only to configured runs: attaching the function
manually follows the ordinary rules for manual callbacks, and calls it
with its own defaults.
Registering again under the same name replaces the earlier registration
if it came from the same module-level function (as when a notebook cell
is re-run); any other duplicate name is an error.
"""
def register(target: Any) -> Any:
_check_callback_kind(target)
if when is None:
raise TypeError(
f"register_callback needs the hook at which {target.__qualname__} runs; "
'use @register_callback(when="daily") or another hook'
)
if when not in _HOOKS:
raise ValueError(f"Invalid callback hook: {when!r}")
registry_name = _registry_name(target, name)
parameters = _configuration_parameters(target, when)
if parameters_model is None:
model = _inferred_model(target, f"{registry_name}_options", parameters)
else:
_check_explicit_model(target, parameters_model, parameters)
model = parameters_model
resolved_priority, resolved_skip = _registration_options(target, when, priority, skip_burn)
factory = _CallbackFactory(target, resolved_priority, resolved_skip)
_check_definition_fields(factory=factory, when=when, parameters_model=model, version=version, output_name=None)
definition = CallbackDefinition(factory, when, model, version, None, kind="callback", source=target)
_publish_new_style(registry_name, definition)
return target
if func is None:
return register
return register(func)
@overload
def register_tracer[TracerT: GenericTracer](
cls: type[TracerT],
/,
*,
name: str | None = None,
parameters_model: type[BaseModel] | None = None,
version: str | None = None,
) -> type[TracerT]: ...
@overload
def register_tracer[TracerT: GenericTracer](
*,
name: str | None = None,
parameters_model: type[BaseModel] | None = None,
version: str | None = None,
) -> Callable[[type[TracerT]], type[TracerT]]: ...
[docs]
def register_tracer(
cls: Any = None,
/,
*,
name: str | None = None,
parameters_model: type[BaseModel] | None = None,
version: str | None = None,
) -> Any:
"""Make a tracer class available to ``config.callbacks``, without attaching it.
Use it as a class decorator, with or without arguments
(``@register_tracer`` or ``@register_tracer(version="2")``), or call it
directly, ``register_tracer(MyTracer)``. The class is returned unchanged.
The hooks, default name, options model, and version come from the class,
as for :func:`register_tracer_factory` (see
:class:`~passengersim.callbacks.tracer.GenericTracer`): the configured
tracer is built as ``cls(**validated_options)`` and its result is stored
under the declaration ID.
Parameters
----------
cls : type[GenericTracer], optional
The tracer class. Omit it to get a decorator.
name : str, optional
Registry name or alias; defaults to ``cls.name``. The configuration's
declaration ID names each result table.
parameters_model : type[pydantic.BaseModel], optional
Overrides ``cls.options_model``. If neither is given, a model is
derived from the constructor's signature (see
:func:`options_model_from_signature`).
version : str, optional
Overrides ``cls.options_version``.
Returns
-------
type[GenericTracer]
`cls`, unchanged; or, without `cls`, a decorator that registers the
class it decorates and returns it unchanged.
Raises
------
TypeError
If `cls` is not a GenericTracer subclass (a function, a tracer
instance, or anything else), or no options model is declared or given
and none can be derived from the constructor.
ValueError
If the name is registered by something else, or the class declares no
hook or an invalid hook or output.
Notes
-----
Registering again under the same name replaces the earlier registration
if it came from the same module-level class (as when a notebook cell is
re-run); any other duplicate name is an error.
"""
def register(target: Any) -> Any:
_check_tracer_kind(target)
registry_name = _registry_name(target, name if name is not None else target.name)
definition = _tracer_definition(target, parameters_model=parameters_model, version=version, kind="tracer")
_publish_new_style(registry_name, definition)
return target
if cls is None:
return register
return register(cls)
# --------------------------------------------------------------------------
# Validation and preparation of declarations
def _resolve(
owner: Any, definitions: dict[str, CallbackDefinition] | None = None
) -> list[tuple[str, CallbackDefinition, BaseModel]]:
"""Validate changed explicit declarations without injecting runtime defaults."""
from passengersim.config.callbacks import CallbackConfig
raw = {}
for key, value in owner.config.callbacks.items():
raw[key] = value.model_dump() if isinstance(value, CallbackConfig) else value
try:
signature = json.dumps(list(raw.items()), sort_keys=True, allow_nan=False)
except (TypeError, ValueError) as error:
raise ValueError(f"callbacks: parameters must be finite JSON values: {error}") from error
if definitions is None:
definitions = _DEFINITIONS
# Replacing a definition leaves the registry dictionary (and its identity)
# unchanged, so the cache also records which definition each declaration
# used, and is reused only while every one of them is still registered.
# Other registrations, which this owner does not use, do not invalidate it.
cached = getattr(owner, "_configured_validation", None)
if (
cached is not None
and cached[0] == signature
and cached[1] is definitions
and all(definitions.get(name) is definition for name, definition in cached[3])
):
return cached[2]
resolved = []
references: list[tuple[str, CallbackDefinition]] = []
for key, value in raw.items():
name = key
try:
declaration = CallbackConfig.model_validate(value)
if not declaration.enabled:
continue
name = declaration.type or key
if name not in definitions:
raise ValueError(f"unknown callback registry name {name!r}")
definition = definitions[name]
if declaration.version is not None and declaration.version != definition.version:
raise ValueError(f"version {declaration.version!r} does not match registered {definition.version!r}")
# Check a declared priority before the options model sees it:
# pydantic would quietly turn ``true`` into 1. Zero is a whole
# number and is left for preflight to reject with its own message.
if "priority" in definition.parameters_model.model_fields:
raw_priority = (
declaration.parameters.get("priority") if isinstance(declaration.parameters, dict) else None
)
if raw_priority is not None and _as_whole_number(raw_priority) is None:
raise ValueError(f"priority {raw_priority!r} is not a whole number of seconds")
options = definition.parameters_model.model_validate(copy.deepcopy(declaration.parameters))
except (ValueError, TypeError) as error:
raise ValueError(f"callbacks.{key} ({name}): parameters or declaration invalid: {error}") from error
resolved.append((key, definition, options))
references.append((name, definition))
owner._configured_validation = signature, definitions, resolved, references
return resolved
def _definition_hooks(definition: CallbackDefinition) -> tuple[str, ...] | None:
"""The hooks a definition's callback runs on, or None if not known before construction."""
if definition.when is not None:
return (definition.when,)
if isinstance(definition.factory, _TracerFactory):
return tracer_hooks(definition.factory.cls)
return None
def _check_declarations(owner: Any, resolved: list[tuple[str, CallbackDefinition, BaseModel]]) -> None:
"""Check current declarations and manual tracer collisions without factories.
This runs before any worker starts, so it also rejects a queued
(begin-sample, daily, or end-sample) callback whose validated options
carry a ``priority`` that is zero or not a whole number of seconds. Configured tracers and decorated callbacks claim
their declaration IDs as result keys. Legacy function factories can
return callbacks whose result names are known only after construction.
"""
outputs: set[str] = set()
for key, definition, options in resolved:
hooks = _definition_hooks(definition)
# A factory whose hooks are unknown until it runs is checked too: such
# a priority is never valid, and prepare would reject it anyway.
# Options that declare no priority leave the callback's default. A
# callback from register_callback is skipped: its priority was fixed
# and checked at registration, and its options, which cannot include a
# priority field, may still expose an unrelated computed attribute.
priority = getattr(options, "priority", None) if definition.kind != "callback" else None
if priority is not None and (hooks is None or any(hook in QUEUED_HOOKS for hook in hooks)):
check_daily_priority(priority, f"callbacks.{key}")
if definition.kind == "callback" or definition.output_name is not None:
if not key:
raise ValueError("Callback declaration IDs used as result keys must be nonempty")
if key in _HOOKS:
raise ValueError(
f"callbacks.{key}: the declaration ID {key!r} is reserved for the data of {key} callbacks; "
"choose another declaration ID, and set type to the registered callback or tracer"
)
outputs.add(key)
# Only manual tracers: those built by a prior prepare() are about to be replaced.
for tracer in owner._distinct_tracers(origin="manual"):
if tracer.name in outputs:
raise ValueError(f"callbacks.{tracer.name}: result key {tracer.name!r} conflicts with manual tracer")
# A manual callback registered with name= stores rows under that key too.
for registration in owner._callback_registry.select(origin="manual"):
name = getattr(registration.func, "result_name", None)
if isinstance(name, str) and name in outputs:
raise ValueError(f"callbacks.{name}: result key {name!r} conflicts with a named manual callback")
[docs]
def preflight(owner: Any) -> dict[str, CallbackDefinition]:
"""Validate the configuration and collect the definitions needed by trial workers."""
resolved = _resolve(owner)
_check_declarations(owner, resolved)
# Workers only need definitions referenced by enabled declarations. _resolve
# has just recorded the registry name each of those used, whether given as
# ``type``, by its legacy spelling, or implied by the declaration ID.
references = owner._configured_validation[3]
return dict(references)
[docs]
def prepare(owner: Any, definitions: dict[str, CallbackDefinition] | None = None) -> None:
"""Build fresh callbacks and replace only prior configured attachments.
Every factory runs, and every result is checked, before anything is
published. A tracer with several hooks is attached to all of them, and
its registrations are replaced together on the next prepare. A callback
registered with :func:`register_callback` is bound to each declaration's
own copy of its validated parameters, and stores its results under that
declaration's ID.
"""
from .base import _result_name, _tracer_entries
resolved = _resolve(owner, definitions)
_check_declarations(owner, resolved)
tracer_names = {key for key, definition, _ in resolved if definition.output_name is not None}
with owner._callback_registry.replacing("configured") as add:
for key, definition, options in resolved:
try:
options = options.model_copy(deep=True)
if definition.kind == "callback":
callback = definition.factory.build(options, result_name=key)
else:
callback = definition.factory(options)
tracer = None
if isinstance(callback, GenericTracer):
if definition.output_name != callback.name:
raise ValueError("declared output_name must match the tracer's canonical name")
hooks = owner._tracer_hooks_for(definition.when, callback)
if isinstance(definition.factory, _TracerFactory):
# Just constructed from its class, so it shares no state;
# a fresh() copy would only repeat the work as a deep copy.
tracer = callback
else:
# A factory function may return a tracer it keeps, so
# attach a fresh copy, as for a manual tracer.
tracer = owner._fresh_tracer(callback)
if not isinstance(tracer, GenericTracer) or tracer.name != definition.output_name:
raise ValueError("fresh() changed the tracer's canonical output name")
# Name the fresh instance so all its hooks and its final table share the declaration ID.
tracer.name = key
entries = _tracer_entries(tracer, hooks)
else:
if not callable(callback):
raise TypeError("factory must return a callable or a tracer")
if definition.output_name is not None:
raise TypeError("output_name requires a GenericTracer result")
# A legacy factory can return a named callback whose result key
# was unknown during preflight.
if (name := _result_name(callback)) in tracer_names:
raise ValueError(
f"A callback named {name!r} would store its results under the same name as a tracer"
)
entries = [(definition.when, callback)]
for hook, func in entries:
add(hook, func, tracer)
try:
# Annotations play no part in the binding check, and may
# name types imported only for type checking, which
# Python 3.14 would otherwise try to evaluate here.
signature = read_signature(func)
except (TypeError, ValueError):
continue # Some extension callables expose no signature.
signature.bind(owner, *([0] if hook == "daily" else []))
except Exception as error:
raise ValueError(f"callbacks.{key}: could not construct callback: {error}") from error