from __future__ import annotations
import hashlib
import importlib.resources
import os
import pathlib
import re
import shutil
import stat
import time
from typing import TYPE_CHECKING, overload
import platformdirs
if TYPE_CHECKING:
from .contrast import Contrast
from .summaries import SimulationTables
_DAY = 24 * 60 * 60
DEMO_CACHE_SCAN_INTERVAL = 7 * _DAY
"""Minimum seconds between scans of the demo result cache for stale entries."""
DEMO_CACHE_MAX_AGE = 183 * _DAY
"""Seconds of disuse after which another version's cached demo results are removed (about six months)."""
_SCAN_MARKER = ".last-scan"
"""File in the demo cache root whose modification time records the last scan."""
[docs]
def demo_network(name: str) -> pathlib.Path:
"""
Load a demo network configuration file.
A few demo networks are bundled with the PassengerSim package, and are always
available to users.
Parameters
----------
name : str
The name of the network directory or a network file. If it is a directory,
the function will look for a `__main__.yaml` file in that directory. Otherwise
it will look for a file with the given name, with a .yaml or .yml extension.
If the extension is not provided, it will be added automatically.
Returns
-------
pathlib.Path
Path object pointing to the network configuration file.
Notes
-----
The network name is converted to lowercase to handle case sensitivity
differences between macOS (case-insensitive) and Linux (case-sensitive)
file systems. All packaged network files are stored in lowercase.
"""
demo_file_base = importlib.resources.files(__package__).joinpath("networks")
for ext in (".yaml", ".yml"):
if demo_file_base.joinpath(name.lower(), "__main__" + ext).exists():
return demo_file_base.joinpath(name.lower(), "__main__" + ext)
if not name.endswith(".yaml"):
name = f"{name}.yaml"
# note: on macOS by default the file system is not case sensitive, but
# on Linux it is. All the network files are lowercase, so we can get around
# this by forcing the name to lowercase.
return demo_file_base.joinpath(name.lower())
@overload
def demo_result(name: str, /) -> SimulationTables: ...
@overload
def demo_result(networks: dict[str, str], /) -> Contrast: ...
@overload
def demo_result(**networks: str) -> Contrast: ...
[docs]
def demo_result(*args: str | dict[str, str], **networks: str) -> SimulationTables | Contrast:
"""Load cached demo results, running networks as needed.
Parameters
----------
*args : str or dict[str, str]
One positional string names a demo network, as accepted by
:func:`demo_network`, and returns its results. Alternatively, one
dictionary maps comparison labels to demo network names.
**networks : str
With no positional arguments, map comparison labels to demo network
names. Cannot be combined with positional arguments.
Returns
-------
SimulationTables or Contrast
A single string returns results loaded from a cached ``.pxsim`` archive.
A dictionary or keyword arguments return a :class:`~passengersim.contrast.Contrast`
containing results under the supplied labels. Detailed SQLite data is
not retained. Close each result when finished with it.
Raises
------
FileNotFoundError
The requested demo configuration does not exist.
OSError
The cache cannot be read or written.
TypeError
Arguments mix positional and keyword forms, contain more than one
positional argument, or contain non-string labels or network names.
Calling without any arguments is also invalid.
Notes
-----
Archives are stored under ``platformdirs.user_cache_dir("passengersim")``
in the ``demo_results`` subdirectory, with one folder per PassengerSim
version. Only the PassengerSim version and lowercased demo name determine
the cache key. Configuration changes do not invalidate the cache; a new
PassengerSim version gets a new cache entry. Each cache hit refreshes the
archive's modification time to record its last use.
Auxiliary output files are disabled and any run database is temporary.
Networks with more than one trial run using :class:`MultiSimulation`;
single-trial networks use :class:`Simulation`. Trials run in parallel
worker processes from notebooks, interactive sessions, and platforms that
fork workers. When called from a script file on platforms that spawn
workers (macOS, Windows), trials run sequentially in the calling process,
because an unguarded script would otherwise be re-executed by each worker.
Delete the corresponding cache file to force a fresh simulation.
The cache is shared by every environment of the same user, so it may hold
results for several versions. At most once a week, a call that loads at
least one demo also scans the cache and deletes the folder of any other
PassengerSim version whose archives have not been used in about six
months. The running version's folder is never deleted by this scan.
Failures while scanning or deleting are ignored.
Examples
--------
>>> result = demo_result("europa")
>>> comparison = demo_result(Europa="europa", ThreeMarket="3mkt/demo")
>>> comparison = demo_result({"Europe": "europa", "Three markets": "3mkt/demo"})
"""
from .contrast import Contrast
if len(args) > 1 or (args and networks):
raise TypeError("Provide one demo name, one dictionary, or keyword arguments, without mixing forms")
if args:
if isinstance(args[0], str):
_prune_demo_cache()
return _demo_result(args[0])
if not isinstance(args[0], dict):
raise TypeError("The positional argument must be a demo name or a dictionary")
networks = args[0]
elif not networks:
raise TypeError("Provide a demo name, a dictionary, or keyword arguments")
# Validate the entire request before running any simulations.
if any(not isinstance(label, str) or not isinstance(name, str) for label, name in networks.items()):
raise TypeError("Comparison labels and demo network names must be strings")
if networks:
_prune_demo_cache()
results = Contrast()
try:
for label, name in networks.items():
results[label] = _demo_result(name)
except BaseException:
# A failed batch must not leave already-opened archive handles behind.
for result in results.values():
result.close()
raise
return results
def _demo_cache_dir() -> pathlib.Path:
"""Return the directory holding cached demo result archives."""
return pathlib.Path(platformdirs.user_cache_dir("passengersim")) / "demo_results"
def _version_dir_name(version: str) -> str:
"""Return the cache subdirectory name for archives written by `version`.
Version strings are normally filename-safe; anything unusual is replaced
so that the name stays a single portable path component.
"""
name = re.sub(r"[^A-Za-z0-9._+-]", "_", version)
# "." and ".." would escape the cache layout; prefix them to stay a plain name.
return name if name.strip(".") else f"v{name}"
def _last_used(path: pathlib.Path) -> float:
"""Return the latest modification time of a version directory or its direct entries.
Cache hits refresh the archive's modification time, so this is the most
recent use of any demo cached for that version.
"""
latest = path.lstat().st_mtime
for entry in path.iterdir():
try:
latest = max(latest, entry.lstat().st_mtime)
except OSError:
# The entry vanished mid-scan (e.g. a finished temporary write).
continue
return latest
def _prune_demo_cache(now: float | None = None) -> list[pathlib.Path]:
"""Delete cached demo results for other versions that have gone unused.
The cache holds one subdirectory per PassengerSim version. A subdirectory
for a version other than the running one is deleted when neither it nor
any archive in it has been used (modified) within
:data:`DEMO_CACHE_MAX_AGE` seconds before `now`. The running version's
directory is never deleted. Loose ``.pxsim`` files in the cache root,
which are not part of this layout, are deleted by the same age rule.
The scan runs at most once per :data:`DEMO_CACHE_SCAN_INTERVAL`, tracked
by the modification time of a marker file. Cleanup is best-effort:
filesystem errors never propagate to the caller.
Parameters
----------
now : float, optional
The current time as a POSIX timestamp. Defaults to :func:`time.time`.
Returns
-------
list[pathlib.Path]
The directories and files that were deleted.
"""
from ._version import __version__
if now is None:
now = time.time()
cache_dir = _demo_cache_dir()
marker = cache_dir / _SCAN_MARKER
try:
# A marker dated in the future (e.g. after a clock correction) does not
# suppress scanning, so a bad timestamp cannot disable cleanup forever.
if 0 <= now - marker.stat().st_mtime < DEMO_CACHE_SCAN_INTERVAL:
return []
except FileNotFoundError:
pass
except OSError:
return []
if not cache_dir.is_dir():
# Nothing is cached yet; avoid creating the directory just to hold a marker.
return []
try:
# Record the scan before doing it, so concurrent or failing calls do not
# repeat the work on every invocation.
marker.touch()
os.utime(marker, (now, now))
entries = list(cache_dir.iterdir())
except OSError:
return []
current = _version_dir_name(__version__)
removed = []
for entry in entries:
if entry.name in (current, _SCAN_MARKER):
continue
try:
info = entry.lstat()
# Never follow links out of the cache, and leave unrelated files alone.
if stat.S_ISDIR(info.st_mode):
if now - _last_used(entry) <= DEMO_CACHE_MAX_AGE:
continue
shutil.rmtree(entry)
elif stat.S_ISREG(info.st_mode) and entry.suffix == ".pxsim":
if now - info.st_mtime <= DEMO_CACHE_MAX_AGE:
continue
entry.unlink()
else:
continue
except OSError:
# Another process may have removed or locked something; skip it.
continue
removed.append(entry)
return removed
def _can_use_worker_processes() -> bool:
"""Report whether a multi-trial demo can safely run in worker processes.
Under the "spawn" and "forkserver" start methods, each worker re-imports
the main module. When that module is a script file without an
``if __name__ == "__main__":`` guard, the re-import calls `demo_result`
again and the run fails with an obscure EOFError. That guard cannot be
detected, so worker processes are used only when the main module is
interactive (a REPL or notebook, which has no ``__file__``) or workers are
forked.
Returns
-------
bool
True if a parallel :class:`MultiSimulation` run is safe here.
"""
import multiprocessing
import sys
if multiprocessing.get_start_method(allow_none=False) == "fork":
return True
main = sys.modules.get("__main__")
return getattr(main, "__file__", None) is None
def _demo_result(name: str) -> SimulationTables:
"""Load or generate one demo's cached summary archive."""
from ._version import __version__
from .config import Config
from .driver import MultiSimulation, Simulation
from .summaries import SimulationTables
# Hash the name so nested demo paths remain safe, portable cache filenames.
key = hashlib.sha256(name.lower().encode()).hexdigest()
cache_file = _demo_cache_dir() / _version_dir_name(__version__) / f"{key}.pxsim"
if cache_file.exists():
try:
# Mark the archive as recently used so other environments' pruning
# (which judges age by last use) keeps it.
os.utime(cache_file)
except OSError:
pass
else:
config = Config.from_yaml(demo_network(name))
config.outputs._write_no_files()
if config.db is not None:
config.db.filename = None
config.db.result_directory = None
config.db.result_storage = "temporary"
multi_trial = config.simulation_controls.num_trials > 1
simulation_class = MultiSimulation if multi_trial else Simulation
with simulation_class(config) as simulation:
if multi_trial and not _can_use_worker_processes():
# Same per-trial results, computed in this process (see above).
result = simulation.sequential_run()
else:
result = simulation.run()
try:
result.to_file(cache_file, add_timestamp_ext=False, make_dirs="git")
finally:
# The live result may hold a temporary run database; callers
# receive the reloaded archive below, so release it now.
result.close()
# Reload even on a miss so callers get the same summary-only behavior.
return SimulationTables.from_file(cache_file, read_latest=False)
[docs]
def demo_output(name: str) -> pathlib.Path:
"""
Load a demo output file.
A few demo output files are bundled with the PassengerSim package, and are always
available to user, without needing to load or run a simulation.
Parameters
----------
name : str
The name of the output file, with or without the .pxsim extension.
If the extension is not provided, it will be added automatically.
Returns
-------
pathlib.Path
Path object pointing to the output file.
Notes
-----
The output name is converted to lowercase to handle case sensitivity
differences between macOS (case-insensitive) and Linux (case-sensitive)
file systems. All output files are stored in lowercase.
"""
if not name.endswith(".pxsim"):
name = f"{name}.pxsim"
return importlib.resources.files(__package__).joinpath("networks").joinpath(name.lower())