app.coordinates_setup module#

Validated orchestration helpers for coordinate persistence and retrieval.

This module provides a thin, validated wrapper around coordinate seeding, insertion, and listing. It centralizes argument checks, enforces geographic bounds, and adds structured logging around database calls. The goal is to give higher-level services a safe, predictable API that delegates the actual persistence and generation logic to app.coordinates_manager.

Notes#

Primary role: validate inputs (types and ranges) and orchestrate calls to lower-level coordinate operations (seed, list, insert).
Key dependencies: a live SQLAlchemy Session and the helpers in app.coordinates_manager for persistence and generation.
Invariants: callers own the Session lifecycle. Latitude must be within [-90, 90] and longitude within [-180, 180].

Examples#

>>> # Minimal validation example
>>> from app.coordinates_setup import validate_range
>>> validate_range(0.0, "x", -1.0, 1.0)

app.coordinates_setup.add_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 database.

Parameters:

sessionsqlalchemy.orm.Session: Database session controlling the transaction.
latitudefloat: Latitude of the coordinate (decimal degrees).
longitudefloat: Longitude of the coordinate (decimal degrees).
labelstr | None, optional: Optional label for the coordinate.
is_centralbool, optional: Whether the coordinate should be marked as central.

Raises:

SQLAlchemyError: If a database error occurs while inserting or committing.

See also

app.coordinates_manager.set_coordinate
app.schemas.CoordinateSchema

app.coordinates_setup.retrieve_all_coordinates(session: sqlalchemy.orm.Session) → list[CoordinateSchema][source]#

Retrieve all coordinates from the database.

Parameters:

sessionsqlalchemy.orm.Session: Open database session.

Returns:

list[app.schemas.CoordinateSchema]: All coordinates represented as Pydantic schemas.

Raises:

SQLAlchemyError: If a database error occurs when querying.

See also

app.coordinates_manager.get_coordinates
app.schemas.CoordinateSchema

Examples

>>> # Using a real DB session in application code
>>> # coords = retrieve_all_coordinates(session)
>>> # isinstance(coords, list)
True

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

Seed or validate central and surrounding coordinates.

Seeds the table with a central point plus surrounding points if empty; when not empty, validates that the persisted central point matches the provided values.

Parameters:

sessionsqlalchemy.orm.Session: Database session controlling the transaction.
central_latitudefloat: Latitude of the central coordinate (decimal degrees).
central_longitudefloat: Longitude of the central coordinate (decimal degrees).

Raises:

RuntimeError: If the stored central coordinate mismatches the provided values.
SQLAlchemyError: If a database error occurs during persistence or queries.

See also

app.coordinates_manager.seed_coordinates_if_needed
app.coordinates_manager.get_coordinates
app.schemas.CoordinateSchema

Examples

>>> # Typical application code (requires a real DB)
>>> # from app.database import SessionLocal
>>> # session = SessionLocal()
>>> # seed_coordinates_if_needed(session, 59.3, 18.06)

app.coordinates_setup.validate_range(value: float, name: str, min_value: float, max_value: float) → None[source]#

Validate that a numeric value lies within an inclusive range.

Parameters:

valuefloat: Numeric value to validate.
namestr: Descriptive name of the value, used in error messages.
min_valuefloat: Minimum allowed value (inclusive).
max_valuefloat: Maximum allowed value (inclusive).

Raises:

AssertionError: If value is outside [min_value, max_value].

See also

app.coordinates_setup.seed_coordinates_if_needed
app.coordinates_setup.add_coordinate
app.coordinates_setup.retrieve_all_coordinates

Examples

>>> validate_range(0.0, "x", -1.0, 1.0)
>>> validate_range(2.0, "x", -1.0, 1.0)
Traceback (most recent call last):
    ...
AssertionError: x must be between -1.0 and 1.0, but was 2.0.

app.coordinates_setup module#

See Also#

Notes#

Examples#