Add immutable Tariff edition selection and contextual results

Author: billyoshall

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.7.0 - 2026-09-24
+
+- Add exact Tariff edition/date selection, answering metadata, contextual search lineage and explanatory null reasons. Explicit selections reject unsupported or mismatched server responses.
+
 ## 1.6.0 - 2026-09-24
 
 Adds Time location inputs and explicit ambiguity candidates, filtered timezone discovery, multiple conversion targets, wall-time disambiguation, and standard/seasonal offset detail. Existing Timezone methods and API 2.0.0 selection remain unchanged.

README.md

@@ -17,7 +17,7 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
 
 ## API versions
 
-Version 1.6.0 explicitly selects the API contract supported by this SDK. It sends `Parse-Version: 2.0.0` on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same.
+Version 1.7.0 explicitly selects the API contract supported by this SDK. It sends `Parse-Version: 2.0.0` on every lookup so responses match the API contract supported by the package. Your key and the team's saved default stay the same.
 
 Upgrade the dependency in staging, review the [release notes](https://parseapi.com/docs/releases), and test the application before deploying the same code and dependency version to production. Commit your dependency lockfile so the tested package travels with your deployment. Future major SDK upgrades can select a newer API contract.
 
@@ -231,6 +231,12 @@ parse.weather(40.7128, -74.006, deep=True, date="2026-08-15")
 
 Tariff starts with the general schedule line. Paid deep adds units and the special and other schedule columns. An optional origin then resolves country-specific measures. The three calls below show those successive choices. Without origin, schedule detail is still returned and origin-dependent fields are null. A null effective rate is not a zero rate.
 
+Tariff lookup and search accept an optional `edition` fingerprint and `date` (`YYYY-MM-DD`). The edition pins exact immutable source bytes. A date is accepted only when verified source coverage exists. An edition without a date returns undated schedule context (`date: null`). Default requests use today. Paid detail exposes an open-string `reason` when `effective_rate` is null, including `incomplete_coverage`. A null rate never means zero. Explicit selections fail with `tariff_selection_mismatch` if an older server ignores the requested scope.
+
+Origin means where the goods originate, not where they ship from. The effective rate covers matched stored schedule measures only. It is not complete duty or landed cost.
+
+Codes contain 4, 6, 8 or 10 ASCII digits; dots and whitespace are optional. Search returns up to 20 description matches with parent `lineage` so a result named "Other" has context. Search is not product classification. In deep, `measures: null` means origin-dependent measures were not resolved. `measures: []` means the resolved lookup found none.
+
 ```python
 parse.tariff("8471.30.01.00")
 parse.tariff("8471.30.01.00", deep=True)

api/public.json

@@ -1324,6 +1324,18 @@
           "kind": "KEYWORD_ONLY",
           "name": "origin",
           "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "edition",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "date",
+          "type": "Optional[str]"
         }
       ],
       "returns": "Json"
@@ -1335,6 +1347,18 @@
           "kind": "POSITIONAL_OR_KEYWORD",
           "name": "query",
           "type": "str"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "edition",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "date",
+          "type": "Optional[str]"
         }
       ],
       "returns": "Json"
@@ -3039,6 +3063,18 @@
           "kind": "KEYWORD_ONLY",
           "name": "origin",
           "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "edition",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "date",
+          "type": "Optional[str]"
         }
       ],
       "returns": "Json"
@@ -3050,6 +3086,18 @@
           "kind": "POSITIONAL_OR_KEYWORD",
           "name": "query",
           "type": "str"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "edition",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "date",
+          "type": "Optional[str]"
         }
       ],
       "returns": "Json"

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "parseapi"
-version = "1.6.0"
+version = "1.7.0"
 description = "Official ParseAPI client for Python. One key, minimal JSON, fast."
 readme = "README.md"
 license = "MIT"

src/parseapi/__init__.py

@@ -2,5 +2,5 @@
 
 from ._client import AsyncParseAPI, ParseAPI, ParseAPIError
 
-__version__ = "1.6.0"
+__version__ = "1.7.0"
 __all__ = ["ParseAPI", "AsyncParseAPI", "ParseAPIError", "__version__"]

src/parseapi/_client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import os
+import re
 import math
 import random
 import time
@@ -10,7 +11,7 @@
 
 import httpx
 
-VERSION = "1.6.0"
+VERSION = "1.7.0"
 _API_VERSION = "2.0.0"
 DEFAULT_BASE_URL = "https://api.parseapi.com"
 DEFAULT_TIMEOUT = 10.0
@@ -474,19 +475,30 @@ def search(self, query: str, *, limit: Optional[int] = None, deep: bool = False)
         return self._client._get("/naics", {"q": query, "limit": limit, "deep": deep})
 
 
+def _tariff_selection(result: Json, edition: Optional[str], date: Optional[str]) -> Json:
+    if (edition is not None or date is not None) and (
+        not isinstance(result.get("edition"), str) or re.fullmatch(r"[a-f0-9]{64}", result["edition"]) is None
+        or (edition is not None and result.get("edition") != edition)
+        or (result.get("date") != date)
+    ):
+        raise ParseAPIError(0, "tariff_selection_mismatch", "Tariff response did not confirm the requested edition/date. The server may not support this selection.", None, None)
+    return result
+
+
 class _TariffSync:
     def __init__(self, client: ParseAPI):
         self._client = client
 
-    def __call__(self, code: str, *, deep: bool = False, origin: Optional[str] = None) -> Json:
+    def __call__(self, code: str, *, deep: bool = False, origin: Optional[str] = None, edition: Optional[str] = None, date: Optional[str] = None) -> Json:
         """Look up the general US duty schedule line. Paid deep adds units and the special and other
         schedule columns. Add origin with deep to resolve country-specific measures. Without
         origin, schedule detail remains available and origin-dependent fields are null. A null
         effective rate is not a zero rate."""
-        return self._client._get(f"/tariff/{_seg(code)}", {"deep": deep, "origin": origin})
+        return _tariff_selection(self._client._get(f"/tariff/{_seg(code)}", {"deep": deep, "origin": origin, "edition": edition, "date": date}), edition, date)
+
+    def search(self, query: str, *, edition: Optional[str] = None, date: Optional[str] = None) -> Json:
+        return _tariff_selection(self._client._get("/tariff", {"q": query, "edition": edition, "date": date}), edition, date)
 
-    def search(self, query: str) -> Json:
-        return self._client._get("/tariff", {"q": query})
 
 
 class AsyncParseAPI:
@@ -861,15 +873,16 @@ class _TariffAsync:
     def __init__(self, client: AsyncParseAPI):
         self._client = client
 
-    async def __call__(self, code: str, *, deep: bool = False, origin: Optional[str] = None) -> Json:
+    async def __call__(self, code: str, *, deep: bool = False, origin: Optional[str] = None, edition: Optional[str] = None, date: Optional[str] = None) -> Json:
         """Look up the general US duty schedule line. Paid deep adds units and the special and other
         schedule columns. Add origin with deep to resolve country-specific measures. Without
         origin, schedule detail remains available and origin-dependent fields are null. A null
         effective rate is not a zero rate."""
-        return await self._client._get(f"/tariff/{_seg(code)}", {"deep": deep, "origin": origin})
+        return _tariff_selection(await self._client._get(f"/tariff/{_seg(code)}", {"deep": deep, "origin": origin, "edition": edition, "date": date}), edition, date)
+
+    async def search(self, query: str, *, edition: Optional[str] = None, date: Optional[str] = None) -> Json:
+        return _tariff_selection(await self._client._get("/tariff", {"q": query, "edition": edition, "date": date}), edition, date)
 
-    async def search(self, query: str) -> Json:
-        return await self._client._get("/tariff", {"q": query})
 
 
 class _DateSync:

tests/test_tariff.py

@@ -0,0 +1,92 @@
+import asyncio
+
+import httpx
+import pytest
+
+from parseapi import AsyncParseAPI, ParseAPI, ParseAPIError
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+@pytest.mark.parametrize("extra", [{}, {"lineage": None}, {"lineage": []}, {"lineage": ["Live horses", "Other horses"]}])
+def test_tariff_search_preserves_parent_context_and_older_results(async_client, extra):
+    body = {"q": "horses & ponies", "revision": "fixture", "lines": [{"hts": "0101.29.00.90", "description": "Other", "general": None, **extra, "future": True}]}
+
+    def respond(request):
+        assert request.url.path == "/tariff"
+        assert dict(request.url.params) == {"q": "horses & ponies"}
+        return httpx.Response(200, json=body)
+
+    transport = httpx.MockTransport(respond)
+    if async_client:
+        async def run():
+            async with AsyncParseAPI("test", transport=transport) as client:
+                assert await client.tariff.search("horses & ponies") == body
+        asyncio.run(run())
+    else:
+        with ParseAPI("test", transport=transport) as client:
+            assert client.tariff.search("horses & ponies") == body
+
+@pytest.mark.parametrize("async_client", [False, True])
+def test_tariff_edition_date_roundtrip(async_client):
+    edition = "a" * 64
+    body = {"hts": "0101", "revision": "fixture", "edition": edition, "date": "2026-09-15", "deep": {"effective_rate": None, "reason": "future_reason", "measures": []}}
+    seen = []
+
+    def respond(request):
+        seen.append(dict(request.url.params))
+        return httpx.Response(200, json={**body, "date": request.url.params.get("date")})
+
+    transport = httpx.MockTransport(respond)
+    if async_client:
+        async def run():
+            async with AsyncParseAPI("test", transport=transport) as client:
+                assert await client.tariff("0101", deep=True, origin="CA", edition=edition, date="2026-09-15") == body
+                assert await client.tariff.search("horses", edition=edition, date="2026-09-15") == body
+                await client.tariff("0101", edition=edition)
+        asyncio.run(run())
+    else:
+        with ParseAPI("test", transport=transport) as client:
+            assert client.tariff("0101", deep=True, origin="CA", edition=edition, date="2026-09-15") == body
+            assert client.tariff.search("horses", edition=edition, date="2026-09-15") == body
+            client.tariff("0101", edition=edition)
+    assert seen == [{"deep": "true", "origin": "CA", "edition": edition, "date": "2026-09-15"}, {"q": "horses", "edition": edition, "date": "2026-09-15"}, {"edition": edition}]
+
+@pytest.mark.parametrize("async_client", [False, True])
+def test_tariff_rejects_ignored_selection(async_client):
+    transport = httpx.MockTransport(lambda request: httpx.Response(200, json={"revision": "old"}))
+    if async_client:
+        async def run():
+            async with AsyncParseAPI("test", transport=transport) as client:
+                with pytest.raises(Exception, match="did not confirm"):
+                    await client.tariff("0101", edition="a" * 64)
+                with pytest.raises(Exception, match="did not confirm"):
+                    await client.tariff.search("horses", date="2026-09-15")
+        asyncio.run(run())
+    else:
+        with ParseAPI("test", transport=transport) as client:
+            with pytest.raises(Exception, match="did not confirm"):
+                client.tariff("0101", edition="a" * 64)
+            with pytest.raises(Exception, match="did not confirm"):
+                client.tariff.search("horses", date="2026-09-15")
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+@pytest.mark.parametrize("edition", ["legacy", "", "A" * 64, "a" * 64 + "\n"])
+def test_tariff_rejects_invalid_returned_edition(async_client, edition):
+    transport = httpx.MockTransport(lambda request: httpx.Response(200, json={"edition": edition, "date": "2026-09-15"}))
+    if async_client:
+        async def run():
+            async with AsyncParseAPI("test", transport=transport) as client:
+                for operation, value in [(client.tariff, "0101"), (client.tariff.search, "horses")]:
+                    with pytest.raises(ParseAPIError) as error:
+                        await operation(value, date="2026-09-15")
+                    assert error.value.code == "tariff_selection_mismatch"
+                    assert error.value.status == 0
+        asyncio.run(run())
+    else:
+        with ParseAPI("test", transport=transport) as client:
+            for operation, value in [(client.tariff, "0101"), (client.tariff.search, "horses")]:
+                with pytest.raises(ParseAPIError) as error:
+                    operation(value, date="2026-09-15")
+                assert error.value.code == "tariff_selection_mismatch"
+                assert error.value.status == 0