Source code for passengersim.tracers.generic

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import TYPE_CHECKING, ClassVar, Literal

if TYPE_CHECKING:
    import pandas as pd
    from pydantic import BaseModel

    from passengersim import Simulation


[docs] class GenericTracer(ABC): """Base class for tracers that collect detail while a simulation runs. Subclasses that can be enabled from a configuration declare, beside their constructor, everything a configured-callback registration needs: :attr:`name`, :attr:`hook`, :attr:`options_model`, and :attr:`options_version`. Then :func:`passengersim.callbacks.register_tracer_factory` registers the class without restating any of them. """ name: str = "generic_tracer" """Canonical result key in ``callback_data``.""" hook: ClassVar[Literal["initialize_sample", "begin_sample", "daily", "end_sample", "finalize_sample"]] """Lifecycle hook at which the tracer runs, for manual and configured attachment.""" options_model: ClassVar[type[BaseModel] | None] = None """Pydantic model of the constructor's keyword options, for configured callbacks. Its fields and defaults must match the constructor's arguments. """ options_version: ClassVar[str] = "1" """Configured-callback implementation version; bump when results change meaning."""
[docs] @abstractmethod def reset(self) -> None: """Reset the internal counters on this tracer to a null state.""" raise NotImplementedError()
[docs] @abstractmethod def fresh(self) -> GenericTracer: """Return a fresh copy of this tracer, tracing the same targets but not sharing state.""" raise NotImplementedError()
[docs] @abstractmethod def attach(self, sim: Simulation) -> None: """Attach this tracer to a Simulation, which will be traced as it runs.""" raise NotImplementedError()
[docs] @abstractmethod def finalize(self) -> pd.DataFrame: """Convert the internal counters on this tracer to a dataframe.""" raise NotImplementedError()