xyp 0.1.0__py3-none-any.whl

xyp/__init__.py

@@ -0,0 +1,60 @@
+"""Typed Python SDK for XYP (ХУР), Mongolia's government data exchange system.
+
+from xyp import Xyp
+
+xyp = Xyp(access_token="...", private_key="private.key")
+card = xyp.citizen.get_citizen_id_card_info(regnum="...")
+"""
+
+from importlib.metadata import version
+
+from xyp._client import AsyncXyp, Xyp
+from xyp._models import Mismatch, XypModel, XypModelMismatchWarning
+from xyp.auth import AuthType, CitizenAuth, OperatorAuth
+from xyp.errors import (
+    AccessDeniedError,
+    AuthRequiredError,
+    CitizenDataError,
+    FingerprintError,
+    InternalError,
+    InvalidRequestError,
+    NotFoundError,
+    ProviderError,
+    SignatureError,
+    XypApiError,
+    XypConfigError,
+    XypConnectionError,
+    XypError,
+    XypResponseError,
+    XypTimeoutError,
+    XypValidationError,
+)
+
+__version__ = version("xyp")
+
+__all__ = [
+    "AccessDeniedError",
+    "AsyncXyp",
+    "AuthRequiredError",
+    "AuthType",
+    "CitizenAuth",
+    "CitizenDataError",
+    "FingerprintError",
+    "InternalError",
+    "InvalidRequestError",
+    "Mismatch",
+    "NotFoundError",
+    "OperatorAuth",
+    "ProviderError",
+    "SignatureError",
+    "Xyp",
+    "XypApiError",
+    "XypConfigError",
+    "XypConnectionError",
+    "XypError",
+    "XypModel",
+    "XypModelMismatchWarning",
+    "XypResponseError",
+    "XypTimeoutError",
+    "XypValidationError",
+]

xyp/_client.py

@@ -0,0 +1,176 @@
+"""The two entry points: `Xyp` (sync) and `AsyncXyp` (async)."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any
+
+import httpx
+from typing_extensions import Self
+
+from xyp._groups import AsyncGroups, SyncGroups
+from xyp._signer import PrivateKeySource, Signer
+from xyp._tls import Verify, build_verify
+from xyp._transport import DEFAULT_BASE_URL, DEFAULT_TIMEOUT_SECONDS, AsyncTransport, SyncTransport
+from xyp.auth import CitizenAuth, OperatorAuth
+from xyp.errors import XypConfigError
+
+ACCESS_TOKEN_ENV = "XYP_ACCESS_TOKEN"  # noqa: S105 - the variable's name, not a token
+PRIVATE_KEY_ENV = "XYP_PRIVATE_KEY"
+
+
+def _checked_base_url(base_url: str) -> str:
+    if not base_url.lower().startswith(("https://", "http://")):
+        raise XypConfigError(f"base_url must start with https:// (or http://), got {base_url!r}")
+    return base_url
+
+
+def _signer_from(
+    access_token: str | None,
+    private_key: PrivateKeySource | None,
+    private_key_password: bytes | None,
+) -> Signer:
+    token = access_token or os.environ.get(ACCESS_TOKEN_ENV)
+    key = private_key or os.environ.get(PRIVATE_KEY_ENV)
+    if not token:
+        raise XypConfigError(
+            f"Pass access_token= or set the {ACCESS_TOKEN_ENV} environment variable"
+        )
+    if not key:
+        raise XypConfigError(
+            f"Pass private_key= (path, PEM text or bytes) or set {PRIVATE_KEY_ENV} to the key path"
+        )
+    return Signer(token, key, private_key_password)
+
+
+class Xyp(SyncGroups):
+    """Synchronous XYP client.
+
+        xyp = Xyp(access_token="...", private_key="path/to/private.key")
+        card = xyp.citizen.get_citizen_id_card_info(regnum="...")
+
+    Services are grouped by XYP endpoint (`xyp.citizen`, `xyp.insurance`, ...).
+    Reuse one client: it keeps a connection pool. Use it as a context manager or
+    call `close()` when done.
+
+    Args:
+        access_token: Token issued by the National Data Center. Falls back to `XYP_ACCESS_TOKEN`.
+        private_key: RSA key as a file path, PEM text or PEM/DER bytes.
+            Falls back to the path in `XYP_PRIVATE_KEY`.
+        private_key_password: Password of an encrypted key.
+        base_url: Change only when you reach XYP through your own proxy.
+        timeout: Seconds to wait for XYP.
+        verify: `True` verifies against the bundled Mongolian national CAs. Pass a CA
+            bundle path or an `ssl.SSLContext` for a proxy, or `False` to disable
+            verification (see docs/tls.md before you do).
+        http_client: Bring your own `httpx.Client`; `timeout` and `verify` are then yours
+            to configure and the client is not closed by this object.
+    """
+
+    def __init__(
+        self,
+        *,
+        access_token: str | None = None,
+        private_key: PrivateKeySource | None = None,
+        private_key_password: bytes | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        verify: Verify = True,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        signer = _signer_from(access_token, private_key, private_key_password)
+        self._owns_client = http_client is None
+        client = http_client or httpx.Client(timeout=timeout, verify=build_verify(verify))
+        self._transport = SyncTransport(signer, _checked_base_url(base_url), client)
+
+    def call(
+        self,
+        operation: str,
+        params: Mapping[str, Any] | None = None,
+        *,
+        auth: CitizenAuth | None = None,
+        operator: OperatorAuth | None = None,
+        endpoint: str | None = None,
+    ) -> Any:
+        """Call a service by its original XYP name and get the raw response data.
+
+            xyp.call("WS100101_getCitizenIDCardInfo", {"regnum": "..."})
+
+        `params` uses XYP's own field names. Pass `endpoint="citizen-1.5.0"` for a
+        service that is newer than this SDK version.
+        """
+        return self._transport.call(operation, params or {}, auth, operator, endpoint)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._transport.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return "Xyp(access_token=***)"
+
+
+class AsyncXyp(AsyncGroups):
+    """Asynchronous XYP client. Same options and services as `Xyp`, awaited:
+
+    async with AsyncXyp(access_token="...", private_key="private.key") as xyp:
+        card = await xyp.citizen.get_citizen_id_card_info(regnum="...")
+    """
+
+    def __init__(
+        self,
+        *,
+        access_token: str | None = None,
+        private_key: PrivateKeySource | None = None,
+        private_key_password: bytes | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        verify: Verify = True,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        signer = _signer_from(access_token, private_key, private_key_password)
+        self._owns_client = http_client is None
+        client = http_client or httpx.AsyncClient(timeout=timeout, verify=build_verify(verify))
+        self._transport = AsyncTransport(signer, _checked_base_url(base_url), client)
+
+    async def call(
+        self,
+        operation: str,
+        params: Mapping[str, Any] | None = None,
+        *,
+        auth: CitizenAuth | None = None,
+        operator: OperatorAuth | None = None,
+        endpoint: str | None = None,
+    ) -> Any:
+        """Async twin of `Xyp.call`."""
+        return await self._transport.call(operation, params or {}, auth, operator, endpoint)
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._transport.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return "AsyncXyp(access_token=***)"

xyp/_groups.py

@@ -0,0 +1,264 @@
+"""GENERATED by xyp-generator from spec/services.json. Do not edit.
+
+Service groups are imported on first access so `import xyp` stays fast.
+"""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+from xyp._transport import AsyncTransport, SyncTransport
+
+if TYPE_CHECKING:
+    from xyp.services.citizen import AsyncCitizenService, CitizenService
+    from xyp.services.education import AsyncEducationService, EducationService
+    from xyp.services.foreign_service import AsyncForeignServiceService, ForeignServiceService
+    from xyp.services.government_service import (
+        AsyncGovernmentServiceService,
+        GovernmentServiceService,
+    )
+    from xyp.services.health import AsyncHealthService, HealthService
+    from xyp.services.insurance import AsyncInsuranceService, InsuranceService
+    from xyp.services.labor_welfare import AsyncLaborWelfareService, LaborWelfareService
+    from xyp.services.legal_entity import AsyncLegalEntityService, LegalEntityService
+    from xyp.services.meta import AsyncMetaService, MetaService
+    from xyp.services.payment import AsyncPaymentService, PaymentService
+    from xyp.services.pki import AsyncPkiService, PkiService
+    from xyp.services.private_service import AsyncPrivateServiceService, PrivateServiceService
+    from xyp.services.property import AsyncPropertyService, PropertyService
+    from xyp.services.statistic import AsyncStatisticService, StatisticService
+    from xyp.services.tax import AsyncTaxService, TaxService
+    from xyp.services.transport import AsyncTransportService, TransportService
+
+
+class SyncGroups:
+    _transport: SyncTransport
+
+    @cached_property
+    def citizen(self) -> CitizenService:
+        """83 services served from citizen-1.5.0."""
+        from xyp.services.citizen import CitizenService
+
+        return CitizenService(self._transport)
+
+    @cached_property
+    def education(self) -> EducationService:
+        """18 services served from education-1.3.0, education-1.5.0."""
+        from xyp.services.education import EducationService
+
+        return EducationService(self._transport)
+
+    @cached_property
+    def foreign_service(self) -> ForeignServiceService:
+        """6 services served from foreign-service-1.5.0."""
+        from xyp.services.foreign_service import ForeignServiceService
+
+        return ForeignServiceService(self._transport)
+
+    @cached_property
+    def government_service(self) -> GovernmentServiceService:
+        """54 services served from government-service-1.5.0."""
+        from xyp.services.government_service import GovernmentServiceService
+
+        return GovernmentServiceService(self._transport)
+
+    @cached_property
+    def health(self) -> HealthService:
+        """76 services served from health-1.5.0."""
+        from xyp.services.health import HealthService
+
+        return HealthService(self._transport)
+
+    @cached_property
+    def insurance(self) -> InsuranceService:
+        """67 services served from insurance-1.5.0."""
+        from xyp.services.insurance import InsuranceService
+
+        return InsuranceService(self._transport)
+
+    @cached_property
+    def labor_welfare(self) -> LaborWelfareService:
+        """19 services served from labor-welfare-1.5.0."""
+        from xyp.services.labor_welfare import LaborWelfareService
+
+        return LaborWelfareService(self._transport)
+
+    @cached_property
+    def legal_entity(self) -> LegalEntityService:
+        """19 services served from legal-entity-1.5.0."""
+        from xyp.services.legal_entity import LegalEntityService
+
+        return LegalEntityService(self._transport)
+
+    @cached_property
+    def meta(self) -> MetaService:
+        """6 services served from meta-1.5.0."""
+        from xyp.services.meta import MetaService
+
+        return MetaService(self._transport)
+
+    @cached_property
+    def payment(self) -> PaymentService:
+        """33 services served from payment-1.5.0."""
+        from xyp.services.payment import PaymentService
+
+        return PaymentService(self._transport)
+
+    @cached_property
+    def pki(self) -> PkiService:
+        """1 services served from pki-1.5.0."""
+        from xyp.services.pki import PkiService
+
+        return PkiService(self._transport)
+
+    @cached_property
+    def private_service(self) -> PrivateServiceService:
+        """6 services served from private-service-1.5.0."""
+        from xyp.services.private_service import PrivateServiceService
+
+        return PrivateServiceService(self._transport)
+
+    @cached_property
+    def property(self) -> PropertyService:
+        """30 services served from property-1.5.0."""
+        from xyp.services.property import PropertyService
+
+        return PropertyService(self._transport)
+
+    @cached_property
+    def statistic(self) -> StatisticService:
+        """24 services served from statistic-1.5.0."""
+        from xyp.services.statistic import StatisticService
+
+        return StatisticService(self._transport)
+
+    @cached_property
+    def tax(self) -> TaxService:
+        """9 services served from tax-1.5.0."""
+        from xyp.services.tax import TaxService
+
+        return TaxService(self._transport)
+
+    @cached_property
+    def transport(self) -> TransportService:
+        """48 services served from transport-1.5.0."""
+        from xyp.services.transport import TransportService
+
+        return TransportService(self._transport)
+
+
+class AsyncGroups:
+    _transport: AsyncTransport
+
+    @cached_property
+    def citizen(self) -> AsyncCitizenService:
+        """83 services served from citizen-1.5.0."""
+        from xyp.services.citizen import AsyncCitizenService
+
+        return AsyncCitizenService(self._transport)
+
+    @cached_property
+    def education(self) -> AsyncEducationService:
+        """18 services served from education-1.3.0, education-1.5.0."""
+        from xyp.services.education import AsyncEducationService
+
+        return AsyncEducationService(self._transport)
+
+    @cached_property
+    def foreign_service(self) -> AsyncForeignServiceService:
+        """6 services served from foreign-service-1.5.0."""
+        from xyp.services.foreign_service import AsyncForeignServiceService
+
+        return AsyncForeignServiceService(self._transport)
+
+    @cached_property
+    def government_service(self) -> AsyncGovernmentServiceService:
+        """54 services served from government-service-1.5.0."""
+        from xyp.services.government_service import AsyncGovernmentServiceService
+
+        return AsyncGovernmentServiceService(self._transport)
+
+    @cached_property
+    def health(self) -> AsyncHealthService:
+        """76 services served from health-1.5.0."""
+        from xyp.services.health import AsyncHealthService
+
+        return AsyncHealthService(self._transport)
+
+    @cached_property
+    def insurance(self) -> AsyncInsuranceService:
+        """67 services served from insurance-1.5.0."""
+        from xyp.services.insurance import AsyncInsuranceService
+
+        return AsyncInsuranceService(self._transport)
+
+    @cached_property
+    def labor_welfare(self) -> AsyncLaborWelfareService:
+        """19 services served from labor-welfare-1.5.0."""
+        from xyp.services.labor_welfare import AsyncLaborWelfareService
+
+        return AsyncLaborWelfareService(self._transport)
+
+    @cached_property
+    def legal_entity(self) -> AsyncLegalEntityService:
+        """19 services served from legal-entity-1.5.0."""
+        from xyp.services.legal_entity import AsyncLegalEntityService
+
+        return AsyncLegalEntityService(self._transport)
+
+    @cached_property
+    def meta(self) -> AsyncMetaService:
+        """6 services served from meta-1.5.0."""
+        from xyp.services.meta import AsyncMetaService
+
+        return AsyncMetaService(self._transport)
+
+    @cached_property
+    def payment(self) -> AsyncPaymentService:
+        """33 services served from payment-1.5.0."""
+        from xyp.services.payment import AsyncPaymentService
+
+        return AsyncPaymentService(self._transport)
+
+    @cached_property
+    def pki(self) -> AsyncPkiService:
+        """1 services served from pki-1.5.0."""
+        from xyp.services.pki import AsyncPkiService
+
+        return AsyncPkiService(self._transport)
+
+    @cached_property
+    def private_service(self) -> AsyncPrivateServiceService:
+        """6 services served from private-service-1.5.0."""
+        from xyp.services.private_service import AsyncPrivateServiceService
+
+        return AsyncPrivateServiceService(self._transport)
+
+    @cached_property
+    def property(self) -> AsyncPropertyService:
+        """30 services served from property-1.5.0."""
+        from xyp.services.property import AsyncPropertyService
+
+        return AsyncPropertyService(self._transport)
+
+    @cached_property
+    def statistic(self) -> AsyncStatisticService:
+        """24 services served from statistic-1.5.0."""
+        from xyp.services.statistic import AsyncStatisticService
+
+        return AsyncStatisticService(self._transport)
+
+    @cached_property
+    def tax(self) -> AsyncTaxService:
+        """9 services served from tax-1.5.0."""
+        from xyp.services.tax import AsyncTaxService
+
+        return AsyncTaxService(self._transport)
+
+    @cached_property
+    def transport(self) -> AsyncTransportService:
+        """48 services served from transport-1.5.0."""
+        from xyp.services.transport import AsyncTransportService
+
+        return AsyncTransportService(self._transport)