Source code for passengersim.callbacks.configured

"""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