utils

Utility functions and helpers for the PISA package.

This module contains utility functions that are used throughout the PISA package, including validation functions, caching mechanisms, and other helper functions that support the core functionality of the package.

Functions

`disk_cache`(→ Callable)	Implement disk-based caching for function results.
`validate_distance_type`(→ str)	Validate and normalize distance type input.
`validate_mode_of_transport`(→ str)	Validate and normalize mode of transport input.
`validate_fallback_speed`(→ int \| float \| None)	Validate that a fallback speed is within reasonable bounds for the given transport mode.

Module Contents

utils.disk_cache(cache_dir: str = 'cache') → Callable

Implement disk-based caching for function results.

This decorator saves the result of a function call to a file on disk and loads it on subsequent calls with the same arguments, avoiding redundant computations.

Parameters:: cache_dir (str, optional) – Directory where cache files will be stored. (default: cache)
Returns:: A decorated function that implements caching behavior
Return type:: callable

Example

>>> @disk_cache()
>>> def expensive_computation(x):
>>>     # Some time-consuming calculation
>>>     return x ** 2

Notes

Cache files are stored as pickle files
Cache keys are generated using SHA-256 hash of function name and arguments
Creates cache directory if it doesn’t exist
Cache files are named using the hash of the function name and arguments

Raises:

pickle.PickleError – If there are issues serializing/deserializing the cached data
OSError – If there are issues with file operations

utils.validate_distance_type(distance_type: str) → str

Validate and normalize distance type input.

Parameters:: distance_type (str) – The distance type to validate (length or travel_time)
Returns:: Normalized distance type (lowercase, stripped of whitespace)
Return type:: str
Raises:: ValueError – If distance_type is not one of the valid types defined in VALID_DISTANCE_TYPES