ares-client 0.1.0__tar.gz

ares_client-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: ares-client
+Version: 0.1.0
+Summary: Typed async client for ARES (Administrativní registr ekonomických subjektů), the Czech business registry API at ares.gov.cz
+Keywords: ares,ares.gov.cz,ico,ičo,dic,dič,rejstřík,czech business registry
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pydantic :: 2
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyrate-limiter>=3.7
+Requires-Dist: tenacity>=9.0
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/jogobeny/ares-client
+Project-URL: Issues, https://github.com/jogobeny/ares-client/issues
+Project-URL: ARES API, https://ares.gov.cz/swagger-ui/
+Description-Content-Type: text/markdown
+
+# ares-client
+
+Typed async client for **ARES** (Administrativní registr ekonomických subjektů), the Czech business registry API at [ares.gov.cz](https://ares.gov.cz/swagger-ui/).
+
+- Fully typed: pydantic v2 models ([`models.py`]) and a typed exception tree ([`exceptions.py`]).
+- The client retries failed requests with exponential backoff ([`client.py`]). It also obeys the ARES limit of [500 requests each minute][limits].
+- The client validates an IČO locally ([`ico.py`]). Invalid input does not go to the network.
+
+The library is **async only**. In synchronous code, wrap each call in `asyncio.run(...)`.
+
+## Installation
+
+The library needs **Python 3.12+**.
+
+```bash
+uv add ares-client   # or: pip install ares-client
+```
+
+## Quick start
+
+```python
+import asyncio
+
+from ares_client import AresClient
+
+
+async def main():
+    async with AresClient() as ares:
+        subject = await ares.get_subject("27082440")  # an int is also valid, zeros are added
+
+    print(subject.obchodni_jmeno)  # Alza.cz a.s.
+    print(subject.sidlo.textova_adresa)  # Jankovcova 1522/53, Holešovice, 17000 Praha 7
+    print(subject.dic)  # CZ27082440
+    print(subject.seznam_registraci.dph)  # SourceState.AKTIVNI
+    print(subject.datum_zaniku)  # None — the subject continues
+    print(subject.datum_vzniku)  # datetime.date(2003, 8, 26)
+
+
+asyncio.run(main())
+```
+
+## Client methods
+
+| Method | Description |
+|---|---|
+| `get_subject(ico)` | Get one subject. An unknown IČO causes `SubjectNotFound`. |
+| `search(filter)` | Get the subjects that match a filter (`SubjectList`). |
+| `search_code_lists(filter)` | Get the ARES code lists — the translations of codes to names. |
+
+```python
+# search
+page = await ares.search(SubjectFilter(obchodni_jmeno="Alza", pocet=10))
+print(page.pocet_celkem, [s.obchodni_jmeno for s in page.ekonomicke_subjekty])
+
+# ARES never returns more than 1 000 results, so one request can hold them all
+page = await ares.search(SubjectFilter(obchodni_jmeno="Alza", pocet=1000))
+```
+
+You can also make the filter first and send it later:
+
+```python
+from ares_client import AddressFilter, SubjectFilter
+
+filter = SubjectFilter(
+    pravni_forma=["112"],  # s.r.o. (limited liability company)
+    sidlo=AddressFilter(kod_obce=554782),  # Praha (RÚIAN code)
+)
+page = await ares.search(filter)
+```
+
+## The `Subject` model
+
+The full model, with the same field names and structure as the ARES schema, is in [`models.py`]. For example, the state of the subject in the source registers:
+
+```python
+from ares_client import SourceState
+
+if subject.seznam_registraci.rzp is SourceState.AKTIVNI:
+    ...  # the subject has an active trade licence
+```
+
+## Errors
+
+The errors that ARES reports are typed ([`exceptions.py`]):
+
+```
+AresError
+├─ InvalidIco             # fails locally, without an API call
+└─ AresAPIError           # has kod, sub_kod, popis, status_code
+   ├─ SubjectNotFound
+   ├─ InvalidRequest
+   │  └─ TooManyResults   # has .found — the number of matched subjects
+   └─ AresServerError
+```
+
+**The client does not wrap network errors.** A timeout or a refused connection is not an ARES error. These errors keep their httpx form. Thus the caller sees the true cause and can use the usual httpx logic:
+
+```python
+import httpx
+from ares_client import AresClient, AresError
+
+try:
+    subject = await ares.get_subject("27082440")
+except httpx.TimeoutException:
+    ...  # the connection was too slow, try again later
+except AresError:
+    ...  # ARES replied with an error
+```
+
+The client retries network errors (`httpx.TransportError`) first. Only the last error goes to the caller.
+
+## ARES limits that the client knows
+
+| Limit | Behavior |
+|---|---|
+| Max **1 000** results for each query | ARES refuses a wider query (it does **not** cut the result). You get `TooManyResults` with the match count |
+| Max **100 IČO** values in a filter | ARES refuses more (`InvalidRequest`) |
+| [**500 requests each minute**][limits] | The client obeys the limit with [`pyrate-limiter`]. When the window is full, the request **waits**. It does not fail. ARES sends no rate-limit headers, so a client cannot react to an error |
+| An IČO has exactly 8 digits | `normalize_ico()` adds the leading zeros. A character that is not a digit is an error |
+| An empty filter | ARES refuses it: `InvalidRequest` with `sub_kod=VSTUP_PRAZDNY` |
+
+The client retries a request after `408`, `429`, `5xx`, and network errors (exponential backoff with jitter). It does not retry `4xx` input errors. A retry cannot help there.
+
+## Important notes
+
+- **`pravni_forma`, `cz_nace`, and `financni_urad` are code-list codes, not names** (`"112"` = s.r.o.). Use `search_code_lists()` to translate the codes to names.
+- **Almost all fields are optional.** The Ministry of Finance has no `datum_vzniku`. A self-employed person frequently has no `dic`.
+- **Read the VAT registration from `seznam_registraci.dph`.** This is the ARES state, not the [VAT payer register][adisreg] of the Financial Administration. For tax decisions (for example the § 109 liability), use that register.
+- ARES contains only Czech registrations. It has no foreign subjects.
+
+## Resources
+
+- [Swagger UI](https://ares.gov.cz/swagger-ui/) · [OpenAPI spec][openapi]
+- [Technical documentation, MF (PDF)][mf-pdf]
+- [Terms of use](https://data.mf.gov.cz/api/ares.html)
+
+[`models.py`]: https://github.com/jogobeny/ares-client/blob/main/src/ares_client/models.py
+[`exceptions.py`]: https://github.com/jogobeny/ares-client/blob/main/src/ares_client/exceptions.py
+[`client.py`]: https://github.com/jogobeny/ares-client/blob/main/src/ares_client/client.py
+[`ico.py`]: https://github.com/jogobeny/ares-client/blob/main/src/ares_client/ico.py
+[openapi]: https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/v3/api-docs
+[limits]: https://ares.gov.cz/stranky/podminky-provozu
+[adisreg]: https://adisspr.mfcr.cz/dpr/DphReg
+[`pyrate-limiter`]: https://github.com/vutran1710/PyrateLimiter
+[mf-pdf]: https://mf.gov.cz/assets/attachments/2023-08-01_ARES-Technicka-dokumentace-Katalog-verejnych-sluzeb_v07.pdf

ares_client-0.1.0/README.md

@@ -0,0 +1,145 @@
+# ares-client
+
+Typed async client for **ARES** (Administrativní registr ekonomických subjektů), the Czech business registry API at [ares.gov.cz](https://ares.gov.cz/swagger-ui/).
+
+- Fully typed: pydantic v2 models ([`models.py`]) and a typed exception tree ([`exceptions.py`]).
+- The client retries failed requests with exponential backoff ([`client.py`]). It also obeys the ARES limit of [500 requests each minute][limits].
+- The client validates an IČO locally ([`ico.py`]). Invalid input does not go to the network.
+
+The library is **async only**. In synchronous code, wrap each call in `asyncio.run(...)`.
+
+## Installation
+
+The library needs **Python 3.12+**.
+
+```bash
+uv add ares-client   # or: pip install ares-client
+```
+
+## Quick start
+
+```python
+import asyncio
+
+from ares_client import AresClient
+
+
+async def main():
+    async with AresClient() as ares:
+        subject = await ares.get_subject("27082440")  # an int is also valid, zeros are added
+
+    print(subject.obchodni_jmeno)  # Alza.cz a.s.
+    print(subject.sidlo.textova_adresa)  # Jankovcova 1522/53, Holešovice, 17000 Praha 7
+    print(subject.dic)  # CZ27082440
+    print(subject.seznam_registraci.dph)  # SourceState.AKTIVNI
+    print(subject.datum_zaniku)  # None — the subject continues
+    print(subject.datum_vzniku)  # datetime.date(2003, 8, 26)
+
+
+asyncio.run(main())
+```
+
+## Client methods
+
+| Method | Description |
+|---|---|
+| `get_subject(ico)` | Get one subject. An unknown IČO causes `SubjectNotFound`. |
+| `search(filter)` | Get the subjects that match a filter (`SubjectList`). |
+| `search_code_lists(filter)` | Get the ARES code lists — the translations of codes to names. |
+
+```python
+# search
+page = await ares.search(SubjectFilter(obchodni_jmeno="Alza", pocet=10))
+print(page.pocet_celkem, [s.obchodni_jmeno for s in page.ekonomicke_subjekty])
+
+# ARES never returns more than 1 000 results, so one request can hold them all
+page = await ares.search(SubjectFilter(obchodni_jmeno="Alza", pocet=1000))
+```
+
+You can also make the filter first and send it later:
+
+```python
+from ares_client import AddressFilter, SubjectFilter
+
+filter = SubjectFilter(
+    pravni_forma=["112"],  # s.r.o. (limited liability company)
+    sidlo=AddressFilter(kod_obce=554782),  # Praha (RÚIAN code)
+)
+page = await ares.search(filter)
+```
+
+## The `Subject` model
+
+The full model, with the same field names and structure as the ARES schema, is in [`models.py`]. For example, the state of the subject in the source registers:
+
+```python
+from ares_client import SourceState
+
+if subject.seznam_registraci.rzp is SourceState.AKTIVNI:
+    ...  # the subject has an active trade licence
+```
+
+## Errors
+
+The errors that ARES reports are typed ([`exceptions.py`]):
+
+```
+AresError
+├─ InvalidIco             # fails locally, without an API call
+└─ AresAPIError           # has kod, sub_kod, popis, status_code
+   ├─ SubjectNotFound
+   ├─ InvalidRequest
+   │  └─ TooManyResults   # has .found — the number of matched subjects
+   └─ AresServerError
+```
+
+**The client does not wrap network errors.** A timeout or a refused connection is not an ARES error. These errors keep their httpx form. Thus the caller sees the true cause and can use the usual httpx logic:
+
+```python
+import httpx
+from ares_client import AresClient, AresError
+
+try:
+    subject = await ares.get_subject("27082440")
+except httpx.TimeoutException:
+    ...  # the connection was too slow, try again later
+except AresError:
+    ...  # ARES replied with an error
+```
+
+The client retries network errors (`httpx.TransportError`) first. Only the last error goes to the caller.
+
+## ARES limits that the client knows
+
+| Limit | Behavior |
+|---|---|
+| Max **1 000** results for each query | ARES refuses a wider query (it does **not** cut the result). You get `TooManyResults` with the match count |
+| Max **100 IČO** values in a filter | ARES refuses more (`InvalidRequest`) |
+| [**500 requests each minute**][limits] | The client obeys the limit with [`pyrate-limiter`]. When the window is full, the request **waits**. It does not fail. ARES sends no rate-limit headers, so a client cannot react to an error |
+| An IČO has exactly 8 digits | `normalize_ico()` adds the leading zeros. A character that is not a digit is an error |
+| An empty filter | ARES refuses it: `InvalidRequest` with `sub_kod=VSTUP_PRAZDNY` |
+
+The client retries a request after `408`, `429`, `5xx`, and network errors (exponential backoff with jitter). It does not retry `4xx` input errors. A retry cannot help there.
+
+## Important notes
+
+- **`pravni_forma`, `cz_nace`, and `financni_urad` are code-list codes, not names** (`"112"` = s.r.o.). Use `search_code_lists()` to translate the codes to names.
+- **Almost all fields are optional.** The Ministry of Finance has no `datum_vzniku`. A self-employed person frequently has no `dic`.
+- **Read the VAT registration from `seznam_registraci.dph`.** This is the ARES state, not the [VAT payer register][adisreg] of the Financial Administration. For tax decisions (for example the § 109 liability), use that register.
+- ARES contains only Czech registrations. It has no foreign subjects.
+
+## Resources
+
+- [Swagger UI](https://ares.gov.cz/swagger-ui/) · [OpenAPI spec][openapi]
+- [Technical documentation, MF (PDF)][mf-pdf]
+- [Terms of use](https://data.mf.gov.cz/api/ares.html)
+
+[`models.py`]: https://github.com/jogobeny/ares-client/blob/main/src/ares_client/models.py
+[`exceptions.py`]: https://github.com/jogobeny/ares-client/blob/main/src/ares_client/exceptions.py
+[`client.py`]: https://github.com/jogobeny/ares-client/blob/main/src/ares_client/client.py
+[`ico.py`]: https://github.com/jogobeny/ares-client/blob/main/src/ares_client/ico.py
+[openapi]: https://ares.gov.cz/ekonomicke-subjekty-v-be/rest/v3/api-docs
+[limits]: https://ares.gov.cz/stranky/podminky-provozu
+[adisreg]: https://adisspr.mfcr.cz/dpr/DphReg
+[`pyrate-limiter`]: https://github.com/vutran1710/PyrateLimiter
+[mf-pdf]: https://mf.gov.cz/assets/attachments/2023-08-01_ARES-Technicka-dokumentace-Katalog-verejnych-sluzeb_v07.pdf

ares_client-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "ares-client"
+version = "0.1.0"
+description = "Typed async client for ARES (Administrativní registr ekonomických subjektů), the Czech business registry API at ares.gov.cz"
+readme = "README.md"
+license = "MIT"
+keywords = [
+    "ares",
+    "ares.gov.cz",
+    "ico",
+    "ičo",
+    "dic",
+    "dič",
+    "rejstřík",
+    "czech business registry",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Framework :: Pydantic :: 2",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "pyrate-limiter>=3.7",
+    "tenacity>=9.0",
+]
+
+[project.urls]
+Repository = "https://github.com/jogobeny/ares-client"
+Issues = "https://github.com/jogobeny/ares-client/issues"
+"ARES API" = "https://ares.gov.cz/swagger-ui/"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.16",
+    "basedpyright>=1.31",
+    "pytest-cov>=7.1.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+addopts = "-m 'not live'"
+markers = ["live: queries the production ARES API (requires network)"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+extend-select = ["W505"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[tool.basedpyright]
+pythonVersion = "3.12"
+extraPaths = ["."]
+
+[[tool.basedpyright.executionEnvironments]]
+root = "tests"
+reportUnknownArgumentType = false
+reportUnknownMemberType = false
+reportUnusedFunction = false

ares_client-0.1.0/pyproject.toml.orig

@@ -0,0 +1,77 @@
+[project]
+name = "ares-client"
+version = "0.1.0"
+description = "Typed async client for ARES (Administrativní registr ekonomických subjektů), the Czech business registry API at ares.gov.cz"
+readme = "README.md"
+license = "MIT"
+keywords = [
+    "ares",
+    "ares.gov.cz",
+    "ico",
+    "ičo",
+    "dic",
+    "dič",
+    "rejstřík",
+    "czech business registry",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Framework :: Pydantic :: 2",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "pyrate-limiter>=3.7",
+    "tenacity>=9.0",
+]
+
+[project.urls]
+Repository = "https://github.com/jogobeny/ares-client"
+Issues = "https://github.com/jogobeny/ares-client/issues"
+"ARES API" = "https://ares.gov.cz/swagger-ui/"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.16",
+    "basedpyright>=1.31",
+    "pytest-cov>=7.1.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+addopts = "-m 'not live'"
+markers = ["live: queries the production ARES API (requires network)"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+extend-select = ["W505"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 100
+
+[tool.basedpyright]
+pythonVersion = "3.12"
+extraPaths = ["."]
+
+[[tool.basedpyright.executionEnvironments]]
+root = "tests"
+reportUnknownArgumentType = false
+reportUnknownMemberType = false
+reportUnusedFunction = false

ares_client-0.1.0/src/ares_client/__init__.py

@@ -0,0 +1,52 @@
+from importlib.metadata import version
+
+from .client import AresClient
+from .exceptions import (
+    AresAPIError,
+    AresError,
+    AresServerError,
+    InvalidIco,
+    InvalidRequest,
+    SubjectNotFound,
+    TooManyResults,
+)
+from .filters import AddressFilter, CodeListFilter, SubjectFilter
+from .models import (
+    Address,
+    CodeList,
+    CodeListItem,
+    CodeListItemName,
+    CodeLists,
+    DeliveryAddress,
+    Registrations,
+    SourceState,
+    Subject,
+    SubjectList,
+)
+
+__version__ = version("ares-client")
+
+__all__ = [
+    "Address",
+    "AddressFilter",
+    "AresAPIError",
+    "AresClient",
+    "AresError",
+    "AresServerError",
+    "CodeList",
+    "CodeListFilter",
+    "CodeListItem",
+    "CodeListItemName",
+    "CodeLists",
+    "DeliveryAddress",
+    "InvalidIco",
+    "InvalidRequest",
+    "Registrations",
+    "SourceState",
+    "Subject",
+    "SubjectFilter",
+    "SubjectList",
+    "SubjectNotFound",
+    "TooManyResults",
+    "__version__",
+]

ares_client-0.1.0/src/ares_client/_transport.py

@@ -0,0 +1,89 @@
+import re
+from typing import Final
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from .exceptions import (
+    AresAPIError,
+    AresServerError,
+    InvalidRequest,
+    SubjectNotFound,
+    TooManyResults,
+)
+from .models import AresModel
+
+_SUBJECTS_PATH: Final = "/ekonomicke-subjekty"
+_CODE_LISTS_PATH: Final = "/ciselniky-nazevniky"
+_RETRY_STATUSES: Final = frozenset({408, 429, 500, 502, 503, 504})
+_FOUND_COUNT = re.compile(
+    r"\((\d[\d\s  ]*)\)"
+)  # "Zadaný dotaz vrací příliš mnoho výsledků (57 825)."
+
+
+def subject_url(base_url: str, ico: str):
+    return f"{base_url.rstrip('/')}{_SUBJECTS_PATH}/{ico}"
+
+
+def search_url(base_url: str):
+    return f"{base_url.rstrip('/')}{_SUBJECTS_PATH}/vyhledat"
+
+
+def code_list_search_url(base_url: str):
+    return f"{base_url.rstrip('/')}{_CODE_LISTS_PATH}/vyhledat"
+
+
+def should_retry_status(status: int):
+    return status in _RETRY_STATUSES
+
+
+class _ErrorBody(AresModel):
+    """The `{kod, popis, subKod}` object ARES returns with every error status."""
+
+    kod: str | None = None
+    popis: str | None = None
+    sub_kod: str | None = None
+
+
+def error_from_response(status: int, content: bytes):
+    """Translate an ARES error response into the matching exception."""
+    try:
+        body = _ErrorBody.model_validate_json(content)
+    except ValidationError:
+        body = _ErrorBody()
+
+    popis = body.popis or f"ARES returned HTTP {status}"
+
+    if status == 404 or body.kod == "NENALEZENO":
+        return SubjectNotFound(popis, status_code=status, kod=body.kod, sub_kod=body.sub_kod)
+
+    if body.sub_kod == "VYSTUP_PRILIS_MNOHO_VYSLEDKU":
+        match = _FOUND_COUNT.search(popis)
+        return TooManyResults(
+            popis,
+            status_code=status,
+            kod=body.kod,
+            sub_kod=body.sub_kod,
+            found=int(re.sub(r"\D", "", match.group(1))) if match else None,
+        )
+
+    if status >= 500 or body.kod == "OBECNA_CHYBA":
+        return AresServerError(popis, status_code=status, kod=body.kod, sub_kod=body.sub_kod)
+
+    if status == 400 or body.kod == "CHYBA_VSTUPU":
+        return InvalidRequest(popis, status_code=status, kod=body.kod, sub_kod=body.sub_kod)
+
+    return AresAPIError(popis, status_code=status, kod=body.kod, sub_kod=body.sub_kod)
+
+
+def parse_response[T: BaseModel](model: type[T], response: httpx.Response):
+    """Parse a successful response into `model`, or raise the matching `AresAPIError`."""
+    if response.status_code >= 400:
+        raise error_from_response(response.status_code, response.content)
+    try:
+        return model.model_validate_json(response.content)
+    except ValidationError as exc:
+        raise AresServerError(
+            "ARES returned a response that does not match the expected schema",
+            status_code=response.status_code,
+        ) from exc

ares_client-0.1.0/src/ares_client/client.py

@@ -0,0 +1,181 @@
+from typing import cast
+
+import httpx
+from pydantic import BaseModel
+from pyrate_limiter import Duration, Limiter, Rate
+from tenacity import (
+    AsyncRetrying,
+    RetryCallState,
+    retry_if_exception_type,
+    retry_if_result,
+    stop_after_attempt,
+    wait_exponential_jitter,
+)
+
+from ._transport import (
+    code_list_search_url,
+    parse_response,
+    search_url,
+    should_retry_status,
+    subject_url,
+)
+from .filters import CodeListFilter, SubjectFilter
+from .ico import normalize_ico
+from .models import CodeLists, Subject, SubjectList
+
+_WAIT = wait_exponential_jitter(initial=0.5, max=8.0)
+_BASE_URL = "https://ares.gov.cz/ekonomicke-subjekty-v-be/rest"
+_DEFAULT_TIMEOUT = 10.0
+_RATE = Rate(500, Duration.MINUTE)  # https://ares.gov.cz/stranky/podminky-provozu
+
+
+def _return_last_value(retry_state: RetryCallState):
+    """Return the final attempt. Do not let tenacity raise `RetryError`.
+
+    With the response available, `parse_response` makes the correct
+    `AresAPIError` from it. A transport failure keeps its httpx form, because
+    `outcome.result()` raises the error from the attempt again.
+
+    https://tenacity.readthedocs.io/en/latest/index.html#custom-callbacks
+    """
+    assert retry_state.outcome is not None
+    return cast("httpx.Response", retry_state.outcome.result())
+
+
+def _is_retryable(response: httpx.Response):
+    return should_retry_status(response.status_code)
+
+
+_RETRY_CONDITION = retry_if_exception_type(httpx.TransportError) | retry_if_result(_is_retryable)
+
+
+def _retrying(max_retries: int):
+    return AsyncRetrying(
+        stop=stop_after_attempt(max_retries + 1),
+        wait=_WAIT,
+        retry=_RETRY_CONDITION,
+        retry_error_callback=_return_last_value,
+    )
+
+
+class AresClient:
+    def __init__(
+        self,
+        *,
+        base_url: str = _BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = 3,
+    ):
+        self.base_url: str = base_url
+        self.max_retries: int = max_retries
+        self._limiter: Limiter = Limiter(_RATE)
+        self._client: httpx.AsyncClient = httpx.AsyncClient(timeout=timeout)
+
+    async def _request[T: BaseModel](
+        self, model: type[T], method: str, url: str, *, json: dict[str, object] | None = None
+    ):
+        """Send the request and return the response parsed into `model`.
+
+        ARES errors become `AresAPIError`. The client does not wrap network
+        failures. After the last retry, they go to the caller as httpx errors
+        (`httpx.TimeoutException`, `httpx.ConnectError`, ...). Thus the true
+        cause stays visible.
+        """
+
+        async def attempt_once():
+            _ = await self._limiter.try_acquire_async("ares")
+            return await self._client.request(method, url, json=json)
+
+        return parse_response(model, await _retrying(self.max_retries)(attempt_once))
+
+    async def get_subject(self, ico: str | int):
+        """Return the subject with the given IČO.
+
+        The IČO can be an `int` or a `string`. The client adds the leading zeros.
+
+        Example:
+            >>> async with AresClient() as ares:
+            ...     subject = await ares.get_subject(27082440)
+            >>> subject.ico
+            '27082440'
+            >>> subject.obchodni_jmeno
+            'Alza.cz a.s.'
+
+        Raises:
+            `InvalidIco`: the IČO failed the local validation. No request was sent.
+            `SubjectNotFound`: ARES does not have a subject with this IČO.
+        """
+        return await self._request(Subject, "GET", subject_url(self.base_url, normalize_ico(ico)))
+
+    async def search(self, filter: SubjectFilter):
+        """Return the subjects that match the filter.
+
+        ARES combines different filter fields with AND. It combines the values
+        in one list with OR.
+
+        Example:
+            >>> async with AresClient() as ares:
+            ...     result = await ares.search(SubjectFilter(obchodni_jmeno="Alza"))
+            >>> result.pocet_celkem
+            2
+            >>> [s.obchodni_jmeno for s in result.ekonomicke_subjekty]
+            ['Alza.cz a.s.', 'MS - alza, s.r.o.']
+
+            >>> # narrowing down — here to joint-stock companies:
+            >>> narrowed = SubjectFilter(obchodni_jmeno="Alza", pravni_forma=["121"])
+            >>> async with AresClient() as ares:
+            ...     result = await ares.search(narrowed)
+            >>> [s.obchodni_jmeno for s in result.ekonomicke_subjekty]
+            ['Alza.cz a.s.']
+
+        `start` and `pocet` divide a result set into pages. The pages connect
+        into the full set in the initial order. `pocet_celkem` shows the total
+        match count on each page. Thus it also shows the limit for paging.
+
+        Paging cannot go around the limit of 1 000 results. ARES compares the
+        limit with the total match count before it reads `start` and `pocet`.
+        Thus ARES refuses each request for an oversized query — `start=1000`
+        does not get the remainder, and `start=999, pocet=1` also fails. Only a
+        narrower filter helps. `TooManyResults.found` shows the size of such a
+        result set. Below the limit, one request is always sufficient —
+        `pocet=1000` holds the full result set.
+
+        Raises:
+            InvalidRequest: ARES refused the filter, for example an empty one.
+            TooManyResults: more than 1 000 subjects match the query.
+        """
+        return await self._request(
+            SubjectList, "POST", search_url(self.base_url), json=filter.to_payload()
+        )
+
+    async def search_code_lists(self, filter: CodeListFilter):
+        """Return the code lists that match the filter.
+
+        ARES uses code-list codes in many fields, for example `pravni_forma`.
+        This endpoint translates the codes to names. An empty filter is valid
+        here. It returns all the code lists.
+
+        Example:
+            >>> async with AresClient() as ares:
+            ...     result = await ares.search_code_lists(
+            ...         CodeListFilter(kod_ciselniku="PravniForma", zdroj_ciselniku="res")
+            ...     )
+            >>> names = result.ciselniky[0].polozky_ciselniku
+            >>> next(n.nazev[0].nazev for n in names if n.kod == "112")
+            'Společnost s ručením omezeným'
+
+        Raises:
+            InvalidRequest: ARES refused the filter.
+        """
+        return await self._request(
+            CodeLists, "POST", code_list_search_url(self.base_url), json=filter.to_payload()
+        )
+
+    async def aclose(self):
+        await self._client.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):  # pyright:ignore[reportMissingParameterType, reportUnknownParameterType]
+        await self.aclose()

ares_client-0.1.0/src/ares_client/exceptions.py

@@ -0,0 +1,60 @@
+"""https://ares.gov.cz/swagger-ui/#/ekonomicke-subjekty/vratEkonomickySubjekt"""
+
+
+class AresError(Exception):
+    """Base class for every error this library raises."""
+
+
+class InvalidIco(AresError, ValueError):
+    """The IČO failed the local validation. No request was sent."""
+
+    def __init__(self, value: object, reason: str):
+        self.value: object = value
+        self.reason: str = reason
+        super().__init__(f"Invalid IČO {value!r}: {reason}")
+
+
+class AresAPIError(AresError):
+    """ARES replied with an error status."""
+
+    def __init__(
+        self, popis: str, *, status_code: int, kod: str | None = None, sub_kod: str | None = None
+    ):
+        self.popis: str = popis
+        self.kod: str | None = kod
+        self.sub_kod: str | None = sub_kod
+        self.status_code: int = status_code
+        super().__init__(popis)
+
+
+class SubjectNotFound(AresAPIError):
+    """ARES does not have a subject with this IČO."""
+
+
+class InvalidRequest(AresAPIError):
+    """ARES refused the input."""
+
+
+class TooManyResults(InvalidRequest):
+    """More than 1 000 subjects match the query.
+
+    ARES refuses such a query. It does not cut the result. A retry without a
+    change cannot help — make the filter narrower. `found` is the number of
+    matched subjects, if the error message contains it.
+    """
+
+    def __init__(
+        self,
+        popis: str,
+        *,
+        status_code: int,
+        kod: str | None = None,
+        sub_kod: str | None = None,
+        found: int | None = None,
+    ):
+        self.found: int | None = found
+        super().__init__(popis, status_code=status_code, kod=kod, sub_kod=sub_kod)
+
+
+class AresServerError(AresAPIError):
+    """ARES failed on its side (HTTP 5xx), and the retries did not help."""

ares_client-0.1.0/src/ares_client/filters.py

@@ -0,0 +1,62 @@
+from collections.abc import Iterable
+from typing import ClassVar
+
+from pydantic import ConfigDict, field_validator
+
+from .ico import normalize_ico
+from .models import AresModel
+
+
+class _FilterModel(AresModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
+    def to_payload(self):
+        return self.model_dump(by_alias=True, exclude_none=True)
+
+
+class AddressFilter(_FilterModel):
+    """AARES schema `AdresaFiltr`."""
+
+    kod_casti_obce: int | None = None
+    kod_spravniho_obvodu: int | None = None
+    kod_mestske_casti_obvodu: int | None = None
+    kod_ulice: int | None = None
+    cislo_domovni: int | None = None
+    kod_obce: int | None = None
+    cislo_orientacni: int | None = None
+    cislo_orientacni_pismeno: str | None = None
+    textova_adresa: str | None = None
+
+
+class SubjectFilter(_FilterModel):
+    """ARES schema `EkonomickeSubjektyKomplexFiltr`."""
+
+    start: int = 0
+    pocet: int = 100
+    razeni: list[str] | None = None
+    ico: list[str] | None = None
+    obchodni_jmeno: str | None = None
+    sidlo: AddressFilter | None = None
+    pravni_forma: list[str] | None = None
+    financni_urad: list[str] | None = None
+    pravni_forma_ros: list[str] | None = None
+    cz_nace: list[str] | None = None
+
+    @field_validator("ico", mode="before")
+    @classmethod
+    def _normalize_icos(cls, value: str | int | Iterable[str | int] | None):
+        if value is None:
+            return None
+        if isinstance(value, str | int):
+            return [normalize_ico(value)]
+        return [normalize_ico(v) for v in value]
+
+
+class CodeListFilter(_FilterModel):
+    """ARES schema `CiselnikyZakladniFiltr`."""
+
+    start: int = 0
+    pocet: int = 100
+    razeni: list[str] | None = None
+    zdroj_ciselniku: str | None = None
+    kod_ciselniku: str | None = None

ares_client-0.1.0/src/ares_client/ico.py

@@ -0,0 +1,38 @@
+from .exceptions import InvalidIco
+
+_WEIGHTS = (8, 7, 6, 5, 4, 3, 2)
+
+
+def ico_checksum_ok(ico: str):
+    """Verify the modulo-11 check digit of an eight-digit IČO.
+
+    See https://w.wiki/Tqv6
+    """
+    if len(ico) != 8 or not ico.isdigit():
+        return False
+
+    total = sum(int(d) * w for d, w in zip(ico[:7], _WEIGHTS, strict=True))
+    expected = (11 - total % 11) % 10
+    return int(ico[7]) == expected
+
+
+def normalize_ico(value: str | int):
+    """Return the IČO in the canonical eight-digit form that ARES expects.
+
+    The function adds the leading zeros. The input must contain only digits.
+
+    Raises:
+        InvalidIco: the value contains a character that is not a digit, has more
+                    than eight digits, or has an incorrect check digit.
+    """
+    digits = str(value)
+
+    if not digits.isdigit():
+        raise InvalidIco(value, "contains characters other than digits")
+    if len(digits) > 8:
+        raise InvalidIco(value, f"has {len(digits)} digits, an IČO has at most 8")
+
+    padded = digits.zfill(8)
+    if not ico_checksum_ok(padded):
+        raise InvalidIco(value, "check digit does not match")
+    return padded

ares_client-0.1.0/src/ares_client/models.py

@@ -0,0 +1,174 @@
+"""https://ares.gov.cz/swagger-ui/#/ekonomicke-subjekty/vratEkonomickySubjekt"""
+
+from datetime import date
+from enum import StrEnum
+from typing import ClassVar, override
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+
+class AresModel(BaseModel):
+    model_config: ClassVar[ConfigDict] = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        extra="ignore",
+        frozen=True,
+    )
+
+
+class SourceState(StrEnum):
+    """ARES schema `StavZdroje`."""
+
+    AKTIVNI = "AKTIVNI"
+    BUDOUCI = "BUDOUCI"
+    HISTORICKY = "HISTORICKY"
+    LOGICKY_SMAZANY = "LOGICKY_SMAZANY"
+    NEEXISTUJICI = "NEEXISTUJICI"
+    POZASTAVENY = "POZASTAVENY"
+    ZANIKLY = "ZANIKLY"
+    UNKNOWN = "UNKNOWN"
+
+    @override
+    @classmethod
+    def _missing_(cls, value: object):
+        return cls.UNKNOWN
+
+
+class Address(AresModel):
+    """ARES schema `Adresa`."""
+
+    kod_statu: str | None = None
+    nazev_statu: str | None = None
+    kod_kraje: int | None = None
+    nazev_kraje: str | None = None
+    kod_okresu: int | None = None
+    nazev_okresu: str | None = None
+    kod_obce: int | None = None
+    nazev_obce: str | None = None
+    kod_spravniho_obvodu: int | None = None
+    nazev_spravniho_obvodu: str | None = None
+    kod_mestskeho_obvodu: int | None = None
+    nazev_mestskeho_obvodu: str | None = None
+    kod_mestske_casti_obvodu: int | None = None
+    kod_ulice: int | None = None
+    nazev_mestske_casti_obvodu: str | None = None
+    nazev_ulice: str | None = None
+    cislo_domovni: int | None = None
+    doplnek_adresy: str | None = None
+    kod_casti_obce: int | None = None
+    cislo_orientacni: int | None = None
+    cislo_orientacni_pismeno: str | None = None
+    nazev_casti_obce: str | None = None
+    kod_adresniho_mista: int | None = None
+    psc: int | None = None
+    textova_adresa: str | None = None
+    cislo_do_adresy: str | None = None
+    standardizace_adresy: bool | None = None
+    psc_txt: str | None = None
+    typ_cislo_domovni: int | None = None
+
+
+class DeliveryAddress(AresModel):
+    """ARES schema `AdresaDorucovaci`."""
+
+    radek_adresy1: str | None = None
+    radek_adresy2: str | None = None
+    radek_adresy3: str | None = None
+
+
+def _source_state_alias(name: str):
+    return to_camel(f"stav_zdroje_{name}")
+
+
+class Registrations(AresModel):
+    """ARES schema `SeznamRegistraci`."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(alias_generator=_source_state_alias)
+
+    ros: SourceState | None = None  # Registr osob
+    vr: SourceState | None = None  # Veřejné restříky
+    res: SourceState | None = None  # Registr ekonomických subjektů
+    rzp: SourceState | None = None  # Registr živnostenského podnikání
+    nrpzs: SourceState | None = None  # Národní registr poskytovatelů zdravotních služeb
+    rpsh: SourceState | None = None  # Registr politických stran a hnutí
+    rcns: SourceState | None = None  # Registr církví a náboženských společností
+    szr: SourceState | None = None  # Společný zemědělský registr
+    dph: SourceState | None = None  # Registr plátců DPH
+    sk_dph: SourceState | None = None  # Registr plátců skupinového DPH
+    sd: SourceState | None = None  # Registr plátců spotřební daně
+    ir: SourceState | None = None  # Insolvenční rejstřík
+    ceu: SourceState | None = None  # Centrální evidence úpadců
+    rs: SourceState | None = None  # Registr škol
+    red: SourceState | None = None  # Registr evidence dotací
+    monitor: SourceState | None = None  # Monitor účetních jednotek státu
+
+
+class Subject(AresModel):
+    """ARES schema `EkonomickySubjekt`."""
+
+    ico: str | None = None
+    obchodni_jmeno: str | None = None
+    sidlo: Address | None = None
+    pravni_forma: str | None = None
+    pravni_forma_ros: str | None = None
+    financni_urad: str | None = None
+    datum_vzniku: date | None = None
+    datum_zaniku: date | None = None
+    datum_aktualizace: date | None = None
+    dic: str | None = None
+    ico_id: str | None = None
+    adresa_dorucovaci: DeliveryAddress | None = None
+    cz_nace2008: list[str] = Field(default_factory=list)
+    seznam_registraci: Registrations | None = None
+    primarni_zdroj: str | None = None
+    dalsi_udaje: list[dict[str, object]] = Field(default_factory=list)
+    cz_nace: list[str] = Field(default_factory=list)
+    sub_registr_szr: str | None = None
+    dic_sk_dph: str | None = None
+
+
+class SubjectList(AresModel):
+    """ARES schema `EkonomickeSubjektySeznam`."""
+
+    pocet_celkem: int = 0
+    ekonomicke_subjekty: list[Subject] = Field(default_factory=list)
+
+    def __len__(self):
+        return len(self.ekonomicke_subjekty)
+
+
+class CodeListItemName(AresModel):
+    """ARES schema `NazevPolozky`."""
+
+    kod_jazyka: str | None = None
+    nazev: str | None = None
+
+
+class CodeListItem(AresModel):
+    """ARES schema `PolozkaCiselniku`."""
+
+    kod: str | None = None
+    nazev: list[CodeListItemName] = Field(default_factory=list)
+    platnost_od: date | None = None
+    platnost_do: date | None = None
+    kod_nadrizeny: str | None = None
+
+
+class CodeList(AresModel):
+    """ARES schema `Ciselnik`."""
+
+    kod_ciselniku: str | None = None
+    nazev_ciselniku: str | None = None
+    polozky_ciselniku: list[CodeListItem] = Field(default_factory=list)
+    zdroj_ciselniku: str | None = None
+
+
+class CodeLists(AresModel):
+    """ARES schema `CiselnikyNazevnikSeznam`."""
+
+    pocet_celkem: int = 0
+    ciselniky: list[CodeList] = Field(default_factory=list)
+
+    def __len__(self):
+        return len(self.ciselniky)