Source code for passengersim.config.paths

from __future__ import annotations

from typing import Any

from pydantic import BaseModel, Field, field_validator


[docs] class Path(BaseModel, extra="forbid"): """A travel path from an origin to a destination, comprised of one or more legs.""" path_id: int | None = None """Optional numeric identifier for the path.""" orig: str """Identifier code for the path origin. This is typically the IATA airport code for the origin airport, but it may be a different code if the path is being used in a non-air-travel context, or if the airport is a hypothetical place that does not have an assigned IATA code. """ dest: str """Identifier code for the path destination. This is typically the IATA airport code for the destination airport, but it may be a different code if the path is being used in a non-air-travel context, or if the airport is a hypothetical place that does not have an assigned IATA code. """ path_quality_index: float """A numeric index representing the quality of the path. Lower values typically indicate a more desirable itinerary. This is typically the number of connections on the path but could also be some other quality measure. """ legs: list[int] """Leg IDs of the legs comprising the path, in order from origin to destination. At least one leg is required. """ carrier: str | None = Field(default=None, exclude=True) """Carrier of the first leg, derived when the containing Config is validated. This metadata supports config filtering and is not used in the simulation or included in serialized configs. Validation replaces any supplied value with the first leg's carrier. A standalone Path defaults to None. After editing leg carriers or path legs, use ``cfg = cfg.model_revalidate()`` to refresh it. """ @field_validator("legs", mode="before") @classmethod def _allow_single_leg(cls, v: Any) -> list[int]: """Coerce a bare integer into a one-element list. Pydantic calls this validator before type coercion, so callers may supply a single flight number instead of a one-element list. Parameters ---------- v : int or list of int or Any The raw (pre-coercion) value supplied for ``legs``. Returns ------- list of int ``v`` wrapped in a list when it is a plain integer, otherwise ``v`` unchanged. """ if isinstance(v, int): return [v] return list(v) @field_validator("legs") @classmethod def _at_least_one_leg(cls, v: Any) -> list[int]: """Ensure the path contains at least one leg. Parameters ---------- v : list of int The post-coercion list of flight numbers. Returns ------- list of int ``v`` unchanged if it contains at least one element. Raises ------ ValueError If ``v`` is an empty list. """ legs: list[int] = list(v) if len(legs) < 1: raise ValueError("path must have at least one leg") return legs @property def market_identifier(self) -> str: """A tilde-separated string identifying the origin–destination market. Returns ------- str A string of the form ``"<orig>~<dest>"``, e.g. ``"JFK~LAX"``. """ return f"{self.orig}~{self.dest}"