Match canonical ISO fields and reviewed Core/Deep responses

Align Country, State and Language wire mappings, types, examples and documentation with the approved current API cleanup. Preserve existing endpoint methods, frozen wire adapters, authoritative nulls and unrelated products. Currency restoration remains in its separate release batch.

Version 1.10.6 is the exact patch approved by Billy. Package interface and runtime transport remain compatible; metadata/docs match the live response.

Author: billyoshall

README.md

@@ -77,6 +77,15 @@ Discovery example: `parse.company.search(country="US", industry="0700", industry
 Supply `industry` and `industry_type` together. The supported namespace is `sic`, with an exact four-digit string such as `0700`; leading zeros are meaningful. Country-only discovery is also supported. Filters intersect and may narrow an existing selector. Country matches the profile country, not a headquarters or operating-presence claim. Unknown values do not match a requested filter. Filter-only candidates use `match.field: "filters"` and `match.value: null`; reuse the same filters and limit with a returned cursor. Counts describe this directory edition, not complete country coverage.
 
 
+## ISO identifiers
+
+Country uses `iso_alpha3` and `iso_numeric`, State uses the full
+`iso_subdivision` code such as `US-CA`, Language uses `iso_alpha3`, and Currency
+uses `iso_numeric`. Primary `country`, `state`, `language` and `currency` codes
+keep their meaning. Results retain the selected API contract's exact keys,
+values, nulls and nesting. Earlier server contracts retain their earlier ISO
+spellings. Use the existing lookup methods for each resource.
+
 ## Calls
 
 One method per endpoint, named after the route.
@@ -225,7 +234,7 @@ Source deep adds `standard_offset`, `standard_offset_seconds`, signed `dst_offse
 
 ## Place statistics and optional detail
 
-Country Core contains the everyday reference: `name`, `name_full`, `name_local`, demonym and country codes, continent, region and subregion, currency, calling code, `flag`, language and timezone codes, borders, bloc memberships and `capital: { name, lat, lon }`. Paid Deep adds specialist detail, including population, total area and national statistics. `gdp_usd` and `gdp_per_capita_usd` are current US dollars; `population_growth_percent`, `urban_population_percent` and `internet_users_percent` use a 0–100 percent scale (growth can be negative or exceed 100). GDP per person and these three percentages round once to two decimals in the API response. `elevation_average` is average terrain elevation in meters; `lowest_point.elevation` and `highest_point.elevation` keep their point-specific meaning. Unknown stays null and a known zero stays zero. Country tax references are grouped once as `deep.tax: { name, rate }`; the rate remains a percentage. Read capital from the Core object and read the tax name and rate from the Deep tax object.
+Country Core contains the everyday reference: `name`, `name_full`, `name_local`, demonym, `iso_alpha3` and `iso_numeric` country identifiers, continent, region and subregion, currency, calling code, `flag`, language and timezone codes, borders, bloc memberships and `capital: { name, lat, lon }`. Paid Deep adds specialist detail, including population, total area and national statistics. `gdp_usd` and `gdp_per_capita_usd` are current US dollars; `population_growth_percent`, `urban_population_percent` and `internet_users_percent` use a 0–100 percent scale (growth can be negative or exceed 100). GDP per person and these three percentages round once to two decimals in the API response. `elevation_average` is average terrain elevation in meters; `lowest_point.elevation` and `highest_point.elevation` keep their point-specific meaning. Unknown stays null and a known zero stays zero. Country tax references are grouped once as `deep.tax: { name, rate }`; the rate remains a percentage. Read capital from the Core object and read the tax name and rate from the Deep tax object.
 
 Australian postal lookups include core `localities` with suburb choices (`city`, `state`, `state_name`) on every plan. Null or an omitted field means unknown, while `[]` means the reviewed reference has no eligible choices. `city` stays null when the source is ambiguous, even if there is only one eligible choice. Let the user select their suburb and keep manual entry available. These are geographic choices, not mailing-address verification. [G-NAF source, adaptations and licence](https://parseapi.com/legal/attribution#postal-au).
 

pyproject.toml

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

smoke/smoke.py

@@ -51,7 +51,7 @@ def expect_error(name, call, code):
 expect_ok("ip.self", lambda: parse.ip.self(), lambda r: None if r.get("ip") else "no ip")
 expect_ok("continent", lambda: parse.continent("NA"), lambda r: None if r["name"] == "North America" else "wrong name")
 expect_ok("continent.countries", lambda: parse.continent.countries("NA"), lambda r: None if r["countries"] else "empty")
-expect_ok("country", lambda: parse.country("US"), lambda r: None if r["iso3"] == "USA" else "wrong iso3")
+expect_ok("country", lambda: parse.country("US"), lambda r: None if r.get("iso_alpha3", r.get("iso3")) == "USA" else "wrong country alpha-3 code")
 expect_ok("country.states", lambda: parse.country.states("US"), lambda r: None if len(r["states"]) >= 50 else "too few")
 expect_ok("state", lambda: parse.state("NC", country="US"), lambda r: None if r["name"] == "North Carolina" else "wrong")
 expect_ok("state.districts", lambda: parse.state.districts("NC", country="US"), lambda r: None if r["districts"] else "empty")

src/parseapi/__init__.py

@@ -3,5 +3,5 @@
 from .city import CityAmbiguityCandidate
 from ._client import AsyncParseAPI, ParseAPI, ParseAPIError
 
-__version__ = "1.10.5"
+__version__ = "1.10.6"
 __all__ = ["CityAmbiguityCandidate", "ParseAPI", "AsyncParseAPI", "ParseAPIError", "__version__"]

src/parseapi/_client.py

@@ -13,7 +13,7 @@
 import httpx
 from .city import CityAmbiguityCandidate, city_error_candidates
 
-VERSION = "1.10.5"
+VERSION = "1.10.6"
 _API_VERSION = "2.0.0"
 DEFAULT_BASE_URL = "https://api.parseapi.com"
 DEFAULT_TIMEOUT = 10.0

tests/fixtures/iso-contract.json

@@ -0,0 +1,93 @@
+[
+  {
+    "operation": "country",
+    "code": "US",
+    "deep": false,
+    "body": {
+      "country": "US",
+      "iso3": "USA",
+      "numeric": 840
+    }
+  },
+  {
+    "operation": "country",
+    "code": "US",
+    "deep": false,
+    "body": {
+      "country": "US",
+      "iso_alpha3": "USA",
+      "iso_numeric": 840
+    }
+  },
+  {
+    "operation": "country",
+    "code": "AQ",
+    "deep": false,
+    "body": {
+      "country": "AQ",
+      "iso_alpha3": "ATA",
+      "iso_numeric": 10
+    }
+  },
+  {
+    "operation": "state",
+    "code": "CA",
+    "country": "US",
+    "deep": true,
+    "body": {
+      "state": "CA",
+      "country": "US",
+      "deep": {
+        "iso_3166_2": "US-CA"
+      }
+    }
+  },
+  {
+    "operation": "state",
+    "code": "CA",
+    "country": "US",
+    "deep": false,
+    "body": {
+      "state": "CA",
+      "country": "US",
+      "iso_subdivision": "US-CA"
+    }
+  },
+  {
+    "operation": "language",
+    "code": "hr",
+    "deep": true,
+    "body": {
+      "language": "hr",
+      "deep": {
+        "iso3": "hrv",
+        "countries": [
+          "BA",
+          "HR"
+        ]
+      }
+    }
+  },
+  {
+    "operation": "language",
+    "code": "hr",
+    "deep": false,
+    "body": {
+      "language": "hr",
+      "iso_alpha3": "hrv",
+      "countries": [
+        "BA",
+        "HR"
+      ]
+    }
+  },
+  {
+    "operation": "language",
+    "code": "gsw",
+    "deep": false,
+    "body": {
+      "language": "gsw",
+      "iso_alpha3": "gsw"
+    }
+  }
+]

tests/test_iso_contract.py

@@ -0,0 +1,40 @@
+import asyncio
+import json
+from pathlib import Path
+
+import httpx
+from parseapi import ParseAPI, AsyncParseAPI
+
+CASES = json.loads((Path(__file__).parent / "fixtures/iso-contract.json").read_text())
+
+def options(sample):
+    return {"deep": sample["deep"], **({"country": sample["country"]} if "country" in sample else {})}
+
+def test_iso_contracts_remain_raw_through_existing_sync_transport():
+    for sample in CASES:
+        calls = []
+        def transport(request):
+            calls.append(request)
+            return httpx.Response(200, json=sample["body"])
+        with ParseAPI("fixture", transport=httpx.MockTransport(transport)) as client:
+            operation = getattr(client, sample["operation"])
+            result = operation(sample["code"], **options(sample))
+        assert result == sample["body"]
+        assert len(calls) == 1
+        assert calls[0].url.path == f"/{sample['operation']}/{sample['code']}"
+        assert calls[0].url.params.get("deep") == ("true" if sample["deep"] else None)
+
+def test_iso_contracts_remain_raw_through_existing_async_transport():
+    async def run():
+        for sample in CASES:
+            calls = []
+            def transport(request):
+                calls.append(request)
+                return httpx.Response(200, json=sample["body"])
+            async with AsyncParseAPI("fixture", transport=httpx.MockTransport(transport)) as client:
+                operation = getattr(client, sample["operation"])
+                result = await operation(sample["code"], **options(sample))
+            assert result == sample["body"]
+            assert len(calls) == 1
+    asyncio.run(run())
+