yoro-maps 0.1.0__tar.gz

yoro_maps-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

yoro_maps-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,25 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v

yoro_maps-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+*.egg
+*.yoromaps
+*.osm.pbf

yoro_maps-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Guindo / Altius Academy SNC
+
+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.

yoro_maps-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: yoro-maps
+Version: 0.1.0
+Summary: Offline maps, routing, and POI for Africa — companion to yoro geocoding
+Project-URL: Homepage, https://github.com/Altius-Academy-SNC/yoro-maps
+Project-URL: Repository, https://github.com/Altius-Academy-SNC/yoro-maps
+Author-email: Paul Guindo <paulguindo@altius-group.ch>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: africa,maps,mbtiles,offline,osm,routing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24
+Requires-Dist: yoro>=0.2.0
+Provides-Extra: all
+Requires-Dist: django>=4.2; extra == 'all'
+Requires-Dist: mercantile>=1.2; extra == 'all'
+Requires-Dist: pyosmium>=3.6; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == 'django'
+Provides-Extra: extract
+Requires-Dist: pyosmium>=3.6; extra == 'extract'
+Provides-Extra: tiles
+Requires-Dist: mercantile>=1.2; extra == 'tiles'
+Description-Content-Type: text/markdown
+
+# Yoro Maps
+
+Offline maps, routing, and POI for Africa — companion to [yoro](https://pypi.org/project/yoro/) geocoding.
+
+## Install
+
+```bash
+pip install yoro-maps
+pip install yoro-maps[django]    # Django integration
+pip install yoro-maps[tiles]     # Tile downloading
+```
+
+## Build a map database
+
+```bash
+# Download OSM data and build road graph for Mali
+yoromaps download ML --output mali.yoromaps
+
+# With map tiles (slower, ~200+ MB)
+yoromaps download ML --output mali.yoromaps --tiles --zoom-max 14
+```
+
+## Route between Yoro codes
+
+```bash
+yoromaps route mali.yoromaps ML-ABC ML-XYZ
+```
+
+```python
+import yoromaps
+
+conn = yoromaps.open_db("mali.yoromaps")
+result = yoromaps.route(conn, start_lat=12.6, start_lon=-8.0, end_lat=14.5, end_lon=-4.0)
+print(f"{result.distance_km} km, {result.duration_min} min")
+```
+
+## Django integration
+
+```python
+# settings.py
+import yoromaps
+
+DATABASES = {
+    "default": { ... },
+    "maps": yoromaps.db_config("/data/mali.yoromaps"),
+}
+
+DATABASE_ROUTERS = ["yoromaps.django.router.YoroMapsRouter"]
+
+# urls.py
+urlpatterns = [
+    path("maps/", include("yoromaps.django.urls")),
+]
+```
+
+## License
+
+MIT — Paul Guindo / Altius Academy SNC.

yoro_maps-0.1.0/README.md

@@ -0,0 +1,58 @@
+# Yoro Maps
+
+Offline maps, routing, and POI for Africa — companion to [yoro](https://pypi.org/project/yoro/) geocoding.
+
+## Install
+
+```bash
+pip install yoro-maps
+pip install yoro-maps[django]    # Django integration
+pip install yoro-maps[tiles]     # Tile downloading
+```
+
+## Build a map database
+
+```bash
+# Download OSM data and build road graph for Mali
+yoromaps download ML --output mali.yoromaps
+
+# With map tiles (slower, ~200+ MB)
+yoromaps download ML --output mali.yoromaps --tiles --zoom-max 14
+```
+
+## Route between Yoro codes
+
+```bash
+yoromaps route mali.yoromaps ML-ABC ML-XYZ
+```
+
+```python
+import yoromaps
+
+conn = yoromaps.open_db("mali.yoromaps")
+result = yoromaps.route(conn, start_lat=12.6, start_lon=-8.0, end_lat=14.5, end_lon=-4.0)
+print(f"{result.distance_km} km, {result.duration_min} min")
+```
+
+## Django integration
+
+```python
+# settings.py
+import yoromaps
+
+DATABASES = {
+    "default": { ... },
+    "maps": yoromaps.db_config("/data/mali.yoromaps"),
+}
+
+DATABASE_ROUTERS = ["yoromaps.django.router.YoroMapsRouter"]
+
+# urls.py
+urlpatterns = [
+    path("maps/", include("yoromaps.django.urls")),
+]
+```
+
+## License
+
+MIT — Paul Guindo / Altius Academy SNC.

yoro_maps-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "yoro-maps"
+version = "0.1.0"
+description = "Offline maps, routing, and POI for Africa — companion to yoro geocoding"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Paul Guindo", email = "paulguindo@altius-group.ch" },
+]
+keywords = ["maps", "routing", "offline", "africa", "osm", "mbtiles"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Framework :: Django",
+]
+dependencies = [
+    "yoro>=0.2.0",
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+django = ["Django>=4.2"]
+tiles = ["mercantile>=1.2"]
+extract = ["pyosmium>=3.6"]
+all = ["yoro-maps[django,tiles,extract]"]
+dev = [
+    "pytest>=7",
+    "pytest-cov",
+    "ruff",
+]
+
+[project.urls]
+Homepage = "https://github.com/Altius-Academy-SNC/yoro-maps"
+Repository = "https://github.com/Altius-Academy-SNC/yoro-maps"
+
+[project.scripts]
+yoromaps = "yoromaps.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yoromaps"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100

yoro_maps-0.1.0/src/yoromaps/__init__.py

@@ -0,0 +1,36 @@
+"""
+Yoro Maps — Offline maps, routing, and POI for Africa.
+
+Companion to the ``yoro`` geocoding package.
+
+Usage::
+
+    import yoromaps
+
+    # Build a .yoromaps file for Mali
+    yoromaps.build("ML", "mali.yoromaps")
+
+    # Route between Yoro codes
+    conn = yoromaps.open_db("mali.yoromaps")
+    result = yoromaps.route(conn, start_lat=12.6, start_lon=-8.0, end_lat=14.5, end_lon=-4.0)
+    print(f"{result.distance_km} km, {result.duration_min} min")
+
+    # Route from Yoro codes
+    legs = yoromaps.route_from_codes(conn, ["ML-ABC", "ML-XYZ"])
+"""
+
+from yoromaps.db import db_config, open_db
+from yoromaps.download import build
+from yoromaps.routing import RouteResult, route, route_from_codes
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "build",
+    "open_db",
+    "db_config",
+    "route",
+    "route_from_codes",
+    "RouteResult",
+    "__version__",
+]

yoro_maps-0.1.0/src/yoromaps/cli.py

@@ -0,0 +1,139 @@
+"""
+CLI for yoro-maps.
+
+Usage::
+
+    yoromaps download ML --output mali.yoromaps
+    yoromaps download ML --output mali.yoromaps --tiles --zoom-max 14
+    yoromaps route mali.yoromaps ML-ABC ML-XYZ
+    yoromaps info mali.yoromaps
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from yoromaps.countries import COUNTRIES
+
+
+def _progress(msg, current, total):
+    if total > 0:
+        pct = current / total * 100
+        print(f"\r  {msg}: {pct:.0f}% ({current}/{total})", end="", flush=True)
+    else:
+        print(f"\r  {msg}", end="", flush=True)
+
+
+def _download(args):
+    from yoromaps.download import build
+
+    code = args.country.upper()
+    if code not in COUNTRIES:
+        print(f"Unknown country: {code}. Available: {', '.join(sorted(COUNTRIES))}", file=sys.stderr)
+        sys.exit(1)
+
+    output = args.output or f"{code.lower()}.yoromaps"
+    print(f"Building {output} for {COUNTRIES[code].name}...")
+
+    build(
+        code,
+        output=output,
+        pbf_path=args.pbf,
+        include_tiles=args.tiles,
+        zoom_min=args.zoom_min,
+        zoom_max=args.zoom_max,
+        progress=_progress,
+    )
+    print(f"\nDone: {output}")
+
+
+def _route(args):
+    from yoromaps.db import open_db
+    from yoromaps.routing import route_from_codes
+
+    conn = open_db(args.db)
+    legs = route_from_codes(conn, args.codes)
+    conn.close()
+
+    total_km = sum(leg.distance_km for leg in legs)
+    total_min = sum(leg.duration_min for leg in legs)
+
+    result = {
+        "total_distance_km": total_km,
+        "total_duration_min": total_min,
+        "legs": [
+            {
+                "distance_km": leg.distance_km,
+                "duration_min": leg.duration_min,
+                "found": leg.found,
+                "steps": leg.steps,
+            }
+            for leg in legs
+        ],
+    }
+    print(json.dumps(result, indent=2))
+
+
+def _info(args):
+    from yoromaps.db import open_db, get_metadata
+    from yoromaps.tiles import tile_count
+
+    conn = open_db(args.db)
+    print(f"Database: {args.db}")
+    for key in ("country", "country_name", "bbox", "graph_nodes", "graph_edges", "tiles_count"):
+        val = get_metadata(conn, key)
+        if val:
+            print(f"  {key}: {val}")
+    tc = tile_count(conn)
+    if tc:
+        print(f"  tiles_in_db: {tc}")
+    conn.close()
+
+
+def _countries(args):
+    for code, c in sorted(COUNTRIES.items()):
+        print(f"  {code}  {c.name}")
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="yoromaps", description="Offline maps & routing for Africa")
+    sub = parser.add_subparsers(dest="command")
+
+    # download
+    dl = sub.add_parser("download", help="Download and build a .yoromaps file")
+    dl.add_argument("country", help="ISO country code (e.g. ML, BF, CI)")
+    dl.add_argument("--output", "-o", help="Output file path")
+    dl.add_argument("--pbf", help="Use existing PBF file instead of downloading")
+    dl.add_argument("--tiles", action="store_true", help="Also download map tiles")
+    dl.add_argument("--zoom-min", type=int, default=6)
+    dl.add_argument("--zoom-max", type=int, default=12)
+
+    # route
+    rt = sub.add_parser("route", help="Calculate route between Yoro codes")
+    rt.add_argument("db", help="Path to .yoromaps file")
+    rt.add_argument("codes", nargs="+", help="Yoro codes (e.g. ML-ABC ML-XYZ)")
+
+    # info
+    nf = sub.add_parser("info", help="Show database info")
+    nf.add_argument("db", help="Path to .yoromaps file")
+
+    # countries
+    sub.add_parser("countries", help="List available countries")
+
+    args = parser.parse_args()
+    if args.command == "download":
+        _download(args)
+    elif args.command == "route":
+        _route(args)
+    elif args.command == "info":
+        _info(args)
+    elif args.command == "countries":
+        _countries(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

yoro_maps-0.1.0/src/yoromaps/countries.py

@@ -0,0 +1,54 @@
+"""
+Country registry — Geofabrik download URLs and metadata.
+
+Focused on Africa, extensible to other regions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class Country:
+    code: str
+    name: str
+    geofabrik_path: str
+    bbox: tuple[float, float, float, float]  # lon_min, lat_min, lon_max, lat_max
+
+
+COUNTRIES: dict[str, Country] = {
+    # --- West Africa (priority) ---
+    "ML": Country("ML", "Mali", "africa/mali", (-12.5, 10.0, 4.5, 25.0)),
+    "NE": Country("NE", "Niger", "africa/niger", (0.0, 11.5, 16.0, 24.0)),
+    "BF": Country("BF", "Burkina Faso", "africa/burkina-faso", (-5.5, 9.0, 2.5, 15.5)),
+    "CI": Country("CI", "Cote d'Ivoire", "africa/ivory-coast", (-8.6, 4.36, -2.49, 10.74)),
+    "GH": Country("GH", "Ghana", "africa/ghana", (-3.26, 4.74, 1.2, 11.17)),
+    "SN": Country("SN", "Senegal", "africa/senegal-and-gambia", (-17.54, 12.31, -11.36, 16.69)),
+    "GN": Country("GN", "Guinee", "africa/guinea", (-15.08, 7.19, -7.64, 12.68)),
+    "TG": Country("TG", "Togo", "africa/togo", (-0.15, 6.1, 1.81, 11.14)),
+    "BJ": Country("BJ", "Benin", "africa/benin", (0.77, 6.14, 3.85, 12.41)),
+    "NG": Country("NG", "Nigeria", "africa/nigeria", (2.69, 4.27, 14.68, 13.89)),
+    "CM": Country("CM", "Cameroun", "africa/cameroon", (8.49, 1.65, 16.19, 13.08)),
+    "SL": Country("SL", "Sierra Leone", "africa/sierra-leone", (-13.3, 6.93, -10.27, 10.0)),
+    "LR": Country("LR", "Liberia", "africa/liberia", (-11.49, 4.35, -7.37, 8.55)),
+    "MR": Country("MR", "Mauritanie", "africa/mauritania", (-17.07, 14.72, -4.83, 27.3)),
+    "GW": Country("GW", "Guinee-Bissau", "africa/guinea-bissau", (-16.71, 10.87, -13.64, 12.68)),
+    # --- Central / East Africa ---
+    "CD": Country("CD", "RD Congo", "africa/congo-democratic-republic", (12.18, -13.46, 31.31, 5.39)),
+    "KE": Country("KE", "Kenya", "africa/kenya", (33.91, -4.68, 41.91, 5.03)),
+    "TZ": Country("TZ", "Tanzanie", "africa/tanzania", (29.33, -11.75, 40.44, -0.99)),
+    "UG": Country("UG", "Ouganda", "africa/uganda", (29.57, -1.48, 35.04, 4.23)),
+    "ET": Country("ET", "Ethiopie", "africa/ethiopia", (32.99, 3.4, 47.99, 14.89)),
+    "MG": Country("MG", "Madagascar", "africa/madagascar", (43.18, -25.61, 50.48, -11.95)),
+}
+
+GEOFABRIK_BASE = "https://download.geofabrik.de"
+
+
+def geofabrik_url(country_code: str) -> str:
+    """Return the Geofabrik PBF download URL for a country."""
+    c = COUNTRIES.get(country_code.upper())
+    if not c:
+        raise ValueError(f"Unknown country: {country_code}. Available: {list(COUNTRIES.keys())}")
+    return f"{GEOFABRIK_BASE}/{c.geofabrik_path}-latest.osm.pbf"

yoro_maps-0.1.0/src/yoromaps/db.py

@@ -0,0 +1,112 @@
+"""
+Database management for .yoromaps files.
+
+A .yoromaps file is a single SQLite database containing:
+- tiles: MBTiles-compatible tile storage
+- nodes: road graph intersections
+- edges: road graph segments
+- pois: points of interest
+- metadata: version, country, timestamps
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+SCHEMA_VERSION = 1
+
+SCHEMA_SQL = """
+-- Metadata
+CREATE TABLE IF NOT EXISTS metadata (
+    key   TEXT PRIMARY KEY,
+    value TEXT
+);
+
+-- MBTiles-compatible tile storage
+CREATE TABLE IF NOT EXISTS tiles (
+    zoom_level  INTEGER NOT NULL,
+    tile_column INTEGER NOT NULL,
+    tile_row    INTEGER NOT NULL,
+    tile_data   BLOB NOT NULL,
+    PRIMARY KEY (zoom_level, tile_column, tile_row)
+);
+
+-- Road graph: nodes (intersections)
+CREATE TABLE IF NOT EXISTS nodes (
+    id  INTEGER PRIMARY KEY,
+    lat REAL NOT NULL,
+    lon REAL NOT NULL
+);
+
+-- Road graph: edges (road segments)
+CREATE TABLE IF NOT EXISTS edges (
+    id        INTEGER PRIMARY KEY AUTOINCREMENT,
+    from_node INTEGER NOT NULL REFERENCES nodes(id),
+    to_node   INTEGER NOT NULL REFERENCES nodes(id),
+    distance_m REAL NOT NULL,
+    duration_s REAL NOT NULL,
+    road_type  TEXT NOT NULL DEFAULT 'road',
+    oneway     INTEGER NOT NULL DEFAULT 0,
+    name       TEXT DEFAULT ''
+);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_node);
+CREATE INDEX IF NOT EXISTS idx_edges_to ON edges(to_node);
+
+-- Points of interest
+CREATE TABLE IF NOT EXISTS pois (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    lat        REAL NOT NULL,
+    lon        REAL NOT NULL,
+    yoro_code  TEXT NOT NULL DEFAULT '',
+    name       TEXT NOT NULL,
+    category   TEXT NOT NULL DEFAULT 'other',
+    source     TEXT NOT NULL DEFAULT 'local',
+    osm_id     INTEGER,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_pois_yoro ON pois(yoro_code);
+CREATE INDEX IF NOT EXISTS idx_pois_category ON pois(category);
+"""
+
+
+def open_db(path: str | Path, create: bool = False) -> sqlite3.Connection:
+    """Open a .yoromaps database. Creates schema if *create* is True."""
+    path = Path(path)
+    exists = path.exists()
+
+    if not exists and not create:
+        raise FileNotFoundError(f"Database not found: {path}")
+
+    conn = sqlite3.connect(str(path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA synchronous=NORMAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+
+    if create and not exists:
+        conn.executescript(SCHEMA_SQL)
+        conn.execute("INSERT OR REPLACE INTO metadata VALUES ('schema_version', ?)",
+                      (str(SCHEMA_VERSION),))
+        conn.commit()
+
+    return conn
+
+
+def set_metadata(conn: sqlite3.Connection, key: str, value: str) -> None:
+    conn.execute("INSERT OR REPLACE INTO metadata VALUES (?, ?)", (key, value))
+    conn.commit()
+
+
+def get_metadata(conn: sqlite3.Connection, key: str) -> str | None:
+    row = conn.execute("SELECT value FROM metadata WHERE key = ?", (key,)).fetchone()
+    return row[0] if row else None
+
+
+def db_config(path: str) -> dict:
+    """Return a Django DATABASES dict entry for a .yoromaps file."""
+    return {
+        "ENGINE": "django.db.backends.sqlite3",
+        "NAME": str(path),
+    }

yoro_maps-0.1.0/src/yoromaps/django/__init__.py

@@ -0,0 +1,18 @@
+"""
+Yoro Maps Django integration.
+
+Add to your settings::
+
+    import yoromaps
+
+    INSTALLED_APPS = [..., "yoromaps.django"]
+
+    DATABASES = {
+        "default": { ... },
+        "maps": yoromaps.db_config("/path/to/country.yoromaps"),
+    }
+
+    DATABASE_ROUTERS = ["yoromaps.django.router.YoroMapsRouter"]
+"""
+
+default_app_config = "yoromaps.django.apps.YoroMapsConfig"

yoro_maps-0.1.0/src/yoromaps/django/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class YoroMapsConfig(AppConfig):
+    name = "yoromaps.django"
+    label = "yoromaps"
+    verbose_name = "Yoro Maps"
+    default_auto_field = "django.db.models.BigAutoField"