ne-loader 0.2.1__tar.gz

ne_loader-0.2.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,43 @@
+# 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/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project]
+name = "ne-loader"
+version = "0.2.1"
+description = "A simple loader for Natural Earth map data."
+authors = [
+    { name = "Eric Tunn", email = "erictunn@icloud.com" }
+]
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.8"
+dependencies = [
+    "geopandas>=0.12",
+    "platformdirs>=4",
+    "requests>=2.25"
+]
+
+[project.urls]
+Homepage = "https://github.com/erictunn/ne-loader"
+
+[project.scripts]
+ne-loader = "ne_loader.cli:main"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "D",
+]

ne_loader-0.2.1/setup.cfg

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

ne_loader-0.2.1/src/ne_loader/__init__.py

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

ne_loader-0.2.1/src/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-0.2.1/src/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-0.2.1/src/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/src/ne_loader.egg-info/PKG-INFO

@@ -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/src/ne_loader.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/ne_loader/__init__.py
+src/ne_loader/cacher.py
+src/ne_loader/cli.py
+src/ne_loader/map_loader.py
+src/ne_loader.egg-info/PKG-INFO
+src/ne_loader.egg-info/SOURCES.txt
+src/ne_loader.egg-info/dependency_links.txt
+src/ne_loader.egg-info/entry_points.txt
+src/ne_loader.egg-info/requires.txt
+src/ne_loader.egg-info/top_level.txt
+tests/test_map_loader.py

ne_loader-0.2.1/src/ne_loader.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ne_loader-0.2.1/src/ne_loader.egg-info/entry_points.txt

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

ne_loader-0.2.1/src/ne_loader.egg-info/requires.txt

@@ -0,0 +1,3 @@
+geopandas>=0.12
+platformdirs>=4
+requests>=2.25

ne_loader-0.2.1/src/ne_loader.egg-info/top_level.txt

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

ne_loader-0.2.1/tests/test_map_loader.py

@@ -0,0 +1,47 @@
+"""Basic tests for map_loader.py constructors."""
+
+from pathlib import Path
+
+from ne_loader.map_loader import (
+    build_ne_filename,
+    build_ne_shp_path,
+    build_ne_url,
+    build_ne_zip_path,
+)
+
+
+def test_build_ne_url() -> None:
+    """Tests that the Natural Earth website URL is built correctly."""
+    assert (
+        build_ne_url("cultural", "admin_0_countries", "10m")
+        == "https://naciscdn.org/naturalearth/10m/cultural/"
+        "ne_10m_admin_0_countries.zip"
+    )
+
+
+def test_build_ne_zip_path() -> None:
+    """Tests that the cache zip path builds correctly."""
+    assert build_ne_zip_path(
+        Path("/tmp/natural-earth-cache"),
+        "admin_0_countries",
+        "10m",
+    ) == Path("/tmp/natural-earth-cache/ne_10m_admin_0_countries.zip")
+
+
+def test_build_ne_filename() -> None:
+    """Tests that the Natural Earth data zip file name is built correctly."""
+    assert build_ne_filename("admin_0_countries", "10m") == (
+        "ne_10m_admin_0_countries.zip"
+    )
+
+
+def test_build_ne_shp_path() -> None:
+    """Tests that the path to the .shp file containing NE data is built correctly."""
+    assert build_ne_shp_path(
+        Path("/tmp/natural-earth-cache"),
+        "admin_0_countries",
+        "10m",
+    ) == Path(
+        "/tmp/natural-earth-cache/ne_10m_admin_0_countries/"
+        "ne_10m_admin_0_countries.shp"
+    )