nmtc-mapper 0.3.2__tar.gz → 0.3.4__tar.gz

{nmtc_mapper-0.3.2 → nmtc_mapper-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nmtc-mapper
-Version: 0.3.2
+Version: 0.3.4
 Summary: Automated NMTC eligibility checker — geocode addresses and check Low-Income Community status using CDFI Fund and Census data
 License: MIT
 Project-URL: Homepage, https://github.com/Jaypatel1511/nmtc-mapper
@@ -13,6 +13,8 @@ Requires-Dist: numpy>=1.21.0
 Requires-Dist: requests>=2.27.0
 Requires-Dist: openpyxl>=3.1.0
 Requires-Dist: pyxlsb>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
 
 # nmtc-mapper 🗺️
 
@@ -70,6 +72,44 @@ get results in seconds, using the same official data source.
 
 ---
 
+## Failure behavior & offline / demo mode
+
+`NMTCMapper()` downloads the official CDFI Fund eligibility and Opportunity Zone
+files (cached under `~/.nmtcmapper/cache`). As of **0.3.4** it **fails loud**: if
+a download or parse fails, it raises a typed error instead of silently
+substituting demo data. (Before 0.3.4 any failure silently fell back to a
+12-tract synthetic sample, which could report a real, eligible tract as
+"ineligible" — see the CHANGELOG.)
+
+    from nmtcmapper import NMTCMapper, NMTCMapperError
+
+    try:
+        mapper = NMTCMapper()
+    except NMTCMapperError as e:
+        # Blocked network, moved URL, corrupt file, etc. — never a fabricated answer.
+        print(f"Could not load real NMTC data: {e}")
+        raise
+
+The exception hierarchy (`NMTCMapperError` → `EligibilityDataError` /
+`OZDataError` → specific `*DownloadError` / `*ParseError` leaves) is exported
+from the top level, so you can catch broadly or precisely.
+
+**Explicit demo / offline data** — for examples, tests, or an air-gapped demo,
+opt in to the synthetic sample dataset. This performs **no network calls** and
+stamps the mapper so you can tell demo answers from real ones:
+
+    from nmtcmapper import NMTCMapper, load_sample_table
+
+    mapper = NMTCMapper.from_sample()   # 12 sample tracts + 6 OZ tracts, offline
+    print(mapper.data_source)           # "sample"   (real data → "cdfi_fund")
+
+    df = load_sample_table()            # the raw 12-tract sample frame
+
+> ⚠️ Sample data is 12 synthetic-vintage tracts for demos and tests. It is
+> **never** valid for a real NMTC eligibility answer.
+
+---
+
 ## Eligibility Rules (2016-2020 ACS — mandatory since Sept 1, 2024)
 
 A census tract qualifies as a Low-Income Community (LIC) if it meets ANY of:
@@ -115,7 +155,8 @@ After running .enrich(), your DataFrame will have:
 
     PYTHONPATH=. pytest tests/ -v
 
-24 tests across all modules.
+44 tests across all modules (including fail-loud and explicit-sample-mode
+coverage added in 0.3.4).
 
 ---
 

{nmtc_mapper-0.3.2 → nmtc_mapper-0.3.4}/README.md

@@ -54,6 +54,44 @@ get results in seconds, using the same official data source.
 
 ---
 
+## Failure behavior & offline / demo mode
+
+`NMTCMapper()` downloads the official CDFI Fund eligibility and Opportunity Zone
+files (cached under `~/.nmtcmapper/cache`). As of **0.3.4** it **fails loud**: if
+a download or parse fails, it raises a typed error instead of silently
+substituting demo data. (Before 0.3.4 any failure silently fell back to a
+12-tract synthetic sample, which could report a real, eligible tract as
+"ineligible" — see the CHANGELOG.)
+
+    from nmtcmapper import NMTCMapper, NMTCMapperError
+
+    try:
+        mapper = NMTCMapper()
+    except NMTCMapperError as e:
+        # Blocked network, moved URL, corrupt file, etc. — never a fabricated answer.
+        print(f"Could not load real NMTC data: {e}")
+        raise
+
+The exception hierarchy (`NMTCMapperError` → `EligibilityDataError` /
+`OZDataError` → specific `*DownloadError` / `*ParseError` leaves) is exported
+from the top level, so you can catch broadly or precisely.
+
+**Explicit demo / offline data** — for examples, tests, or an air-gapped demo,
+opt in to the synthetic sample dataset. This performs **no network calls** and
+stamps the mapper so you can tell demo answers from real ones:
+
+    from nmtcmapper import NMTCMapper, load_sample_table
+
+    mapper = NMTCMapper.from_sample()   # 12 sample tracts + 6 OZ tracts, offline
+    print(mapper.data_source)           # "sample"   (real data → "cdfi_fund")
+
+    df = load_sample_table()            # the raw 12-tract sample frame
+
+> ⚠️ Sample data is 12 synthetic-vintage tracts for demos and tests. It is
+> **never** valid for a real NMTC eligibility answer.
+
+---
+
 ## Eligibility Rules (2016-2020 ACS — mandatory since Sept 1, 2024)
 
 A census tract qualifies as a Low-Income Community (LIC) if it meets ANY of:
@@ -99,7 +137,8 @@ After running .enrich(), your DataFrame will have:
 
     PYTHONPATH=. pytest tests/ -v
 
-24 tests across all modules.
+44 tests across all modules (including fail-loud and explicit-sample-mode
+coverage added in 0.3.4).
 
 ---
 

{nmtc_mapper-0.3.2 → nmtc_mapper-0.3.4}/nmtc_mapper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nmtc-mapper
-Version: 0.3.2
+Version: 0.3.4
 Summary: Automated NMTC eligibility checker — geocode addresses and check Low-Income Community status using CDFI Fund and Census data
 License: MIT
 Project-URL: Homepage, https://github.com/Jaypatel1511/nmtc-mapper
@@ -13,6 +13,8 @@ Requires-Dist: numpy>=1.21.0
 Requires-Dist: requests>=2.27.0
 Requires-Dist: openpyxl>=3.1.0
 Requires-Dist: pyxlsb>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
 
 # nmtc-mapper 🗺️
 
@@ -70,6 +72,44 @@ get results in seconds, using the same official data source.
 
 ---
 
+## Failure behavior & offline / demo mode
+
+`NMTCMapper()` downloads the official CDFI Fund eligibility and Opportunity Zone
+files (cached under `~/.nmtcmapper/cache`). As of **0.3.4** it **fails loud**: if
+a download or parse fails, it raises a typed error instead of silently
+substituting demo data. (Before 0.3.4 any failure silently fell back to a
+12-tract synthetic sample, which could report a real, eligible tract as
+"ineligible" — see the CHANGELOG.)
+
+    from nmtcmapper import NMTCMapper, NMTCMapperError
+
+    try:
+        mapper = NMTCMapper()
+    except NMTCMapperError as e:
+        # Blocked network, moved URL, corrupt file, etc. — never a fabricated answer.
+        print(f"Could not load real NMTC data: {e}")
+        raise
+
+The exception hierarchy (`NMTCMapperError` → `EligibilityDataError` /
+`OZDataError` → specific `*DownloadError` / `*ParseError` leaves) is exported
+from the top level, so you can catch broadly or precisely.
+
+**Explicit demo / offline data** — for examples, tests, or an air-gapped demo,
+opt in to the synthetic sample dataset. This performs **no network calls** and
+stamps the mapper so you can tell demo answers from real ones:
+
+    from nmtcmapper import NMTCMapper, load_sample_table
+
+    mapper = NMTCMapper.from_sample()   # 12 sample tracts + 6 OZ tracts, offline
+    print(mapper.data_source)           # "sample"   (real data → "cdfi_fund")
+
+    df = load_sample_table()            # the raw 12-tract sample frame
+
+> ⚠️ Sample data is 12 synthetic-vintage tracts for demos and tests. It is
+> **never** valid for a real NMTC eligibility answer.
+
+---
+
 ## Eligibility Rules (2016-2020 ACS — mandatory since Sept 1, 2024)
 
 A census tract qualifies as a Low-Income Community (LIC) if it meets ANY of:
@@ -115,7 +155,8 @@ After running .enrich(), your DataFrame will have:
 
     PYTHONPATH=. pytest tests/ -v
 
-24 tests across all modules.
+44 tests across all modules (including fail-loud and explicit-sample-mode
+coverage added in 0.3.4).
 
 ---
 

{nmtc_mapper-0.3.2 → nmtc_mapper-0.3.4}/nmtc_mapper.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ nmtc_mapper.egg-info/dependency_links.txt
 nmtc_mapper.egg-info/requires.txt
 nmtc_mapper.egg-info/top_level.txt
 nmtcmapper/__init__.py
+nmtcmapper/exceptions.py
 nmtcmapper/mapper.py
 nmtcmapper/data/__init__.py
 nmtcmapper/data/loader.py
@@ -15,8 +16,9 @@ nmtcmapper/eligibility/__init__.py
 nmtcmapper/eligibility/checker.py
 nmtcmapper/geocoder/__init__.py
 nmtcmapper/geocoder/census.py
-tests/__init__.py
-tests/conftest.py
 tests/test_checker.py
+tests/test_exceptions.py
+tests/test_fail_loud.py
 tests/test_loader.py
-tests/test_mapper.py
+tests/test_mapper.py
+tests/test_sample_mode.py

{nmtc_mapper-0.3.2 → nmtc_mapper-0.3.4}/nmtc_mapper.egg-info/requires.txt

@@ -5,3 +5,6 @@ numpy>=1.21.0
 requests>=2.27.0
 openpyxl>=3.1.0
 pyxlsb>=1.0.0
+
+[dev]
+pytest>=7.0

{nmtc_mapper-0.3.2 → nmtc_mapper-0.3.4}/nmtc_mapper.egg-info/top_level.txt

@@ -1,2 +1 @@
 nmtcmapper
-tests

nmtc_mapper-0.3.4/nmtcmapper/__init__.py

@@ -0,0 +1,24 @@
+from nmtcmapper.mapper import NMTCMapper
+from nmtcmapper.eligibility.checker import EligibilityResult
+from nmtcmapper.data.loader import load_eligibility_table, load_sample_table
+from nmtcmapper.geocoder.census import geocode_address
+from nmtcmapper.exceptions import (
+    NMTCMapperError,
+    EligibilityDataError, EligibilityDownloadError, EligibilityParseError,
+    OZDataError, OZDownloadError, OZParseError,
+)
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("nmtc-mapper")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "NMTCMapper", "EligibilityResult",
+    "load_eligibility_table", "load_sample_table", "geocode_address",
+    "NMTCMapperError",
+    "EligibilityDataError", "EligibilityDownloadError", "EligibilityParseError",
+    "OZDataError", "OZDownloadError", "OZParseError",
+]

{nmtc_mapper-0.3.2 → nmtc_mapper-0.3.4}/nmtcmapper/data/loader.py

@@ -7,6 +7,10 @@ import requests
 import pandas as pd
 from pathlib import Path
 
+from nmtcmapper.exceptions import (
+    EligibilityDataError, EligibilityDownloadError, EligibilityParseError,
+    OZDataError, OZDownloadError, OZParseError,
+)
 from nmtcmapper.data.schema import (
     CACHE_DIR, CDFI_FUND_LIC_URL_2020,
     ELIGIBILITY_FILE_COLUMNS,
@@ -37,33 +41,68 @@ def download_eligibility_file(force: bool = False) -> Path:
         print(f"Using cached eligibility file: {path}")
         return path
     print("Downloading NMTC eligibility file from CDFI Fund...")
+    # Stream to a .part temp and atomically rename on success, so a mid-stream
+    # failure can never leave a truncated file at the final cache path (which
+    # would make every later run parse-fail on poisoned cache).
+    tmp = path.with_suffix(path.suffix + ".part")
     try:
         response = requests.get(CDFI_FUND_LIC_URL_2020, stream=True, timeout=120)
         response.raise_for_status()
-        with open(path, "wb") as f:
+        with open(tmp, "wb") as f:
             for chunk in response.iter_content(chunk_size=8192):
                 f.write(chunk)
+        tmp.replace(path)
         print(f"Saved to {path}")
         return path
-    except Exception as e:
-        print(f"Download failed: {e}")
-        return None
+    except requests.exceptions.HTTPError as e:
+        tmp.unlink(missing_ok=True)
+        status = getattr(e.response, "status_code", None)
+        if status == 404:
+            reason = "not found (404) — the CDFI Fund file path may have moved"
+        elif status == 403:
+            reason = "access blocked (403 Forbidden)"
+        else:
+            reason = f"HTTP {status}"
+        raise EligibilityDownloadError(
+            f"Failed to download NMTC eligibility file from "
+            f"{CDFI_FUND_LIC_URL_2020}: {reason}"
+        ) from e
+    except requests.exceptions.RequestException as e:
+        tmp.unlink(missing_ok=True)
+        raise EligibilityDownloadError(
+            f"Failed to download NMTC eligibility file from "
+            f"{CDFI_FUND_LIC_URL_2020}: connection/DNS/timeout error "
+            f"({type(e).__name__}: {e})"
+        ) from e
 
 
 def load_eligibility_table(force: bool = False) -> pd.DataFrame:
     path = download_eligibility_file(force=force)
     if path is None or not path.exists():
-        print("Using built-in sample eligibility data.")
-        return _build_sample_table()
+        # download_eligibility_file now raises on any download failure, so a
+        # missing file here means the download step was skipped and no local
+        # copy exists. Fail loud — never substitute demo data (F2).
+        raise EligibilityDownloadError(
+            f"No eligibility file available at "
+            f"{_cache_path('NMTC_LIC_Eligibility_2016_2020.xlsb')} and no download "
+            f"was performed."
+        )
     print(f"Loading eligibility table from {path}...")
     try:
         if path.suffix == ".xlsb":
             return _load_xlsb_table(path)
         df = pd.read_excel(path, dtype=str)
         return _process_eligibility_table(df)
+    except EligibilityDataError:
+        raise
+    except ImportError:
+        # Missing optional engine (e.g. pyxlsb) — its own message is actionable
+        # and is a dependency problem, not a corrupt-file problem. Don't mask it.
+        raise
     except Exception as e:
-        print(f"Error loading file: {e}. Using sample data.")
-        return _build_sample_table()
+        raise EligibilityParseError(
+            f"Failed to parse eligibility file {path}: {type(e).__name__}: {e}"
+        ) from e
 
 
 def _load_xlsb_table(path: Path) -> pd.DataFrame:
@@ -193,7 +232,16 @@ def _compute_eligibility(df: pd.DataFrame) -> pd.DataFrame:
     return df
 
 
-def _build_sample_table() -> pd.DataFrame:
+def load_sample_table() -> pd.DataFrame:
+    """Build the 12-tract synthetic demo table — an EXPLICIT opt-in only.
+
+    WARNING: this is 12 synthetic-vintage tracts for demos, examples, and tests.
+    It is NEVER valid for a real NMTC eligibility answer. Before 0.3.4 this table
+    was substituted silently whenever a download or parse failed, fabricating
+    'ineligible' results for real tracts; that path is gone. Use it only through
+    ``load_sample_table()`` or ``NMTCMapper.from_sample()`` when you knowingly
+    want demo data with ``data_source == "sample"``.
+    """
     sample_tracts = [
         ("17031840100", 0.38, 0.55, 0.12, False, False, False),
         ("17031839100", 0.42, 0.48, 0.15, False, False, False),
@@ -226,6 +274,11 @@ def _build_sample_table() -> pd.DataFrame:
     return df
 
 
+# Backwards-compatible alias: the examples/ notebook imports the private name.
+# Kept intentionally so that existing imports keep working after the F4 rename.
+_build_sample_table = load_sample_table
+
+
 # ── Opportunity Zone lookup ───────────────────────────────────────────────────
 
 def load_opportunity_zones(force: bool = False) -> set:
@@ -236,24 +289,44 @@ def load_opportunity_zones(force: bool = False) -> set:
     Source: CDFI Fund designated-qozs.12.14.18.xlsx (8,764 tracts).
     Sheet "QOZs 14Jun", header on row 5 (index 4),
     tract FIPS in column "Census Tract Number".
-    Falls back to a known sample set if download fails.
+    Raises OZDownloadError / OZParseError on any failure — never falls back.
     """
+    from nmtcmapper.data.schema import OZ_URL_2018
+
     filename = "QOZ_Designated_2018.xlsx"
     path = _cache_path(filename)
 
     if not path.exists() or force:
+        # Same atomic .part-then-rename pattern as download_eligibility_file —
+        # a mid-stream failure must never poison the final cache path.
+        tmp = path.with_suffix(path.suffix + ".part")
         try:
-            from nmtcmapper.data.schema import OZ_URL_2018
             print("Downloading Opportunity Zone tract list...")
             response = requests.get(OZ_URL_2018, stream=True, timeout=60)
             response.raise_for_status()
-            with open(path, "wb") as f:
+            with open(tmp, "wb") as f:
                 for chunk in response.iter_content(chunk_size=8192):
                     f.write(chunk)
+            tmp.replace(path)
             print(f"Saved to {path}")
-        except Exception as e:
-            print(f"OZ download failed: {e}. Using sample OZ data.")
-            return _sample_oz_tracts()
+        except requests.exceptions.HTTPError as e:
+            tmp.unlink(missing_ok=True)
+            status = getattr(e.response, "status_code", None)
+            if status == 404:
+                reason = "not found (404) — the OZ file path may have moved"
+            elif status == 403:
+                reason = "access blocked (403 Forbidden)"
+            else:
+                reason = f"HTTP {status}"
+            raise OZDownloadError(
+                f"Failed to download Opportunity Zone file from {OZ_URL_2018}: {reason}"
+            ) from e
+        except requests.exceptions.RequestException as e:
+            tmp.unlink(missing_ok=True)
+            raise OZDownloadError(
+                f"Failed to download Opportunity Zone file from {OZ_URL_2018}: "
+                f"connection/DNS/timeout error ({type(e).__name__}: {e})"
+            ) from e
 
     try:
         df = pd.read_excel(
@@ -269,15 +342,27 @@ def load_opportunity_zones(force: bool = False) -> set:
                 tracts = set(df[col].dropna().str.strip().str.zfill(11).tolist())
                 print(f"Loaded {len(tracts):,} Opportunity Zone tracts")
                 return tracts
-        print("OZ file parse error: tract column not found. Using sample data.")
+    except OZDataError:
+        raise
     except Exception as e:
-        print(f"OZ file parse error: {e}. Using sample data.")
-
-    return _sample_oz_tracts()
+        raise OZParseError(
+            f"Failed to parse Opportunity Zone file {path}: {type(e).__name__}: {e}"
+        ) from e
+
+    # File parsed, but none of the known tract columns were present — fail loud
+    # rather than degrade to the 6-tract sample (F3).
+    raise OZParseError(
+        f"Opportunity Zone file {path} parsed but no tract column was found "
+        f"(looked for CENSUS TRACT NUMBER / GEOID / CENSUS_TRACT / TRACT_ID / TRACT)."
+    )
 
 
 def _sample_oz_tracts() -> set:
-    """Known OZ tracts for testing — subset of real designations."""
+    """6 known OZ tracts — EXPLICIT opt-in only (used by NMTCMapper.from_sample()).
+
+    As of 0.3.4 this is never reached from a download/parse failure path; OZ
+    failures raise OZDownloadError / OZParseError instead of degrading to this set.
+    """
     return {
         "17031840100",  # Chicago South Side
         "17031839100",  # Chicago West Side

nmtc_mapper-0.3.4/nmtcmapper/exceptions.py

@@ -0,0 +1,66 @@
+"""
+Typed exception hierarchy for nmtc-mapper (F1, added 0.3.4).
+
+Before 0.3.4 the loader silently substituted a synthetic sample dataset on ANY
+download or parse failure, so a blocked network or a corrupt file produced a
+*fabricated* eligibility answer with no signal to the caller. These exceptions
+replace that behavior: every data-acquisition failure now raises, and the
+message names the URL attempted and distinguishes access-blocked (403 /
+connection / DNS) from not-found (404) from parse — so a caught error can never
+be mistaken for a different problem (the HMDA 0.3.1 lesson: a typed error with a
+misleading message misdirects just as badly as a swallowed one).
+
+    NMTCMapperError
+    ├─ EligibilityDataError
+    │  ├─ EligibilityDownloadError   # 403 / 404 / DNS / timeout / connection
+    │  └─ EligibilityParseError      # corrupt / wrong content-type / missing sheet / bad zip
+    └─ OZDataError
+       ├─ OZDownloadError
+       └─ OZParseError
+
+Downstream code can catch at any level: `except NMTCMapperError` for anything,
+`except EligibilityDataError` for eligibility-only, or a specific leaf.
+"""
+
+
+class NMTCMapperError(Exception):
+    """Base class for every error raised by nmtc-mapper."""
+
+
+class EligibilityDataError(NMTCMapperError):
+    """The CDFI Fund NMTC eligibility dataset could not be obtained."""
+
+
+class EligibilityDownloadError(EligibilityDataError):
+    """Could not download the eligibility file (403 / 404 / DNS / timeout / connection),
+    and no usable cached copy was available."""
+
+
+class EligibilityParseError(EligibilityDataError):
+    """The eligibility file was obtained but could not be parsed
+    (corrupt bytes, wrong content-type / HTML error page, missing sheet, bad zip)."""
+
+
+class OZDataError(NMTCMapperError):
+    """The Opportunity Zone designation dataset could not be obtained."""
+
+
+class OZDownloadError(OZDataError):
+    """Could not download the Opportunity Zone file (403 / 404 / DNS / timeout / connection),
+    and no usable cached copy was available."""
+
+
+class OZParseError(OZDataError):
+    """The Opportunity Zone file was obtained but could not be parsed
+    (corrupt bytes, wrong content-type, missing sheet / tract column, bad zip)."""
+
+
+__all__ = [
+    "NMTCMapperError",
+    "EligibilityDataError",
+    "EligibilityDownloadError",
+    "EligibilityParseError",
+    "OZDataError",
+    "OZDownloadError",
+    "OZParseError",
+]

{nmtc_mapper-0.3.2 → nmtc_mapper-0.3.4}/nmtcmapper/mapper.py

@@ -4,7 +4,10 @@ NMTCMapper — main public API for NMTC eligibility checking.
 import pandas as pd
 from typing import Optional
 
-from nmtcmapper.data.loader import load_eligibility_table, load_opportunity_zones
+from nmtcmapper.data.loader import (
+    load_eligibility_table, load_opportunity_zones,
+    load_sample_table, _sample_oz_tracts,
+)
 from nmtcmapper.geocoder.census import geocode_address, geocode_batch
 from nmtcmapper.eligibility.checker import (
     check_tract, enrich_dataframe, EligibilityResult
@@ -32,7 +35,12 @@ class NMTCMapper:
 
     def __init__(self, force_reload: bool = False):
         """
-        Initialize NMTCMapper and load the eligibility table.
+        Initialize NMTCMapper against the real CDFI Fund data.
+
+        Raises on any download or parse failure (EligibilityDownloadError /
+        EligibilityParseError / OZDownloadError / OZParseError) rather than
+        silently substituting demo data. For offline demos/tests, use the
+        explicit ``NMTCMapper.from_sample()`` constructor instead.
 
         Args:
             force_reload: Re-download the eligibility file even if cached
@@ -42,6 +50,29 @@ class NMTCMapper:
         print(f"Ready. {len(self._table):,} census tracts loaded.")
         self._oz_tracts = load_opportunity_zones()
         print(f"Opportunity Zones loaded: {len(self._oz_tracts):,} tracts")
+        self.data_source = "cdfi_fund"
+
+    @classmethod
+    def from_sample(cls) -> "NMTCMapper":
+        """
+        Construct a mapper on the built-in synthetic sample data — no network.
+
+        WARNING: the sample is 12 synthetic-vintage tracts (+ 6 OZ tracts) for
+        demos, examples, and tests. It is NEVER valid for a real NMTC eligibility
+        answer. The resulting mapper is stamped ``data_source == "sample"`` so
+        downstream code can assert provenance. Use ``NMTCMapper()`` for real data.
+        """
+        obj = cls.__new__(cls)
+        obj._table = load_sample_table()
+        obj._oz_tracts = _sample_oz_tracts()
+        obj.data_source = "sample"
+        return obj
+
+    def __repr__(self) -> str:
+        return (
+            f"NMTCMapper(data_source={self.data_source!r}, "
+            f"tracts={len(self._table):,}, oz_tracts={len(self._oz_tracts):,})"
+        )
 
     def check_address(self, address: str) -> EligibilityResult:
         """

{nmtc_mapper-0.3.2 → nmtc_mapper-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nmtc-mapper"
-version = "0.3.2"
+version = "0.3.4"
 description = "Automated NMTC eligibility checker — geocode addresses and check Low-Income Community status using CDFI Fund and Census data"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -19,5 +19,15 @@ dependencies = [
     "pyxlsb>=1.0.0",
 ]
 
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
 [project.urls]
 Homepage = "https://github.com/Jaypatel1511/nmtc-mapper"
+
+# Explicit discovery: the repo root also contains a generated `site/` (mkdocs
+# output) and `docs/`, `examples/` dirs. With the setup.py pin removed, build-time
+# auto-discovery would error on multiple top-level candidates — pin it to the
+# real package. (find_packages() in the old setup.py did this implicitly.)
+[tool.setuptools.packages.find]
+include = ["nmtcmapper*"]

nmtc_mapper-0.3.4/setup.py

@@ -0,0 +1,6 @@
+# Shim retained for `pip install -e .` and legacy tooling only.
+# All package metadata — including the authoritative version — lives in
+# pyproject.toml ([project]). Do not re-add a version or dependency pin here.
+from setuptools import setup
+
+setup()

nmtc_mapper-0.3.4/tests/test_exceptions.py

@@ -0,0 +1,47 @@
+"""Typed exception hierarchy (F1) — importable from the package top level,
+with the inheritance contract downstream catch-blocks will rely on."""
+import pytest
+
+
+def test_exceptions_importable_from_top_level():
+    from nmtcmapper import (
+        NMTCMapperError,
+        EligibilityDataError, EligibilityDownloadError, EligibilityParseError,
+        OZDataError, OZDownloadError, OZParseError,
+    )
+    assert issubclass(NMTCMapperError, Exception)
+
+
+def test_eligibility_hierarchy():
+    from nmtcmapper import (
+        NMTCMapperError, EligibilityDataError,
+        EligibilityDownloadError, EligibilityParseError,
+    )
+    assert issubclass(EligibilityDataError, NMTCMapperError)
+    assert issubclass(EligibilityDownloadError, EligibilityDataError)
+    assert issubclass(EligibilityParseError, EligibilityDataError)
+    # download and parse are siblings, not each other
+    assert not issubclass(EligibilityDownloadError, EligibilityParseError)
+
+
+def test_oz_hierarchy():
+    from nmtcmapper import (
+        NMTCMapperError, OZDataError, OZDownloadError, OZParseError,
+    )
+    assert issubclass(OZDataError, NMTCMapperError)
+    assert issubclass(OZDownloadError, OZDataError)
+    assert issubclass(OZParseError, OZDataError)
+    assert not issubclass(OZDownloadError, OZParseError)
+
+
+def test_a_single_except_catches_every_data_error():
+    """The whole point: one `except NMTCMapperError` catches all six leaves."""
+    from nmtcmapper import (
+        NMTCMapperError,
+        EligibilityDownloadError, EligibilityParseError,
+        OZDownloadError, OZParseError,
+    )
+    for exc in (EligibilityDownloadError, EligibilityParseError,
+                OZDownloadError, OZParseError):
+        with pytest.raises(NMTCMapperError):
+            raise exc("boom")

nmtc_mapper-0.3.4/tests/test_fail_loud.py

@@ -0,0 +1,189 @@
+"""F2/F3 — fail loud, never fabricate.
+
+Every eligibility/OZ download or parse failure must RAISE a typed error instead
+of silently returning a synthetic sample (0.3.3 behavior — see repro evidence in
+the 0.3.4 changelog). These are the negative-case tests: under 0.3.3 each returns
+a fabricated frame/set; under 0.3.4 each raises.
+"""
+import pytest
+import requests
+
+import nmtcmapper.data.loader as loader
+from nmtcmapper.data.loader import load_eligibility_table, load_opportunity_zones
+from nmtcmapper import (
+    NMTCMapper,
+    EligibilityDownloadError, EligibilityParseError,
+    OZDownloadError, OZParseError,
+)
+
+ELIG_FILENAME = "NMTC_LIC_Eligibility_2016_2020.xlsb"
+OZ_FILENAME = "QOZ_Designated_2018.xlsx"
+
+
+@pytest.fixture
+def isolated_cache(tmp_path, monkeypatch):
+    """Point the loader at an empty cache dir so no real cached file interferes."""
+    monkeypatch.setattr(loader, "CACHE_DIR", str(tmp_path))
+    return tmp_path
+
+
+def _block_network(monkeypatch, exc=None):
+    def _boom(*a, **k):
+        raise exc or requests.exceptions.ConnectionError(
+            "simulated blocked egress / DNS failure"
+        )
+    monkeypatch.setattr(loader.requests, "get", _boom)
+
+
+# ── Eligibility ───────────────────────────────────────────────────────────────
+
+def test_download_failure_raises(isolated_cache, monkeypatch):
+    _block_network(monkeypatch)
+    with pytest.raises(EligibilityDownloadError):
+        load_eligibility_table(force=True)
+
+
+def test_download_failure_mapper_constructor_raises(isolated_cache, monkeypatch):
+    _block_network(monkeypatch)
+    with pytest.raises(EligibilityDownloadError):
+        NMTCMapper()
+
+
+def test_corrupt_file_raises(isolated_cache):
+    (isolated_cache / ELIG_FILENAME).write_bytes(b"\x00\x01\x02 not a zip garbage")
+    with pytest.raises(EligibilityParseError):
+        load_eligibility_table(force=False)
+
+
+def test_html_error_page_raises(isolated_cache):
+    # A 403/404 HTML error page saved under the .xlsb name (a real CDN failure mode).
+    (isolated_cache / ELIG_FILENAME).write_bytes(
+        b"<!DOCTYPE html><html><body><h1>403 Forbidden</h1></body></html>"
+    )
+    with pytest.raises(EligibilityParseError):
+        load_eligibility_table(force=False)
+
+
+def test_old_sample_on_failure_now_raises(isolated_cache, monkeypatch):
+    """The explicit old-behavior guard: blocked egress raises, and crucially NO
+    12-row sample frame is returned in its place."""
+    _block_network(monkeypatch)
+    sentinel = object()
+    returned = sentinel
+    with pytest.raises(EligibilityDownloadError):
+        returned = load_eligibility_table(force=True)
+    # Nothing escaped the raise — in particular, not a fabricated 12-tract frame.
+    assert returned is sentinel
+
+
+# ── Opportunity Zones ─────────────────────────────────────────────────────────
+
+def test_oz_download_failure_raises(isolated_cache, monkeypatch):
+    _block_network(monkeypatch)
+    with pytest.raises(OZDownloadError):
+        load_opportunity_zones(force=True)
+
+
+def test_oz_parse_failure_raises(isolated_cache):
+    (isolated_cache / OZ_FILENAME).write_bytes(b"not a real xlsx \x00\x01 garbage")
+    with pytest.raises(OZParseError):
+        load_opportunity_zones(force=False)
+
+
+class _DroppingResponse:
+    """Mocks a download whose connection drops mid-stream after one chunk."""
+    def raise_for_status(self):
+        pass
+
+    def iter_content(self, chunk_size=8192):
+        yield b"PARTIAL_CONTENT_" * 512
+        raise requests.exceptions.ChunkedEncodingError("connection dropped mid-stream")
+
+
+def test_partial_download_cleanup_and_retry(isolated_cache, monkeypatch):
+    """H2: a mid-stream download failure must raise the typed download error AND
+    leave nothing at the final cache path (no poisoned partial file, no .part
+    temp) so the next attempt re-downloads instead of parse-failing forever."""
+    monkeypatch.setattr(loader.requests, "get", lambda *a, **k: _DroppingResponse())
+    with pytest.raises(EligibilityDownloadError):
+        load_eligibility_table(force=True)
+    assert not (isolated_cache / ELIG_FILENAME).exists(), \
+        "partial download left a poisoned file at the final cache path"
+    assert list(isolated_cache.glob("*.part")) == [], ".part temp file left behind"
+
+    # Second attempt: the mock now succeeds. force=False proves no poisoned
+    # cache short-circuits the retry — the loader must actually re-download.
+    payload = b"FULL_CONTENT" * 100
+    calls = []
+
+    class _GoodResponse:
+        def raise_for_status(self):
+            pass
+
+        def iter_content(self, chunk_size=8192):
+            yield payload
+
+    def _good_get(*a, **k):
+        calls.append(1)
+        return _GoodResponse()
+
+    monkeypatch.setattr(loader.requests, "get", _good_get)
+    path = loader.download_eligibility_file(force=False)
+    assert calls, "retry never re-downloaded (a leftover file short-circuited it)"
+    assert path == isolated_cache / ELIG_FILENAME
+    assert path.read_bytes() == payload
+    assert list(isolated_cache.glob("*.part")) == []
+
+
+def test_oz_partial_download_cleanup_and_retry(isolated_cache, monkeypatch):
+    """H2, OZ twin — mid-stream drop raises OZDownloadError with a clean cache,
+    then a successful retry re-downloads and the full load works end-to-end."""
+    import io
+    import openpyxl
+
+    monkeypatch.setattr(loader.requests, "get", lambda *a, **k: _DroppingResponse())
+    with pytest.raises(OZDownloadError):
+        load_opportunity_zones(force=True)
+    assert not (isolated_cache / OZ_FILENAME).exists(), \
+        "partial OZ download left a poisoned file at the final cache path"
+    assert list(isolated_cache.glob("*.part")) == [], ".part temp file left behind"
+
+    # Retry serves a valid OZ workbook -> construction works end-to-end.
+    wb = openpyxl.Workbook()
+    ws = wb.active
+    ws.title = "QOZs 14Jun"
+    for _ in range(4):            # junk rows 1-4; header on row 5 (index 4)
+        ws.append([""])
+    ws.append(["Census Tract Number"])
+    ws.append(["17031840100"])
+    buf = io.BytesIO()
+    wb.save(buf)
+    data = buf.getvalue()
+
+    class _GoodResponse:
+        def raise_for_status(self):
+            pass
+
+        def iter_content(self, chunk_size=8192):
+            yield data
+
+    monkeypatch.setattr(loader.requests, "get", lambda *a, **k: _GoodResponse())
+    oz = load_opportunity_zones(force=False)
+    assert oz == {"17031840100"}
+    assert list(isolated_cache.glob("*.part")) == []
+
+
+def test_oz_missing_tract_column_raises(isolated_cache):
+    """A structurally-valid xlsx whose tract column is absent must raise, not
+    degrade to the 6-tract sample (0.3.3 loader.py:272)."""
+    import openpyxl
+    wb = openpyxl.Workbook()
+    ws = wb.active
+    ws.title = "QOZs 14Jun"
+    for _ in range(4):            # junk rows 1-4; header is on row 5 (index 4)
+        ws.append(["", "", ""])
+    ws.append(["WRONG_COLUMN", "OTHER"])   # header row, no tract column
+    ws.append(["17031840100", "x"])        # a data row
+    wb.save(isolated_cache / OZ_FILENAME)
+    with pytest.raises(OZParseError):
+        load_opportunity_zones(force=False)

nmtc_mapper-0.3.4/tests/test_sample_mode.py

@@ -0,0 +1,56 @@
+"""F4 — explicit sample mode.
+
+Sample data survives only as a deliberate, provenance-marked opt-in. It must
+NEVER be reachable implicitly from a failure path (that's F2/F3), and when used
+explicitly it must (a) require no network, and (b) stamp the mapper so downstream
+code can tell a demo answer from a real one.
+"""
+import pytest
+from nmtcmapper.mapper import NMTCMapper
+
+
+def test_load_sample_table_public():
+    from nmtcmapper import load_sample_table
+    df = load_sample_table()
+    assert len(df) == 12
+    assert df["nmtc_eligible"].any()
+
+
+def test_underscore_alias_preserved_for_notebook():
+    # examples/ notebook imports the private name — keep it working.
+    from nmtcmapper.data.loader import _build_sample_table, load_sample_table
+    assert len(_build_sample_table()) == 12
+    assert _build_sample_table is load_sample_table
+
+
+def test_from_sample_explicit_works(monkeypatch):
+    # The whole contract: zero network. Any requests.get is a hard failure.
+    def _no_network(*a, **k):
+        raise AssertionError("from_sample() must not touch the network")
+    monkeypatch.setattr("nmtcmapper.data.loader.requests.get", _no_network)
+
+    m = NMTCMapper.from_sample()
+    assert m.tract_count == 12
+    assert m.oz_tract_count == 6
+    assert m.data_source == "sample"
+    # sample data still answers the known eligible demo tract
+    assert m.check_tract("17031840100").nmtc_eligible is True
+
+
+def test_data_source_marker(monkeypatch):
+    """Real-path constructor stamps data_source == 'cdfi_fund' (mocked success)."""
+    from nmtcmapper import load_sample_table
+    fake_table = load_sample_table()  # any real-shaped frame stands in for the CDFI download
+    monkeypatch.setattr(
+        "nmtcmapper.mapper.load_eligibility_table", lambda force=False: fake_table
+    )
+    monkeypatch.setattr(
+        "nmtcmapper.mapper.load_opportunity_zones", lambda force=False: {"17031840100"}
+    )
+    m = NMTCMapper()
+    assert m.data_source == "cdfi_fund"
+
+
+def test_data_source_surfaced_in_repr():
+    m = NMTCMapper.from_sample()
+    assert "sample" in repr(m).lower()

nmtc_mapper-0.3.2/nmtcmapper/__init__.py

@@ -1,10 +0,0 @@
-from nmtcmapper.mapper import NMTCMapper
-from nmtcmapper.eligibility.checker import EligibilityResult
-from nmtcmapper.data.loader import load_eligibility_table
-from nmtcmapper.geocoder.census import geocode_address
-
-__version__ = "0.1.0"
-__all__ = [
-    "NMTCMapper", "EligibilityResult",
-    "load_eligibility_table", "geocode_address",
-]

nmtc_mapper-0.3.2/setup.py

@@ -1,15 +0,0 @@
-from setuptools import setup, find_packages
-
-setup(
-    name="nmtc-mapper",
-    version="0.3.0",
-    packages=find_packages(),
-    install_requires=[
-        "pandas>=1.4.0",
-        "numpy>=1.21.0",
-        "requests>=2.27.0",
-        "aiohttp>=3.8.0",
-        "tqdm>=4.64.0",
-        "openpyxl>=3.0.0",
-    ],
-)

nmtc_mapper-0.3.2/tests/conftest.py

@@ -1,37 +0,0 @@
-import pytest
-import pandas as pd
-from nmtcmapper.data.loader import _build_sample_table
-from nmtcmapper.mapper import NMTCMapper
-
-
-@pytest.fixture
-def sample_table():
-    return _build_sample_table()
-
-
-@pytest.fixture
-def mapper(monkeypatch):
-    """NMTCMapper with sample data — no real download."""
-    monkeypatch.setattr(
-        "nmtcmapper.data.loader.download_eligibility_file",
-        lambda force=False: None
-    )
-    return NMTCMapper()
-
-
-@pytest.fixture
-def sample_df():
-    return pd.DataFrame({
-        "project_name": [
-            "Southside Health Center",
-            "North Shore Office",
-            "Detroit Manufacturing",
-            "NYC Bronx Project",
-        ],
-        "tract_id": [
-            "17031840100",  # Chicago South Side — eligible
-            "17031010100",  # Chicago North Shore — not eligible
-            "26163518300",  # Detroit — eligible
-            "36061015900",  # NYC Bronx — eligible
-        ]
-    })