parseapi 1.1.0__tar.gz → 1.4.0__tar.gz

parseapi-1.4.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 1.4.0 - 2026-09-24
+
+Adds Australian Postal suburb choices while preserving null, empty, and ambiguous results. Existing calls, compact nearby/distance responses, and API contract `2.0.0` remain unchanged.
+
+## 1.3.0 - Unreleased
+
+Adds Stack site inventory lookup with eight technology category arrays, nullable versions, and explicit page coverage. Stack uses a 35-second default attempt timeout while explicit caller settings remain honored. Existing calls and API contract `2.0.0` remain unchanged.
+
+## 1.1.0 - 2026-09-20
+
+Email deep results now include nullable suggested first name, no-reply flag, plus-address tag, mail provider, verification status and reason. Existing lookup calls, retry defaults and API contract `2.0.0` remain unchanged. Missing details remain unknown, and suggested names do not verify identity.

{parseapi-1.1.0 → parseapi-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: parseapi
-Version: 1.1.0
+Version: 1.4.0
 Summary: Official ParseAPI client for Python. One key, minimal JSON, fast.
 Project-URL: Homepage, https://parseapi.com
 Project-URL: Documentation, https://parseapi.com/docs
@@ -36,7 +36,7 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
 
 ## API versions
 
-Version 1.1.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.4.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.
 
@@ -185,6 +185,8 @@ Unit discovery accepts optional `query`, `type`, and `unit` filters. `unit` sele
 
 ## Place statistics and optional detail
 
+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).
+
 Postal and District paid profiles include `deep.property_tax` where supported. It contains `annual_median`, `currency` and `period`: median annual property tax payable on owner-occupied homes in the statistical area. The amount is adjusted to the final year of the reporting period (`YYYY-YYYY`). This is an area statistic, not a rate or an individual property bill. Unsupported, missing and censored estimates are null.
 
 ```python
@@ -293,3 +295,18 @@ basic = parse.time("America/New_York")
 detail = parse.time("America/New_York", deep=True)
 print(basic["at"], detail.get("deep", {}).get("next_dst"))
 ```
+
+## Stack API
+
+```python
+result = parse.stack("example.com")
+# AsyncParseAPI exposes the same calls with await.
+```
+
+Pass a public hostname without a scheme, path, port or IP address. Stack returns the checked URL and `checked_at` time, followed by `scope`, `pages` and `partial`. `scope` is `homepage` or `site`; `pages` counts successfully checked HTML pages. `partial` is true for homepage-only or incomplete bounded site checks. False means the known in-scope candidates were completed, not that every page on a website was visited. A homepage result has `scope: "homepage"`, `pages: 1` and `partial: true`.
+
+`cms`, `servers`, `frameworks`, `ecommerce`, `analytics`, `chat`, `payments` and `hosting` are arrays because a site can use several technologies in each category. Each entry contains `technology`, `name` and nullable `version`. Technology codes are open strings. A successful check uses empty arrays for categories with no matches. When no HTML page could be checked, `checked_at` and all categories are null, `pages` is 0 and `partial` is null. Unknown or conflicting versions are null. Missing detections do not prove absence.
+
+Successful checks may be reused for up to 24 hours. `pretty` optionally formats the wire JSON. Stack uses your plan's request allowance and API version 2.0.0 selected by this client.
+
+Stack defaults to a 35-second transport timeout so a first scan has time to finish. Other lookups retain their 10-second default. An explicit client timeout takes precedence.

{parseapi-1.1.0 → parseapi-1.4.0}/README.md

@@ -17,7 +17,7 @@ Get a key at [parseapi.com](https://parseapi.com). The client also reads `PARSEA
 
 ## API versions
 
-Version 1.1.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.4.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.
 
@@ -166,6 +166,8 @@ Unit discovery accepts optional `query`, `type`, and `unit` filters. `unit` sele
 
 ## Place statistics and optional detail
 
+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).
+
 Postal and District paid profiles include `deep.property_tax` where supported. It contains `annual_median`, `currency` and `period`: median annual property tax payable on owner-occupied homes in the statistical area. The amount is adjusted to the final year of the reporting period (`YYYY-YYYY`). This is an area statistic, not a rate or an individual property bill. Unsupported, missing and censored estimates are null.
 
 ```python
@@ -274,3 +276,18 @@ basic = parse.time("America/New_York")
 detail = parse.time("America/New_York", deep=True)
 print(basic["at"], detail.get("deep", {}).get("next_dst"))
 ```
+
+## Stack API
+
+```python
+result = parse.stack("example.com")
+# AsyncParseAPI exposes the same calls with await.
+```
+
+Pass a public hostname without a scheme, path, port or IP address. Stack returns the checked URL and `checked_at` time, followed by `scope`, `pages` and `partial`. `scope` is `homepage` or `site`; `pages` counts successfully checked HTML pages. `partial` is true for homepage-only or incomplete bounded site checks. False means the known in-scope candidates were completed, not that every page on a website was visited. A homepage result has `scope: "homepage"`, `pages: 1` and `partial: true`.
+
+`cms`, `servers`, `frameworks`, `ecommerce`, `analytics`, `chat`, `payments` and `hosting` are arrays because a site can use several technologies in each category. Each entry contains `technology`, `name` and nullable `version`. Technology codes are open strings. A successful check uses empty arrays for categories with no matches. When no HTML page could be checked, `checked_at` and all categories are null, `pages` is 0 and `partial` is null. Unknown or conflicting versions are null. Missing detections do not prove absence.
+
+Successful checks may be reused for up to 24 hours. `pretty` optionally formats the wire JSON. Stack uses your plan's request allowance and API version 2.0.0 selected by this client.
+
+Stack defaults to a 35-second transport timeout so a first scan has time to finish. Other lookups retain their 10-second default. An explicit client timeout takes precedence.

{parseapi-1.1.0 → parseapi-1.4.0}/api/public.json

@@ -1224,6 +1224,29 @@
       ],
       "returns": "Json"
     },
+    "stack": {
+      "async": true,
+      "parameters": [
+        {
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "name": "domain",
+          "type": "str"
+        },
+        {
+          "default": false,
+          "kind": "KEYWORD_ONLY",
+          "name": "deep",
+          "type": "bool"
+        },
+        {
+          "default": false,
+          "kind": "KEYWORD_ONLY",
+          "name": "pretty",
+          "type": "bool"
+        }
+      ],
+      "returns": "Json"
+    },
     "state": {
       "async": true,
       "parameters": [
@@ -2778,6 +2801,29 @@
       ],
       "returns": "Json"
     },
+    "stack": {
+      "async": false,
+      "parameters": [
+        {
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "name": "domain",
+          "type": "str"
+        },
+        {
+          "default": false,
+          "kind": "KEYWORD_ONLY",
+          "name": "deep",
+          "type": "bool"
+        },
+        {
+          "default": false,
+          "kind": "KEYWORD_ONLY",
+          "name": "pretty",
+          "type": "bool"
+        }
+      ],
+      "returns": "Json"
+    },
     "state": {
       "async": false,
       "parameters": [

{parseapi-1.1.0 → parseapi-1.4.0}/pyproject.toml

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

{parseapi-1.1.0 → parseapi-1.4.0}/src/parseapi/__init__.py

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

{parseapi-1.1.0 → parseapi-1.4.0}/src/parseapi/_client.py

@@ -10,7 +10,7 @@ from urllib.parse import quote
 
 import httpx
 
-VERSION = "1.1.0"
+VERSION = "1.4.0"
 _API_VERSION = "2.0.0"
 DEFAULT_BASE_URL = "https://api.parseapi.com"
 DEFAULT_TIMEOUT = 10.0
@@ -96,12 +96,16 @@ class _Config:
         self.api_key = key
         self.base_url = (base_url or os.environ.get("PARSEAPI_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
         self.timeout = DEFAULT_TIMEOUT if timeout is None else timeout
+        self.timeout_explicit = timeout is not None
         self.retries = retries
         if type(self.timeout) not in (int, float) or not math.isfinite(self.timeout) or self.timeout <= 0:
             raise ValueError("parseapi: timeout must be a finite positive number.")
         if self.retries is not None and (type(self.retries) is not int or self.retries < 0):
             raise ValueError("parseapi: retries must be a non-negative integer.")
 
+    def timeout_for(self, path: str) -> float:
+        return 35.0 if not self.timeout_explicit and path.startswith("/stack/") else self.timeout
+
     def headers(self) -> Dict[str, str]:
         return {"X-API-Key": self.api_key, "User-Agent": f"parseapi-python/{VERSION}", "Parse-Version": _API_VERSION}
 
@@ -157,7 +161,7 @@ class ParseAPI:
         attempt = 0
         while True:
             try:
-                response = self._http.get(path, params=_clean(params or {}), headers=headers)
+                response = self._http.get(path, params=_clean(params or {}), headers=headers, timeout=self._config.timeout_for(path))
             except httpx.HTTPError:
                 if attempt < retries:
                     time.sleep(_retry_delay(attempt, None))
@@ -230,6 +234,15 @@ class ParseAPI:
         diagnostics within the same metered lookup. No automatic retries by default."""
         return self._get(f"/hlr/{_seg(number)}", {"country": country, "deep": deep})
 
+    def stack(self, domain: str, *, deep: bool = False, pretty: bool = False) -> Json:
+        """Identify website technologies and versions by category.
+
+        All categories are lists. Scope, pages and partial describe bounded coverage.
+        Lists are null when no page could be checked and empty for no matches.
+        Pass a hostname without a URL scheme or path.
+        """
+        return self._get(f"/stack/{_seg(domain)}", {"deep": deep, "pretty": pretty})
+
     def domain(self, domain: str, *, deep: bool = False) -> Json:
         """Check whether a domain is registered. Deep adds registration dates, registrar, status and DNSSEC on paid plans."""
         return self._get(f"/domain/{_seg(domain)}", {"deep": deep})
@@ -531,7 +544,7 @@ class AsyncParseAPI:
         attempt = 0
         while True:
             try:
-                response = await self._http.get(path, params=_clean(params or {}), headers=headers)
+                response = await self._http.get(path, params=_clean(params or {}), headers=headers, timeout=self._config.timeout_for(path))
             except httpx.HTTPError:
                 if attempt < retries:
                     await asyncio.sleep(_retry_delay(attempt, None))
@@ -602,6 +615,15 @@ class AsyncParseAPI:
         diagnostics within the same metered lookup. No automatic retries by default."""
         return await self._get(f"/hlr/{_seg(number)}", {"country": country, "deep": deep})
 
+    async def stack(self, domain: str, *, deep: bool = False, pretty: bool = False) -> Json:
+        """Identify website technologies and versions by category.
+
+        All categories are lists. Scope, pages and partial describe bounded coverage.
+        Lists are null when no page could be checked and empty for no matches.
+        Pass a hostname without a URL scheme or path.
+        """
+        return await self._get(f"/stack/{_seg(domain)}", {"deep": deep, "pretty": pretty})
+
     async def domain(self, domain: str, *, deep: bool = False) -> Json:
         """Check whether a domain is registered. Deep adds registration dates, registrar, status and DNSSEC on paid plans."""
         return await self._get(f"/domain/{_seg(domain)}", {"deep": deep})

parseapi-1.4.0/tests/test_postal_localities.py

@@ -0,0 +1,25 @@
+import asyncio
+
+import httpx
+import pytest
+
+from parseapi import AsyncParseAPI, ParseAPI
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+@pytest.mark.parametrize("extra", [
+    {}, {"localities": None}, {"localities": []},
+    {"localities": [{"city": "SYDNEY", "state": "NSW", "state_name": "New South Wales", "future": True}]},
+    {"localities": [{"city": "SYDNEY", "state": "NSW", "state_name": "New South Wales"}, {"city": "HAYMARKET", "state": "NSW", "state_name": "New South Wales"}]},
+])
+def test_postal_choices_preserve_observation_without_inferring_city(async_client, extra):
+    body = {"postal": "2000", "country": "AU", "city": None, **extra}
+    transport = httpx.MockTransport(lambda request: httpx.Response(200, json=body))
+    if async_client:
+        async def run():
+            async with AsyncParseAPI("test", transport=transport) as client:
+                assert await client.postal("2000", country="AU") == body
+        asyncio.run(run())
+    else:
+        with ParseAPI("test", transport=transport) as client:
+            assert client.postal("2000", country="AU") == body

parseapi-1.4.0/tests/test_stack.py

@@ -0,0 +1,251 @@
+import asyncio
+import json
+import httpx
+from parseapi import ParseAPI, AsyncParseAPI
+
+RECORDS = json.loads(r'''
+[
+  {
+    "domain": "xn--bcher-kva.example",
+    "url": "https://xn--bcher-kva.example/",
+    "checked_at": null,
+    "scope": "homepage",
+    "pages": 0,
+    "partial": null,
+    "cms": null,
+    "servers": null,
+    "frameworks": null,
+    "ecommerce": null,
+    "analytics": null,
+    "chat": null,
+    "payments": null,
+    "hosting": null,
+    "future": true
+  },
+  {
+    "domain": "xn--bcher-kva.example",
+    "url": "https://xn--bcher-kva.example/",
+    "checked_at": "2026-09-21T12:00:00Z",
+    "scope": "homepage",
+    "pages": 1,
+    "partial": true,
+    "cms": [],
+    "servers": [],
+    "frameworks": [],
+    "ecommerce": [],
+    "analytics": [],
+    "chat": [],
+    "payments": [],
+    "hosting": [],
+    "deep": {},
+    "future": true
+  },
+  {
+    "domain": "xn--bcher-kva.example",
+    "url": "https://xn--bcher-kva.example/",
+    "checked_at": "2026-09-21T12:00:00Z",
+    "scope": "homepage",
+    "pages": 1,
+    "partial": true,
+    "cms": [
+      {
+        "technology": "wordpress",
+        "name": "WordPress",
+        "version": "6.8.2"
+      }
+    ],
+    "servers": [
+      {
+        "technology": "nginx",
+        "name": "nginx",
+        "version": null
+      }
+    ],
+    "frameworks": [
+      {
+        "technology": "react",
+        "name": "React",
+        "version": null
+      }
+    ],
+    "ecommerce": [],
+    "analytics": [],
+    "chat": [],
+    "payments": [],
+    "hosting": [],
+    "future": true
+  },
+  {
+    "domain": "xn--bcher-kva.example",
+    "url": "https://xn--bcher-kva.example/",
+    "checked_at": "2026-09-21T12:00:00Z",
+    "scope": "site",
+    "pages": 6,
+    "partial": false,
+    "cms": [
+      {
+        "technology": "wordpress",
+        "name": "WordPress",
+        "version": "6.8.2"
+      },
+      {
+        "technology": "ghost",
+        "name": "Ghost",
+        "version": null
+      }
+    ],
+    "servers": [
+      {
+        "technology": "nginx",
+        "name": "nginx",
+        "version": null
+      },
+      {
+        "technology": "apache",
+        "name": "Apache",
+        "version": null
+      }
+    ],
+    "frameworks": [
+      {
+        "technology": "nextjs",
+        "name": "Next.js",
+        "version": "15.0.0",
+        "future": true
+      },
+      {
+        "technology": "react",
+        "name": "React",
+        "version": null
+      }
+    ],
+    "ecommerce": [
+      {
+        "technology": "woocommerce",
+        "name": "WooCommerce",
+        "version": null
+      }
+    ],
+    "analytics": [
+      {
+        "technology": "google-analytics",
+        "name": "Google Analytics",
+        "version": null
+      }
+    ],
+    "chat": [
+      {
+        "technology": "intercom",
+        "name": "Intercom",
+        "version": null
+      }
+    ],
+    "payments": [
+      {
+        "technology": "stripe",
+        "name": "Stripe",
+        "version": null
+      }
+    ],
+    "hosting": [
+      {
+        "technology": "vercel",
+        "name": "Vercel",
+        "version": null
+      }
+    ],
+    "future": true
+  },
+  {
+    "domain": "xn--bcher-kva.example",
+    "url": "https://xn--bcher-kva.example/",
+    "checked_at": "2026-09-21T12:00:00Z",
+    "scope": "site",
+    "pages": 3,
+    "partial": true,
+    "cms": [],
+    "servers": [],
+    "frameworks": [
+      {
+        "technology": "nextjs",
+        "name": "Next.js",
+        "version": null,
+        "future": true
+      }
+    ],
+    "ecommerce": [],
+    "analytics": [],
+    "chat": [],
+    "payments": [],
+    "hosting": [],
+    "deep": {},
+    "future": true
+  },
+  {
+    "domain": "xn--bcher-kva.example",
+    "url": "https://xn--bcher-kva.example/",
+    "checked_at": null,
+    "scope": "site",
+    "pages": 0,
+    "partial": null,
+    "cms": null,
+    "servers": null,
+    "frameworks": null,
+    "ecommerce": null,
+    "analytics": null,
+    "chat": null,
+    "payments": null,
+    "hosting": null,
+    "deep": {},
+    "future": true
+  }
+]
+''')
+
+def test_stack_sync_and_async_preserve_site_inventory_shapes_and_encoding():
+    async def run_async(record):
+        calls = []
+        async def handler(request):
+            calls.append(request)
+            return httpx.Response(200, json=record)
+        async with AsyncParseAPI("test_key", transport=httpx.MockTransport(handler)) as client:
+            assert await client.stack("bücher.example", deep=True, pretty=True) == record
+            assert await client.stack("example.com") == record
+        check(calls)
+    for record in RECORDS:
+        calls = []
+        def handler(request):
+            calls.append(request)
+            return httpx.Response(200, json=record)
+        with ParseAPI("test_key", transport=httpx.MockTransport(handler)) as client:
+            assert client.stack("bücher.example", deep=True, pretty=True) == record
+            assert client.stack("example.com") == record
+        check(calls)
+        asyncio.run(run_async(record))
+
+def check(calls):
+    assert str(calls[0].url) == "https://api.parseapi.com/stack/b%C3%BCcher.example?deep=true&pretty=true"
+    assert str(calls[1].url) == "https://api.parseapi.com/stack/example.com"
+    assert all(request.headers["Parse-Version"] == "2.0.0" for request in calls)
+
+def test_stack_deadline_defaults_and_explicit_sync_async_settings():
+    for explicit in [None, 10.0, 1.2, 45.0]:
+        expected = 35.0 if explicit is None else explicit
+        calls = []
+        def handler(request):
+            calls.append(request.extensions["timeout"])
+            return httpx.Response(200, json={**RECORDS[0], "deep": {}})
+        with ParseAPI("test_key", timeout=explicit, transport=httpx.MockTransport(handler)) as client:
+            assert client.stack("example.com")["deep"] == {}
+            client.domain("example.com")
+            client.stack("example.com", deep=True)
+        assert [call["read"] for call in calls] == [expected, 10.0 if explicit is None else explicit, expected]
+        assert all(len(set(call.values())) == 1 for call in calls)
+        async def run():
+            calls.clear()
+            async with AsyncParseAPI("test_key", timeout=explicit, transport=httpx.MockTransport(handler)) as client:
+                assert (await client.stack("example.com"))["deep"] == {}
+                await client.domain("example.com")
+                await client.stack("example.com", deep=True)
+            assert [call["read"] for call in calls] == [expected, 10.0 if explicit is None else explicit, expected]
+        asyncio.run(run())

parseapi-1.1.0/CHANGELOG.md

@@ -1,5 +0,0 @@
-# Changelog
-
-## 1.1.0 - 2026-09-20
-
-Email deep results now include nullable suggested first name, no-reply flag, plus-address tag, mail provider, verification status and reason. Existing lookup calls, retry defaults and API contract `2.0.0` remain unchanged. Missing details remain unknown, and suggested names do not verify identity.