app.coordinates_manager module#

Coordinate management for seeding, retrieval, and central-point validation.

This module provides a focused set of utilities for initializing and validating the coordinate grid used by the weather pipeline. It inserts a single central coordinate and a deterministic ring of surrounding coordinates, and exposes read helpers that return Pydantic schemas. The goal is to keep persistence and validation responsibilities decoupled from input validation and orchestration logic in higher-level modules.

Notes#

Primary role: persist a central coordinate and a deterministic set of surrounding points and validate that the stored central coordinate matches the configured central values.
Key dependencies: a live SQLAlchemy Session, the ORM model app.models.Coordinate, and the Pydantic schema app.schemas.CoordinateSchema. Geodesic calculations are delegated to app.coordinates_utils.calculate_destination_point.
Invariants: callers own the Session lifecycle. Exactly one row is marked as the central coordinate (is_central=True). Generated points are deterministic for the given bearings and distances.

Examples#

>>> # Typical usage within a request/worker context (requires a real DB)
>>> # from app.database import SessionLocal
>>> # session = SessionLocal()
>>> # seed_coordinates_if_needed(session, 59.3293, 18.0686)
>>> # coords = get_coordinates(session)
>>> # len(coords) > 0
True

app.coordinates_manager.get_coordinates(session: sqlalchemy.orm.Session) → List[CoordinateSchema][source]#

Retrieve all coordinates as Pydantic schemas.

Parameters:

sessionsqlalchemy.orm.Session: Open database session to run the query.

Returns:

list[app.schemas.CoordinateSchema]: List of coordinates converted from ORM objects using model_validate.

Raises:

sqlalchemy.exc.SQLAlchemyError: If an underlying database error occurs during the query.

Examples

>>> # coords = get_coordinates(session)
>>> # isinstance(coords, list)
True

app.coordinates_manager.seed_coordinates_if_needed(session: sqlalchemy.orm.Session, central_latitude: float, central_longitude: float) → None[source]#

Seed the table or validate the persisted central coordinate.

If the table is empty, inserts the central point and a deterministic set of surrounding points. Otherwise validates that the stored central point is equal (within tolerance) to the configured central coordinate.

Parameters:

sessionsqlalchemy.orm.Session: Database session controlling the transaction.
central_latitudefloat: Central latitude, typically provided by configuration.
central_longitudefloat: Central longitude, typically provided by configuration.

Raises:

RuntimeError: If the central coordinate is missing or mismatches the provided values.

See also

app.coordinates_manager.get_coordinates
app.coordinates_manager.set_coordinate
app.coordinates_utils.calculate_destination_point

Examples

>>> # Using a real DB session in application code
>>> # seed_coordinates_if_needed(session, 59.3293, 18.0686)
>>> # (no return value)

app.coordinates_manager.set_coordinate(session: sqlalchemy.orm.Session, latitude: float, longitude: float, label: str | None = None, is_central: bool = False) → None[source]#

Add a new coordinate to the table.

Parameters:

sessionsqlalchemy.orm.Session: Session used to persist the new coordinate.
latitudefloat: Latitude in decimal degrees.
longitudefloat: Longitude in decimal degrees.
labelstr | None, optional: Optional label describing the coordinate.
is_centralbool, optional: Whether the coordinate represents the central point (default False).

Raises:

sqlalchemy.exc.SQLAlchemyError: If a database error occurs while persisting the new coordinate.

Notes

Commits immediately after inserting the object.

app.coordinates_manager module#

See Also#

Notes#

Examples#