app.utils module#

Utility helpers for logging, time formatting, and startup checks.

This module centralizes a few cross-cutting utilities used throughout the application: persistent log configuration, simple conversion/formatting of timestamps to a Sweden-specific display timezone, and a startup helper that seeds or validates central coordinates based on configuration. Keeping these helpers in one place reduces duplication across the FastAPI app and background jobs.

Notes#

Primary role: provide persistent logging configuration; convert and format timestamps for the UI; perform idempotent coordinate seeding/validation at process startup.
Key dependencies: app.config.settings for optional central latitude and longitude; app.database.SessionLocal for DB access; and app.coordinates_manager.seed_coordinates_if_needed for the seeding logic.
Invariants: log files are rotated daily and written to the path in FASTAPI_LOG_PATH (default /data/logs/fastapi.log). Timezone handling uses a fixed UTC+2 offset and does not account for daylight saving time.

Examples#

>>> # Convert a UTC timestamp to the Sweden display timezone
>>> from datetime import datetime, timezone
>>> from app.utils import to_sweden_time, format_sweden_time
>>> dt = datetime(2024, 1, 1, 12, 0, tzinfo=timezone.utc)
>>> to_sweden_time(dt).utcoffset().total_seconds() == 2 * 3600
True
>>> format_sweden_time(dt)
'2024-01-01 14:00:00'

app.utils.build_status_data(logs: Mapping[str, TrainingLogDetails]) → Dict[str, Dict[str, Any]][source]#

Transform latest training logs into a rendering‑friendly mapping.

Parameters:

logsMapping[str, app.ml_utils.TrainingLogDetails]: Mapping where each key is a horizon and each value describes the latest training result for that horizon.

Returns:

dict[str, dict[str, Any]]: Mapping from display keys to status dictionaries (see _build_status_entry()). Returns an empty mapping when logs is empty.

Raises:

AssertionError: If logs is not a Mapping.

Examples

>>> from datetime import datetime, timezone
>>> from app.utils import build_status_data
>>> dt = datetime(2024, 1, 1, 12, 0, tzinfo=timezone.utc)
>>> logs = {
...     'h1': {
...         'timestamp': dt,
...         'sklearn_score': 0.9,
...         'pytorch_score': 0.8,
...         'data_count': 42,
...         'coord_latitude': 59.3,
...         'coord_longitude': 18.1,
...         'horizon_label': '1h',
...         'horizon_display_name': 'Coord (59.30, 18.10) - Horizon: 1h',
...     }
... }
>>> data = build_status_data(logs)
>>> list(data.keys()) == ['Coord (59.30, 18.10) - Horizon: 1h']
True

app.utils.configure_persistent_logging() → None[source]#

Configure persistent, daily‑rotated logging to a file.

Sets up a TimedRotatingFileHandler writing to FASTAPI_LOG_PATH (default /data/logs/fastapi.log), rotating at midnight, keeping a bounded number of backups, and applying a consistent formatter. If a matching handler is already installed on the root logger, this function is a no‑op to avoid duplicate log lines.

Returns:

None: This function mutates the global logging configuration and does not return a value.

Notes

The default stream handler is removed to prevent duplicate logs if both handlers are present. Adjust in callers if both sinks are desired.
This helper touches the filesystem to create the log directory.

Examples

>>> # Configures a rotating file handler on the root logger
>>> from app.utils import configure_persistent_logging
>>> configure_persistent_logging()

app.utils.format_sweden_time(utc_dt: datetime) → str[source]#

Format a UTC timestamp as a Sweden‑timezone display string.

Parameters:

utc_dtdatetime: A timezone‑aware UTC datetime or a naive datetime interpreted as UTC.

Returns:

str: A formatted YYYY-MM-DD HH:MM:SS string in the fixed Sweden timezone.

Examples

>>> from datetime import datetime, timezone
>>> from app.utils import format_sweden_time
>>> format_sweden_time(datetime(2024, 1, 1, 12, 0, tzinfo=timezone.utc))
'2024-01-01 14:00:00'

app.utils.format_sweden_time_iso(utc_dt: datetime) → str[source]#

Format a UTC timestamp as an ISO 8601 string in Sweden timezone.

Parameters:

utc_dtdatetime: A timezone‑aware UTC datetime or a naive datetime interpreted as UTC.

Returns:

str: An ISO 8601 formatted string in the fixed Sweden timezone.

Examples

>>> from datetime import datetime, timezone
>>> from app.utils import format_sweden_time_iso
>>> s = format_sweden_time_iso(datetime(2024, 1, 1, 12, 0, tzinfo=timezone.utc))
>>> s.endswith('+02:00')
True

app.utils.to_sweden_time(utc_dt: datetime) → datetime[source]#

Convert a UTC timestamp to the Sweden display timezone (UTC+2).

Naive datetimes are interpreted as UTC. This simplified conversion uses a fixed UTC+2 offset and intentionally does not account for daylight saving time transitions.

Parameters:

utc_dtdatetime: A timezone‑aware UTC datetime or a naive datetime interpreted as UTC.

Returns:

datetime: A datetime converted to the fixed Sweden timezone (UTC+2).

Raises:

AssertionError: If utc_dt is not a datetime instance.

Examples

>>> from datetime import datetime, timezone
>>> from app.utils import to_sweden_time
>>> dt = datetime(2024, 1, 1, 12, 0, tzinfo=timezone.utc)
>>> to_sweden_time(dt).strftime('%Y-%m-%d %H:%M:%S')
'2024-01-01 14:00:00'

app.utils module#

See Also#

Notes#

Examples#