traderoutes 0.0.3__tar.gz

traderoutes-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mario Milone
+
+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.

traderoutes-0.0.3/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: traderoutes
+Version: 0.0.3
+Summary: Compute weighted international trade routes on a worldwide network.
+Author-email: Mario Milone <milonemario@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/milonemario/traderoutes
+Project-URL: Repository, https://github.com/milonemario/traderoutes
+Project-URL: Issues, https://github.com/milonemario/traderoutes/issues
+Keywords: trade routes,transportation network,graph,geography
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.4.0
+Requires-Dist: igraph>=0.11.8
+Requires-Dist: simplekml>=1.3.6
+Requires-Dist: geopy>=2.4.1
+Dynamic: license-file
+
+# traderoutes for Python
+
+`traderoutes` provides country-border queries and weighted shortest-path trade
+routes on a worldwide road, port, and shipping network.
+
+The package bundles the precomputed graph assets required at runtime. Users do
+not need the graph-generation code or a container to install and use
+the published package.
+
+## Installation
+
+```bash
+python -m pip install traderoutes
+```
+
+For development from this repository:
+
+```bash
+python -m pip install -e .
+```
+
+The package requires Python 3.11 or newer. Runtime dependencies are declared
+in [`pyproject.toml`](pyproject.toml).
+
+## Quick start
+
+```python
+import traderoutes as tr
+
+tr.are_neighbors("FRA", "ITA")       # True
+tr.get_neighbors("FRA")              # neighboring ISO3 codes
+
+origin = tr.get_main_city("FRA")
+destination = tr.get_main_city("NLD")
+path = tr.get_path(origin, destination, road_cost=7, port_cost=1e4)
+
+tr.get_pattern(path)                  # e.g. "crc"
+tr.road_distance(path)                # road distance in km
+tr.sea_distance(path)                 # sea distance in km
+tr.transits_i(path)
+tr.transits_j(path)
+tr.to_kml(path, "fra_nld.kml")
+```
+
+## Main API
+
+| Function | Description |
+|---|---|
+| `are_neighbors(c1, c2)` | Whether two countries share a land border |
+| `get_neighbors(c)` | Neighboring ISO3 country codes |
+| `get_second_neighbors(c)` | Countries two border hops away |
+| `get_common_neighbors(c1, c2)` | Countries neighboring both inputs |
+| `countries()` | Countries represented in the transportation graph |
+| `get_main_city(c)` | Main city vertex for a country |
+| `get_great_circle(c1, c2)` | Great-circle distance in km |
+| `get_path(v1, v2, ...)` | Weighted shortest path |
+| `get_pattern(path)` | Compact path vertex-type pattern |
+| `get_countries(path, ...)` | Country segments and distances |
+| `road_distance(path)` | Road distance in km |
+| `sea_distance(path)` | Sea distance in km |
+| `transits_i(path, ...)` | Origin-side transit countries |
+| `transits_j(path, ...)` | Destination-side transit countries |
+| `to_kml(path, file)` | Export a path to KML |
+
+## Podman targets
+
+The [`Dockerfile`](Dockerfile) provides reproducible development, testing, and
+build environments. Build from this directory after retrieving Git LFS files:
+
+```bash
+git lfs pull
+podman build --target build-env -t traderoutes-python-build-env .
+podman build --target test -t traderoutes-python-test .
+podman build --target build -t traderoutes-python-build .
+podman build --target wheel-test -t traderoutes-python-wheel-test .
+```
+
+The stages have different purposes:
+
+- `build-env` provides only the build toolchain. Mount the source and output
+  directories to write artifacts directly to the host. It can also be used as
+  an interactive development environment by mounting the source tree.
+- `test` installs the package from the source tree and runs the unit tests.
+- `build` creates the wheel and source distribution under `/dist`.
+- `wheel-test` installs the built wheel and runs the tests against that exact
+  wheel, which is the release artifact to be uploaded to PyPI.
+
+The `test` and `wheel-test` stages run their tests during `podman build`, so a
+failing test causes the image build to fail. They also have test commands as
+their default container commands, so a successful image can be tested again:
+
+```bash
+podman run --rm traderoutes-python-test
+podman run --rm traderoutes-python-wheel-test
+```
+
+The build stages do not publish anything and do not require PyPI credentials.
+For local development, build directly into a host directory with Podman:
+
+```bash
+mkdir -p dist/python
+podman run --rm \
+  -v "$PWD:/workspace:Z" \
+  -v "$PWD/dist/python:/out:Z" \
+  traderoutes-python-build-env \
+  python -m build --outdir /out
+```
+
+To test the exported wheel in the same clean toolchain:
+
+```bash
+podman run --rm \
+  -v "$PWD:/workspace:Z" \
+  -v "$PWD/dist/python:/dist:Z" \
+  traderoutes-python-build-env \
+  sh -c 'python -m pip install --no-cache-dir --no-deps /dist/*.whl && python -m unittest discover -s /workspace/tests -v'
+```
+
+Validate the package metadata before uploading:
+
+```bash
+podman run --rm \
+  -v "$PWD/dist/python:/dist:Z" \
+  traderoutes-python-build-env \
+  python -m twine check /dist/*
+```
+
+## Local tests
+
+With the runtime dependencies installed:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT; see [`LICENSE`](LICENSE).

traderoutes-0.0.3/README.md

@@ -0,0 +1,138 @@
+# traderoutes for Python
+
+`traderoutes` provides country-border queries and weighted shortest-path trade
+routes on a worldwide road, port, and shipping network.
+
+The package bundles the precomputed graph assets required at runtime. Users do
+not need the graph-generation code or a container to install and use
+the published package.
+
+## Installation
+
+```bash
+python -m pip install traderoutes
+```
+
+For development from this repository:
+
+```bash
+python -m pip install -e .
+```
+
+The package requires Python 3.11 or newer. Runtime dependencies are declared
+in [`pyproject.toml`](pyproject.toml).
+
+## Quick start
+
+```python
+import traderoutes as tr
+
+tr.are_neighbors("FRA", "ITA")       # True
+tr.get_neighbors("FRA")              # neighboring ISO3 codes
+
+origin = tr.get_main_city("FRA")
+destination = tr.get_main_city("NLD")
+path = tr.get_path(origin, destination, road_cost=7, port_cost=1e4)
+
+tr.get_pattern(path)                  # e.g. "crc"
+tr.road_distance(path)                # road distance in km
+tr.sea_distance(path)                 # sea distance in km
+tr.transits_i(path)
+tr.transits_j(path)
+tr.to_kml(path, "fra_nld.kml")
+```
+
+## Main API
+
+| Function | Description |
+|---|---|
+| `are_neighbors(c1, c2)` | Whether two countries share a land border |
+| `get_neighbors(c)` | Neighboring ISO3 country codes |
+| `get_second_neighbors(c)` | Countries two border hops away |
+| `get_common_neighbors(c1, c2)` | Countries neighboring both inputs |
+| `countries()` | Countries represented in the transportation graph |
+| `get_main_city(c)` | Main city vertex for a country |
+| `get_great_circle(c1, c2)` | Great-circle distance in km |
+| `get_path(v1, v2, ...)` | Weighted shortest path |
+| `get_pattern(path)` | Compact path vertex-type pattern |
+| `get_countries(path, ...)` | Country segments and distances |
+| `road_distance(path)` | Road distance in km |
+| `sea_distance(path)` | Sea distance in km |
+| `transits_i(path, ...)` | Origin-side transit countries |
+| `transits_j(path, ...)` | Destination-side transit countries |
+| `to_kml(path, file)` | Export a path to KML |
+
+## Podman targets
+
+The [`Dockerfile`](Dockerfile) provides reproducible development, testing, and
+build environments. Build from this directory after retrieving Git LFS files:
+
+```bash
+git lfs pull
+podman build --target build-env -t traderoutes-python-build-env .
+podman build --target test -t traderoutes-python-test .
+podman build --target build -t traderoutes-python-build .
+podman build --target wheel-test -t traderoutes-python-wheel-test .
+```
+
+The stages have different purposes:
+
+- `build-env` provides only the build toolchain. Mount the source and output
+  directories to write artifacts directly to the host. It can also be used as
+  an interactive development environment by mounting the source tree.
+- `test` installs the package from the source tree and runs the unit tests.
+- `build` creates the wheel and source distribution under `/dist`.
+- `wheel-test` installs the built wheel and runs the tests against that exact
+  wheel, which is the release artifact to be uploaded to PyPI.
+
+The `test` and `wheel-test` stages run their tests during `podman build`, so a
+failing test causes the image build to fail. They also have test commands as
+their default container commands, so a successful image can be tested again:
+
+```bash
+podman run --rm traderoutes-python-test
+podman run --rm traderoutes-python-wheel-test
+```
+
+The build stages do not publish anything and do not require PyPI credentials.
+For local development, build directly into a host directory with Podman:
+
+```bash
+mkdir -p dist/python
+podman run --rm \
+  -v "$PWD:/workspace:Z" \
+  -v "$PWD/dist/python:/out:Z" \
+  traderoutes-python-build-env \
+  python -m build --outdir /out
+```
+
+To test the exported wheel in the same clean toolchain:
+
+```bash
+podman run --rm \
+  -v "$PWD:/workspace:Z" \
+  -v "$PWD/dist/python:/dist:Z" \
+  traderoutes-python-build-env \
+  sh -c 'python -m pip install --no-cache-dir --no-deps /dist/*.whl && python -m unittest discover -s /workspace/tests -v'
+```
+
+Validate the package metadata before uploading:
+
+```bash
+podman run --rm \
+  -v "$PWD/dist/python:/dist:Z" \
+  traderoutes-python-build-env \
+  python -m twine check /dist/*
+```
+
+## Local tests
+
+With the runtime dependencies installed:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT; see [`LICENSE`](LICENSE).

traderoutes-0.0.3/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "traderoutes"
+version = "0.0.3"
+description = "Compute weighted international trade routes on a worldwide network."
+requires-python = ">=3.11"
+dependencies = [
+  "numpy>=2.4.0",
+  "igraph>=0.11.8",
+  "simplekml>=1.3.6",
+  "geopy>=2.4.1"
+]
+authors = [
+  {name = "Mario Milone", email = "milonemario@gmail.com"}
+]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+keywords = ["trade routes", "transportation network", "graph", "geography"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: GIS",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+
+[project.urls]
+Homepage = "https://github.com/milonemario/traderoutes"
+Repository = "https://github.com/milonemario/traderoutes"
+Issues = "https://github.com/milonemario/traderoutes/issues"
+
+[tool.setuptools.package-data]
+traderoutes = ["assets/*.pkl"]

traderoutes-0.0.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

traderoutes-0.0.3/src/traderoutes/__init__.py

@@ -0,0 +1,4 @@
+from .borders import *
+from .routes import *
+
+# __all__ = []

traderoutes-0.0.3/src/traderoutes/assets/fullgraph.pkl

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: traderoutes-0.0.3/src/traderoutes/assets/fullgraph.pkl
+size: 43837293 bytes
+sha256: 2b052401007f6095ef5966a84c741a89af2835b9df69a17e8f1e06cfae7b929a

traderoutes-0.0.3/src/traderoutes/borders.py

@@ -0,0 +1,112 @@
+# Module to query about borders information
+
+import os
+from importlib.resources import files
+
+import igraph as ig
+
+# Import the borders graph
+b = ig.read(files("traderoutes.assets").joinpath("bordersgraph.pkl"), format="pickle")
+
+
+def are_neighbors(country1, country2):
+    """Return True if the two countries share a land border.
+
+    Args:
+        country1 (str): ISO 3-letter code of the first country (e.g. ``"FRA"``).
+        country2 (str): ISO 3-letter code of the second country (e.g. ``"ITA"``).
+
+    Returns:
+        bool: ``True`` if the countries are direct neighbors, ``False`` otherwise.
+
+    Examples:
+        >>> are_neighbors("FRA", "ITA")
+        True
+        >>> are_neighbors("FRA", "USA")
+        False
+    """
+    return country2 in get_neighbors(country1)
+
+
+def get_neighbors(country):
+    """Return the ISO3 codes of all countries sharing a land border with *country*.
+
+    Args:
+        country (str): ISO 3-letter code of the country (e.g. ``"FRA"``).
+
+    Returns:
+        list[str]: Sorted list of ISO3 codes of neighboring countries.
+            Returns an empty list if the country is not found in the graph.
+
+    Examples:
+        >>> get_neighbors("USA")
+        ['CAN', 'MEX']
+    """
+    countries = b.vs["name"]
+    neighbors = []
+    if country in countries:
+        c = b.vs.find(country)
+        ns = c.neighbors()
+        for n in ns:
+            neighbors += [n["name"]]
+    return neighbors
+
+
+def get_second_neighbors(country):
+    """Return countries reachable in exactly two border hops from *country*.
+
+    The returned list excludes *country* itself and its direct neighbors.
+
+    Args:
+        country (str): ISO 3-letter code of the country (e.g. ``"FRA"``).
+
+    Returns:
+        list[str]: List of ISO3 codes of second-degree neighbors, in the order
+            they are encountered while traversing the border graph.
+            Returns an empty list if the country is not found.
+
+    Examples:
+        >>> "PRT" in get_second_neighbors("FRA")
+        True
+        >>> "ITA" in get_second_neighbors("FRA")  # direct neighbor — excluded
+        False
+    """
+    countries = b.vs["name"]
+    second_neighbors = []
+    neighbors = get_neighbors(country)
+    if country in countries:
+        c = b.vs.find(country)
+        ns = c.neighbors()
+        for n in ns:
+            sns = n.neighbors()
+            for sn in sns:
+                name = sn["name"]
+                if (
+                    name not in second_neighbors
+                    and name not in neighbors
+                    and name != country
+                ):
+                    second_neighbors += [name]
+    return second_neighbors
+
+
+def get_common_neighbors(country1, country2):
+    """Return countries that share a land border with both *country1* and *country2*.
+
+    Args:
+        country1 (str): ISO 3-letter code of the first country.
+        country2 (str): ISO 3-letter code of the second country.
+
+    Returns:
+        list[str]: List of ISO3 codes of countries neighboring both inputs.
+            Returns an empty list if no common neighbors exist.
+
+    Examples:
+        >>> get_common_neighbors("FRA", "ITA")
+        ['CHE']
+        >>> get_common_neighbors("FRA", "USA")
+        []
+    """
+    ns1 = get_neighbors(country1)
+    ns2 = get_neighbors(country2)
+    return [n for n in ns1 if n in ns2]

traderoutes-0.0.3/src/traderoutes/routes.py

@@ -0,0 +1,539 @@
+# import logging
+# import os
+# import re
+# import sys
+import warnings
+from importlib.resources import files
+
+import igraph as ig
+
+import numpy as np
+
+# import pandas as pd
+import simplekml
+from geopy.distance import great_circle
+
+from .borders import *
+
+SEA_EDGE_TYPES = ("sea", "sea_border")
+BORDER_EDGE_TYPES = ("road_border", "sea_border")
+ROAD_EDGE_TYPES = ("road", "road_sea")
+OPEN_SEA_COUNTRY = "sea"
+
+# Load the full graph
+g = ig.load(files("traderoutes.assets").joinpath("fullgraph.pkl"), format="pickle")
+
+
+def _clean_country(country):
+    if country is None:
+        return None
+    if isinstance(country, str):
+        country = country.strip()
+        if country == "" or country == "None":
+            return None
+        return country
+    if isinstance(country, float) and np.isnan(country):
+        return None
+    return country
+
+
+def countries():
+    """Return a sorted list of all countries present in the transportation network.
+
+    A country is included if it has at least one city vertex (``vtype="city"``)
+    in the graph.
+
+    Returns:
+        list[str]: Sorted list of ISO 3-letter country codes.
+
+    Examples:
+        >>> cs = countries()
+        >>> "FRA" in cs
+        True
+    """
+    return np.unique(g.vs.select(vtype="city")["country"]).tolist()
+
+
+def get_main_city(country):
+    """Return the main city vertex for a given country.
+
+    The main city is the vertex with ``vtype="city"`` and ``maincity=1``
+    for the specified country. It is used as the representative location for
+    great-circle distance calculations and as the default path endpoint.
+
+    Args:
+        country (str): ISO 3-letter code of the country (e.g. ``"FRA"``).
+
+    Returns:
+        igraph.Vertex | None: The main city vertex, or ``None`` if not found.
+
+    Warns:
+        UserWarning: If no main city is found for the country.
+        UserWarning: If more than one main city is found (returns the first).
+
+    Examples:
+        >>> v = get_main_city("FRA")
+        >>> v["name"]
+        'Paris'
+    """
+    mcs = g.vs.select(vtype="city", maincity=1, country=country)
+    if len(mcs) == 0:
+        warnings.warn(f"No main city found for country {country}.")
+        return None
+    elif len(mcs) > 1:
+        warnings.warn(
+            f"More than one main city found for country {country}. Return the first one."
+        )
+    return mcs[0]
+
+
+def get_great_circle(country1, country2):
+    """Return the great-circle distance in km between the main cities of two countries.
+
+    Args:
+        country1 (str): ISO 3-letter code of the origin country.
+        country2 (str): ISO 3-letter code of the destination country.
+
+    Returns:
+        float: Great-circle distance in kilometres.
+
+    Examples:
+        >>> round(get_great_circle("FRA", "ITA"), 2)
+        1109.56
+    """
+    city1 = get_main_city(country1)
+    city2 = get_main_city(country2)
+    return great_circle((city1["lat"], city1["lon"]), (city2["lat"], city2["lon"])).km
+
+
+def get_trade_route_great_circle(country1, country2):
+    """Return a dict with country codes and the great-circle distance between them.
+
+    Args:
+        country1 (str): ISO 3-letter code of the origin country.
+        country2 (str): ISO 3-letter code of the destination country.
+
+    Returns:
+        dict: Dictionary with keys ``"iso_i"`` (origin), ``"iso_j"`` (destination),
+            and ``"dist"`` (great-circle distance in km).
+
+    Examples:
+        >>> r = get_trade_route_great_circle("FRA", "ITA")
+        >>> r["iso_i"], r["iso_j"]
+        ('FRA', 'ITA')
+    """
+    return {
+        "iso_i": country1,
+        "iso_j": country2,
+        "dist": get_great_circle(country1, country2),
+    }
+
+
+def get_path(
+    v1,
+    v2,
+    road_cost=1,
+    road_cost_countries={},
+    port_cost=1,
+    port_cost_countries={},
+    border_cost=0,
+    border_cost_countries={},
+):
+    """Return the shortest-path trade route between two graph vertices.
+
+    The returned path corresponds to the shortest path weighted by the costs
+    applied to the graph edges, as determined by the arguments.
+
+    Cost application order:
+
+    1. All edges are initialized to their true distance (``wdist = dist``).
+    2. **Port edges** (``etype="road_sea"``): ``wdist = dist + port_cost``.
+       Per-country overrides in *port_cost_countries* take precedence.
+    3. **Border edges** (``etype`` in ``("road_border", "sea_border")``):
+       ``wdist = dist + border_cost``. Per-pair overrides in
+       *border_cost_countries* take precedence.
+    4. **Road edges** (``etype="road"``): ``wdist = dist * road_cost``.
+       Per-country overrides in *road_cost_countries* take precedence.
+
+    Args:
+        v1: Source vertex (igraph Vertex object).
+        v2: Destination vertex (igraph Vertex object).
+        road_cost (float): Multiplicative cost factor for road edges.
+            Applies to all road edges not listed in *road_cost_countries*,
+            excluding cross-border road edges. Default: ``1``.
+        road_cost_countries (dict[str, float]): Per-country road cost overrides.
+            Keys are ISO3 codes; values replace the global *road_cost* for
+            road edges fully inside that country. Example: ``{"FRA": 2}``.
+        port_cost (float): Additive cost for land-to-sea transitions
+            (``road_sea`` edges). Default: ``1``.
+        port_cost_countries (dict[str, float]): Per-country port cost overrides.
+            Keys are ISO3 codes. Example: ``{"FRA": 2}``.
+        border_cost (float): Additive cost for crossing a country border
+            (``road_border`` and ``sea_border`` edges). Default: ``0``.
+        border_cost_countries (dict[tuple[str, str], float]): Per-country-pair
+            border cost overrides. Keys are tuples of ISO3 codes.
+            Example: ``{("FRA", "DEU"): 500}``.
+
+    Returns:
+        dict: Dictionary with two keys:
+
+            - ``"epath"`` (list[int]): Edge indices of the shortest path.
+            - ``"vpath"`` (list[int]): Vertex indices of the shortest path.
+
+    Examples:
+        >>> v_fra = get_main_city("FRA")
+        >>> v_nld = get_main_city("NLD")
+        >>> path = get_path(v_fra, v_nld, road_cost=7, port_cost=1e4)
+        >>> get_pattern(path)
+        'crc'
+    """
+    # 0. Initialize all weighted distance at actual distance
+    g.es["wdist"] = g.es["dist"]
+    # 1. Apply port costs
+    ports = g.es.select(etype="road_sea")
+    ports["wdist"] = (np.array(ports["dist"]) + port_cost).tolist()
+    for c in port_cost_countries:
+        ports_c = ports.select(country=c)
+        country_port_cost = port_cost_countries[c]
+        ports_c["wdist"] = (np.array(ports_c["dist"]) + country_port_cost).tolist()
+    # 2. Apply border costs
+    borders = g.es.select(etype_in=BORDER_EDGE_TYPES)
+    borders["wdist"] = (np.array(borders["dist"]) + border_cost).tolist()
+    for cs in border_cost_countries:
+        borders_c = borders.select(country1_in=cs, country2_in=cs)
+        country_border_cost = border_cost_countries[cs]
+        borders_c["wdist"] = (
+            np.array(borders_c["dist"]) + country_border_cost
+        ).tolist()
+    # 3. Apply road costs
+    roads = g.es.select(etype="road")
+    roads["wdist"] = (np.array(roads["dist"]) * road_cost).tolist()
+    for c in road_cost_countries:
+        roads_c = roads.select(country=c)
+        country_road_cost = road_cost_countries[c]
+        roads_c["wdist"] = (np.array(roads_c["dist"]) * country_road_cost).tolist()
+
+    # Compute shortest path
+    epath = g.get_shortest_paths(v1, v2, weights="wdist", output="epath")[0]
+    vpath = g.get_shortest_paths(v1, v2, weights="wdist", output="vpath")[0]
+
+    return {"epath": epath, "vpath": vpath}
+
+
+def get_pattern(path):
+    """Return a string encoding the sequence of vertex types along a path.
+
+    The pattern compresses consecutive vertices of the same type into a single
+    character: ``c`` = city, ``r`` = road, ``p`` = port, ``s`` = sea.
+    Intermediate city vertices (i.e. not the first or last vertex) are treated
+    as road vertices so they do not break the road segment pattern.
+
+    Args:
+        path (dict): Path dict as returned by :func:`get_path`, with key
+            ``"vpath"`` containing vertex indices.
+
+    Returns:
+        str: Pattern string, e.g. ``"crc"`` (land route), ``"csrc"``
+            (sea route with sea from origin side).
+
+    Examples:
+        >>> path = get_path(get_main_city("FRA"), get_main_city("DEU"), road_cost=7)
+        >>> get_pattern(path)
+        'crc'
+    """
+    vpath = path["vpath"]
+    vtypes = [g.vs.select(vpath)[0]["vtype"]]
+    for v in g.vs.select(vpath)[1:-1]:
+        vtype = v["vtype"]
+        if vtype == "city":
+            vtype = "road"
+        if vtype != vtypes[-1]:
+            vtypes.append(vtype)
+    vtypes.append(g.vs.select(vpath)[-1]["vtype"])
+
+    return "".join(
+        list(map({"city": "c", "port": "p", "road": "r", "sea": "s"}.get, vtypes))
+    )
+
+
+def get_countries(path, with_sea=False, clean_dist=None):
+    """Return the sequence of countries traversed along a path.
+
+    Each entry in the returned list is a ``(country, distance)`` tuple, where
+    *distance* is the total distance (km) traveled within that country segment.
+
+    Args:
+        path (dict): Path dict as returned by :func:`get_path`.
+        with_sea (bool): If ``True``, sea segments are included as entries with
+            country code ``"sea"``. Default: ``False``.
+        clean_dist (float | None): If set, iteratively removes intermediate
+            countries whose segment distance is below *clean_dist* km, until
+            all remaining intermediate segments are at or above the threshold
+            (or only the origin and destination remain). Default: ``None``.
+
+    Returns:
+        list[tuple[str, float]]: List of ``(country_iso3, distance_km)`` tuples
+            in traversal order. Sea segments appear as ``("sea", distance)`` when
+            *with_sea* is ``True``.
+
+    Examples:
+        >>> path = get_path(get_main_city("FRA"), get_main_city("POL"), road_cost=7)
+        >>> [c for c, _ in get_countries(path)]
+        ['FRA', 'DEU', 'POL']
+    """
+    vpath = path["vpath"]
+    countries = []
+    vs = g.vs.select(vpath)
+    c = _clean_country(vs[0]["country"])
+    d = 0
+    for i in range(1, len(vs)):
+        d += g.es.select(_source=vpath[i - 1], _target=vpath[i])[0]["dist"]
+        next_c = _clean_country(vs[i]["country"])
+        if next_c != c:
+            segment_country = OPEN_SEA_COUNTRY if c is None and with_sea else c
+            if segment_country is not None:
+                countries += [(segment_country, d)]
+            c = next_c
+            d = 0
+    segment_country = OPEN_SEA_COUNTRY if c is None and with_sea else c
+    if segment_country is not None:
+        countries += [(segment_country, d)]
+    if clean_dist is not None:
+        cleaned = False
+        while not cleaned and len(countries) > 2:
+            dists = [c[1] for c in countries]
+            min_d = min(dists[1:-1])
+            if min_d < clean_dist:
+                countries = [
+                    countries[i]
+                    for i in range(0, len(countries))
+                    if i != dists.index(min_d)
+                ]
+                # Consolidate consecutive same-country segments
+                countries_new = []
+                cd = countries[0]
+                for i in range(1, len(countries)):
+                    if countries[i][0] == cd[0]:
+                        cd = (cd[0], cd[1] + countries[i][1])
+                    else:
+                        countries_new += [cd]
+                        cd = countries[i]
+                countries_new += [cd]
+                countries = countries_new
+            else:
+                cleaned = True
+
+    return countries
+
+
+def road_distance(path):
+    """Return the total road distance (km) along a path.
+
+    Sums the ``dist`` attribute of all edges with ``etype`` in
+    ``("road", "road_sea")``.
+
+    Args:
+        path (dict): Path dict as returned by :func:`get_path`.
+
+    Returns:
+        float: Total road distance in kilometres.
+    """
+    roads = g.es.select(path["epath"]).select(etype_in=ROAD_EDGE_TYPES)
+    return sum(roads["dist"])
+
+
+def sea_distance(path):
+    """Return the total sea distance (km) along a path.
+
+    Sums the ``dist`` attribute of all edges with ``etype`` in
+    ``("sea", "sea_border")``.
+
+    Args:
+        path (dict): Path dict as returned by :func:`get_path`.
+
+    Returns:
+        float: Total sea distance in kilometres.
+    """
+    seas = g.es.select(path["epath"]).select(etype_in=SEA_EDGE_TYPES)
+    return sum(seas["dist"])
+
+
+def transits_i(path, clean_dist=None):
+    """Return transit country ISO3 codes from the origin side of a path.
+
+    For **land-only** routes (no sea segment): all intermediate countries
+    between origin and destination are returned.
+
+    For routes **with sea**: only countries between the origin and the first
+    sea segment are returned.
+
+    Args:
+        path (dict): Path dict as returned by :func:`get_path`.
+        clean_dist (float | None): Passed to :func:`get_countries` to remove
+            very short country segments. Default: ``None``.
+
+    Returns:
+        list[str]: ISO3 codes of transit countries on the origin side,
+            in traversal order.
+
+    Raises:
+        Exception: If the sea is used more than once in the path.
+
+    Examples:
+        >>> path = get_path(get_main_city("CHE"), get_main_city("POL"), road_cost=7)
+        >>> transits_i(path)  # Switzerland → (DEU or AUT) → Poland
+        ['DEU']
+    """
+    pattern = get_pattern(path)
+    if "s" not in pattern:
+        cs = [c[0] for c in get_countries(path, clean_dist=clean_dist)]
+        return cs[1:-1]
+    else:
+        if pattern.count("s") > 1:
+            raise Exception(
+                f"Cannot compute transit countries for pattern '{pattern}' because sea is used more than once."
+            )
+        cs = [c[0] for c in get_countries(path, with_sea=True, clean_dist=clean_dist)]
+        if OPEN_SEA_COUNTRY not in cs:
+            return cs[1:-1]
+        return cs[1 : cs.index(OPEN_SEA_COUNTRY)]
+
+
+def transits_j(path, clean_dist=None):
+    """Return transit country ISO3 codes from the destination side of a path.
+
+    Equivalent to :func:`transits_i` applied to the reversed path, identifying
+    countries between the destination and the last sea segment (or all
+    intermediate countries for land-only routes).
+
+    Args:
+        path (dict): Path dict as returned by :func:`get_path`.
+        clean_dist (float | None): Passed to :func:`get_countries` to remove
+            very short country segments. Default: ``None``.
+
+    Returns:
+        list[str]: ISO3 codes of transit countries on the destination side,
+            in reverse traversal order (i.e. destination-outward).
+
+    Raises:
+        Exception: If the sea is used more than once in the path.
+    """
+    path_reversed = {
+        "vpath": list(reversed(path["vpath"])),
+        "epath": list(reversed(path["epath"])),
+    }
+    return transits_i(path_reversed, clean_dist=clean_dist)
+
+
+######################
+# Plotting Functions #
+######################
+
+
+def to_kml(path, filename):
+    """Export a trade route path to a KML file for viewing in Google Earth.
+
+    The path is drawn as a red line connecting consecutive vertices.
+
+    Args:
+        path (dict): Path dict as returned by :func:`get_path`.
+        filename (str): Output file path (e.g. ``"route.kml"``).
+
+    Examples:
+        >>> path = get_path(get_main_city("FRA"), get_main_city("NLD"), road_cost=7)
+        >>> to_kml(path, "fra_nld.kml")
+    """
+    vpath = path["vpath"]
+    kml = simplekml.Kml()
+    coord0 = (g.vs[vpath[0]]["lon"], g.vs[vpath[0]]["lat"])
+    for i in range(1, len(vpath)):
+        coord1 = (g.vs[vpath[i]]["lon"], g.vs[vpath[i]]["lat"])
+        ls = kml.newlinestring(coords=[coord0, coord1])
+        ls.style.linestyle.width = 5
+        ls.style.linestyle.color = simplekml.Color.red
+        coord0 = coord1
+    kml.save(filename)
+
+
+def cities_to_kml(filename, all_cities=False):
+    """Export city locations to a KML file, organised by country folder.
+
+    Args:
+        filename (str): Output file path.
+        all_cities (bool): If ``False`` (default), only main cities are exported.
+            If ``True``, all city vertices are exported.
+    """
+    kml = simplekml.Kml()
+    if all_cities:
+        cities = g.vs.select(vtype="city")
+    else:
+        cities = g.vs.select(vtype="city", maincity=True)
+
+    for co in countries():
+        fc = kml.newfolder(name=co)
+        for c in cities.select(country=co):
+            coord = (c["lon"], c["lat"])
+            pt = kml.newpoint(name=f"{c['name']} - {c['country']}", coords=[coord])
+            pt.style.iconstyle.color = simplekml.Color.yellow
+    kml.save(filename)
+
+
+def ports_to_kml(filename):
+    """Export port locations to a KML file, organised by country folder.
+
+    Args:
+        filename (str): Output file path.
+    """
+    kml = simplekml.Kml()
+    ports = g.vs.select(vtype="port")
+    for c in countries():
+        fc = kml.newfolder(name=c)
+        for p in ports.select(country=c):
+            coord = (p["lon"], p["lat"])
+            pt = fc.newpoint(name=f"{p['name']} - {p['country']}", coords=[coord])
+            pt.style.iconstyle.color = simplekml.Color.aqua
+    kml.save(filename)
+
+
+def roads_to_kml(filename):
+    """Export the road network to a KMZ file, organised by country folder.
+
+    Args:
+        filename (str): Output file path (without extension; ``.kmz`` is appended).
+    """
+    kml = simplekml.Kml()
+    edges = g.es.select(etype_in=ROAD_EDGE_TYPES)
+    road_countries = np.unique(g.vs.select(vtype="road")["country"])
+
+    for c in road_countries.tolist() + [None]:
+        print(c, end="\r")
+        es = edges.select(country=c)
+        fc = kml.newfolder(name=c)
+        for e in es:
+            coords_source = (g.vs[e.source]["lon"], g.vs[e.source]["lat"])
+            coords_target = (g.vs[e.target]["lon"], g.vs[e.target]["lat"])
+            ls = fc.newlinestring(coords=[coords_source, coords_target])
+            ls.style.linestyle.width = 1
+            ls.style.linestyle.color = simplekml.Color.yellow
+
+    print("Save file")
+    kml.savekmz(f"{filename}.kmz", format=False)
+
+
+def seas_to_kml(filename):
+    """Export the sea-lane network, including sea-border edges, to a KMZ file.
+
+    Args:
+        filename (str): Output file path (without extension; ``.kmz`` is appended).
+    """
+    kml = simplekml.Kml()
+    edges = g.es.select(etype_in=SEA_EDGE_TYPES)
+
+    for e in edges:
+        coords_source = (g.vs[e.source]["lon"], g.vs[e.source]["lat"])
+        coords_target = (g.vs[e.target]["lon"], g.vs[e.target]["lat"])
+        ls = kml.newlinestring(coords=[coords_source, coords_target])
+        ls.style.linestyle.width = 1
+        ls.style.linestyle.color = simplekml.Color.cyan
+
+    kml.savekmz(f"{filename}.kmz", format=False)

traderoutes-0.0.3/src/traderoutes.egg-info/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: traderoutes
+Version: 0.0.3
+Summary: Compute weighted international trade routes on a worldwide network.
+Author-email: Mario Milone <milonemario@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/milonemario/traderoutes
+Project-URL: Repository, https://github.com/milonemario/traderoutes
+Project-URL: Issues, https://github.com/milonemario/traderoutes/issues
+Keywords: trade routes,transportation network,graph,geography
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.4.0
+Requires-Dist: igraph>=0.11.8
+Requires-Dist: simplekml>=1.3.6
+Requires-Dist: geopy>=2.4.1
+Dynamic: license-file
+
+# traderoutes for Python
+
+`traderoutes` provides country-border queries and weighted shortest-path trade
+routes on a worldwide road, port, and shipping network.
+
+The package bundles the precomputed graph assets required at runtime. Users do
+not need the graph-generation code or a container to install and use
+the published package.
+
+## Installation
+
+```bash
+python -m pip install traderoutes
+```
+
+For development from this repository:
+
+```bash
+python -m pip install -e .
+```
+
+The package requires Python 3.11 or newer. Runtime dependencies are declared
+in [`pyproject.toml`](pyproject.toml).
+
+## Quick start
+
+```python
+import traderoutes as tr
+
+tr.are_neighbors("FRA", "ITA")       # True
+tr.get_neighbors("FRA")              # neighboring ISO3 codes
+
+origin = tr.get_main_city("FRA")
+destination = tr.get_main_city("NLD")
+path = tr.get_path(origin, destination, road_cost=7, port_cost=1e4)
+
+tr.get_pattern(path)                  # e.g. "crc"
+tr.road_distance(path)                # road distance in km
+tr.sea_distance(path)                 # sea distance in km
+tr.transits_i(path)
+tr.transits_j(path)
+tr.to_kml(path, "fra_nld.kml")
+```
+
+## Main API
+
+| Function | Description |
+|---|---|
+| `are_neighbors(c1, c2)` | Whether two countries share a land border |
+| `get_neighbors(c)` | Neighboring ISO3 country codes |
+| `get_second_neighbors(c)` | Countries two border hops away |
+| `get_common_neighbors(c1, c2)` | Countries neighboring both inputs |
+| `countries()` | Countries represented in the transportation graph |
+| `get_main_city(c)` | Main city vertex for a country |
+| `get_great_circle(c1, c2)` | Great-circle distance in km |
+| `get_path(v1, v2, ...)` | Weighted shortest path |
+| `get_pattern(path)` | Compact path vertex-type pattern |
+| `get_countries(path, ...)` | Country segments and distances |
+| `road_distance(path)` | Road distance in km |
+| `sea_distance(path)` | Sea distance in km |
+| `transits_i(path, ...)` | Origin-side transit countries |
+| `transits_j(path, ...)` | Destination-side transit countries |
+| `to_kml(path, file)` | Export a path to KML |
+
+## Podman targets
+
+The [`Dockerfile`](Dockerfile) provides reproducible development, testing, and
+build environments. Build from this directory after retrieving Git LFS files:
+
+```bash
+git lfs pull
+podman build --target build-env -t traderoutes-python-build-env .
+podman build --target test -t traderoutes-python-test .
+podman build --target build -t traderoutes-python-build .
+podman build --target wheel-test -t traderoutes-python-wheel-test .
+```
+
+The stages have different purposes:
+
+- `build-env` provides only the build toolchain. Mount the source and output
+  directories to write artifacts directly to the host. It can also be used as
+  an interactive development environment by mounting the source tree.
+- `test` installs the package from the source tree and runs the unit tests.
+- `build` creates the wheel and source distribution under `/dist`.
+- `wheel-test` installs the built wheel and runs the tests against that exact
+  wheel, which is the release artifact to be uploaded to PyPI.
+
+The `test` and `wheel-test` stages run their tests during `podman build`, so a
+failing test causes the image build to fail. They also have test commands as
+their default container commands, so a successful image can be tested again:
+
+```bash
+podman run --rm traderoutes-python-test
+podman run --rm traderoutes-python-wheel-test
+```
+
+The build stages do not publish anything and do not require PyPI credentials.
+For local development, build directly into a host directory with Podman:
+
+```bash
+mkdir -p dist/python
+podman run --rm \
+  -v "$PWD:/workspace:Z" \
+  -v "$PWD/dist/python:/out:Z" \
+  traderoutes-python-build-env \
+  python -m build --outdir /out
+```
+
+To test the exported wheel in the same clean toolchain:
+
+```bash
+podman run --rm \
+  -v "$PWD:/workspace:Z" \
+  -v "$PWD/dist/python:/dist:Z" \
+  traderoutes-python-build-env \
+  sh -c 'python -m pip install --no-cache-dir --no-deps /dist/*.whl && python -m unittest discover -s /workspace/tests -v'
+```
+
+Validate the package metadata before uploading:
+
+```bash
+podman run --rm \
+  -v "$PWD/dist/python:/dist:Z" \
+  traderoutes-python-build-env \
+  python -m twine check /dist/*
+```
+
+## Local tests
+
+With the runtime dependencies installed:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+## License
+
+MIT; see [`LICENSE`](LICENSE).

traderoutes-0.0.3/src/traderoutes.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/traderoutes/__init__.py
+src/traderoutes/borders.py
+src/traderoutes/routes.py
+src/traderoutes.egg-info/PKG-INFO
+src/traderoutes.egg-info/SOURCES.txt
+src/traderoutes.egg-info/dependency_links.txt
+src/traderoutes.egg-info/requires.txt
+src/traderoutes.egg-info/top_level.txt
+src/traderoutes/assets/bordersgraph.pkl
+src/traderoutes/assets/fullgraph.pkl
+tests/test_borders.py
+tests/test_routes.py

traderoutes-0.0.3/src/traderoutes.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

traderoutes-0.0.3/src/traderoutes.egg-info/requires.txt

@@ -0,0 +1,4 @@
+numpy>=2.4.0
+igraph>=0.11.8
+simplekml>=1.3.6
+geopy>=2.4.1

traderoutes-0.0.3/src/traderoutes.egg-info/top_level.txt

@@ -0,0 +1 @@
+traderoutes

traderoutes-0.0.3/tests/test_borders.py

@@ -0,0 +1,38 @@
+import unittest
+
+from traderoutes.borders import *
+
+
+class TestBorders(unittest.TestCase):
+
+    def test_get_neighbors(self):
+        self.assertEqual(get_neighbors("USA"), ["MEX", "CAN"])
+
+    def test_are_neighbors(self):
+        self.assertEqual(are_neighbors("FRA", "ITA"), True)
+        self.assertEqual(are_neighbors("FRA", "USA"), False)
+
+    def test_get_second_neighbors(self):
+        self.assertEqual(
+            get_second_neighbors("FRA"),
+            [
+                "MAR",
+                "PRT",
+                "AUT",
+                "CZE",
+                "POL",
+                "NLD",
+                "DNK",
+                "SVN",
+                "SMR",
+                "VAT",
+                "LIE",
+            ],
+        )
+
+    def test_get_common_neighbors(self):
+        self.assertEqual(get_common_neighbors("FRA", "ITA"), ["CHE"])
+
+
+if __name__ == "__main":
+    unittest.main()

traderoutes-0.0.3/tests/test_routes.py

@@ -0,0 +1,80 @@
+import unittest
+import warnings
+
+import numpy as np
+
+from traderoutes.routes import *
+
+
+class TestRoutes(unittest.TestCase):
+    def _trade_path(self, country1, country2, border_cost=0, border_cost_countries=None):
+        if border_cost_countries is None:
+            border_cost_countries = {}
+        return get_path(
+            get_main_city(country1),
+            get_main_city(country2),
+            road_cost=7,
+            port_cost=1e4,
+            port_cost_countries={country1: 5e3, country2: 5e3},
+            border_cost=border_cost,
+            border_cost_countries=border_cost_countries,
+        )
+
+    def test_get_main_city(self):
+        # Check only one main city per country
+        countries = np.unique(g.vs.select(vtype="city")["country"])
+        with warnings.catch_warnings(record=True) as warnings_log:
+            warnings.simplefilter("always")
+            for c in countries:
+                mc = get_main_city(c)
+            self.assertEqual(
+                len(warnings_log),
+                0,
+                f"Unexpected warnings: {[w.message for w in warnings_log]}",
+            )
+
+    def test_get_great_circle(self):
+        self.assertAlmostEqual(get_great_circle("FRA", "ITA"), 1109.56, places=2)
+
+    def test_get_trade_route_great_circle(self):
+        tr = get_trade_route_great_circle("FRA", "ITA")
+        self.assertEqual(tr["iso_i"], "FRA")
+        self.assertEqual(tr["iso_j"], "ITA")
+        self.assertAlmostEqual(tr["dist"], 1109.56, places=2)
+
+    def test_sea_distance_includes_sea_border(self):
+        path = self._trade_path("PRY", "USA")
+        edges = g.es.select(path["epath"])
+        self.assertIn("sea_border", edges["etype"])
+
+        expected = sum(e["dist"] for e in edges if e["etype"] in SEA_EDGE_TYPES)
+        self.assertAlmostEqual(sea_distance(path), expected)
+
+    def test_paraguay_usa_origin_transits(self):
+        path = self._trade_path("PRY", "USA")
+        ti = transits_i(path)
+        tj = transits_j(path)
+
+        self.assertGreater(len(ti), 0)
+        self.assertIn("ARG", ti)
+        self.assertNotIn("PRY", ti + tj)
+        self.assertNotIn("USA", ti + tj)
+
+    def test_sea_border_country_pair_costs(self):
+        self._trade_path(
+            "PRY",
+            "USA",
+            border_cost=1e4,
+            border_cost_countries={("ARG", "PRY"): 5e4},
+        )
+        edges = g.es.select(
+            etype="sea_border", country1_in=("ARG", "PRY"), country2_in=("ARG", "PRY")
+        )
+
+        self.assertGreater(len(edges), 0)
+        for edge in edges:
+            self.assertAlmostEqual(edge["wdist"], edge["dist"] + 5e4)
+
+
+if __name__ == "__main":
+    unittest.main()