graphways.pyi

"""
Type stubs for graphways -- the compiled Rust extension.

Geometry results are structured Python objects. Use ``to_geojson()`` when you
need serialized GeoJSON for Folium, GeoPandas, or web maps.
"""

from __future__ import annotations

# ---------------------------------------------------------------------------
# Result objects
# ---------------------------------------------------------------------------

class SnapResult:
    """Nearest-network-node snap diagnostics for coordinate-based operations."""

    @property
    def input_lat(self) -> float: ...

    @property
    def input_lon(self) -> float: ...

    @property
    def node_id(self) -> int: ...

    @property
    def node_lat(self) -> float: ...

    @property
    def node_lon(self) -> float: ...

    @property
    def distance_m(self) -> float: ...

    def as_dict(self) -> dict[str, float | int]: ...

    def __repr__(self) -> str: ...

class RouteResult:
    """Fastest route result with metrics, snap diagnostics, and GeoJSON export."""

    @property
    def coordinates(self) -> list[tuple[float, float]]: ...

    @property
    def cumulative_times_s(self) -> list[float]: ...

    @property
    def distance_m(self) -> float: ...

    @property
    def duration_s(self) -> float: ...

    @property
    def origin_snap(self) -> SnapResult: ...

    @property
    def destination_snap(self) -> SnapResult: ...

    def as_dict(self) -> dict[str, object]: ...

    def to_geojson(self) -> str:
        """Return this route as a GeoJSON ``Feature`` string."""
        ...

    def __repr__(self) -> str: ...

class IsochroneResult:
    """One isochrone polygon for one travel-time threshold."""

    @property
    def minutes(self) -> float: ...

    def as_dict(self) -> dict[str, object]: ...

    def to_geojson(self) -> str:
        """Return this isochrone polygon as a GeoJSON geometry string."""
        ...

    def __repr__(self) -> str: ...

class Poi:
    """OpenStreetMap point of interest returned by ``SpatialGraph.fetch_pois``."""

    @property
    def id(self) -> int: ...

    @property
    def lat(self) -> float: ...

    @property
    def lon(self) -> float: ...

    @property
    def tags(self) -> dict[str, str]: ...

    def as_dict(self) -> dict[str, object]: ...

    def __repr__(self) -> str: ...

class PoiCollection:
    """Collection of POIs with structured access and GeoJSON export."""

    @property
    def count(self) -> int: ...

    @property
    def pois(self) -> list[Poi]: ...

    def as_dict(self) -> dict[str, object]: ...

    def to_geojson(self) -> str:
        """Return POIs as a GeoJSON ``FeatureCollection`` string."""
        ...

    def __len__(self) -> int: ...

    def __repr__(self) -> str: ...

# ---------------------------------------------------------------------------
# Graph views
# ---------------------------------------------------------------------------

class ReachableGraph:
    """
    Travel-time-labeled graph view produced by ``SpatialGraph.reachable``.

    Cheap inspection methods operate on the parent graph plus reachable labels.
    Constrained routing and isochrones materialize a bounded subgraph internally.
    """

    @property
    def max_time_s(self) -> float: ...

    def node_count(self) -> int: ...

    def edge_count(self) -> int: ...

    def contains_node(self, node_id: int) -> bool: ...

    def nearest_node(
        self, lat: float, lon: float
    ) -> tuple[int, float, float] | None: ...

    def travel_time_to_node_id(self, node_id: int) -> float | None: ...

    def nodes(self) -> list[dict[str, float | int]]:
        """
        Return reachable nodes with ``node_id``, ``lat``, ``lon``, and
        ``travel_time_s``.
        """
        ...

    def nodes_geojson(self) -> str:
        """
        Return reachable nodes as a GeoJSON ``FeatureCollection`` of points.
        """
        ...

    def edges_geojson(self) -> str:
        """
        Return edges whose source and target nodes are both reachable.
        """
        ...

    def to_geojson(self) -> str:
        """
        Return reachable nodes and edges in one GeoJSON ``FeatureCollection``.
        """
        ...

    def isochrone(
        self,
        origin: tuple[float, float],
        minutes: list[float],
        max_snap_m: float | None = 100.0,
    ) -> list[IsochroneResult]:
        """
        Compute isochrones within this reachable subgraph.
        """
        ...

    def route(
        self,
        origin: tuple[float, float],
        destination: tuple[float, float],
        max_snap_m: float | None = 100.0,
    ) -> RouteResult:
        """
        Find the fastest route constrained to this reachable subgraph.
        """
        ...

    def __repr__(self) -> str: ...

class PrismGraph:
    """
    Network-time prism produced by ``SpatialGraph.prism``.

    Cheap inspection methods operate on the parent graph plus prism labels.
    Constrained routing and isochrones materialize a bounded subgraph internally.
    """

    @property
    def max_time_s(self) -> float: ...

    @property
    def traversal_budget_s(self) -> float: ...

    @property
    def stop_time_s(self) -> float: ...

    @property
    def buffer_s(self) -> float: ...

    @property
    def direct_time_s(self) -> float: ...

    def node_count(self) -> int: ...

    def edge_count(self) -> int: ...

    def contains_node(self, node_id: int) -> bool: ...

    def nearest_node(
        self, lat: float, lon: float
    ) -> tuple[int, float, float] | None: ...

    def slack_at_node_id(self, node_id: int) -> float | None: ...

    def nodes(self) -> list[dict[str, float | int]]:
        """
        Return nodes with ``node_id``, ``lat``, ``lon``, ``inbound_time_s``,
        ``outbound_time_s``, and ``slack_s``.
        """
        ...

    def nodes_geojson(self) -> str:
        """
        Return prism nodes as a GeoJSON ``FeatureCollection`` of points.
        """
        ...

    def edges_geojson(self) -> str:
        """
        Return edges whose source and target nodes are both inside the prism.
        """
        ...

    def to_geojson(self) -> str:
        """
        Return prism nodes and edges in one GeoJSON ``FeatureCollection``.
        """
        ...

    def slack_polygon(self, min_slack_s: float = 0.0) -> str | None:
        """
        Build a GeoJSON polygon enclosing nodes with at least ``min_slack_s``.
        """
        ...

    def slack_polygons(self, min_slack_values: list[float]) -> list[str | None]:
        """
        Build one slack polygon per minimum-slack threshold.
        """
        ...

    def isochrone(
        self,
        origin: tuple[float, float],
        minutes: list[float],
        max_snap_m: float | None = 100.0,
    ) -> list[IsochroneResult]:
        """
        Compute isochrones constrained to this prism subgraph.
        """
        ...

    def route(
        self,
        origin: tuple[float, float],
        destination: tuple[float, float],
        max_snap_m: float | None = 100.0,
    ) -> RouteResult:
        """
        Find the fastest route constrained to this prism subgraph.
        """
        ...

    def __repr__(self) -> str: ...

class SpatialGraph:
    """
    A road-network graph loaded from OpenStreetMap.

    Construct once with :meth:`from_place`, :meth:`from_pbf`, or :meth:`from_osm`.
    Reuse the same object across multiple queries to avoid rebuilding the graph.

    Attributes are read-only; all mutations happen inside Rust.
    """

    @staticmethod
    def from_pbf(
        path: str,
        network: str,
        retain_all: bool = False,
    ) -> SpatialGraph:
        """
        Load a local OSM PBF file into a reusable ``SpatialGraph``.

        ``network`` accepts ``"drive"``, ``"drive_service"``, ``"walk"``,
        ``"bike"``, ``"all"``, or ``"all_private"``.
        """
        ...

    @staticmethod
    def from_osm(
        xml: str,
        network: str,
        retain_all: bool = False,
    ) -> SpatialGraph:
        """
        Parse an OSM XML string into a reusable ``SpatialGraph``.

        ``network`` accepts ``"drive"``, ``"drive_service"``, ``"walk"``,
        ``"bike"``, ``"all"``, or ``"all_private"``.
        """
        ...

    @staticmethod
    def from_place(
        place: str,
        network: str,
        max_dist: float | None = None,
        retain_all: bool = False,
    ) -> SpatialGraph:
        """
        Geocode a place name and build a reusable ``SpatialGraph`` around it.

        ``network`` accepts ``"drive"``, ``"drive_service"``, ``"walk"``,
        ``"bike"``, ``"all"``, or ``"all_private"``.
        """
        ...

    def node_count(self) -> int:
        """Number of nodes in the graph."""
        ...

    def edge_count(self) -> int:
        """Number of directed edges in the graph."""
        ...

    def nearest_node(
        self, lat: float, lon: float
    ) -> tuple[int, float, float] | None:
        """
        Return ``(osm_id, lat, lon)`` for the node nearest to ``(lat, lon)``.

        Uses the internal R-tree spatial index -- O(log n).
        Returns ``None`` if the graph is empty.
        """
        ...

    def isochrone(
        self,
        origin: tuple[float, float],
        minutes: list[float],
        max_snap_m: float | None = 100.0,
    ) -> list[IsochroneResult]:
        """
        Compute isochrones from ``(lat, lon)`` using this graph.

        Parameters
        ----------
        origin:
            ``(lat, lon)`` origin coordinates.
        minutes:
            Travel-time thresholds in minutes.
        Returns
        -------
        list[IsochroneResult]
            One polygon result per time limit, in the same order as
            ``minutes``. Call ``to_geojson()`` when you need serialized
            GeoJSON.
        """
        ...

    def route(
        self,
        origin: tuple[float, float],
        destination: tuple[float, float],
        max_snap_m: float | None = 100.0,
    ) -> RouteResult:
        """
        Find the fastest route between two coordinates using A*.

        The network type (drive/walk/bike) is inherited from the ``SpatialGraph``.

        Returns
        -------
        RouteResult
            Structured result with ``distance_m``, ``duration_s``,
            ``coordinates``, ``cumulative_times_s``, and snap diagnostics.

        """
        ...

    def fetch_pois(self, isochrone: IsochroneResult | str) -> PoiCollection:
        """
        Fetch OSM points of interest within a given isochrone polygon.

        Parameters
        ----------
        isochrone:
            An ``IsochroneResult`` from :meth:`isochrone`, or a GeoJSON
            geometry string.

        Returns
        -------
        str
            Structured POI collection. Call ``to_geojson()`` for a GeoJSON
            ``FeatureCollection``.
        """
        ...

    def snap_point(self, lat: float, lon: float) -> SnapResult | None:
        """
        Return snap diagnostics for the nearest graph node to ``(lat, lon)``.

        Use ``as_dict()`` if you need a plain dictionary.
        """
        ...

    def reachable(
        self,
        origin: tuple[float, float],
        minutes: float,
        max_snap_m: float | None = 100.0,
    ) -> ReachableGraph:
        """
        Compute one-sided reachability from ``(lat, lon)`` within ``minutes``.
        """
        ...

    def prism(
        self,
        origin: tuple[float, float],
        destination: tuple[float, float],
        max_minutes: float,
        stop_minutes: float = 0.0,
        buffer_minutes: float = 0.0,
        max_snap_m: float | None = 100.0,
    ) -> PrismGraph:
        """
        Return the network-time prism for nodes that fit within:

        ``origin -> node -> destination + stop_minutes + buffer_minutes <= max_minutes``.
        """
        ...

    def nodes_geojson(self) -> str:
        """
        All graph nodes as a GeoJSON ``FeatureCollection`` of ``Point`` features.

        Properties per feature: ``id``, ``lat``, ``lon``.
        """
        ...

    def edges_geojson(self) -> str:
        """
        All graph edges as a GeoJSON ``FeatureCollection`` of ``LineString`` features.

        Properties per feature: ``highway``, ``length_m``, ``speed_kph``,
        ``drive_time_s``, ``walk_time_s``, ``bike_time_s``.
        """
        ...

    def __repr__(self) -> str: ...

# ---------------------------------------------------------------------------
# Module-level functions
# ---------------------------------------------------------------------------

def geocode(place: str) -> tuple[float, float]:
    """
    Convert a place name to ``(lat, lon)`` via the Nominatim API.

    Parameters
    ----------
    place:
        Any Nominatim-supported query string (e.g. ``"Marienplatz, Munich, Germany"``).

    Returns
    -------
    tuple[float, float]
        ``(latitude, longitude)``
    """
    ...

def cache_dir() -> str:
    """
    Return the path to the on-disk XML cache directory.

    Override the default by setting the ``GRAPHWAYS_CACHE_DIR`` environment variable.
    """
    ...

def clear_cache() -> None:
    """
    Clear both the in-memory and on-disk XML caches.
    """
    ...