tha-map-runner 0.1.0__py3-none-any.whl

tha_map_runner/__init__.py

@@ -0,0 +1,7 @@
+"""tha-map-runner: join JSON responses into CSV-style rows with dotted-path projection."""
+
+from .errors import MapperError
+from .mapper import enrich_rows
+
+__version__ = "0.1.0"
+__all__ = ["MapperError", "enrich_rows"]

tha_map_runner/errors.py

@@ -0,0 +1,2 @@
+class MapperError(Exception):
+    """Raised for invalid mapper configuration."""

tha_map_runner/mapper.py

@@ -0,0 +1,69 @@
+import warnings
+
+from .errors import MapperError
+from .paths import resolve_path
+
+_ON_NO_MATCH = {"skip", "error", "blank"}
+
+
+def enrich_rows(
+    rows: list[dict],
+    source: list[dict],
+    mapping: dict[str, str],
+    row_key: str,
+    source_key: str,
+    *,
+    on_no_match: str = "skip",
+    allow_empty_source: bool = False,
+    skip_statuses: list[str] | None = None,
+) -> list[dict]:
+    if on_no_match not in _ON_NO_MATCH:
+        raise MapperError(f"on_no_match must be one of {sorted(_ON_NO_MATCH)}, got {on_no_match!r}")
+
+    statuses_to_skip = set(skip_statuses if skip_statuses is not None else ["error", "warning"])
+
+    if not source:
+        if allow_empty_source:
+            return [row.copy() for row in rows]
+        raise MapperError("source is empty — pass allow_empty_source=True to allow this")
+
+    index: dict[object, dict] = {}
+    for item in source:
+        key = item.get(source_key)
+        if key in index:
+            warnings.warn(
+                f"Duplicate {source_key!r} value {key!r} in source; using last occurrence",
+                stacklevel=2,
+            )
+        index[key] = item
+
+    output: list[dict] = []
+    for row in rows:
+        if row.get("row status") in statuses_to_skip:
+            output.append(row.copy())
+            continue
+
+        key_val = row.get(row_key)
+        match = index.get(key_val)
+
+        if match is None:
+            new_row = row.copy()
+            if on_no_match == "error":
+                new_row["row status"] = "error"
+                new_row["message"] = f"No match for {row_key}={key_val!r}"
+                for field in mapping:
+                    new_row[field] = ""
+            elif on_no_match == "blank":
+                for field in mapping:
+                    new_row[field] = ""
+            output.append(new_row)
+            continue
+
+        new_row = row.copy()
+        for field, path in mapping.items():
+            value = resolve_path(match, path)
+            new_row[field] = "" if value is None else value
+
+        output.append(new_row)
+
+    return output

tha_map_runner/paths.py

@@ -0,0 +1,8 @@
+def resolve_path(obj: object, path: str) -> object:
+    if not path:
+        raise ValueError("path must not be empty")
+    for segment in path.split("."):
+        if not isinstance(obj, dict):
+            return None
+        obj = obj.get(segment)
+    return obj

tha_map_runner-0.1.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: tha-map-runner
+Version: 0.1.0
+Summary: Join JSON responses into CSV-style rows with dotted-path projection — a Tabular Helper API.
+Project-URL: Homepage, https://github.com/tha-guy-nate/tha-map-runner
+Project-URL: Issues, https://github.com/tha-guy-nate/tha-map-runner/issues
+Author: Nate Wright
+License: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tha-map-runner
+
+[![CI](https://github.com/tha-guy-nate/tha-map-runner/actions/workflows/ci.yml/badge.svg)](https://github.com/tha-guy-nate/tha-map-runner/actions/workflows/ci.yml)
+
+A small Python library that joins a list of row dicts with a lookup source on a key, projecting values into flat row columns via a mapping config.
+
+Think "left join between rows and a lookup source, with dotted-path projection on the source side."
+
+## Install
+
+```bash
+pip install tha-map-runner
+```
+
+## Quick start
+
+```python
+from tha_map_runner import enrich_rows
+
+rows = [
+    {"Org BK": "school-001", "Start Date": "08/15"},
+    {"Org BK": "school-002", "Start Date": "08/16"},
+]
+
+api_response = [
+    {"sourcedId": "school-001", "name": "Lincoln Elementary", "parent": {"sourcedId": "dist-A"}},
+    {"sourcedId": "school-002", "name": "Roosevelt Middle",   "parent": {"sourcedId": "dist-A"}},
+]
+
+enriched = enrich_rows(
+    rows=rows,
+    source=api_response,
+    mapping={
+        "Org Name":  "name",
+        "Parent BK": "parent.sourcedId",
+    },
+    row_key="Org BK",
+    source_key="sourcedId",
+)
+```
+
+## How it works
+
+1. Builds an index of `source` on `source_key` — O(n+m), no nested loops
+2. For each row, looks up a match by `row[row_key]`
+3. Walks dotted paths (`"parent.sourcedId"`) into the matched source entry
+4. Projects resolved values into new columns on a copy of the row
+5. Returns a new list — input is never mutated
+
+Rows whose `row status` is in `skip_statuses` are passed through unchanged.
+
+## API
+
+```python
+enrich_rows(
+    rows,                              # list of row dicts
+    source,                            # list of dicts to join against
+    mapping,                           # {"output_column": "dotted.path"} — callable values planned
+    row_key,                           # column name in rows to match on
+    source_key,                        # field in source to match on
+    *,
+    on_no_match="skip",                # "skip" | "error" | "blank"
+    allow_empty_source=False,          # if True, empty source is not an error
+    skip_statuses=["error", "warning"],# rows with these statuses are passed through
+) -> list[dict]
+```
+
+### `on_no_match`
+
+| Value | Behaviour |
+|---|---|
+| `"skip"` | Row is returned unchanged — no new columns added |
+| `"error"` | `row status="error"`, `message=...`, mapping columns set to `""` |
+| `"blank"` | Mapping columns set to `""`, row status untouched |
+
+### `skip_statuses`
+
+By default, rows already marked `row status="error"` or `row status="warning"` are passed through without processing. Override with any list:
+
+```python
+enrich_rows(..., skip_statuses=["error"])        # only skip errors
+enrich_rows(..., skip_statuses=["error", "pending"])  # custom statuses
+enrich_rows(..., skip_statuses=[])               # process every row regardless
+```
+
+### Composing with `tha-csv-runner`
+
+```python
+from tha_csv_runner import ThaCSV
+from tha_map_runner import enrich_rows
+import requests
+
+runner = ThaCSV()
+runner.read("Step 1 of 2", "input.csv", ["Org BK"])
+
+api_response = requests.get(api_url).json()
+
+runner.rows = enrich_rows(
+    rows=runner.rows,
+    source=api_response,
+    mapping={"Org Name": "name", "District": "parent.sourcedId"},
+    row_key="Org BK",
+    source_key="sourcedId",
+)
+
+runner.write("Step 2 of 2", "output.csv")
+```
+
+## License
+
+MIT

tha_map_runner-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+tha_map_runner/__init__.py,sha256=pt7XYPQBdwuNQ-dSJ8AjldTHuqncbyFhSaNxjnDQfIE,220
+tha_map_runner/errors.py,sha256=te2Nm0mL_RP3rg-HAccZYRcKlfSF7qkY_JUTXMTPuio,81
+tha_map_runner/mapper.py,sha256=uB4Ftfb2Kktt6wtO1Z86PJ3zAe3dYeIFqF_bkRbApwY,2073
+tha_map_runner/paths.py,sha256=UG-NoqwcfZUFaQahdLf7fINX-avXk-b7o4cigWL0bGI,264
+tha_map_runner-0.1.0.dist-info/METADATA,sha256=0lLOjYQP5Ib9klmKMfeZ2nwaeM5qwvvbelE1gAlGNns,4290
+tha_map_runner-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+tha_map_runner-0.1.0.dist-info/licenses/LICENSE,sha256=bCtVwn7MJmnj7wfasPJG_OXozVSo1RGg1FXERKSv6ps,1070
+tha_map_runner-0.1.0.dist-info/RECORD,,

tha_map_runner-0.1.0.dist-info/WHEEL

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

tha_map_runner-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Wright
+
+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.