duva 0.1.0__tar.gz

duva-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: duva
+Version: 0.1.0
+Requires-Python: >=3.12
+Requires-Dist: geopandas>=1.0.0

duva-0.1.0/README.md

@@ -0,0 +1,39 @@
+# duva 🕊️
+
+Reverse geocode Swedish coordinates to RegSO areas.
+
+## Install
+
+```bash
+pip install duva
+```
+
+## Usage
+
+```python
+from duva import duva, duva_many, duva_df, duva_from_kod
+
+# Single coordinate (WGS84)
+duva(x=17.88, y=59.35)
+# {'regsonamn': 'Blackeberg', 'kommunnamn': 'Stockholm', 'lansnamn': 'Stockholms län', ...}
+
+# As object
+result = duva(x=17.88, y=59.35, as_object=True)
+result.regsonamn  # 'Blackeberg'
+
+# List of coordinates
+duva_many([(17.88, 59.35), (18.07, 59.28)])
+
+# Enrich a Polars DataFrame
+duva_df(df, x_col="lon", y_col="lat")
+
+# Lookup by RegSO code
+duva_from_kod("0180R009")
+```
+
+## Notes
+
+- Input coordinates must be WGS84 (standard GPS)
+- Raises `ValueError` for invalid coordinates or coordinates outside Sweden
+- Returns `not_on_land=True` for water areas, `is_baltic=True` for international water
+- Based on SCB's RegSO 2025 and municipality boundaries

duva-0.1.0/duva/Kommun_Sweref99TM.TAB

@@ -0,0 +1,15 @@
+!table
+!version 300
+!charset WindowsLatin1
+
+Definition Table
+  Type NATIVE Charset "WindowsLatin1"
+  Fields 2
+    KnKod Char (4) Index 1 ;
+    KnNamn Char (15) Index 2 ;
+begin_metadata
+"\MapInfo" = ""
+"\MapInfo\TableID" = "6b951346-0ed0-4fdf-9893-79398f968eb8"
+"\MapInfo\ParentTableID" = "5505f6c7-db00-4b1a-a344-db38bbddbb57"
+"\IsReadOnly" = "FALSE"
+end_metadata

duva-0.1.0/duva/__init__.py

@@ -0,0 +1,222 @@
+from pathlib import Path
+
+import geopandas as gpd
+import polars as pl
+from shapely.geometry import Point
+
+_GPKG_PATH = Path(__file__).parent / "RegSO_2025.gpkg"
+_KOMMUN_PATH = Path(__file__).parent / "Kommun_Sweref99TM.TAB"
+
+_GDF: gpd.GeoDataFrame = gpd.read_file(_GPKG_PATH).drop(columns=["objectid", "geometry"])
+_GDF_GEO: gpd.GeoDataFrame = gpd.read_file(_GPKG_PATH)[["regsokod", "geometry"]]
+_KOMMUN_GEO: gpd.GeoDataFrame = gpd.read_file(_KOMMUN_PATH)[["KnKod", "KnNamn", "geometry"]].set_crs("EPSG:3006", allow_override=True)
+_KOD_INDEX: dict[str, dict] = {
+    row["regsokod"]: row
+    for row in _GDF.to_dict(orient="records")
+}
+
+_LAN: dict[str, str] = {
+    "01": "Stockholms län",
+    "03": "Uppsala län",
+    "04": "Södermanlands län",
+    "05": "Östergötlands län",
+    "06": "Jönköpings län",
+    "07": "Kronobergs län",
+    "08": "Kalmar län",
+    "09": "Gotlands län",
+    "10": "Blekinge län",
+    "12": "Skåne län",
+    "13": "Hallands län",
+    "14": "Västra Götalands län",
+    "17": "Värmlands län",
+    "18": "Örebro län",
+    "19": "Västmanlands län",
+    "20": "Dalarnas län",
+    "21": "Gävleborgs län",
+    "22": "Västernorrlands län",
+    "23": "Jämtlands län",
+    "24": "Västerbottens län",
+    "25": "Norrbottens län",
+}
+
+_LON_MIN, _LAT_MIN, _LON_MAX, _LAT_MAX = 10.59, 55.13, 24.18, 69.06
+
+
+class RegSO:
+    def __init__(
+        self,
+        not_on_land: bool,
+        is_baltic: bool = False,
+        objektidentitet: str | None = None,
+        objekttyp: str | None = None,
+        regsokod: str | None = None,
+        regsonamn: str | None = None,
+        lanskod: str | None = None,
+        lansnamn: str | None = None,
+        kommunkod: str | None = None,
+        kommunnamn: str | None = None,
+        version: str | None = None,
+        ansvarig_organisation: str | None = None,
+        referensdatum: str | None = None,
+    ) -> None:
+        self.not_on_land = not_on_land
+        self.is_baltic = is_baltic
+        self.objektidentitet = objektidentitet
+        self.objekttyp = objekttyp
+        self.regsokod = regsokod
+        self.regsonamn = regsonamn
+        self.lanskod = lanskod
+        self.lansnamn = lansnamn
+        self.kommunkod = kommunkod
+        self.kommunnamn = kommunnamn
+        self.version = version
+        self.ansvarig_organisation = ansvarig_organisation
+        self.referensdatum = referensdatum
+
+    def __repr__(self) -> str:
+        return (
+            f"RegSO(regsokod={self.regsokod!r}, regsonamn={self.regsonamn!r}, "
+            f"kommunkod={self.kommunkod!r}, kommunnamn={self.kommunnamn!r}, "
+            f"lansnamn={self.lansnamn!r}, not_on_land={self.not_on_land}, "
+            f"is_baltic={self.is_baltic})"
+        )
+
+
+def _validate(x: float, y: float) -> None:
+    if not (-180 <= x <= 180):
+        raise ValueError(f"Invalid longitude: {x}. Must be between -180 and 180.")
+    if not (-90 <= y <= 90):
+        raise ValueError(f"Invalid latitude: {y}. Must be between -90 and 90.")
+    if not (_LON_MIN <= x <= _LON_MAX and _LAT_MIN <= y <= _LAT_MAX):
+        raise ValueError(f"Coordinates ({x}, {y}) are outside Sweden.")
+
+
+def _lookup_kommun(point_3006: gpd.GeoDataFrame) -> tuple[str | None, str | None]:
+    match = _KOMMUN_GEO[_KOMMUN_GEO.contains(point_3006.geometry.iloc[0])]
+    if match.empty:
+        return None, None
+    return match.iloc[0]["KnKod"], match.iloc[0]["KnNamn"]
+
+
+def _lookup_point(x: float, y: float) -> dict:
+    point = gpd.GeoDataFrame(
+        geometry=[Point(x, y)],
+        crs="EPSG:4326",
+    ).to_crs("EPSG:3006")
+
+    match = _GDF_GEO[_GDF_GEO.contains(point.geometry.iloc[0])]
+
+    if match.empty:
+        kommunkod, kommunnamn = _lookup_kommun(point)
+        return {
+            "not_on_land": True,
+            "is_baltic": kommunkod is None,
+            "kommunkod": kommunkod,
+            "kommunnamn": kommunnamn,
+        }
+
+    row = dict(_KOD_INDEX[match.iloc[0]["regsokod"]])
+    km = _KOMMUN_GEO[_KOMMUN_GEO["KnKod"] == row["kommunkod"]]
+    row["kommunnamn"] = km.iloc[0]["KnNamn"] if not km.empty else None
+    row["lansnamn"] = _LAN.get(row["lanskod"])
+    row["not_on_land"] = False
+    row["is_baltic"] = False
+    return row
+
+
+def duva(x: float, y: float, as_object: bool = False) -> dict | RegSO:
+    _validate(x, y)
+    row = _lookup_point(x, y)
+    return RegSO(**row) if as_object else row
+
+
+def duva_many(
+    coords: list[tuple[float, float]],
+    as_object: bool = False,
+) -> list[dict | RegSO]:
+    results = []
+    for x, y in coords:
+        try:
+            _validate(x, y)
+            row = _lookup_point(x, y)
+        except ValueError as e:
+            row = {"error": str(e), "not_on_land": None}
+        results.append(RegSO(**row) if as_object else row)
+    return results
+
+
+def duva_df(
+    df: pl.DataFrame,
+    x_col: str = "lon",
+    y_col: str = "lat",
+) -> pl.DataFrame:
+    pdf = df.to_pandas()
+    valid = pdf[x_col].notna() & pdf[y_col].notna()
+
+    gdf = gpd.GeoDataFrame(
+        pdf[valid][[x_col, y_col]].copy(),
+        geometry=gpd.points_from_xy(
+            pdf.loc[valid, x_col].astype(float),
+            pdf.loc[valid, y_col].astype(float),
+        ),
+        crs="EPSG:4326",
+    ).to_crs("EPSG:3006")
+
+    joined_regso = gpd.sjoin(gdf, _GDF_GEO, how="left", predicate="within")
+    joined_kommun = gpd.sjoin(gdf, _KOMMUN_GEO, how="left", predicate="within")
+
+    regsokod_list: list[str | None] = [None] * len(pdf)
+    regsonamn_list: list[str | None] = [None] * len(pdf)
+    kommunkod_list: list[str | None] = [None] * len(pdf)
+    kommunnamn_list: list[str | None] = [None] * len(pdf)
+    lanskod_list: list[str | None] = [None] * len(pdf)
+    lansnamn_list: list[str | None] = [None] * len(pdf)
+    not_on_land_list: list[bool] = [False] * len(pdf)
+    is_baltic_list: list[bool] = [False] * len(pdf)
+
+    for idx in pdf[valid].index:
+        regso_match = joined_regso[joined_regso.index == idx]
+        kommun_match = joined_kommun[joined_kommun.index == idx]
+
+        kod = regso_match["regsokod"].iloc[0] if len(regso_match) else None
+        if kod and not isinstance(kod, float):
+            meta = _KOD_INDEX.get(kod, {})
+            regsokod_list[idx] = kod
+            regsonamn_list[idx] = meta.get("regsonamn")
+            lanskod_list[idx] = meta.get("lanskod")
+            lansnamn_list[idx] = _LAN.get(meta.get("lanskod", ""))
+            kommunkod_list[idx] = meta.get("kommunkod")
+            km = _KOMMUN_GEO[_KOMMUN_GEO["KnKod"] == kommunkod_list[idx]]
+            kommunnamn_list[idx] = km.iloc[0]["KnNamn"] if not km.empty else None
+        else:
+            not_on_land_list[idx] = True
+            if len(kommun_match):
+                kk = kommun_match["KnKod"].iloc[0]
+                kn = kommun_match["KnNamn"].iloc[0]
+                kommunkod_list[idx] = None if isinstance(kk, float) else kk
+                kommunnamn_list[idx] = None if isinstance(kn, float) else kn
+            is_baltic_list[idx] = kommunkod_list[idx] is None
+
+    return df.with_columns([
+        pl.Series("regsokod", regsokod_list, dtype=pl.String),
+        pl.Series("regsonamn", regsonamn_list, dtype=pl.String),
+        pl.Series("kommunkod", kommunkod_list, dtype=pl.String),
+        pl.Series("kommunnamn", kommunnamn_list, dtype=pl.String),
+        pl.Series("lanskod", lanskod_list, dtype=pl.String),
+        pl.Series("lansnamn", lansnamn_list, dtype=pl.String),
+        pl.Series("not_on_land", not_on_land_list, dtype=pl.Boolean),
+        pl.Series("is_baltic", is_baltic_list, dtype=pl.Boolean),
+    ])
+
+
+def duva_from_kod(kod: str, as_object: bool = False) -> dict | RegSO | None:
+    row = _KOD_INDEX.get(kod)
+    if row is None:
+        return None
+    row = dict(row)
+    km = _KOMMUN_GEO[_KOMMUN_GEO["KnKod"] == row["kommunkod"]]
+    row["kommunnamn"] = km.iloc[0]["KnNamn"] if not km.empty else None
+    row["lansnamn"] = _LAN.get(row["lanskod"])
+    row["not_on_land"] = False
+    row["is_baltic"] = False
+    return RegSO(**row) if as_object else row

duva-0.1.0/duva.egg-info/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: duva
+Version: 0.1.0
+Requires-Python: >=3.12
+Requires-Dist: geopandas>=1.0.0

duva-0.1.0/duva.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+duva/Kommun_Sweref99TM.DAT
+duva/Kommun_Sweref99TM.ID
+duva/Kommun_Sweref99TM.IND
+duva/Kommun_Sweref99TM.MAP
+duva/Kommun_Sweref99TM.TAB
+duva/RegSO_2025.gpkg
+duva/__init__.py
+duva.egg-info/PKG-INFO
+duva.egg-info/SOURCES.txt
+duva.egg-info/dependency_links.txt
+duva.egg-info/requires.txt
+duva.egg-info/top_level.txt
+tests/test_duva.py
+tests/test_duva_df.py
+tests/test_duva_from_kod.py
+tests/test_duva_many.py

duva-0.1.0/duva.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

duva-0.1.0/duva.egg-info/requires.txt

@@ -0,0 +1 @@
+geopandas>=1.0.0

duva-0.1.0/duva.egg-info/top_level.txt

@@ -0,0 +1 @@
+duva

duva-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "duva"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = [
+    "geopandas>=1.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["duva*"]
+
+[tool.setuptools.package-data]
+duva = ["*.gpkg", "*.TAB", "*.DAT", "*.ID", "*.IND", "*.MAP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

duva-0.1.0/setup.cfg

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

duva-0.1.0/tests/test_duva.py

@@ -0,0 +1,84 @@
+import pytest
+from duva import duva, RegSO
+
+BLACKEBERG = (17.88, 59.35)
+GAMLA_ENSKEDE = (18.07, 59.28)
+BALTIC = (20.5, 57.5)
+
+
+def test_returns_dict_by_default():
+    result = duva(*BLACKEBERG)
+    assert isinstance(result, dict)
+
+
+def test_returns_regso_object():
+    result = duva(*BLACKEBERG, as_object=True)
+    assert isinstance(result, RegSO)
+
+
+def test_correct_regsonamn():
+    result = duva(*BLACKEBERG)
+    assert result["regsonamn"] == "Blackeberg"
+
+
+def test_correct_kommunkod():
+    result = duva(*BLACKEBERG)
+    assert result["kommunkod"] == "0180"
+
+
+def test_correct_kommunnamn():
+    result = duva(*BLACKEBERG)
+    assert result["kommunnamn"] == "Stockholm"
+
+
+def test_correct_lansnamn():
+    result = duva(*BLACKEBERG)
+    assert result["lansnamn"] == "Stockholms län"
+
+
+def test_not_on_land_false_for_land():
+    result = duva(*BLACKEBERG)
+    assert result["not_on_land"] is False
+
+
+def test_is_baltic_false_for_land():
+    result = duva(*BLACKEBERG)
+    assert result["is_baltic"] is False
+
+
+def test_not_on_land_true_for_water():
+    result = duva(*BALTIC)
+    assert result["not_on_land"] is True
+
+
+def test_is_baltic_true_for_baltic():
+    result = duva(*BALTIC)
+    assert result["is_baltic"] is True
+
+
+def test_water_has_no_regsonamn():
+    result = duva(*BALTIC)
+    assert result.get("regsonamn") is None
+
+
+def test_object_attributes_match_dict():
+    d = duva(*GAMLA_ENSKEDE)
+    obj = duva(*GAMLA_ENSKEDE, as_object=True)
+    assert obj.regsonamn == d["regsonamn"]
+    assert obj.kommunkod == d["kommunkod"]
+    assert obj.lansnamn == d["lansnamn"]
+
+
+def test_invalid_longitude_raises():
+    with pytest.raises(ValueError, match="longitude"):
+        duva(x=200.0, y=59.0)
+
+
+def test_invalid_latitude_raises():
+    with pytest.raises(ValueError, match="latitude"):
+        duva(x=17.0, y=100.0)
+
+
+def test_outside_sweden_raises():
+    with pytest.raises(ValueError, match="outside Sweden"):
+        duva(x=10.0, y=50.0)

duva-0.1.0/tests/test_duva_df.py

@@ -0,0 +1,92 @@
+import polars as pl
+import pytest
+from duva import duva_df
+
+
+@pytest.fixture
+def sample_df() -> pl.DataFrame:
+    return pl.DataFrame({
+        "lon": [17.88, 20.5, 18.07, None],
+        "lat": [59.35, 57.5, 59.28, None],
+    })
+
+
+def test_returns_polars_dataframe(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert isinstance(result, pl.DataFrame)
+
+
+def test_adds_regsonamn_column(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert "regsonamn" in result.columns
+
+
+def test_adds_kommunkod_column(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert "kommunkod" in result.columns
+
+
+def test_adds_kommunnamn_column(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert "kommunnamn" in result.columns
+
+
+def test_adds_lanskod_column(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert "lanskod" in result.columns
+
+
+def test_adds_lansnamn_column(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert "lansnamn" in result.columns
+
+
+def test_adds_not_on_land_column(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert "not_on_land" in result.columns
+
+
+def test_adds_is_baltic_column(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert "is_baltic" in result.columns
+
+
+def test_row_count_unchanged(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert len(result) == len(sample_df)
+
+
+def test_correct_regsonamn_for_land(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert result["regsonamn"][0] == "Blackeberg"
+
+
+def test_not_on_land_false_for_land(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert result["not_on_land"][0] is False
+
+
+def test_not_on_land_true_for_baltic(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert result["not_on_land"][1] is True
+
+
+def test_is_baltic_true_for_baltic(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert result["is_baltic"][1] is True
+
+
+def test_null_coords_produce_null_regso(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert result["regsonamn"][3] is None
+
+
+def test_custom_column_names():
+    df = pl.DataFrame({"x": [17.88], "y": [59.35]})
+    result = duva_df(df, x_col="x", y_col="y")
+    assert result["regsonamn"][0] == "Blackeberg"
+
+
+def test_lansnamn_correct(sample_df: pl.DataFrame):
+    result = duva_df(sample_df)
+    assert result["lansnamn"][0] == "Stockholms län"

duva-0.1.0/tests/test_duva_from_kod.py

@@ -0,0 +1,62 @@
+from duva import duva_from_kod, RegSO
+
+BLACKEBERG_KOD = "0180R009"
+INVALID_KOD = "INVALID"
+
+
+def test_returns_dict_by_default():
+    result = duva_from_kod(BLACKEBERG_KOD)
+    assert isinstance(result, dict)
+
+
+def test_returns_regso_object():
+    result = duva_from_kod(BLACKEBERG_KOD, as_object=True)
+    assert isinstance(result, RegSO)
+
+
+def test_correct_regsonamn():
+    result = duva_from_kod(BLACKEBERG_KOD)
+    assert result["regsonamn"] == "Blackeberg"
+
+
+def test_correct_kommunkod():
+    result = duva_from_kod(BLACKEBERG_KOD)
+    assert result["kommunkod"] == "0180"
+
+
+def test_correct_kommunnamn():
+    result = duva_from_kod(BLACKEBERG_KOD)
+    assert result["kommunnamn"] == "Stockholm"
+
+
+def test_correct_lansnamn():
+    result = duva_from_kod(BLACKEBERG_KOD)
+    assert result["lansnamn"] == "Stockholms län"
+
+
+def test_not_on_land_false():
+    result = duva_from_kod(BLACKEBERG_KOD)
+    assert result["not_on_land"] is False
+
+
+def test_is_baltic_false():
+    result = duva_from_kod(BLACKEBERG_KOD)
+    assert result["is_baltic"] is False
+
+
+def test_invalid_kod_returns_none():
+    result = duva_from_kod(INVALID_KOD)
+    assert result is None
+
+
+def test_invalid_kod_as_object_returns_none():
+    result = duva_from_kod(INVALID_KOD, as_object=True)
+    assert result is None
+
+
+def test_object_attributes_match_dict():
+    d = duva_from_kod(BLACKEBERG_KOD)
+    obj = duva_from_kod(BLACKEBERG_KOD, as_object=True)
+    assert obj.regsonamn == d["regsonamn"]
+    assert obj.kommunkod == d["kommunkod"]
+    assert obj.lansnamn == d["lansnamn"]

duva-0.1.0/tests/test_duva_many.py

@@ -0,0 +1,64 @@
+from duva import duva_many, RegSO
+
+BLACKEBERG = (17.88, 59.35)
+BALTIC = (20.5, 57.5)
+OUTSIDE_SWEDEN = (10.0, 50.0)
+INVALID_LON = (200.0, 59.0)
+
+
+def test_returns_list():
+    result = duva_many([BLACKEBERG])
+    assert isinstance(result, list)
+
+
+def test_returns_correct_length():
+    coords = [BLACKEBERG, BALTIC, OUTSIDE_SWEDEN]
+    result = duva_many(coords)
+    assert len(result) == 3
+
+
+def test_returns_dicts_by_default():
+    result = duva_many([BLACKEBERG, BALTIC])
+    assert all(isinstance(r, dict) for r in result)
+
+
+def test_returns_regso_objects():
+    result = duva_many([BLACKEBERG, BALTIC], as_object=True)
+    assert all(isinstance(r, RegSO) for r in result)
+
+
+def test_correct_result_for_land():
+    result = duva_many([BLACKEBERG])
+    assert result[0]["regsonamn"] == "Blackeberg"
+
+
+def test_water_returns_not_on_land():
+    result = duva_many([BALTIC])
+    assert result[0]["not_on_land"] is True
+
+
+def test_invalid_coords_returns_error_key():
+    result = duva_many([OUTSIDE_SWEDEN])
+    assert "error" in result[0]
+
+
+def test_invalid_coords_not_on_land_is_none():
+    result = duva_many([OUTSIDE_SWEDEN])
+    assert result[0]["not_on_land"] is None
+
+
+def test_mixed_coords():
+    result = duva_many([BLACKEBERG, BALTIC, OUTSIDE_SWEDEN])
+    assert result[0]["regsonamn"] == "Blackeberg"
+    assert result[1]["not_on_land"] is True
+    assert "error" in result[2]
+
+
+def test_empty_list():
+    result = duva_many([])
+    assert result == []
+
+
+def test_invalid_lon_returns_error():
+    result = duva_many([INVALID_LON])
+    assert "error" in result[0]