tiny-osm 0.1.0__py3-none-any.whl

tiny_osm/__init__.py

@@ -0,0 +1,24 @@
+"""TinyOSM: Fetch OpenStreetMap data for a bounding box."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from tiny_osm import exceptions
+from tiny_osm._logging import configure_logger
+from tiny_osm.exceptions import OverpassError
+from tiny_osm.osm_fetch import OSMFilters, fetch
+
+try:
+    __version__ = version("tiny_osm")
+except PackageNotFoundError:
+    __version__ = "999"
+
+__all__ = [
+    "OSMFilters",
+    "OverpassError",
+    "__version__",
+    "configure_logger",
+    "exceptions",
+    "fetch",
+]

tiny_osm/_geojson.py

@@ -0,0 +1,325 @@
+"""Convert Overpass API responses into GeoJSON Features.
+
+The Overpass queries built by :mod:`tiny_osm.osm_fetch` use ``out geom;``,
+so every way and every relation member already carries its lat/lon
+coordinates inline - no secondary node-ID lookup is needed.
+
+This module turns that raw response stream into a valid GeoJSON
+``FeatureCollection`` dict that can be fed directly to
+``geopandas.GeoDataFrame.from_features`` without any post-processing.
+Responses from multiple tile/layer queries are deduplicated by
+``(type, id)`` in a single pass, so callers can pass the full list of
+per-query responses straight through.
+
+Geometry rules
+--------------
+* ``node`` elements become ``Point`` features **only if they carry tags**.
+  Untagged nodes that appear in Overpass responses are orphan geometry
+  primitives and are silently dropped.
+* ``way`` elements become ``LineString`` features, unless the way is
+  closed and its tags mark it as an area (see :func:`_is_area`) - in
+  which case it becomes a ``Polygon``.
+* ``relation`` elements become ``Polygon`` or ``MultiPolygon`` features
+  **only when ``type=multipolygon``**.  Other relation types (routes,
+  boundaries, turn restrictions, …) are silently dropped: they don't fit
+  the highway/waterway/water-body data model tiny-osm targets.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tiny_osm._logging import logger
+
+__all__ = ["elements_to_features"]
+
+# ---------------------------------------------------------------------------
+# Tag heuristics
+# ---------------------------------------------------------------------------
+
+# Keys whose presence on a closed way marks it as an area (polygon).
+# Derived from the OSM wiki Polygon Features table, restricted to the tags
+# tiny-osm can plausibly return.  Tags not in this set default to "line",
+# so a closed road without ``area=yes`` stays a LineString.
+_AREA_KEYS: frozenset[str] = frozenset(
+    {
+        "amenity",
+        "basin",
+        "boundary",
+        "building",
+        "landuse",
+        "leisure",
+        "natural",
+        "place",
+        "water",
+        "waterway",  # e.g. waterway=riverbank, waterway=dock - closed = polygon
+    }
+)
+
+# ``natural`` values that stay as linestrings even when closed.
+_NATURAL_LINE_VALUES: frozenset[str] = frozenset({"coastline", "cliff", "ridge", "tree_row"})
+
+# ``waterway`` values that stay as linestrings even when closed.
+_WATERWAY_LINE_VALUES: frozenset[str] = frozenset(
+    {"river", "stream", "canal", "drain", "ditch", "brook", "tidal_channel"}
+)
+
+
+def _is_area(tags: dict[str, str]) -> bool:
+    """Return ``True`` if a closed way's tags imply a polygon geometry.
+
+    Implements the Polygon Features rule tree:
+
+    1. ``area=yes`` → always polygon
+    2. ``area=no`` → always line
+    3. ``natural=coastline|cliff|ridge|tree_row`` → line
+    4. ``waterway=river|stream|canal|...`` → line (even when closed)
+    5. Any area-implying key present → polygon
+    6. Otherwise → line
+    """
+    area = tags.get("area")
+    if area == "yes":
+        return True
+    if area == "no":
+        return False
+    if tags.get("natural") in _NATURAL_LINE_VALUES:
+        return False
+    if tags.get("waterway") in _WATERWAY_LINE_VALUES:
+        return False
+    return any(k in tags for k in _AREA_KEYS)
+
+
+# ---------------------------------------------------------------------------
+# Coordinate helpers
+# ---------------------------------------------------------------------------
+
+
+def _coords_from_geometry(geom: list[dict[str, float]]) -> list[list[float]]:
+    """Convert Overpass ``[{lat, lon}, ...]`` to GeoJSON ``[[lon, lat], ...]``."""
+    return [[p["lon"], p["lat"]] for p in geom]
+
+
+def _is_closed(coords: list[list[float]]) -> bool:
+    """A ring needs at least 4 points (3 unique + closure) and equal endpoints."""
+    return len(coords) >= 4 and coords[0] == coords[-1]
+
+
+def _make_feature(
+    osm_type: str,
+    osm_id: int,
+    geometry: dict[str, Any],
+    tags: dict[str, str],
+) -> dict[str, Any]:
+    """Assemble a GeoJSON Feature.
+
+    The ``id`` is a string of the form ``"way/12345"`` so that identifiers
+    remain unique across node/way/relation spaces.  Tags go directly into
+    ``properties``; an ``osm_type`` key is added so downstream code can
+    tell node-Points from way-LineStrings even after flattening into a
+    GeoDataFrame.
+    """
+    return {
+        "type": "Feature",
+        "id": f"{osm_type}/{osm_id}",
+        "geometry": geometry,
+        "properties": {"osm_type": osm_type, "osm_id": osm_id, **tags},
+    }
+
+
+# ---------------------------------------------------------------------------
+# Element converters
+# ---------------------------------------------------------------------------
+
+
+def _node_to_feature(node: dict[str, Any]) -> dict[str, Any] | None:
+    tags = node.get("tags")
+    if not tags:
+        return None  # orphan member node - drop
+    return _make_feature(
+        "node",
+        node["id"],
+        {"type": "Point", "coordinates": [node["lon"], node["lat"]]},
+        tags,
+    )
+
+
+def _way_to_feature(way: dict[str, Any]) -> dict[str, Any] | None:
+    tags = way.get("tags") or {}
+    geometry = way.get("geometry")
+    if not geometry:
+        return None  # way outside queried bbox or otherwise empty
+
+    coords = _coords_from_geometry(geometry)
+    if len(coords) < 2:
+        return None
+
+    if _is_closed(coords) and _is_area(tags):
+        return _make_feature(
+            "way",
+            way["id"],
+            {"type": "Polygon", "coordinates": [coords]},
+            tags,
+        )
+    return _make_feature(
+        "way",
+        way["id"],
+        {"type": "LineString", "coordinates": coords},
+        tags,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Multipolygon ring assembly
+# ---------------------------------------------------------------------------
+
+
+def _assemble_rings(ways: list[list[list[float]]]) -> list[list[list[float]]]:  # noqa: C901
+    """Stitch a list of way coordinate sequences into closed rings.
+
+    Ways that arrive already closed pass through unchanged.  Open ways are
+    joined pairwise by shared endpoints - each iteration looks for a
+    remaining way whose first or last point matches the current chain's
+    first or last point, and extends (reversing if needed).  Fragments
+    that cannot be closed are logged and dropped.
+    """
+    closed: list[list[list[float]]] = []
+    remaining: list[list[list[float]]] = []
+    for way in ways:
+        if len(way) < 2:
+            continue
+        (closed if _is_closed(way) else remaining).append(way)
+
+    while remaining:
+        chain = list(remaining.pop(0))
+        extended = True
+        while extended and not _is_closed(chain):
+            extended = False
+            for i, way in enumerate(remaining):
+                if way[0] == chain[-1]:
+                    chain.extend(way[1:])
+                elif way[-1] == chain[-1]:
+                    chain.extend(reversed(way[:-1]))
+                elif way[-1] == chain[0]:
+                    chain = list(way) + chain[1:]
+                elif way[0] == chain[0]:
+                    chain = list(reversed(way)) + chain[1:]
+                else:
+                    continue
+                remaining.pop(i)
+                extended = True
+                break
+        if _is_closed(chain):
+            closed.append(chain)
+        else:
+            logger.debug(f"multipolygon fragment with {len(chain)} points could not close")
+    return closed
+
+
+def _ring_contains_point(ring: list[list[float]], point: list[float]) -> bool:
+    """Ray-casting point-in-ring test.  Input ring is assumed closed."""
+    x, y = point
+    inside = False
+    n = len(ring)
+    j = n - 1
+    for i in range(n):
+        xi, yi = ring[i]
+        xj, yj = ring[j]
+        if ((yi > y) != (yj > y)) and (x < (xj - xi) * (y - yi) / (yj - yi) + xi):
+            inside = not inside
+        j = i
+    return inside
+
+
+def _relation_to_feature(relation: dict[str, Any]) -> dict[str, Any] | None:  # noqa: C901
+    tags = relation.get("tags") or {}
+    if tags.get("type") != "multipolygon":
+        return None  # only multipolygon relations produce geometries here
+
+    outer_ways: list[list[list[float]]] = []
+    inner_ways: list[list[list[float]]] = []
+    for member in relation.get("members", []):
+        if member.get("type") != "way":
+            continue
+        member_geom = member.get("geometry")
+        if not member_geom:
+            continue
+        coords = _coords_from_geometry(member_geom)
+        if len(coords) < 2:
+            continue
+        # Members without an explicit role default to "outer" - matches the
+        # osmnx + JOSM convention for legacy relations.
+        if member.get("role") == "inner":
+            inner_ways.append(coords)
+        else:
+            outer_ways.append(coords)
+
+    outer_rings = _assemble_rings(outer_ways)
+    if not outer_rings:
+        return None
+    inner_rings = _assemble_rings(inner_ways)
+
+    # Each polygon starts as [outer]; we append its contained inner rings.
+    polygons: list[list[list[list[float]]]] = [[ring] for ring in outer_rings]
+    for inner in inner_rings:
+        for idx, outer in enumerate(outer_rings):
+            # A point on the inner ring is either inside its outer shell or
+            # inside no shell at all; testing the first vertex is sufficient.
+            if _ring_contains_point(outer, inner[0]):
+                polygons[idx].append(inner)
+                break
+
+    if len(polygons) == 1:
+        return _make_feature(
+            "relation",
+            relation["id"],
+            {"type": "Polygon", "coordinates": polygons[0]},
+            tags,
+        )
+    return _make_feature(
+        "relation",
+        relation["id"],
+        {"type": "MultiPolygon", "coordinates": polygons},
+        tags,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def _element_to_feature(element: dict[str, Any]) -> dict[str, Any] | None:
+    """Dispatch a single OSM element to its type-specific converter."""
+    el_type = element.get("type")
+    if el_type == "node":
+        return _node_to_feature(element)
+    if el_type == "way":
+        return _way_to_feature(element)
+    if el_type == "relation":
+        return _relation_to_feature(element)
+    return None
+
+
+def elements_to_features(responses: list[dict[str, Any]]) -> dict[str, Any]:
+    """Convert Overpass responses into a GeoJSON FeatureCollection dict.
+
+    Elements are deduplicated by ``(type, id)`` across all responses - so
+    the same way appearing in two tile responses is emitted once.  Any
+    ``remark`` field present in a response is surfaced via the logger.
+    Orphan member nodes (nodes without tags) and relations other than
+    ``type=multipolygon`` are silently dropped.  The returned dict is a
+    valid GeoJSON FeatureCollection:
+
+    >>> fc = elements_to_features(responses)
+    >>> import geopandas as gpd
+    >>> gdf = gpd.GeoDataFrame.from_features(fc["features"], crs="EPSG:4326")
+    """
+    seen: dict[tuple[str, int], dict[str, Any]] = {}
+    for resp in responses:
+        if remark := resp.get("remark"):
+            logger.warning(f"Overpass remarked: {remark!r}")
+        for el in resp.get("elements", []):
+            seen.setdefault((el["type"], el["id"]), el)
+
+    features = [f for el in seen.values() if (f := _element_to_feature(el)) is not None]
+    return {"type": "FeatureCollection", "features": features}

tiny_osm/_logging.py

@@ -0,0 +1,160 @@
+"""Logging utilities for tiny_osm.
+
+Example:
+-------
+>>> from tiny_osm import configure_logger, logger
+>>> configure_logger(verbose=True)          # console shows DEBUG+
+>>> configure_logger(file="run.log")        # also log to file
+>>> logger.info("Starting pipeline")
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import IO, Literal
+
+__all__ = [
+    "configure_logger",
+    "generate_log_path",
+    "get_log_file_path",
+    "logger",
+]
+
+logger = logging.getLogger("tiny_osm")
+logger.setLevel(logging.DEBUG)
+logger.propagate = False
+
+_file_handler: logging.FileHandler | None = None
+_console_handler: logging.StreamHandler[IO[str]] | None = None
+
+_handlers = logger.handlers
+if not _handlers:
+    _sh: logging.StreamHandler[IO[str]] = logging.StreamHandler(sys.stderr)
+    _sh.setFormatter(logging.Formatter("%(levelname)-8s %(message)s"))
+    _sh.setLevel(logging.WARNING)
+    logger.addHandler(_sh)
+    _console_handler = _sh
+
+
+def generate_log_path(work_dir: Path, prefix: str = "tiny_osm") -> Path:
+    """Generate a timestamped log file path.
+
+    Parameters
+    ----------
+    work_dir : Path
+        Directory where the log file will be created.
+    prefix : str, optional
+        Prefix for the log file name. Defaults to ``"tiny_osm"``.
+
+    Returns
+    -------
+    Path
+        Path to the log file (e.g., ``<work_dir>/tiny_osm-20260206-140112.log``).
+    """
+    timestamp = datetime.now().astimezone().strftime("%Y%m%d-%H%M%S")
+    return work_dir / f"{prefix}-{timestamp}.log"
+
+
+def get_log_file_path() -> Path | None:
+    """Get the current log file path if file logging is enabled."""
+    if _file_handler is not None:
+        return Path(_file_handler.baseFilename)
+    return None
+
+
+def _validate_level(level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | int) -> int:
+    if isinstance(level, str):
+        level_upper = level.upper()
+        if level_upper not in ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"):
+            msg = f"Invalid log level: {level!r}. Must be DEBUG, INFO, WARNING, ERROR, or CRITICAL."
+            raise ValueError(msg)
+        return getattr(logging, level_upper)
+
+    if level not in (
+        logging.DEBUG,
+        logging.INFO,
+        logging.WARNING,
+        logging.ERROR,
+        logging.CRITICAL,
+    ):
+        msg = f"Invalid log level: {level!r}. Must be a valid logging level constant."
+        raise ValueError(msg)
+    return level
+
+
+def configure_logger(  # noqa: C901
+    *,
+    verbose: bool | None = None,
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | int | None = None,
+    file: str | Path | None = None,
+    file_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] | int | None = None,
+    file_mode: Literal["a", "w"] = "a",
+    file_only: bool = False,
+) -> None:
+    """Configure logging settings.
+
+    Parameters
+    ----------
+    verbose : bool, optional
+        Shortcut: ``True`` sets console to DEBUG, ``False`` to WARNING.
+        If both ``level`` and ``verbose`` are given, ``level`` wins.
+    level : str or int, optional
+        Console logging level (``"DEBUG"``, ``"INFO"``, ``"WARNING"``, etc.).
+    file : str or Path, optional
+        Enable file logging at this path. Pass ``None`` to disable file logging.
+    file_level : str or int, optional
+        File handler level. Defaults to ``DEBUG``.
+    file_mode : {'a', 'w'}, optional
+        Append or overwrite the log file. Defaults to ``'a'``.
+    file_only : bool, optional
+        If ``True``, disable console logging. Requires ``file`` to be set.
+    """
+    global _file_handler  # noqa: PLW0603
+
+    if level is not None:
+        level_int = _validate_level(level)
+        if _console_handler is not None:
+            _console_handler.setLevel(level_int)
+    elif verbose is not None:
+        console_level = logging.DEBUG if verbose else logging.WARNING
+        if _console_handler is not None:
+            _console_handler.setLevel(console_level)
+
+    if file is not None:
+        if _file_handler is not None:
+            logger.removeHandler(_file_handler)
+            _file_handler.close()
+            _file_handler = None
+
+        file_level_int = _validate_level(file_level) if file_level is not None else logging.DEBUG
+
+        filepath = Path(file)
+        filepath.parent.mkdir(parents=True, exist_ok=True)
+
+        if file_mode not in ("a", "w"):
+            msg = f"Invalid file_mode: {file_mode!r}. Must be 'a' or 'w'."
+            raise ValueError(msg)
+
+        _file_handler = logging.FileHandler(filepath, mode=file_mode)
+        _file_handler.setLevel(file_level_int)
+        _file_handler.setFormatter(
+            logging.Formatter(
+                fmt="[%(asctime)s] %(levelname)-8s %(message)s",
+                datefmt="%Y/%m/%d %H:%M:%S",
+            )
+        )
+        logger.addHandler(_file_handler)
+
+        if _file_handler.stream is not None:  # pyright: ignore[reportUnnecessaryComparison]
+            _file_handler.stream.reconfigure(line_buffering=True)
+
+        if file_only and _console_handler is not None:
+            logger.removeHandler(_console_handler)
+
+    elif _file_handler is not None:
+        logger.removeHandler(_file_handler)
+        _file_handler.close()
+        _file_handler = None

tiny_osm/exceptions.py

@@ -0,0 +1,12 @@
+"""Exceptions for tiny_osm."""
+
+from __future__ import annotations
+
+__all__ = ["OverpassError"]
+
+
+class OverpassError(RuntimeError):
+    """Raised when all Overpass API mirrors fail to return a response."""
+
+    def __init__(self) -> None:
+        super().__init__("All Overpass mirrors failed.")

tiny_osm/osm_fetch.py

@@ -0,0 +1,347 @@
+"""Fetch OpenStreetMap data for a bounding box as a GeoJSON FeatureCollection.
+
+Large bounding boxes are automatically subdivided into tiles and fetched
+sequentially via the Overpass API.  Responses from every tile are merged,
+deduplicated by ``(type, id)``, and converted to valid GeoJSON.
+"""
+
+from __future__ import annotations
+
+import atexit
+import contextlib
+import math
+import time
+from collections.abc import Sequence
+from typing import Any
+
+import httpx
+
+try:
+    from orjson import loads as _json_loads  # pyright: ignore[reportMissingImports]
+except ImportError:
+    from json import loads as _json_loads
+
+from tiny_osm._geojson import elements_to_features
+from tiny_osm._logging import logger
+from tiny_osm.exceptions import OverpassError
+
+__all__ = ["OSMFilters", "fetch"]
+
+
+_OVERPASS_MIRRORS = [
+    "https://overpass-api.de/api/interpreter",
+    "https://overpass.private.coffee/api/interpreter",  # no rate limits
+]
+_OVERPASS_SERVER_TIMEOUT = 180  # seconds the server spends executing the query
+_OVERPASS_TRANSFER_BUFFER = 30  # seconds to receive the response body
+_CLIENT_TIMEOUT = _OVERPASS_SERVER_TIMEOUT + _OVERPASS_TRANSFER_BUFFER
+_REQUEST_ROUNDS = 3  # max rounds - each round tries every mirror once
+_TRANSPORT_BACKOFF = 1.0  # base seconds for transport-error backoff within a round
+_BUSY_BACKOFF = 55.0  # seconds to wait between rounds
+_USER_AGENT = "tiny-osm (https://github.com/cheginit/tiny-osm)"
+_HTTP_HEADERS = {
+    "User-Agent": _USER_AGENT,
+    "referer": _USER_AGENT,
+    "Accept-Language": "en",
+}
+_STATUS_POLL_PAUSE = 5  # seconds between /status re-polls when no slot is free
+_STATUS_POLL_MAX = 12  # maximum number of /status polls before giving up
+
+_MAX_QUERY_AREA_M2 = 50_000 * 50_000  # 2 500 km²
+
+# Module-level HTTP clients — one per mirror so TCP/TLS connections are
+# reused across ``fetch`` calls for the lifetime of the process.
+_TIMEOUT = httpx.Timeout(_CLIENT_TIMEOUT)
+_CLIENTS: dict[str, httpx.Client] = {
+    mirror: httpx.Client(timeout=_TIMEOUT, headers=_HTTP_HEADERS) for mirror in _OVERPASS_MIRRORS
+}
+
+
+def _close_clients() -> None:
+    """Close all module-level HTTP clients on process exit."""
+    for c in _CLIENTS.values():
+        c.close()
+
+
+atexit.register(_close_clients)
+
+
+class OSMFilters:
+    """Predefined Overpass QL tag-filter strings for :func:`fetch`.
+
+    Each attribute is a valid ``osm_filter`` value — either a single string
+    or a tuple of strings (which :func:`fetch` issues as separate queries
+    and merges into one FeatureCollection).  Any other Overpass QL tag-filter
+    string works too.
+    """
+
+    HIGHWAY: str = (
+        '["highway"]["area"!~"yes"]'
+        '["highway"!~"abandoned|construction|no|planned|platform|proposed|'
+        'raceway|razed|rest_area|services"]'
+    )
+    WATERWAY: str = '["waterway"]'
+    WATER_BODY: tuple[str, ...] = (
+        '["natural"="water"]["water"~"basin|pond|reservoir|detention|retention|lake|lagoon"]',
+        '["natural"="water"][!"water"]',
+        '["landuse"="basin"]',
+        '["basin"~"retention|detention|infiltration|stormwater"]',
+    )
+
+
+def _bbox_area_m2(left: float, bottom: float, right: float, top: float) -> float:
+    """Approximate bounding box area via an equirectangular projection."""
+    lat_m = (top - bottom) * 111_320.0
+    lon_m = (right - left) * 111_320.0 * math.cos(math.radians((bottom + top) / 2))
+    return abs(lat_m * lon_m)
+
+
+def _subdivide_bbox(
+    left: float, bottom: float, right: float, top: float
+) -> list[tuple[float, float, float, float]]:
+    """Split bbox into an nxn grid if it exceeds _MAX_QUERY_AREA_M2."""
+    area = _bbox_area_m2(left, bottom, right, top)
+    if area <= _MAX_QUERY_AREA_M2:
+        return [(left, bottom, right, top)]
+    n = math.ceil(math.sqrt(area / _MAX_QUERY_AREA_M2))
+    lon_step = (right - left) / n
+    lat_step = (top - bottom) / n
+    return [
+        (
+            left + i * lon_step,
+            bottom + j * lat_step,
+            left + (i + 1) * lon_step,
+            bottom + (j + 1) * lat_step,
+        )
+        for i in range(n)
+        for j in range(n)
+    ]
+
+
+def _validate_bbox(left: float, bottom: float, right: float, top: float) -> None:
+    """Validate that the bbox is a well-formed WGS84 bounding box."""
+    if left >= right:
+        msg = f"left ({left}) must be less than right ({right})"
+        raise ValueError(msg)
+    if bottom >= top:
+        msg = f"bottom ({bottom}) must be less than top ({top})"
+        raise ValueError(msg)
+
+
+def _build_overpass_query(
+    left: float,
+    bottom: float,
+    right: float,
+    top: float,
+    osm_filter: str,
+) -> str:
+    bbox_str = f"{bottom},{left},{top},{right}"
+    settings = f"[out:json][timeout:{_OVERPASS_SERVER_TIMEOUT}]"
+    # Query both ways and relations so that polygon features (e.g.
+    # multipolygon water bodies) are captured alongside linear ones.
+    # `out geom;` embeds coordinates inline — no node-recursion needed.
+    return f"{settings};(way{osm_filter}({bbox_str});relation{osm_filter}({bbox_str}););out geom;"
+
+
+def _parse_status(text: str) -> tuple[str, float]:
+    """Parse a /status response body into a (action, seconds) decision.
+
+    Returns one of:
+
+    - ``("done", 0)`` - a slot is free, the mirror has no slot management, or
+      the format is unrecognized; proceed with the query immediately.
+    - ``("poll", 0)`` - all slots are currently occupied; sleep briefly and
+      re-poll ``/status``.
+    - ``("wait", N)`` - a slot becomes free in ``N`` seconds; sleep then proceed.
+    """
+    lines = text.strip().splitlines()
+
+    # Rate limit: 0 means the mirror has no slot management (e.g. private.coffee).
+    rate_limit = 0
+    for line in lines:
+        if line.startswith("Rate limit:"):
+            with contextlib.suppress(IndexError, ValueError):
+                rate_limit = int(line.split(":")[1].strip())
+            break
+    if rate_limit == 0:
+        return ("done", 0.0)
+
+    # Line index 4 holds the slot-availability status when rate_limit > 0.
+    try:
+        slot_line = lines[4]
+        first = slot_line.split()[0]
+    except IndexError:
+        return ("done", 0.0)
+
+    # Format A: "N slots available now."
+    try:
+        available = int(first)
+    except ValueError:
+        available = None
+    if available is not None:
+        return ("done", 0.0) if available > 0 else ("poll", 0.0)
+
+    # Format B: Slot available after an ISO timestamp, in N seconds.
+    if first == "Slot":
+        try:
+            tokens = slot_line.split()
+            wait = max(float(tokens[tokens.index("in") + 1]), 1.0)
+        except (ValueError, IndexError):
+            return ("poll", 0.0)
+        else:
+            return ("wait", wait)
+
+    # Format C: "Currently running queries:", all slots occupied.
+    # Anything else is an unrecognized status, proceed with the query.
+    return ("poll", 0.0) if first == "Currently" else ("done", 0.0)
+
+
+def _overpass_pause(mirror: str) -> None:
+    """Block until an Overpass slot is available on *mirror*.
+
+    Fetches ``{mirror_base}/status`` and parses the slot-availability line.
+    Servers with ``Rate limit: 0`` (e.g. overpass.private.coffee) are treated
+    as always-available and return immediately.  If the status endpoint is
+    unreachable the function returns immediately so the query is attempted
+    regardless.
+    """
+    status_url = mirror.replace("/interpreter", "/status")
+
+    for _ in range(_STATUS_POLL_MAX):
+        try:
+            resp = _CLIENTS[mirror].get(status_url, timeout=10)
+            resp.raise_for_status()
+        except httpx.HTTPError:
+            return  # unreachable - proceed anyway
+
+        action, seconds = _parse_status(resp.text)
+        if action == "done":
+            return
+        if action == "wait":
+            logger.info(f"No Overpass slot on {mirror!r}; waiting {seconds:.0f}s…")
+            time.sleep(seconds)
+            return
+        # action == "poll": all slots occupied, re-check after a short pause.
+        time.sleep(_STATUS_POLL_PAUSE)
+
+
+def _is_retryable(exc: Exception) -> bool:
+    """Return True for transient errors worth retrying."""
+    if isinstance(exc, httpx.HTTPStatusError):
+        status = exc.response.status_code
+        # 429: rate-limited - our slot is occupied by a still-running timed-out query;
+        # _overpass_pause on the next attempt will poll /status and wait for a free slot.
+        return status == 429 or status >= 500
+    return isinstance(exc, httpx.TransportError)
+
+
+def _fetch_one_query(query: str) -> dict[str, Any]:
+    """Send one query, rotating across mirrors and retrying on transient errors.
+
+    Each "round" tries every mirror in ``_OVERPASS_MIRRORS`` once.  On a
+    transient error (429/503/504 or a transport error) the next mirror is
+    tried *immediately* - because the primary mirror's 504 often comes back
+    within seconds, falling over to the alternate mirror is much faster than
+    sleeping 55 s and retrying the same mirror.  Only if *all* mirrors fail
+    in a round do we sleep ``_BUSY_BACKOFF`` before the next round, giving
+    the servers time to recover.
+    """
+    last_exc: Exception | None = None
+    for round_idx in range(_REQUEST_ROUNDS):
+        for mirror in _OVERPASS_MIRRORS:
+            # On retry rounds, check /status first: by now the rate-limit
+            # window has likely reset and /status reflects real availability.
+            # On the first round we skip the check - /status only tracks
+            # rate-limit slots, not general server load, so it can say
+            # "proceed" while the server is still too busy to respond (504).
+            if round_idx > 0:
+                _overpass_pause(mirror)
+            try:
+                resp = _CLIENTS[mirror].post(mirror, data={"data": query})
+                resp.raise_for_status()
+                return _json_loads(resp.content)
+            except httpx.HTTPStatusError as exc:
+                last_exc = exc
+                if not _is_retryable(exc):
+                    raise
+                logger.info(f"HTTP {exc.response.status_code} on {mirror!r}; trying next mirror…")
+            except httpx.TransportError as exc:
+                last_exc = exc
+                logger.debug(f"Transport error on {mirror!r}: {exc}; trying next mirror…")
+                time.sleep(_TRANSPORT_BACKOFF)
+        # All mirrors failed this round - sleep before the next round.
+        if round_idx < _REQUEST_ROUNDS - 1:
+            logger.info(
+                f"All mirrors failed round {round_idx + 1}; "
+                f"waiting {_BUSY_BACKOFF:.0f}s before next round…"
+            )
+            time.sleep(_BUSY_BACKOFF)
+    assert last_exc is not None  # noqa: S101 - loop always sets it on failure
+    raise last_exc
+
+
+def fetch(
+    left: float,
+    bottom: float,
+    right: float,
+    top: float,
+    osm_filter: str | Sequence[str],
+) -> dict[str, Any]:
+    """Fetch OSM data within a bounding box as a GeoJSON FeatureCollection.
+
+    Large bounding boxes are automatically subdivided into tiles and fetched
+    across rotating Overpass mirrors with retries.  The response is returned
+    as a valid GeoJSON ``FeatureCollection`` dict that can be fed directly
+    to ``geopandas`` with no post-processing.
+
+    Parameters
+    ----------
+    left, bottom, right, top : float
+        Bounding box coordinates in WGS84 (EPSG:4326).
+    osm_filter : str or sequence of str
+        Overpass QL tag-filter string(s) selecting which features to fetch.
+        Use a member of :class:`OSMFilters` for the built-in presets
+        (``OSMFilters.HIGHWAY``, ``OSMFilters.WATERWAY``,
+        ``OSMFilters.WATER_BODY``) or pass any valid Overpass QL tag-filter
+        (e.g. ``'["amenity"="restaurant"]'``).  When a sequence is given,
+        each filter is queried separately and the results are merged into a
+        single deduplicated FeatureCollection.
+
+    Returns
+    -------
+    dict[str, Any]
+        A GeoJSON FeatureCollection dict — ``{"type": "FeatureCollection",
+        "features": [...]}`` — where every feature has an ``osm_type`` and
+        ``osm_id`` in its ``properties`` alongside the OSM tags.
+
+    Raises
+    ------
+    ValueError
+        If the bounding box is invalid.
+    OverpassError
+        If all Overpass mirrors fail to return a response.
+
+    Examples
+    --------
+    Fetch highway features using a preset:
+
+    >>> import geopandas as gpd
+    >>> fc = fetch(-97.75, 30.25, -97.70, 30.30, osm_filter=OSMFilters.HIGHWAY)
+    >>> gdf = gpd.GeoDataFrame.from_features(fc, crs=4326)
+
+    Fetch with a custom Overpass filter:
+
+    >>> fc = fetch(-97.75, 30.25, -97.70, 30.30, osm_filter='["amenity"="restaurant"]')
+    """
+    _validate_bbox(left, bottom, right, top)
+
+    filters = [osm_filter] if isinstance(osm_filter, str) else list(osm_filter)
+    tiles = _subdivide_bbox(left, bottom, right, top)
+    queries = [_build_overpass_query(*tile, f) for tile in tiles for f in filters]
+
+    try:
+        responses = [_fetch_one_query(q) for q in queries]
+    except Exception as exc:
+        raise OverpassError from exc
+
+    return elements_to_features(responses)

tiny_osm-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: tiny-osm
+Version: 0.1.0
+Summary: Fetch OpenStreetMap road, waterway, and water-body data for a bounding box.
+Project-URL: Changelog, https://github.com/cheginit/tiny-osm/blob/main/CHANGELOG.md
+Project-URL: CI, https://github.com/cheginit/tiny-osm/actions
+Project-URL: Documentation, https://cheginit.github.io/tiny-osm
+Project-URL: Homepage, https://cheginit.github.io/tiny-osm
+Project-URL: Issues, https://github.com/cheginit/tiny-osm/issues
+Author-email: Taher Chegini <cheginit@gmail.com>
+License: MIT
+License-File: AUTHORS.md
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: geopandas>=1; extra == 'dev'
+Requires-Dist: git-cliff; extra == 'dev'
+Requires-Dist: ipykernel; extra == 'dev'
+Requires-Dist: ipywidgets; extra == 'dev'
+Requires-Dist: jupytext; extra == 'dev'
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: nbconvert; extra == 'dev'
+Requires-Dist: orjson; extra == 'dev'
+Requires-Dist: pyproj; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: jupytext; extra == 'docs'
+Requires-Dist: mike>=2; extra == 'docs'
+Requires-Dist: mkdocs-jupyter; extra == 'docs'
+Requires-Dist: mkdocs-materialx; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Requires-Dist: ruff; extra == 'docs'
+Provides-Extra: lint
+Requires-Dist: codespell; extra == 'lint'
+Requires-Dist: pre-commit; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: coverage[toml]; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest-sugar; extra == 'test'
+Provides-Extra: typecheck
+Requires-Dist: pyright; extra == 'typecheck'
+Description-Content-Type: text/markdown
+
+# TinyOSM: Lightweight OpenStreetMap GeoJSON Fetcher
+
+[![PyPI](https://img.shields.io/pypi/v/tiny-osm)](https://pypi.org/project/tiny-osm/)
+[![Conda](https://img.shields.io/conda/vn/conda-forge/tiny-osm)](https://anaconda.org/conda-forge/tiny-osm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/cheginit/tiny-osm/HEAD?labpath=docs%2Fexamples)
+
+[![codecov](https://codecov.io/gh/cheginit/tiny-osm/graph/badge.svg?token=U2638J9WKM)](https://codecov.io/gh/cheginit/tiny-osm)
+[![CI](https://github.com/cheginit/tiny-osm/actions/workflows/test.yml/badge.svg)](https://github.com/cheginit/tiny-osm/actions/workflows/test.yml)
+[![Documentation](https://github.com/cheginit/tiny-osm/actions/workflows/docs.yml/badge.svg)](https://github.com/cheginit/tiny-osm/actions/workflows/docs.yml)
+[![Downloads](https://static.pepy.tech/badge/tiny-osm)](https://pepy.tech/project/tiny-osm)
+
+Fetch OpenStreetMap data for a bounding box as GeoJSON. One function, one dependency,
+minimal footprint.
+
+## Why
+
+[OSMnx](https://github.com/gboeing/osmnx) is the go-to tool for working with
+OpenStreetMap data in Python. It handles street-network analysis, building footprints,
+amenity lookups, graph-theoretic routing, and more. But it pulls in `geopandas`,
+`shapely`, and `networkx`, a heavy dependency stack, that can be slow to install in
+constrained environments like AWS Lambda, minimal Docker images, or CI runners.
+
+`tiny-osm` exists for the narrower case where you just need **OSM features as clean
+GeoJSON**. It ships with presets for roads, waterways, and water bodies, and accepts any
+Overpass QL tag-filter for custom queries. It has one runtime dependency (`httpx`),
+installs in seconds, and returns standards-compliant GeoJSON that works with any
+downstream tool such as `geopandas`, `shapely`, or even a JavaScript map library.
+
+|               | `tiny-osm`              | `osmnx`                                      |
+| ------------- | ----------------------- | -------------------------------------------- |
+| Dependencies  | 1 (`httpx`)             | 7+ (`geopandas`, `shapely`, `networkx`, ...) |
+| Output format | GeoJSON dicts           | GeoDataFrames/`networkx` graphs              |
+| Scope         | Any Overpass tag-filter | Full OSM toolkit                             |
+| API surface   | 1 function              | Dozens of modules                            |
+
+## Installation
+
+```console
+pip install tiny-osm
+```
+
+Or with conda/pixi:
+
+```console
+pixi add tiny-osm
+```
+
+> **Tip:** If [`orjson`](https://github.com/ijl/orjson) is installed, `tiny-osm` uses it
+> automatically for faster JSON parsing of Overpass API responses.
+
+## Usage
+
+```python
+import tiny_osm
+
+# Each call returns a GeoJSON FeatureCollection dict
+bbox = (-97.75, 30.25, -97.70, 30.30)
+highways = tiny_osm.fetch(*bbox, osm_filter=tiny_osm.OSMFilters.HIGHWAY)
+waterways = tiny_osm.fetch(*bbox, osm_filter=tiny_osm.OSMFilters.WATERWAY)
+water_bodies = tiny_osm.fetch(*bbox, osm_filter=tiny_osm.OSMFilters.WATER_BODY)
+
+# Load into geopandas (optional - tiny-osm doesn't require it)
+import geopandas as gpd
+
+gdf = gpd.GeoDataFrame.from_features(highways, crs=4326)
+
+# Custom Overpass QL filter
+parks = tiny_osm.fetch(*bbox, osm_filter='["leisure"="park"]')
+```
+
+### Filters
+
+| `osm_filter`            | What it queries                                                             |
+| ----------------------- | --------------------------------------------------------------------------- |
+| `OSMFilters.HIGHWAY`    | `highway=*` ways (excluding areas, abandoned, planned, raceway)             |
+| `OSMFilters.WATERWAY`   | `waterway=*` ways                                                           |
+| `OSMFilters.WATER_BODY` | Closed water features: ponds, lakes, reservoirs, detention/retention basins |
+| any string              | Raw Overpass QL tag-filter (e.g. `'["amenity"="restaurant"]'`)              |
+
+### What it handles
+
+- Auto-subdivides large bounding boxes into tiles
+- Retries across multiple Overpass API mirrors with automatic failover
+- Assembles multi-polygon relations (ring stitching, hole assignment)
+- Deduplicates elements across tile boundaries
+- Applies the OSM polygon-features rule tree (area=yes/no, coastline exceptions, etc.)
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

tiny_osm-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+tiny_osm/__init__.py,sha256=SaWAX3065qiepj6GT3roSP1_BmPVWFUmbph29sis5cg,558
+tiny_osm/_geojson.py,sha256=yqReHOMMiJ8DkDsnL3UBFqF2oO0uSv5ZABDndQxjrV8,11603
+tiny_osm/_logging.py,sha256=tEEwprtQuaC8ahPQl9JE2kWmSozxUnHAvaE9buUkF3E,5321
+tiny_osm/exceptions.py,sha256=3J5pSE7j_8kfskM3uAbGkHixLbb2SuESnWlZNWTSQAE,297
+tiny_osm/osm_fetch.py,sha256=FeEZPyVc9l55PM1XTpaS2qxr8Usv-hlGW9AdB7m3r5k,13103
+tiny_osm-0.1.0.dist-info/METADATA,sha256=TBZCTOvBeaEg3OeU69MNuOKFK-IWvLDY3oMsUXhpRuo,6849
+tiny_osm-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tiny_osm-0.1.0.dist-info/licenses/AUTHORS.md,sha256=W8oRmxEdM_L4-KeEqNzoI0x3oPRMMAroXZNEuO7AwV0,70
+tiny_osm-0.1.0.dist-info/licenses/LICENSE,sha256=pqsW5hip0KzY90LsJbL-z4uKR788CZbOCkJ8y031ddo,1070
+tiny_osm-0.1.0.dist-info/RECORD,,

tiny_osm-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tiny_osm-0.1.0.dist-info/licenses/AUTHORS.md

@@ -0,0 +1,3 @@
+# Authors
+
+- Taher Chegini ([@cheginit](https://github.com/cheginit))

tiny_osm-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Taher Chegini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.