giso 1.0.0__py3-none-any.whl

giso/__init__.py

@@ -0,0 +1 @@
+from ._core import *

giso/_cli.py

@@ -0,0 +1,99 @@
+import click
+
+
+@click.command(
+    no_args_is_help=True,
+    context_settings={"ignore_unknown_options": True},
+)
+@click.argument("args", nargs=-1)
+@click.option(
+    "--update", help="Re-download the lookup dataset before querying it.", is_flag=True
+)
+def cli(args, update):
+    # noinspection PyUnresolvedReferences
+    """
+    A simple command line tool to help with geocoding country/region ISO 3166-2 codes.
+
+    Uses the dataset "ne_10m_admin_1_states_provinces" from https://github.com/nvkelso/natural-earth-vector
+
+    Takes one of two inputs:
+
+    1. A longitude/latitude coordinate pair. (Decimal degrees in WGS 1984 separated by a comma or a space.)
+    Returns the corresponding ISO 3166-2 code.
+
+        Example:
+
+        \b
+        >>> giso -122.2483823, 37.8245529
+        US-CA
+
+    2. A valid ISO 3166-2 code. Returns the corresponding geometry as Well-Known Text (WKT).
+
+        Example:
+
+       \b
+        >>> giso US-CA
+        MULTIPOLYGON (((-114.724285 32.712836, -114.764541 32.709839, [...]
+
+    """
+    if update:
+        from ._core import update
+
+        update(overwrite=True)
+        if len(args) == 0:
+            return None
+
+    iso_code, x, y = None, None, None
+    try:
+        if len(args) == 1:
+            arg = args[0]
+            if "-" in arg and not arg.startswith("-"):  # geocode
+                iso_code = arg.strip().upper()
+                assert len(iso_code.split("-")) == 2
+            elif "," in arg:  # reverse geocode comma delimited
+                coordinates = arg.split(",")
+                x, y = map(float, coordinates)
+
+            elif " " in arg:  # reverse geocode space delimited
+                while "  " in arg:
+                    arg = arg.replace("  ", " ")
+                coordinates = arg.split(" ")
+                x, y = map(float, coordinates)
+            else:
+                assert False
+
+        elif len(args) == 2:  # reverse geocode
+            x = float(args[0].strip(","))
+            y = float(args[1].strip(","))
+
+        else:
+            assert False
+
+    except (AssertionError, ValueError):
+        click.echo(
+            "Invalid input: Please provide either a valid ISO 3166-2 code "
+            "or a comma/space-separated longitude/latitude pair.",
+            err=True,
+        )
+        return None
+
+    if iso_code:
+        # click.echo(f"Geocoding: {iso_code}")
+        from ._core import geocode
+
+        result = geocode(iso_code)
+        click.echo(str(result))
+        return result
+    elif x and y:
+        # click.echo(f"Reverse geocoding: x={x}, y={y}")
+        from ._core import reverse_geocode
+
+        result = reverse_geocode(x, y)
+        click.echo(str(result))
+        return result
+    else:
+        raise RuntimeError
+
+
+if __name__ == "__main__":
+    cli()

giso/_core.py

@@ -0,0 +1,149 @@
+import os
+
+import geopandas as gpd
+import sedona.db
+import shapely
+
+
+_DATA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "data")
+_DATA_FILE = os.path.join(_DATA_DIR, "ne_10m_admin_1_states_provinces.parquet")
+_DATA_URL = "https://raw.githubusercontent.com/nvkelso/natural-earth-vector/master/geojson/ne_10m_admin_1_states_provinces.geojson"
+
+__all__ = ["Giso", "clear", "geocode", "reverse_geocode", "update"]
+
+
+def clear():
+    """Clears the data directory and file.
+
+    This function removes the data directory and its contents.
+    It first checks if the data file exists and removes it if it does.
+    Then, it checks if the data directory exists and removes it if it does.
+    """
+    if os.path.exists(_DATA_FILE):
+        print(f"Removing {_DATA_FILE}")
+        os.remove(_DATA_FILE)
+
+
+class Giso:
+    """
+    This class provides functionality to download, read, and geocode
+    natural earth vector data.
+    """
+
+    def __init__(
+        self,
+        data_file: str = _DATA_FILE,
+        data_url: str = _DATA_URL,
+        autoupdate: bool = True,
+    ):
+        self._data_file = data_file
+        self._data_url = data_url
+        self._sd: sedona.db.context.SedonaContext = sedona.db.connect()
+
+        if autoupdate:
+            self.update()
+
+        if not os.path.exists(self._data_file):
+            print("Giso object must be initialized with Giso.update()")
+        else:
+            df = self._sd.read_parquet(self._data_file)
+            df.to_view("subdivisions")
+
+    def geocode(
+        self, iso_3166_2: str
+    ) -> type[shapely.Polygon, shapely.MultiPolygon] | None:
+        """
+        This function geocodes a location based on its ISO 3166-2 country code.
+        It retrieves the corresponding geographic data from a GeoDataFrame and
+        returns it as a GeoJSON feature. If no data is found, it prints a
+        message to the console and returns None.
+        """
+        queried: sedona.db.dataframe.DataFrame = self._sd.sql(
+            f"SELECT geometry FROM subdivisions WHERE iso_3166_2 = '{iso_3166_2}'"
+        )
+        queried: gpd.GeoDataFrame = queried.to_pandas()
+        if len(queried) >= 1:
+            result: type[shapely.Polygon, shapely.MultiPolygon] = queried["geometry"][0]
+            return result
+        else:
+            return None
+
+    def reverse_geocode(self, x: float, y: float) -> str | None:
+        """
+        This function performs a reverse geocode lookup using a GeoDataFrame.
+
+        Args:
+            x: The longitude coordinate of the point.
+            y: The latitude coordinate of the point.
+        """
+        query_pt = gpd.GeoDataFrame(geometry=[shapely.Point(x, y)], crs="EPSG:4326")
+        query_pt = self._sd.create_data_frame(query_pt)
+        query_pt.to_view("query_pt")
+
+        queried: sedona.db.dataframe.DataFrame = self._sd.sql(
+            """
+            SELECT
+                subdivisions.iso_3166_2 as iso_3166_2,
+                subdivisions.geometry as geometry
+            FROM subdivisions
+                     JOIN query_pt ON ST_Intersects(subdivisions.geometry, query_pt.geometry)
+            """
+        )
+        queried: gpd.GeoDataFrame = queried.to_pandas()
+        self._sd.drop_view("query_pt")
+
+        if len(queried) >= 1:
+            result = queried["iso_3166_2"][0]
+            assert isinstance(result, str)
+            return result
+        else:
+            return None
+
+    def update(self, overwrite: bool = False) -> None:
+        """
+        Pulls from a public domain dataset on GitHub
+
+        References:
+            - https://github.com/nvkelso/natural-earth-vector
+            - https://www.naturalearthdata.com/
+
+        """
+        data_dir = os.path.dirname(self._data_file)
+
+        if os.path.exists(self._data_file):
+            if not overwrite:
+                # print("File already exists")
+                return
+            else:
+                print(f"Removing {self._data_file}")
+                os.remove(self._data_file)
+
+        if not os.path.exists(data_dir):
+            os.mkdir(data_dir)
+
+        print(f"Downloading {self._data_url} to {self._data_file}")
+        gdf = gpd.read_file(self._data_url)
+        gdf.to_parquet(self._data_file, compression="brotli")
+
+        try:
+            assert os.path.exists(self._data_file)
+            assert os.path.getsize(self._data_file) > 1000
+        except AssertionError:
+            raise ValueError(f"Invalid file {self._data_file}")
+
+        print("Done!")
+
+
+_inst = Giso()
+
+
+def geocode(iso_3166_2: str) -> type[shapely.Polygon, shapely.MultiPolygon] | None:
+    return _inst.geocode(iso_3166_2=iso_3166_2)
+
+
+def reverse_geocode(x: float, y: float) -> str | None:
+    return _inst.reverse_geocode(x=x, y=y)
+
+
+def update(overwrite: bool = False):
+    _inst.update(overwrite=overwrite)

giso-1.0.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: giso
+Version: 1.0.0
+Summary: A simple command line tool to help with geocoding country/region ISO 3166-2 codes
+Project-URL: homepage, https://pypi.org/project/giso/
+Project-URL: repository, https://github.com/corbel-spatial/giso
+Project-URL: issues, https://github.com/corbel-spatial/giso/issues
+Project-URL: changelog, https://github.com/corbel-spatial/giso/blob/main/CHANGELOG.md
+Author-email: Peter Von der Porten <dev@corbelspatial.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: Microsoft :: Windows :: Windows 11
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+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 :: GIS
+Requires-Python: >=3.10
+Requires-Dist: apache-sedona[db]<2,>=1.8.0
+Requires-Dist: click
+Requires-Dist: geopandas>=1.1.0
+Requires-Dist: pyarrow
+Description-Content-Type: text/markdown
+
+[![PyPI - Version](https://img.shields.io/pypi/v/giso)](https://pypi.org/project/giso/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/giso)](https://pypi.org/project/giso/)
+[![PyPI Downloads](https://static.pepy.tech/badge/giso/month)](https://pepy.tech/projects/giso)
+[![License: MIT](https://img.shields.io/badge/License-MIT-lightgrey.svg?logo=)](https://github.com/corbel-spatial/giso/blob/main/LICENSE)
+[![Pixi Badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
+
+# giso
+
+A simple command line tool to help with geocoding country/region [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) codes.
+
+Includes a public domain reference dataset from [Natural Earth Data](https://github.com/nvkelso/natural-earth-vector)
+which is stored in [GeoParquet](https://geoparquet.org/) format and is accessed with [SedonaDB](https://sedona.apache.org/sedonadb/latest/).
+
+## Installation
+
+```shell
+python -m pip install giso
+```
+
+## Basic Usage
+
+`giso` takes one of two inputs:
+
+- A longitude/latitude coordinate pair. (Decimal degrees in WGS 1984 separated by a comma or a space.)
+Returns the corresponding ISO 3166-2 code.
+
+```shell
+giso -122.2483823, 37.8245529
+# US-CA
+```
+
+- A valid ISO 3166-2 code. Returns the corresponding geometry as Well-Known Text (WKT).
+
+```shell
+giso US-CA
+# MULTIPOLYGON (((-114.724285 32.712836, -114.764541 32.709839, [...]
+```
+
+Returns `None` if there are no hits.
+
+`giso` can also be used as a Python package:
+
+```python
+>>> import giso
+>>> giso.reverse_geocode(103.8455041, 1.2936855)
+'SG-01'
+>>> giso.geocode("SG-01")
+< POLYGON((103.898 1.305, 103.888 1.301, 103.853 1.277, 103.847 1.272, 103.8 ... >
+```
+
+
+## References
+
+- [Natural Earth Data homepage](https://www.naturalearthdata.com/)

giso-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+giso/__init__.py,sha256=0zpBfzO64sy3FMVSKxe4TzTdDEXGpDaPHgG23YWlvts,21
+giso/_cli.py,sha256=QUY_cQ5lcSnwmjK4mMkdEcoV6zDLvCcGNpsaU0IWsgM,2776
+giso/_core.py,sha256=7tKcjDSBrazV-a_KgIwH_XeA4MvRL_2bIqNu_Gnuz6Q,4812
+giso/data/ne_10m_admin_1_states_provinces.parquet,sha256=BWIaWCPQ1mv68d76h4WawrBPaEqZ0LmvdRLtv_MKilA,11114502
+giso-1.0.0.dist-info/METADATA,sha256=fZNgv0Fsy-ddjuhCneAFIzrn_4GsbfvtUofPgNNwDO8,3192
+giso-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+giso-1.0.0.dist-info/entry_points.txt,sha256=tgEgLvB__Gtfdhv00GDox-nV4VSFjlWIV_Y0W_tcAbE,39
+giso-1.0.0.dist-info/licenses/LICENSE,sha256=oNiQolItTsRy91IINMUk_2K5S1Lwp_KVA1g2BXxwyog,1077
+giso-1.0.0.dist-info/RECORD,,

giso-1.0.0.dist-info/WHEEL

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

giso-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+giso = giso._cli:cli

giso-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter Von der Porten
+
+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.