register_callback¶
-
passengersim.callbacks.register_callback(func: CallbackT, /, *, when: 'initialize_sample' | 'begin_sample' | 'daily' | 'end_sample' | 'finalize_sample', name: str | None =
None, parameters_model: type[BaseModel] | None =None, version: str ='1', priority: int | None =None, skip_burn: bool | None =None) CallbackT[source]¶ -
passengersim.callbacks.register_callback(*, when: 'initialize_sample' | 'begin_sample' | 'daily' | 'end_sample' | 'finalize_sample', name: str | None =
None, parameters_model: type[BaseModel] | None =None, version: str ='1', priority: int | None =None, skip_burn: bool | None =None) collections.abc.Callable[[CallbackT], CallbackT] 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’sparameters:@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, orend_sample); seedaily_callback(). Defaults to the function’s ownpriorityattribute, 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_burnattribute, 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
priorityandskip_burnare 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.