register_callback

passengersim.callbacks.configured.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.configured.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’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 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.