ne-loader 0.3__tar.gz → 0.3.2__tar.gz

{ne_loader-0.3 → ne_loader-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ne-loader
-Version: 0.3
+Version: 0.3.2
 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
@@ -32,6 +32,16 @@ from ne_loader import map_loader
 world = map_loader.get_natural_earth('cultural', 'admin_0_countries')
 ```
 
+Errors are raised by default. To return the caught exception instead:
+
+```python
+result = map_loader.get_natural_earth(
+    'cultural',
+    'admin_0_countries',
+    error_mode='return',
+)
+```
+
 ## CLI
 
 ```bash
@@ -47,7 +57,7 @@ export NATURAL_EARTH_CACHE_DIR="..."
 ## Tests
 
 ```bash
-python3 -m pytest tests/test_map_loader.py
+python3 -m pytest tests
 ```
 
 ## License

{ne_loader-0.3 → ne_loader-0.3.2}/README.md

@@ -20,6 +20,16 @@ from ne_loader import map_loader
 world = map_loader.get_natural_earth('cultural', 'admin_0_countries')
 ```
 
+Errors are raised by default. To return the caught exception instead:
+
+```python
+result = map_loader.get_natural_earth(
+    'cultural',
+    'admin_0_countries',
+    error_mode='return',
+)
+```
+
 ## CLI
 
 ```bash
@@ -35,7 +45,7 @@ export NATURAL_EARTH_CACHE_DIR="..."
 ## Tests
 
 ```bash
-python3 -m pytest tests/test_map_loader.py
+python3 -m pytest tests
 ```
 
 ## License

{ne_loader-0.3 → ne_loader-0.3.2}/pyproject.toml

@@ -7,7 +7,7 @@ where = ["src"]
 
 [project]
 name = "ne-loader"
-version = "0.3"
+version = "0.3.2"
 description = "A simple loader for Natural Earth map data."
 authors = [
     { name = "Eric Tunn", email = "erictunn@icloud.com" }

ne_loader-0.3.2/src/ne_loader/__init__.py

@@ -0,0 +1,4 @@
+"""Natural Earth Loader package.
+
+See map_loader.py for public API entrypoint.
+"""

{ne_loader-0.3 → ne_loader-0.3.2}/src/ne_loader/cli.py

@@ -12,16 +12,20 @@ def main() -> None:
     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(
+        "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,
+        category=args.category,
+        name=args.name,
+        res=args.res,
     )
     if args.out:
         gdf.to_file(args.out, driver="GeoJSON")
@@ -29,5 +33,6 @@ def main() -> None:
     else:
         print(gdf.head())
 
+
 if __name__ == "__main__":
     main()

{ne_loader-0.3 → ne_loader-0.3.2}/src/ne_loader/map_loader.py

@@ -1,6 +1,8 @@
 """Handles downloading and fetching of NE data."""
 
+import contextlib
 import logging
+import shutil
 import zipfile
 from pathlib import Path
 from typing import Literal, Optional, Union, overload
@@ -22,7 +24,7 @@ def build_ne_filename(name: str, res: str = "10m", suffix: str = ".zip") -> str:
     return f"ne_{res}_{name}{suffix}"
 
 
-def build_ne_url(category: str, name: str, res: str = "10m") -> str:
+def build_ne_url(category: str, name: str, res: Resolution) -> str:
     """Build the download URL for a Natural Earth vector dataset."""
     return (
         f"https://naciscdn.org/naturalearth/{res}/{category}/"
@@ -30,17 +32,17 @@ def build_ne_url(category: str, name: str, res: str = "10m") -> str:
     )
 
 
-def build_ne_zip_path(data_dir: PathLike, name: str, res: str = "10m") -> Path:
+def build_ne_zip_path(data_dir: PathLike, name: str, res: Resolution) -> 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:
+def build_ne_extract_dir(data_dir: PathLike, name: str, res: Resolution) -> 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:
+def build_ne_shp_path(data_dir: PathLike, name: str, res: Resolution) -> 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")
@@ -51,19 +53,9 @@ def get_natural_earth(
     category: str,
     name: str,
     res: Resolution = "10m",
+    *,
     dir_override: Optional[PathLike] = None,
-    error_mode: Literal["raise"] = "raise",
-    user_logger: Optional[logging.Logger] = None,
-) -> gpd.GeoDataFrame: ...
-
-
-@overload
-def get_natural_earth(
-    category: str,
-    name: str,
-    res: Resolution = "10m",
-    dir_override: Optional[PathLike] = None,
-    error_mode: Literal["ignore"] = "ignore",
+    error_mode: Literal["ignore"],
     user_logger: Optional[logging.Logger] = None,
 ) -> Optional[gpd.GeoDataFrame]: ...
 
@@ -73,10 +65,11 @@ def get_natural_earth(
     category: str,
     name: str,
     res: Resolution = "10m",
+    *,
     dir_override: Optional[PathLike] = None,
-    error_mode: Literal["return"] = "return",
+    error_mode: Literal["raise"] = "raise",
     user_logger: Optional[logging.Logger] = None,
-) -> Union[gpd.GeoDataFrame, Exception]: ...
+) -> gpd.GeoDataFrame: ...
 
 
 @overload
@@ -84,16 +77,18 @@ def get_natural_earth(
     category: str,
     name: str,
     res: Resolution = "10m",
+    *,
     dir_override: Optional[PathLike] = None,
-    error_mode: ErrorMode = "raise",
+    error_mode: Literal["return"],
     user_logger: Optional[logging.Logger] = None,
-) -> Union[gpd.GeoDataFrame, Exception, None]: ...
+) -> Union[gpd.GeoDataFrame, Exception]: ...
 
 
 def get_natural_earth(
     category: str,
     name: str,
     res: Resolution = "10m",
+    *,
     dir_override: Optional[PathLike] = None,
     error_mode: ErrorMode = "raise",
     user_logger: Optional[logging.Logger] = None,
@@ -107,6 +102,8 @@ def get_natural_earth(
             "admin_0_countries".
         res: Natural Earth resolution. "10m", "50m" and "110m" are accepted.
             However, not all datasets will have all 3 resolutions available.
+
+    Keyword Args:
         dir_override: Optional cache directory override. This takes precedence over the
             ``NATURAL_EARTH_CACHE_DIR`` environment variable.
         error_mode: Error handling mode. Default is raise. Upon error:
@@ -122,6 +119,7 @@ def get_natural_earth(
     logger = user_logger or fallback_logger
     try:
         validate_error_mode(error_mode)
+        validate_res(res)
 
         data_dir: Path = get_cache_dir(dir_override)
         data_dir.mkdir(parents=True, exist_ok=True)
@@ -143,10 +141,10 @@ def get_natural_earth(
 
         return gpd.read_file(shp_file)
     except Exception as error:
-        logger.error(f"ne-loader: error caught fetching data with get_natural_earth():"\
-                     f"\n{error}")
-        print(f"ne-loader: error caught fetching data with get_natural_earth():"\
-                     f"\n{error}")
+        logger.error(
+            "ne-loader: error caught fetching data with get_natural_earth():\n",
+            error,
+        )
         return error_handler(error, error_mode)
 
 
@@ -163,7 +161,7 @@ def _download_ne_data(
     if shp_file.exists():
         return
 
-    print(f"ne-loader: Downloading {name} ({res})...")
+    logger.info(f"ne-loader: Downloading {name} ({res})...")
 
     try:
         response: requests.Response = requests.get(url, stream=True, timeout=10)
@@ -176,7 +174,6 @@ def _download_ne_data(
 
         with zipfile.ZipFile(zip_path, "r") as zip_ref:
             zip_ref.extractall(extract_dir)
-        zip_path.unlink()
         return None
 
     except requests.exceptions.HTTPError as error:
@@ -186,7 +183,6 @@ def _download_ne_data(
             "This may cause an error when attempting to load the data.",
             error,
         )
-        print(f"A HTTP error occurred while attempting to fetch data: {error}")
         raise
     except requests.exceptions.RequestException as error:
         logger.error(
@@ -195,5 +191,25 @@ def _download_ne_data(
             "This may cause an error when attempting to load the data.",
             error,
         )
-        print(f"A request error occurred while attempting to fetch data: {error}")
         raise
+
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            zip_path.unlink()
+        if (not shp_file.exists() and
+        extract_dir.name == build_ne_filename(name, res, suffix="")):
+            shutil.rmtree(extract_dir, ignore_errors=True)
+
+def validate_res(res: str) -> None:
+    """Validate the resolution against "10m", "50m", "110m".
+
+    Args:
+        res (Resolution): The resolution to be validated.
+
+    Raises:
+        ValueError: If res is invalid, raises ValueError.
+
+    """
+    if res not in ("10m", "50m", "110m"):
+        raise ValueError(f"Invalid resolution: {res}.\
+                         \nResolution must be one of (\"10m\", \"50m\", \"110m\")")

{ne_loader-0.3 → ne_loader-0.3.2}/src/ne_loader.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ne-loader
-Version: 0.3
+Version: 0.3.2
 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
@@ -32,6 +32,16 @@ from ne_loader import map_loader
 world = map_loader.get_natural_earth('cultural', 'admin_0_countries')
 ```
 
+Errors are raised by default. To return the caught exception instead:
+
+```python
+result = map_loader.get_natural_earth(
+    'cultural',
+    'admin_0_countries',
+    error_mode='return',
+)
+```
+
 ## CLI
 
 ```bash
@@ -47,7 +57,7 @@ export NATURAL_EARTH_CACHE_DIR="..."
 ## Tests
 
 ```bash
-python3 -m pytest tests/test_map_loader.py
+python3 -m pytest tests
 ```
 
 ## License

{ne_loader-0.3 → ne_loader-0.3.2}/tests/test_map_loader.py

@@ -1,12 +1,15 @@
 """Basic tests for map_loader.py constructors."""
 
 from pathlib import Path
+import re
+import pytest
 
 from ne_loader.map_loader import (
     build_ne_filename,
     build_ne_shp_path,
     build_ne_url,
     build_ne_zip_path,
+    validate_res
 )
 
 
@@ -45,3 +48,9 @@ def test_build_ne_shp_path() -> None:
         "/tmp/natural-earth-cache/ne_10m_admin_0_countries/"
         "ne_10m_admin_0_countries.shp"
     )
+
+def test_validate_res() -> None:
+    """Tests that validate_res(res=kaboom) raises the correct ValueError."""
+    with pytest.raises(ValueError, match=re.escape(f"Invalid resolution: kaboom.\
+                         \nResolution must be one of (\"10m\", \"50m\", \"110m\")")):
+        validate_res("kaboom")

ne_loader-0.3/src/ne_loader/__init__.py

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