ne-loader 0.2.1__py3-none-any.whl

ne_loader/__init__.py

@@ -0,0 +1 @@
+# Natural Earth Loader package

ne_loader/cacher.py

@@ -0,0 +1,35 @@
+"""Resolve the cache directory used for downloaded Natural Earth data."""
+
+import os
+from pathlib import Path
+from typing import Optional, Union
+
+from platformdirs import user_cache_dir
+
+
+PathLike = Union[str, Path]
+
+
+def get_cache_dir(path_override: Optional[PathLike] = None) -> Path:
+    """Return the directory used to cache Natural Earth downloads.
+
+    Cache directory in order of precedence:
+    1. Explicit function argument 'path_override'
+    2. ``NATURAL_EARTH_CACHE_DIR`` environment variable.
+    3. Platform-specific user cache directory.
+
+    Args:
+        path_override: Optional cache directory
+    Returns:
+        A ``pathlib.Path`` pointing to the cache directory.
+
+    """
+    if path_override:
+        return Path(path_override).expanduser()
+
+    env_path: Optional[str] = os.getenv("NATURAL_EARTH_CACHE_DIR")
+    if env_path:
+        return Path(env_path).expanduser()
+
+    default_cache_dir: str = user_cache_dir(appname="ne-loader", appauthor="erictunn")
+    return Path(default_cache_dir)

ne_loader/cli.py

@@ -0,0 +1,33 @@
+"""Provides basic command line functionality."""
+
+import argparse
+
+import geopandas as gpd
+
+from . import map_loader
+
+
+def main() -> None:
+    """Run the Natural Earth loader command-line interface."""
+    parser: argparse.ArgumentParser = argparse.ArgumentParser(
+        description="Download and load Natural Earth data."
+    )
+    parser.add_argument("category", choices=["cultural", "physical"], help="Data category")
+    parser.add_argument("name", help="Dataset name (e.g., admin_0_countries)")
+    parser.add_argument("--res", default="10m", help="Resolution (default: 10m)")
+    parser.add_argument("--out", help="Output file to save as GeoJSON (optional)")
+    args: argparse.Namespace = parser.parse_args()
+
+    gdf: gpd.GeoDataFrame = map_loader.get_natural_earth(
+        args.category,
+        args.name,
+        args.res,
+    )
+    if args.out:
+        gdf.to_file(args.out, driver="GeoJSON")
+        print(f"Saved to {args.out}")
+    else:
+        print(gdf.head())
+
+if __name__ == "__main__":
+    main()

ne_loader/map_loader.py

@@ -0,0 +1,129 @@
+"""Handles downloading and fetching of NE data."""
+
+import logging
+import zipfile
+from pathlib import Path
+from typing import Optional
+
+import geopandas as gpd
+import requests
+
+from .cacher import PathLike, get_cache_dir
+
+
+def build_ne_filename(name: str, res: str = "10m", suffix: str = ".zip") -> str:
+    """Build a Natural Earth dataset filename."""
+    return f"ne_{res}_{name}{suffix}"
+
+
+def build_ne_url(category: str, name: str, res: str = "10m") -> str:
+    """Build the download URL for a Natural Earth vector dataset."""
+    return (
+        f"https://naciscdn.org/naturalearth/{res}/{category}/"
+        f"{build_ne_filename(name, res)}"
+    )
+
+
+def build_ne_zip_path(data_dir: PathLike, name: str, res: str = "10m") -> Path:
+    """Build the local cache path for a Natural Earth zip file."""
+    return Path(data_dir) / build_ne_filename(name, res)
+
+
+def build_ne_extract_dir(data_dir: PathLike, name: str, res: str = "10m") -> Path:
+    """Build the local extraction directory for a Natural Earth dataset."""
+    return Path(data_dir) / build_ne_filename(name, res, suffix="")
+
+
+def build_ne_shp_path(data_dir: PathLike, name: str, res: str = "10m") -> Path:
+    """Build the local shapefile path for an extracted Natural Earth dataset."""
+    extract_dir: Path = build_ne_extract_dir(data_dir, name, res)
+    return extract_dir / build_ne_filename(name, res, suffix=".shp")
+
+
+def get_natural_earth(
+    category: str,
+    name: str,
+    res: str = "10m",
+    dir_override: Optional[PathLike] = None,
+) -> gpd.GeoDataFrame:
+    """Download, cache, and load a Natural Earth vector dataset.
+
+    Args:
+        category: Natural Earth data category, e.g. "cultural" or
+            "physical".
+        name: Dataset name without the ``ne_{res}_`` prefix, e.g.
+            "admin_0_countries".
+        res: Natural Earth resolution. "10m", "50m" and "110m" are accepted.
+            However, not all datasets will have all 3 resolutions available.
+        dir_override: Optional cache directory override. This takes precedence over the
+            ``NATURAL_EARTH_CACHE_DIR`` environment variable.
+
+    Returns:
+        A GeoPandas ``GeoDataFrame`` loaded from the cached shapefile.
+
+    """
+    logger: logging.Logger = logging.getLogger(__name__)
+
+    data_dir: Path = get_cache_dir(dir_override)
+    data_dir.mkdir(parents=True, exist_ok=True)
+
+    url: str = build_ne_url(category, name, res)
+    zip_path: Path = build_ne_zip_path(data_dir, name, res)
+    extract_dir: Path = build_ne_extract_dir(data_dir, name, res)
+    shp_file: Path = build_ne_shp_path(data_dir, name, res)
+
+    _download_ne_data(
+        url=url,
+        extract_dir=extract_dir,
+        name=name,
+        res=res,
+        zip_path=zip_path,
+        shp_file=shp_file,
+        logger=logger,
+    )
+
+    return gpd.read_file(shp_file)
+
+
+def _download_ne_data(
+    url: str,
+    extract_dir: Path,
+    name: str,
+    res: str,
+    zip_path: Path,
+    shp_file: Path,
+    logger: logging.Logger,
+) -> None:
+    """Download and extract a dataset when the expected shapefile is absent."""
+    if shp_file.exists():
+        return
+
+    print(f"Downloading {name} ({res})...")
+
+    try:
+        response: requests.Response = requests.get(url, stream=True, timeout=10)
+        response.raise_for_status()
+
+        with zip_path.open("wb") as zip_file:
+            chunk: bytes
+            for chunk in response.iter_content(chunk_size=8192):
+                zip_file.write(chunk)
+
+        with zipfile.ZipFile(zip_path, "r") as zip_ref:
+            zip_ref.extractall(extract_dir)
+        zip_path.unlink()
+
+    except requests.exceptions.HTTPError as error:
+        logger.error(
+            "A HTTP error occurred while attempting to fetch data: %s\n"
+            "This may cause an error when attempting to load the data.",
+            error,
+        )
+        print(f"A HTTP error occurred while attempting to fetch data: {error}")
+    except requests.exceptions.RequestException as error:
+        logger.error(
+            "A request error occurred while attempting to fetch data: %s\n"
+            "This may cause an error when attempting to load the data.",
+            error,
+        )
+        print(f"A request error occurred while attempting to fetch data: {error}")

ne_loader-0.2.1.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: ne-loader
+Version: 0.2.1
+Summary: A simple loader for Natural Earth map data.
+Author-email: Eric Tunn <erictunn@icloud.com>
+Project-URL: Homepage, https://github.com/erictunn/ne-loader
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: geopandas>=0.12
+Requires-Dist: platformdirs>=4
+Requires-Dist: requests>=2.25
+
+# NE Loader
+
+A simple, robust Python package to download and load Natural Earth map data using GeoPandas.
+
+## Features
+
+- Download and cache Natural Earth datasets
+- Load shapefiles as GeoDataFrames
+
+## Installation
+
+```bash
+pip install ne-loader
+```
+
+## Usage
+
+```python
+from ne_loader import map_loader
+world = map_loader.get_natural_earth('cultural', 'admin_0_countries')
+```
+
+## CLI
+
+```bash
+ne-loader --help
+```
+
+To set an environment override for the NE data save path:
+
+```bash
+export NATURAL_EARTH_CACHE_DIR="..."
+```
+
+## Tests
+
+```bash
+python3 -m pytest tests/test_map_loader.py
+```
+
+## License
+
+MIT

ne_loader-0.2.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+ne_loader/__init__.py,sha256=IyFStSqzurEnHsWbr6oaINAptDDkZdLzR6XC20o5ADc,31
+ne_loader/cacher.py,sha256=UDslouaxYNIacEUb9Tk9cnFtxeeREBDrzvsSoMWT_AY,1015
+ne_loader/cli.py,sha256=ViZzCzTPS9Lgf-N5zkc_ugVYOZyE-6xBtjf6Bd3zzMM,1021
+ne_loader/map_loader.py,sha256=mW2PmRjNpAlfSbE5QJCt7lPCJ_5cXt0WlY6W6uJLu-s,4256
+ne_loader-0.2.1.dist-info/METADATA,sha256=ycbwPkB4DMotS-SWyThAGym0a7ZjIK6HvYeUaNavewc,978
+ne_loader-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ne_loader-0.2.1.dist-info/entry_points.txt,sha256=lfC4UxVdYCouf-dRbZ8W3L6MMn_1LTDiedybSGDb9Ws,49
+ne_loader-0.2.1.dist-info/top_level.txt,sha256=lnHLytilCj9bNbVduIlhzJunYyjDkUpl8aYutmjG--I,10
+ne_loader-0.2.1.dist-info/RECORD,,

ne_loader-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ne_loader-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ne-loader = ne_loader.cli:main

ne_loader-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+ne_loader