parseapi 1.8.0__tar.gz → 1.9.0__tar.gz

{parseapi-1.8.0 → parseapi-1.9.0}/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.9.0 — 2026-09-29
+
+- Add Company stable-ID lookup, candidate search and coverage for the current public-company cohort.
+- Preserve existing Company calls and all published compatibility methods.
+
 ## 1.8.0 — 2026-09-25
 
 - Add Bank diagnostics, POST requests, requirements and explicit US ACH helpers; Card Core and optional Deep; Provider; Industry; and Vehicle.

{parseapi-1.8.0 → parseapi-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: parseapi
-Version: 1.8.0
+Version: 1.9.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.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.
+This SDK 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.
 
@@ -66,6 +66,36 @@ Results are plain data. Pass a returned code or coordinate to another operation
 
 Use `parse.postal("28202", country="US", deep=True)` for US ZIP tax references. `deep.tax` names the levy and `deep.tax_rate` is a percentage, so `7.9` means 7.9%. The state, county, city and special components explain that combined rate. An exact address can differ. Country and state lookups provide their own geographic reference rates, which should not be added to the ZIP rate. `None` means unknown and `0` means known zero. Country `deep.tax_id_format` and `deep.tax_id_regex` describe registration-number format only. Use `vat` for a metered registration check with `deep` explicitly enabled.
 
+## Company directory
+
+Find candidates, then fetch the profile you selected.
+
+```python
+candidates = parse.company.search(query="GitLab", country="US", limit=5)
+selected_id = "co_caczn6wf36hj"  # Explicitly chosen after reviewing candidates.
+profile = parse.company.id(selected_id, deep=True)
+if candidates["next"] is not None:
+    next_page = parse.company.search(
+        query="GitLab", country="US", limit=5, cursor=candidates["next"]
+    )
+coverage = parse.company.coverage()
+```
+
+Use at most one selector: `query` for a name, `domain`, `ticker`, or `identifier`; country or exact industry filters also allow discovery without a selector. The API validates selectors and filters. Use `country` to scope candidates, `exchange` with a ticker, and `authority` with an identifier. Search returns `companies` and an opaque `next` cursor. Review candidate identity and match details before choosing a stable Company ID. Pass `next` as `cursor` with the same selector, filters and limit to continue that result set.
+
+Directory profiles are plain JSON data. `deep` belongs to each company in search results and adds legal/reference detail plus nullable `description`, `logo`, `founded`, and the `social_profiles`, `phone_numbers`, `email_addresses`, `domains` and `sources` collections. A logo is a reported URL. `founded` has `value` and `precision`, distinct from incorporation. Sources identify the website, filing or business register, supported fields and observation/update timestamps. Employee observations retain count, measurement date, organization scope and approximation; null means unknown. Missing, null, empty and unknown fields retain their response values. An empty search is a successful result. Invalid inputs and unknown IDs raise the existing API error.
+
+Company directory social profiles contain `platform`, `url` and `handle`; unknown metadata stays null. Phone and email records use `type` for the source-reported purpose. Earlier response fields remain readable by the client.
+
+The recipe requests one candidate page, one explicitly chosen profile and directory coverage, plus a second page when a cursor is returned. Each operation uses the existing retry settings. The number-validation call remains unchanged. `lang` applies to national company-number lookup, while directory calls use the source labels.
+
+`AsyncParseAPI` exposes the same `company`, `company.id`, `company.search` and `company.coverage` calls with `await`.
+
+Discovery example: `parse.company.search(country="US", industry="0700", industry_type="sic")`
+
+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.
+
+
 ## Calls
 
 One method per endpoint, named after the route.
@@ -89,6 +119,11 @@ parse.postal.distance("28202", "10001", country="US")
 parse.address("1600 Pennsylvania Ave NW, Washington DC", country="US")
 parse.address.search("1600 Pennsylvania", country="US", postal="20500")
 parse.company("51 824 753 556", country="AU")
+parse.company.id("co_caczn6wf36hj", deep=True)
+parse.company.search(domain="about.gitlab.com")
+parse.company.search(ticker="GTLB", exchange="Nasdaq")
+parse.company.search(identifier="0001653482", authority="sec")
+parse.company.coverage()
 parse.city("charlotte", country="US")
 parse.city.id("city_mb8mbqrkz8zb")
 parse.city.search("char", country="US", limit=10)
@@ -166,7 +201,7 @@ Choose display names for one request:
 parse.country("DE", lang="fr")
 ```
 
-`lang` is optional on geography lookups and their lists/searches, Currency lookup, Language, Date, Time/Timezone, Emoji lookup/search, and unit discovery. IP, ASN, Company and NPI also accept it for their geographic labels. Codes, native names, quantities and response structure retain their meanings. Source coverage determines which labels are translated; unavailable labels use the API's documented fallback.
+`lang` is optional on geography lookups and their lists/searches, Currency lookup, Language, Date, Time/Timezone, Emoji lookup/search, and unit discovery. IP, ASN, national Company number lookup and NPI also accept it for their geographic labels. Codes, native names, quantities and response structure retain their meanings. Source coverage determines which labels are translated; unavailable labels use the API's documented fallback.
 
 The next call keeps its usual default unless it also supplies `lang`. Existing `deep` rules still apply. Date `format` and measurement `locale` remain explicit input-parsing controls.
 
@@ -389,7 +424,7 @@ before dispatch, accepted input is forwarded unchanged. Never send a full card n
 
 ## Optional detail
 
-The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, Industry and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to.deep`; only the source has `deep.next_dst`.
+The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, Company directory, Industry and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to.deep` or each `targets` item; only the source has `deep.next_dst`.
 
 ```python
 basic = parse.time("America/New_York")

{parseapi-1.8.0 → parseapi-1.9.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.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.
+This SDK 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.
 
@@ -47,6 +47,36 @@ Results are plain data. Pass a returned code or coordinate to another operation
 
 Use `parse.postal("28202", country="US", deep=True)` for US ZIP tax references. `deep.tax` names the levy and `deep.tax_rate` is a percentage, so `7.9` means 7.9%. The state, county, city and special components explain that combined rate. An exact address can differ. Country and state lookups provide their own geographic reference rates, which should not be added to the ZIP rate. `None` means unknown and `0` means known zero. Country `deep.tax_id_format` and `deep.tax_id_regex` describe registration-number format only. Use `vat` for a metered registration check with `deep` explicitly enabled.
 
+## Company directory
+
+Find candidates, then fetch the profile you selected.
+
+```python
+candidates = parse.company.search(query="GitLab", country="US", limit=5)
+selected_id = "co_caczn6wf36hj"  # Explicitly chosen after reviewing candidates.
+profile = parse.company.id(selected_id, deep=True)
+if candidates["next"] is not None:
+    next_page = parse.company.search(
+        query="GitLab", country="US", limit=5, cursor=candidates["next"]
+    )
+coverage = parse.company.coverage()
+```
+
+Use at most one selector: `query` for a name, `domain`, `ticker`, or `identifier`; country or exact industry filters also allow discovery without a selector. The API validates selectors and filters. Use `country` to scope candidates, `exchange` with a ticker, and `authority` with an identifier. Search returns `companies` and an opaque `next` cursor. Review candidate identity and match details before choosing a stable Company ID. Pass `next` as `cursor` with the same selector, filters and limit to continue that result set.
+
+Directory profiles are plain JSON data. `deep` belongs to each company in search results and adds legal/reference detail plus nullable `description`, `logo`, `founded`, and the `social_profiles`, `phone_numbers`, `email_addresses`, `domains` and `sources` collections. A logo is a reported URL. `founded` has `value` and `precision`, distinct from incorporation. Sources identify the website, filing or business register, supported fields and observation/update timestamps. Employee observations retain count, measurement date, organization scope and approximation; null means unknown. Missing, null, empty and unknown fields retain their response values. An empty search is a successful result. Invalid inputs and unknown IDs raise the existing API error.
+
+Company directory social profiles contain `platform`, `url` and `handle`; unknown metadata stays null. Phone and email records use `type` for the source-reported purpose. Earlier response fields remain readable by the client.
+
+The recipe requests one candidate page, one explicitly chosen profile and directory coverage, plus a second page when a cursor is returned. Each operation uses the existing retry settings. The number-validation call remains unchanged. `lang` applies to national company-number lookup, while directory calls use the source labels.
+
+`AsyncParseAPI` exposes the same `company`, `company.id`, `company.search` and `company.coverage` calls with `await`.
+
+Discovery example: `parse.company.search(country="US", industry="0700", industry_type="sic")`
+
+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.
+
+
 ## Calls
 
 One method per endpoint, named after the route.
@@ -70,6 +100,11 @@ parse.postal.distance("28202", "10001", country="US")
 parse.address("1600 Pennsylvania Ave NW, Washington DC", country="US")
 parse.address.search("1600 Pennsylvania", country="US", postal="20500")
 parse.company("51 824 753 556", country="AU")
+parse.company.id("co_caczn6wf36hj", deep=True)
+parse.company.search(domain="about.gitlab.com")
+parse.company.search(ticker="GTLB", exchange="Nasdaq")
+parse.company.search(identifier="0001653482", authority="sec")
+parse.company.coverage()
 parse.city("charlotte", country="US")
 parse.city.id("city_mb8mbqrkz8zb")
 parse.city.search("char", country="US", limit=10)
@@ -147,7 +182,7 @@ Choose display names for one request:
 parse.country("DE", lang="fr")
 ```
 
-`lang` is optional on geography lookups and their lists/searches, Currency lookup, Language, Date, Time/Timezone, Emoji lookup/search, and unit discovery. IP, ASN, Company and NPI also accept it for their geographic labels. Codes, native names, quantities and response structure retain their meanings. Source coverage determines which labels are translated; unavailable labels use the API's documented fallback.
+`lang` is optional on geography lookups and their lists/searches, Currency lookup, Language, Date, Time/Timezone, Emoji lookup/search, and unit discovery. IP, ASN, national Company number lookup and NPI also accept it for their geographic labels. Codes, native names, quantities and response structure retain their meanings. Source coverage determines which labels are translated; unavailable labels use the API's documented fallback.
 
 The next call keeps its usual default unless it also supplies `lang`. Existing `deep` rules still apply. Date `format` and measurement `locale` remain explicit input-parsing controls.
 
@@ -370,7 +405,7 @@ before dispatch, accepted input is forwarded unchanged. Never send a full card n
 
 ## Optional detail
 
-The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, Industry and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to.deep`; only the source has `deep.next_dst`.
+The default response answers the common task. Ask for `deep` when you need more detail about that same result. Core fields stay equal. City, Company directory, Industry and Emoji searches put detail inside each result. Postal nearby and distance put metropolitan detail beside the entity it describes. Time conversion keeps target detail in `to.deep` or each `targets` item; only the source has `deep.next_dst`.
 
 ```python
 basic = parse.time("America/New_York")

{parseapi-1.8.0 → parseapi-1.9.0}/api/public.json

@@ -453,6 +453,106 @@
       ],
       "returns": "Json"
     },
+    "company.coverage": {
+      "async": true,
+      "parameters": [],
+      "returns": "Json"
+    },
+    "company.id": {
+      "async": true,
+      "parameters": [
+        {
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "name": "id",
+          "type": "str"
+        },
+        {
+          "default": false,
+          "kind": "KEYWORD_ONLY",
+          "name": "deep",
+          "type": "bool"
+        }
+      ],
+      "returns": "Json"
+    },
+    "company.search": {
+      "async": true,
+      "parameters": [
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "query",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "domain",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "ticker",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "identifier",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "country",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "exchange",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "authority",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "limit",
+          "type": "Optional[int]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "cursor",
+          "type": "Optional[str]"
+        },
+        {
+          "default": false,
+          "kind": "KEYWORD_ONLY",
+          "name": "deep",
+          "type": "bool"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "industry",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "industry_type",
+          "type": "Optional[str]"
+        }
+      ],
+      "returns": "Json"
+    },
     "constructor": {
       "async": false,
       "parameters": [
@@ -2345,6 +2445,106 @@
       ],
       "returns": "Json"
     },
+    "company.coverage": {
+      "async": false,
+      "parameters": [],
+      "returns": "Json"
+    },
+    "company.id": {
+      "async": false,
+      "parameters": [
+        {
+          "kind": "POSITIONAL_OR_KEYWORD",
+          "name": "id",
+          "type": "str"
+        },
+        {
+          "default": false,
+          "kind": "KEYWORD_ONLY",
+          "name": "deep",
+          "type": "bool"
+        }
+      ],
+      "returns": "Json"
+    },
+    "company.search": {
+      "async": false,
+      "parameters": [
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "query",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "domain",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "ticker",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "identifier",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "country",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "exchange",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "authority",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "limit",
+          "type": "Optional[int]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "cursor",
+          "type": "Optional[str]"
+        },
+        {
+          "default": false,
+          "kind": "KEYWORD_ONLY",
+          "name": "deep",
+          "type": "bool"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "industry",
+          "type": "Optional[str]"
+        },
+        {
+          "default": null,
+          "kind": "KEYWORD_ONLY",
+          "name": "industry_type",
+          "type": "Optional[str]"
+        }
+      ],
+      "returns": "Json"
+    },
     "constructor": {
       "async": false,
       "parameters": [

{parseapi-1.8.0 → parseapi-1.9.0}/pyproject.toml

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

{parseapi-1.8.0 → parseapi-1.9.0}/src/parseapi/__init__.py

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

{parseapi-1.8.0 → parseapi-1.9.0}/src/parseapi/_client.py

@@ -7,12 +7,12 @@ import random
 import re
 import time
 from email.utils import parsedate_to_datetime
-from typing import Any, Dict, Optional, overload
+from typing import Any, Dict, Optional, Protocol, Union, overload
 from urllib.parse import quote
 
 import httpx
 
-VERSION = "1.8.0"
+VERSION = "1.9.0"
 _API_VERSION = "2.0.0"
 DEFAULT_BASE_URL = "https://api.parseapi.com"
 DEFAULT_TIMEOUT = 10.0
@@ -129,6 +129,54 @@ class _Config:
         return {"X-API-Key": self.api_key, "User-Agent": f"parseapi-python/{VERSION}", "Parse-Version": _API_VERSION}
 
 
+class _CompanySyncClassCall(Protocol):
+    def __call__(self, client: ParseAPI, /, number: str, *, country: Optional[str] = None,
+        deep: bool = False, lang: Optional[str] = None) -> Json: ...
+
+
+class _CompanyAsyncClassCall(Protocol):
+    async def __call__(self, client: AsyncParseAPI, /, number: str, *, country: Optional[str] = None,
+        deep: bool = False, lang: Optional[str] = None) -> Json: ...
+
+
+# A typed, non-data descriptor keeps the published class-level number method
+# while exposing a callable namespace to instances and static type checkers.
+class _CompanySyncDescriptor:
+    def __init__(self, lookup: _CompanySyncClassCall):
+        self._lookup = lookup
+
+    @overload
+    def __get__(self, instance: None, owner: Optional[type[Any]] = None) -> _CompanySyncClassCall: ...
+
+    @overload
+    def __get__(self, instance: ParseAPI, owner: Optional[type[Any]] = None) -> _CompanySync: ...
+
+    def __get__(self, instance: Optional[ParseAPI], owner: Optional[type[Any]] = None) -> Union[_CompanySyncClassCall, _CompanySync]:
+        if instance is None:
+            return self._lookup
+        namespace = _CompanySync(instance, self._lookup)
+        instance.__dict__["company"] = namespace
+        return namespace
+
+
+class _CompanyAsyncDescriptor:
+    def __init__(self, lookup: _CompanyAsyncClassCall):
+        self._lookup = lookup
+
+    @overload
+    def __get__(self, instance: None, owner: Optional[type[Any]] = None) -> _CompanyAsyncClassCall: ...
+
+    @overload
+    def __get__(self, instance: AsyncParseAPI, owner: Optional[type[Any]] = None) -> _CompanyAsync: ...
+
+    def __get__(self, instance: Optional[AsyncParseAPI], owner: Optional[type[Any]] = None) -> Union[_CompanyAsyncClassCall, _CompanyAsync]:
+        if instance is None:
+            return self._lookup
+        namespace = _CompanyAsync(instance, self._lookup)
+        instance.__dict__["company"] = namespace
+        return namespace
+
+
 class ParseAPI:
     """Synchronous client. `parse = ParseAPI()` reads PARSEAPI_KEY from the env."""
 
@@ -316,6 +364,7 @@ class ParseAPI:
     def vin(self, vin: str, *, deep: bool = False) -> Json:
         return self._get(f"/vin/{_seg(vin)}", {"deep": deep})
 
+    @_CompanySyncDescriptor
     def company(self, number: str, *, country: Optional[str] = None, deep: bool = False, lang: Optional[str] = None) -> Json:
         return self._get(f"/company/{_seg(number)}", {"country": country, "deep": deep, "lang": lang})
 
@@ -735,6 +784,7 @@ class AsyncParseAPI:
     async def vin(self, vin: str, *, deep: bool = False) -> Json:
         return await self._get(f"/vin/{_seg(vin)}", {"deep": deep})
 
+    @_CompanyAsyncDescriptor
     async def company(self, number: str, *, country: Optional[str] = None, deep: bool = False, lang: Optional[str] = None) -> Json:
         return await self._get(f"/company/{_seg(number)}", {"country": country, "deep": deep, "lang": lang})
 
@@ -1106,6 +1156,70 @@ class _MeasureAsync:
         """Discover reviewed units. unit filters compatible conversion targets."""
         return await self._client._get("/measure/units", {"q": query, "type": type, "unit": unit, "lang": lang})
 
+
+class _CompanySync:
+    def __init__(self, client: ParseAPI, lookup: _CompanySyncClassCall):
+        self._client = client
+        self._number_lookup = lookup
+
+    def __call__(self, number: str, *, country: Optional[str] = None, deep: bool = False, lang: Optional[str] = None) -> Json:
+        return self._number_lookup(self._client, number, country=country, deep=deep, lang=lang)
+
+    def id(self, id: str, *, deep: bool = False) -> Json:
+        """Fetch a directory profile by its stable Company ID. Deep adds profile detail."""
+        return self._client._get(f"/company/id/{_seg(id)}", {"deep": deep})
+
+    def search(self, *, query: Optional[str] = None, domain: Optional[str] = None,
+        ticker: Optional[str] = None, identifier: Optional[str] = None, country: Optional[str] = None,
+        exchange: Optional[str] = None, authority: Optional[str] = None, limit: Optional[int] = None,
+        cursor: Optional[str] = None, deep: bool = False, industry: Optional[str] = None,
+        industry_type: Optional[str] = None) -> Json:
+        """Use at most one selector, or discover by country, industry or selected registration.
+        Pair a four-digit SIC industry string with industry_type="sic".
+        Administrative registration status does not establish current business activity.
+        The API validates selectors and filters. Review candidates before choosing an ID.
+        Pass a returned cursor with the same selector and filters. Deep belongs to each result.
+        """
+        return self._client._get("/company", {"q": query, "domain": domain, "ticker": ticker,
+            "identifier": identifier, "country": country, "exchange": exchange, "authority": authority,
+            "limit": limit, "cursor": cursor, "deep": deep, "industry": industry, "industry_type": industry_type})
+
+    def coverage(self) -> Json:
+        """Read the directory edition and source coverage."""
+        return self._client._get("/company/directory/coverage")
+
+
+class _CompanyAsync:
+    def __init__(self, client: AsyncParseAPI, lookup: _CompanyAsyncClassCall):
+        self._client = client
+        self._number_lookup = lookup
+
+    async def __call__(self, number: str, *, country: Optional[str] = None, deep: bool = False, lang: Optional[str] = None) -> Json:
+        return await self._number_lookup(self._client, number, country=country, deep=deep, lang=lang)
+
+    async def id(self, id: str, *, deep: bool = False) -> Json:
+        """Fetch a directory profile by its stable Company ID. Deep adds profile detail."""
+        return await self._client._get(f"/company/id/{_seg(id)}", {"deep": deep})
+
+    async def search(self, *, query: Optional[str] = None, domain: Optional[str] = None,
+        ticker: Optional[str] = None, identifier: Optional[str] = None, country: Optional[str] = None,
+        exchange: Optional[str] = None, authority: Optional[str] = None, limit: Optional[int] = None,
+        cursor: Optional[str] = None, deep: bool = False, industry: Optional[str] = None,
+        industry_type: Optional[str] = None) -> Json:
+        """Use at most one selector, or discover by country, industry or selected registration.
+        Pair a four-digit SIC industry string with industry_type="sic".
+        Administrative registration status does not establish current business activity.
+        The API validates selectors and filters. Review candidates before choosing an ID.
+        Pass a returned cursor with the same selector and filters. Deep belongs to each result.
+        """
+        return await self._client._get("/company", {"q": query, "domain": domain, "ticker": ticker,
+            "identifier": identifier, "country": country, "exchange": exchange, "authority": authority,
+            "limit": limit, "cursor": cursor, "deep": deep, "industry": industry, "industry_type": industry_type})
+
+    async def coverage(self) -> Json:
+        """Read the directory edition and source coverage."""
+        return await self._client._get("/company/directory/coverage")
+
 def _time_source(timezone, **values):
     primary = [values.get(key) for key in ("ip", "city", "iata", "icao", "unlocode", "address") if values.get(key) is not None]
     present = any(value is not None for value in values.values())

parseapi-1.9.0/tests/test_company_directory.py

@@ -0,0 +1,160 @@
+import asyncio
+import inspect
+import json
+import re
+from pathlib import Path
+
+import httpx
+import pytest
+from parseapi import ParseAPI, AsyncParseAPI, ParseAPIError
+
+BASE = {"id": "co_caczn6wf36hj", "name": "GitLab", "country": "US", "website": None, "listings": [], "address": None, "future": {"unknown": None}}
+RICH = {"description": None, "logo": "https://example.com/logo.svg", "socials": [], "founded": {"value": "2011", "precision": "future_precision"}, "sources": [{"type": "future_source", "url": "https://example.com/", "fields": ["logo"], "observed_at": None, "updated_at": None, "future": True}], "parent": None, "future": [None, {}]}
+
+
+def exercise(async_client, operations, responses, **config):
+    calls = []
+    queue = list(responses)
+    def handler(request):
+        calls.append(request)
+        status, body = queue.pop(0)
+        return httpx.Response(status, json=body, headers={"Retry-After": "0"})
+    async def run():
+        cls = AsyncParseAPI if async_client else ParseAPI
+        client = cls("test_company", transport=httpx.MockTransport(handler), **config)
+        results = []
+        try:
+            for operation in operations:
+                value = operation(client)
+                results.append(await value if inspect.isawaitable(value) else value)
+        finally:
+            value = client.close()
+            if inspect.isawaitable(value):
+                await value
+        return results
+    return asyncio.run(run()), calls
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+@pytest.mark.parametrize("operation,path,params", [
+    (lambda p: p.company.id("co_/é?+", deep=True), "/company/id/co_%2F%C3%A9%3F%2B", {"deep": "true"}),
+    (lambda p: p.company.id("co_caczn6wf36hj"), "/company/id/co_caczn6wf36hj", {}),
+    (lambda p: p.company.search(query="Café & Co", country="us", limit=2, cursor="a+/=?&", deep=True), "/company", {"q": "Café & Co", "country": "us", "limit": "2", "cursor": "a+/=?&", "deep": "true"}),
+    (lambda p: p.company.search(domain="WWW.Example.COM."), "/company", {"domain": "WWW.Example.COM."}),
+    (lambda p: p.company.search(ticker="BRK/B", exchange="X/Y"), "/company", {"ticker": "BRK/B", "exchange": "X/Y"}),
+    (lambda p: p.company.search(identifier="0000/123", authority="US/SEC", country="US"), "/company", {"identifier": "0000/123", "authority": "US/SEC", "country": "US"}),
+    (lambda p: p.company.search(query="", limit=0, cursor=""), "/company", {"q": "", "limit": "0", "cursor": ""}),
+    (lambda p: p.company.search(country="US"), "/company", {"country": "US"}),
+    (lambda p: p.company.search(industry="0700", industry_type="sic"), "/company", {"industry": "0700", "industry_type": "sic"}),
+    (lambda p: p.company.search(country="US", industry="0700", industry_type="sic", cursor="opaque+/=", limit=2, deep=True), "/company", {"country": "US", "industry": "0700", "industry_type": "sic", "cursor": "opaque+/=", "limit": "2", "deep": "true"}),
+    (lambda p: p.company.search(query="Example", industry="0700", industry_type="sic", deep=False), "/company", {"q": "Example", "industry": "0700", "industry_type": "sic"}),
+    (lambda p: p.company.coverage(), "/company/directory/coverage", {}),
+])
+def test_routes_encoding_and_direct_request(async_client, operation, path, params):
+    body = {"companies": [], "next": None, "future": None}
+    results, calls = exercise(async_client, [operation], [(200, body)], timeout=1.25)
+    assert results == [body]
+    assert len(calls) == 1
+    assert calls[0].url.raw_path.split(b"?")[0].decode() == path
+    assert dict(calls[0].url.params) == params
+    assert calls[0].headers["Parse-Version"] == "2.0.0"
+    assert calls[0].headers["X-API-Key"] == "test_company"
+    assert calls[0].extensions["timeout"]["read"] == 1.25
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+def test_plain_profiles_deep_triad_pagination_and_coverage(async_client):
+    profiles = [BASE, {**BASE, "deep": {}}, {**BASE, "deep": RICH}, {**BASE, "deep": {"description": None, "logo": None, "socials": None, "founded": None, "sources": None}}]
+    page = {"companies": [{**p, "match": {"field": "future_field", "value": None}} for p in profiles], "next": "opaque+/=", "future": None}
+    empty = {"companies": [], "next": None}
+    coverage = {"scope": "future_scope", "companies": 0, "countries": [], "future": None}
+    operations = [lambda p: p.company.id(BASE["id"]), lambda p: p.company.id(BASE["id"], deep=True), lambda p: p.company.id(BASE["id"], deep=True), lambda p: p.company.id(BASE["id"], deep=True), lambda p: p.company.search(query="GitLab", deep=True, limit=4), lambda p: p.company.search(query="GitLab", deep=True, limit=4, cursor=page["next"]), lambda p: p.company.coverage()]
+    expected = profiles + [page, empty, coverage]
+    results, calls = exercise(async_client, operations, [(200, item) for item in expected])
+    assert results == expected
+    assert len(calls) == len(operations)
+    assert dict(calls[5].url.params) == {"q": "GitLab", "limit": "4", "cursor": "opaque+/=", "deep": "true"}
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+@pytest.mark.parametrize("status,operation", [(400, lambda p: p.company.search(query="A", domain="B")), (400, lambda p: p.company.search()), (404, lambda p: p.company.id("co_unknown"))])
+def test_errors_remain_errors_with_api_validation(async_client, status, operation):
+    code = "invalid_request" if status == 400 else "not_found"
+    with pytest.raises(ParseAPIError) as error:
+        exercise(async_client, [operation], [(status, {"code": code, "message": "source error", "docs": None, "request_id": "r1"})])
+    assert (error.value.status, error.value.code, error.value.request_id) == (status, code, "r1")
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+def test_company_number_callable_and_class_method_are_preserved(async_client):
+    cls = AsyncParseAPI if async_client else ParseAPI
+    body = {"valid": True, "company": "51824753556", "deep": {"activity": None}}
+    results, calls = exercise(async_client, [lambda p: p.company("51 824 753 556", country="AU", deep=True, lang="fr"), lambda p: cls.company(p, "51 824 753 556", country="AU", deep=True, lang="fr")], [(200, body)] * 2)
+    assert results == [body, body]
+    assert str(calls[0].url) == str(calls[1].url) == "https://api.parseapi.com/company/51%20824%20753%20556?country=AU&deep=true&lang=fr"
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+def test_directory_uses_existing_retry_controls(async_client):
+    result, calls = exercise(async_client, [lambda p: p.company.id(BASE["id"], deep=True)], [(503, {}), (503, {}), (200, BASE)])
+    assert result == [BASE] and len(calls) == 3
+    with pytest.raises(ParseAPIError):
+        exercise(async_client, [lambda p: p.company.coverage()], [(503, {})], retries=0)
+
+
+def test_sync_async_signatures_and_no_directory_lang():
+    with ParseAPI("fixture") as sync:
+        assert sync.company is sync.company
+        async_client = AsyncParseAPI("fixture")
+        try:
+            assert async_client.company is async_client.company
+            for name in ("__call__", "id", "search", "coverage"):
+                assert inspect.signature(getattr(sync.company, name)) == inspect.signature(getattr(async_client.company, name))
+            for method, arguments in [(sync.company.id, (BASE["id"],)), (sync.company.search, ())]:
+                with pytest.raises(TypeError):
+                    method(*arguments, lang="fr")
+        finally:
+            asyncio.run(async_client.close())
+
+
+def test_readme_recipe_uses_explicit_selection_and_returned_cursor():
+    section = (Path(__file__).resolve().parents[1] / "README.md").read_text().split("## Company directory\n", 1)[1]
+    code = re.search(r"```python\n(.*?)```", section, re.S).group(1)
+    responses = [{"companies": [BASE], "next": "opaque+/="}, {**BASE, "deep": RICH}, {"companies": [], "next": None}, {"scope": "sample"}]
+    calls = []
+    def handler(request):
+        calls.append(request)
+        return httpx.Response(200, json=responses.pop(0))
+    with ParseAPI("fixture", transport=httpx.MockTransport(handler)) as parse:
+        exec(compile(code, "README.md", "exec"), {"parse": parse})
+    assert len(calls) == 4
+    assert calls[1].url.path == "/company/id/co_caczn6wf36hj"
+    assert calls[2].url.params["cursor"] == "opaque+/="
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+def test_employee_observations_preserve_zero_false_dates_scope_and_missing(async_client):
+    values = [
+        {}, {"employees": None},
+        {"employees": {"count": 0, "as_of": "2025-12-31", "scope": "legal_entity", "method": "reported", "approximate": False}},
+        {"employees": {"count": 12500, "as_of": "2026-06-30", "scope": "consolidated_group", "method": "reported", "approximate": True}},
+        {"employees": {"count": 7, "as_of": "2026-01-15", "scope": "future_scope", "method": "future_method", "approximate": False, "future": None}},
+    ]
+    for deep in values:
+        profile = {**BASE, "deep": deep}
+        page = {"companies": [{**profile, "match": {"field": "name", "value": BASE["name"]}}], "next": None}
+        operations = [lambda p: p.company.id(BASE["id"], deep=True), lambda p: p.company.search(query=BASE["name"], deep=True)]
+        results, calls = exercise(async_client, operations, [(200, profile), (200, page)])
+        assert results == [profile, page]
+        assert ("employees" in results[0]["deep"]) == ("employees" in deep)
+        assert len(calls) == 2
+
+
+@pytest.mark.parametrize("async_client", [False, True])
+def test_registrations_preserve_source_roles_nulls_and_leading_zeros(async_client):
+    registration = json.loads(r'{"authority":"RA000599","number":"0001234567","jurisdiction":{"country":"US","state":"CO"},"role":"domestic","legal_form":{"code":"DNC","name":"Domestic Non-profit Corporation"},"status":"Good Standing","formation_date":"2004-02-29","address":{"kind":"principal","line1":"12 Main St.","line2":"Suite 2","city":"Example","state":"CO","postal":"00123-0001","country_raw":"US"},"future":"retained"}')
+    for deep in [{}, {"registrations": None}, {"registrations": []}, {"registrations": [registration]}, {"registrations": [{**registration, "role": "future_role", "formation_date": None, "address": None}]}]:
+        profile = {**BASE, "deep": deep}
+        page = {"companies": [{**profile, "match": {"field": "identifier", "value": registration["number"]}}], "next": None}
+        results, calls = exercise(async_client, [lambda p: p.company.id(BASE["id"], deep=True), lambda p: p.company.search(identifier=registration["number"], authority=registration["authority"], deep=True)], [(200, profile), (200, page)])
+        assert results == [profile, page] and len(calls) == 2

parseapi-1.9.0/tests/typing_company_directory.py

@@ -0,0 +1,32 @@
+"""Compile-only consumer for the typed callable namespace and previous methods.
+
+pyright --pythonpath .venv/bin/python tests/typing_company_directory.py
+No functions in this fixture are invoked.
+"""
+from parseapi import ParseAPI, AsyncParseAPI
+
+
+def sync_directory(parse: ParseAPI) -> None:
+    number_lookup = ParseAPI.company
+    number_lookup(parse, "51 824 753 556", country="AU", deep=True, lang="fr")
+    lookup = parse.company
+    lookup("51 824 753 556", country="AU", deep=True, lang="fr")
+    lookup.id("co_caczn6wf36hj", deep=True)
+    lookup.search(query="GitLab", country="US", limit=5, cursor="opaque", deep=True)
+    lookup.search(domain="about.gitlab.com")
+    lookup.search(ticker="GTLB", exchange="Nasdaq")
+    lookup.search(identifier="0001653482", authority="sec")
+    lookup.coverage()
+
+
+async def async_directory(parse: AsyncParseAPI) -> None:
+    number_lookup = AsyncParseAPI.company
+    await number_lookup(parse, "51 824 753 556", country="AU", deep=True, lang="fr")
+    lookup = parse.company
+    await lookup("51 824 753 556", country="AU", deep=True, lang="fr")
+    await lookup.id("co_caczn6wf36hj", deep=True)
+    await lookup.search(query="GitLab", country="US", limit=5, cursor="opaque", deep=True)
+    await lookup.search(domain="about.gitlab.com")
+    await lookup.search(ticker="GTLB", exchange="Nasdaq")
+    await lookup.search(identifier="0001653482", authority="sec")
+    await lookup.coverage()