dpp-sdk 0.1.0__py3-none-any.whl

dpp_sdk/__init__.py

@@ -0,0 +1,76 @@
+"""Python SDK for Digital Product Passports (DPP).
+
+Idiomatic Pydantic v2 port of the Java DPP SDK (see ../dpp-sdk-platform).
+
+Sub-packages:
+    dpp_sdk.core      -- reusable core DPP model, validation, identifiers
+    dpp_sdk.dpp4fun   -- furniture-specific DPP aggregate, validation, JSON transport
+    dpp_sdk.clients   -- HTTP clients for the DPP repository and registry APIs
+"""
+
+from .core import (
+    Address,
+    Contact,
+    Documentation,
+    Dpp,
+    DppCore,
+    DppError,
+    DppMappingError,
+    DppValidationError,
+    Email,
+    Nameplate,
+    Organization,
+    OrganizationRole,
+    PassportMetadata,
+    Telephone,
+    validate_dpp_core,
+)
+from .dpp4fun import (
+    BillOfMaterials,
+    Characteristics,
+    Component,
+    Dimensions,
+    Dpp4Fun,
+    Dpp4FunJsonCodec,
+    Material,
+    Part,
+    ProductClassification,
+    from_json,
+    from_json_and_validate,
+    to_json,
+    validate_dpp4fun,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Address",
+    "BillOfMaterials",
+    "Characteristics",
+    "Component",
+    "Contact",
+    "Dimensions",
+    "Documentation",
+    "Dpp",
+    "Dpp4Fun",
+    "Dpp4FunJsonCodec",
+    "DppCore",
+    "DppError",
+    "DppMappingError",
+    "DppValidationError",
+    "Email",
+    "Material",
+    "Nameplate",
+    "Organization",
+    "OrganizationRole",
+    "PassportMetadata",
+    "Part",
+    "ProductClassification",
+    "Telephone",
+    "__version__",
+    "from_json",
+    "from_json_and_validate",
+    "to_json",
+    "validate_dpp4fun",
+    "validate_dpp_core",
+]

dpp_sdk/clients/__init__.py

@@ -0,0 +1,54 @@
+"""HTTP clients for the DPP repository and registry APIs (prEN-18222-aligned).
+
+Port of `dpp.repo.client.*` / `dpp.registry.client.*` from
+../dpp-sdk-platform/dpp-sdk-clients.
+"""
+
+from ._http import DppCodec, DppValidator
+from .errors import (
+    DppApiClientError,
+    DppClientError,
+    DppHttpClientError,
+    DppMappingClientError,
+    DppNetworkClientError,
+    DppValidationClientError,
+)
+from .payloads import (
+    CreateDppResponse,
+    DeleteDppResponse,
+    DppApiMessage,
+    DppApiResponse,
+    DppStatusCode,
+    MessageType,
+    ReadDppIdsRequest,
+    ReadDppIdsResponse,
+    RegisterDppRequest,
+    RegisterDppResponse,
+    UpdateDataElementRequest,
+)
+from .registry import DppRegistryClient
+from .repo import DppRepoClient
+
+__all__ = [
+    "CreateDppResponse",
+    "DeleteDppResponse",
+    "DppApiClientError",
+    "DppApiMessage",
+    "DppApiResponse",
+    "DppClientError",
+    "DppCodec",
+    "DppHttpClientError",
+    "DppMappingClientError",
+    "DppNetworkClientError",
+    "DppRegistryClient",
+    "DppRepoClient",
+    "DppStatusCode",
+    "DppValidationClientError",
+    "DppValidator",
+    "MessageType",
+    "ReadDppIdsRequest",
+    "ReadDppIdsResponse",
+    "RegisterDppRequest",
+    "RegisterDppResponse",
+    "UpdateDataElementRequest",
+]

dpp_sdk/clients/_http.py

@@ -0,0 +1,143 @@
+"""Shared HTTP transport and JSON helpers (port of ``HttpSupport``).
+
+Provides base-URL handling, URL encoding, the request/parse/validate pipeline for
+the API wrapper envelope, and the ``DppCodec`` / ``DppValidator`` typing contracts.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, TypeVar
+from urllib.parse import quote
+
+import httpx
+from pydantic import ValidationError
+
+from .errors import (
+    DppApiClientError,
+    DppHttpClientError,
+    DppMappingClientError,
+    DppNetworkClientError,
+)
+from .payloads import DppApiResponse
+
+T = TypeVar("T")
+T_contra = TypeVar("T_contra", contravariant=True)
+
+DEFAULT_CONNECT_TIMEOUT = 5.0
+DEFAULT_REQUEST_TIMEOUT = 15.0
+
+
+class DppCodec(Protocol[T]):
+    """Converts a caller-owned DPP type to and from full JSON payloads."""
+
+    def to_json(self, dpp: T) -> str: ...
+
+    def from_json(self, raw: str) -> T: ...
+
+
+class DppValidator(Protocol[T_contra]):
+    """Validates a caller-owned DPP type before a create request is sent."""
+
+    def __call__(self, dpp: T_contra) -> None: ...
+
+
+def build_client() -> httpx.Client:
+    return httpx.Client(
+        timeout=httpx.Timeout(DEFAULT_REQUEST_TIMEOUT, connect=DEFAULT_CONNECT_TIMEOUT)
+    )
+
+
+def normalize_base_url(base_url: str) -> str:
+    trimmed = base_url.strip()
+    if not trimmed:
+        raise ValueError("baseUrl must not be blank")
+    return trimmed.rstrip("/")
+
+
+def resolve(base_url: str, path_and_query: str) -> str:
+    normalized = path_and_query if path_and_query else "/"
+    if not normalized.startswith("/"):
+        normalized = "/" + normalized
+    return base_url + normalized
+
+
+def encode_segment(value: str) -> str:
+    return quote(value, safe="")
+
+
+def request_api(
+    client: httpx.Client,
+    method: str,
+    url: str,
+    body: str | None,
+) -> DppApiResponse:
+    """Run the full request pipeline and return a validated success envelope."""
+    headers = {"Accept": "application/json"}
+    if body is not None:
+        headers["Content-Type"] = "application/json"
+    try:
+        response = client.request(method, url, content=body, headers=headers)
+    except httpx.TimeoutException as exc:
+        raise DppNetworkClientError("DPP HTTP request timed out") from exc
+    except httpx.TransportError as exc:
+        raise DppNetworkClientError("DPP HTTP request could not complete") from exc
+
+    _require_http_success(response)
+    api_response = _parse_api_response(response.text)
+    _require_api_success(api_response, response.text)
+    return api_response
+
+
+def _require_http_success(response: httpx.Response) -> None:
+    if not 200 <= response.status_code < 300:
+        raise DppHttpClientError(
+            f"DPP endpoint returned non-success HTTP status {response.status_code}",
+            response.status_code,
+            response.text,
+        )
+
+
+def _parse_api_response(raw_body: str) -> DppApiResponse:
+    try:
+        return DppApiResponse.model_validate_json(raw_body)
+    except ValidationError as exc:
+        raise DppMappingClientError("DPP API response could not be mapped") from exc
+
+
+def _require_api_success(response: DppApiResponse, raw_body: str) -> None:
+    status_code = response.statusCode
+    if status_code is None:
+        raise DppMappingClientError("DPP API response could not be mapped: missing statusCode")
+    if not status_code.is_success:
+        raise DppApiClientError(
+            f"DPP API returned error status {status_code.value}",
+            status_code,
+            response.messages,
+            raw_body,
+        )
+
+
+def require_payload(response: DppApiResponse) -> Any:
+    payload = response.payload
+    if payload is None:
+        raise _missing_field("payload")
+    return payload
+
+
+def require_text_field(payload: Any, field_name: str, field_path: str) -> str:
+    if not isinstance(payload, dict):
+        raise _missing_field(field_path)
+    value = payload.get(field_name)
+    if not isinstance(value, str) or not value.strip():
+        raise _missing_field(field_path)
+    return value
+
+
+def require_field(payload: Any, field_name: str, field_path: str) -> Any:
+    if not isinstance(payload, dict) or payload.get(field_name) is None:
+        raise _missing_field(field_path)
+    return payload[field_name]
+
+
+def _missing_field(field_path: str) -> DppMappingClientError:
+    return DppMappingClientError(f"Missing required response field: {field_path}")

dpp_sdk/clients/errors.py

@@ -0,0 +1,49 @@
+"""Client exception hierarchy (port of ``dpp.*.client.exception``)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .payloads import DppApiMessage, DppStatusCode
+
+
+class DppClientError(Exception):
+    """Base class for all DPP HTTP client errors."""
+
+
+class DppValidationClientError(DppClientError):
+    """Raised when a DPP fails validation before a request is sent."""
+
+
+class DppMappingClientError(DppClientError):
+    """Raised when request/response JSON cannot be serialized or parsed."""
+
+
+class DppNetworkClientError(DppClientError):
+    """Raised when the HTTP request cannot complete (connection/timeout)."""
+
+
+class DppHttpClientError(DppClientError):
+    """Raised when an endpoint returns a non-2xx HTTP status."""
+
+    def __init__(self, message: str, status_code: int, response_body: str) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+
+class DppApiClientError(DppClientError):
+    """Raised when a 2xx response carries an error status in the API wrapper."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: DppStatusCode | None,
+        messages: list[DppApiMessage] | None,
+        raw_response_body: str,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.messages = messages
+        self.raw_response_body = raw_response_body

dpp_sdk/clients/payloads.py

@@ -0,0 +1,118 @@
+"""API wrapper envelope and request/response DTOs for the DPP HTTP clients.
+
+Ports ``dpp.repo.payloads.*`` and ``dpp.registry.payloads.*`` (which are
+identical for the shared envelope) into a single module. These models use
+``extra='ignore'`` to mirror the clients' Jackson config, which disables
+``FAIL_ON_UNKNOWN_PROPERTIES``.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class DppStatusCode(StrEnum):
+    """Application-level status in the API wrapper ``statusCode`` field."""
+
+    Success = "Success"
+    SuccessCreated = "SuccessCreated"
+    SuccessAccepted = "SuccessAccepted"
+    SuccessNoContent = "SuccessNoContent"
+    ClientErrorBadRequest = "ClientErrorBadRequest"
+    ClientNotAuthorized = "ClientNotAuthorized"
+    ClientForbidden = "ClientForbidden"
+    ClientMethodNotAllowed = "ClientMethodNotAllowed"
+    ClientErrorResourceNotFound = "ClientErrorResourceNotFound"
+    ClientResourceConflict = "ClientResourceConflict"
+    ServerInternalError = "ServerInternalError"
+    ServerErrorBadGateway = "ServerErrorBadGateway"
+
+    @classmethod
+    def _missing_(cls, value: object) -> DppStatusCode | None:
+        # Mirror the Java @JsonCreator aliases.
+        aliases = {
+            "ClientErrorNotAuthorized": cls.ClientNotAuthorized,
+            "ClientErrorForbidden": cls.ClientForbidden,
+        }
+        if isinstance(value, str):
+            return aliases.get(value)
+        return None
+
+    @property
+    def is_success(self) -> bool:
+        return self in {
+            DppStatusCode.Success,
+            DppStatusCode.SuccessCreated,
+            DppStatusCode.SuccessAccepted,
+            DppStatusCode.SuccessNoContent,
+        }
+
+
+class MessageType(StrEnum):
+    """Severity/category for API wrapper messages."""
+
+    Info = "Info"
+    Warning = "Warning"
+    Error = "Error"
+    Exception = "Exception"
+
+
+class _ClientBase(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+
+class DppApiMessage(_ClientBase):
+    messageType: MessageType | None = None
+    text: str | None = None
+    code: str | None = None
+    correlationId: str | None = None
+    timestamp: datetime | None = None
+
+
+class DppApiResponse(_ClientBase):
+    """Standard response envelope; ``payload`` is left as raw JSON (``Any``)."""
+
+    statusCode: DppStatusCode | None = None
+    payload: Any = None
+    messages: list[DppApiMessage] | None = None
+
+
+# --- repository DTOs ------------------------------------------------------------
+class CreateDppResponse(_ClientBase):
+    dppId: str | None = None
+
+
+class DeleteDppResponse(_ClientBase):
+    statusCode: DppStatusCode | None = None
+    messages: list[DppApiMessage] | None = None
+
+
+class ReadDppIdsRequest(_ClientBase):
+    productIdentifiers: list[str] | None = None
+    limit: int | None = None
+    cursor: str | None = None
+
+
+class ReadDppIdsResponse(_ClientBase):
+    dppIdentifiers: list[str] | None = None
+    nextCursor: str | None = None
+
+
+class UpdateDataElementRequest(_ClientBase):
+    payload: Any = None
+
+
+# --- registry DTOs --------------------------------------------------------------
+class RegisterDppRequest(_ClientBase):
+    productIdentifier: str | None = None
+    dppIdentifier: str | None = None
+    operatorIdentifier: str | None = None
+    repoUrl: str | None = None
+
+
+class RegisterDppResponse(_ClientBase):
+    registryIdentifier: str | None = None

dpp_sdk/clients/registry.py

@@ -0,0 +1,25 @@
+"""HTTP client for the DPP registry API (port of ``HttpDppRegistryClient``)."""
+
+from __future__ import annotations
+
+import httpx
+
+from . import _http
+from .payloads import RegisterDppRequest, RegisterDppResponse
+
+_REGISTER_PATH = "/registerDPP"
+
+
+class DppRegistryClient:
+    def __init__(self, base_url: str, *, client: httpx.Client | None = None) -> None:
+        self._base_url = _http.normalize_base_url(base_url)
+        self._client = client if client is not None else _http.build_client()
+
+    def post_new_dpp_to_registry(self, request: RegisterDppRequest) -> RegisterDppResponse:
+        body = request.model_dump_json()
+        response = _http.request_api(
+            self._client, "POST", _http.resolve(self._base_url, _REGISTER_PATH), body
+        )
+        payload = _http.require_payload(response)
+        _http.require_text_field(payload, "registryIdentifier", "payload.registryIdentifier")
+        return RegisterDppResponse.model_validate(payload)

dpp_sdk/clients/repo.py

@@ -0,0 +1,130 @@
+"""HTTP client for the DPP repository API (port of ``HttpDppRepoClient``).
+
+Generic over a caller-owned DPP model type ``T``, mediated by a :class:`DppCodec`
+(full-payload JSON) and a validator callable. Endpoint paths and the request
+pipeline match the Java client exactly.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any, Generic, TypeVar
+
+import httpx
+
+from . import _http
+from .errors import DppMappingClientError, DppValidationClientError
+from .payloads import CreateDppResponse, DeleteDppResponse, ReadDppIdsRequest, ReadDppIdsResponse
+
+T = TypeVar("T")
+
+_DPPS_PATH = "/dpps"
+_DPPS_BY_PRODUCT_ID_PATH = "/dppsByProductId/"
+_DPPS_BY_PRODUCT_ID_AND_DATE_PATH = "/dppsByProductIdAndDate/"
+_DPPS_BY_PRODUCT_IDS_PATH = "/dppsByProductIds"
+
+
+class DppRepoClient(Generic[T]):
+    def __init__(
+        self,
+        base_url: str,
+        codec: _http.DppCodec[T],
+        validator: _http.DppValidator[T],
+        *,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self._base_url = _http.normalize_base_url(base_url)
+        self._codec = codec
+        self._validator = validator
+        self._client = client if client is not None else _http.build_client()
+
+    # --- lifecycle --------------------------------------------------------------
+    def create_dpp(self, dpp: T) -> CreateDppResponse:
+        try:
+            self._validator(dpp)
+        except Exception as exc:  # noqa: BLE001 - re-raised as a client error
+            raise DppValidationClientError("DPP validation failed before request") from exc
+        body = self._serialize(dpp)
+        response = self._send("POST", _DPPS_PATH, body)
+        payload = _http.require_payload(response)
+        _http.require_text_field(payload, "dppId", "payload.dppId")
+        return CreateDppResponse.model_validate(payload)
+
+    def read_dpp_by_id(self, dpp_id: str) -> T:
+        response = self._send("GET", self._dpp_path(dpp_id), None)
+        return self._decode_dpp_payload(response)
+
+    def read_dpp_by_product_id(self, product_id: str) -> T:
+        path = _DPPS_BY_PRODUCT_ID_PATH + _http.encode_segment(product_id)
+        response = self._send("GET", path, None)
+        return self._decode_dpp_payload(response)
+
+    def read_dpp_version_by_product_id_and_date(self, product_id: str, date: datetime) -> T:
+        path = (
+            _DPPS_BY_PRODUCT_ID_AND_DATE_PATH
+            + _http.encode_segment(product_id)
+            + "?date="
+            + _http.encode_segment(date.isoformat())
+        )
+        response = self._send("GET", path, None)
+        return self._decode_dpp_payload(response)
+
+    def read_dpp_ids_by_product_ids(
+        self, product_ids: list[str], limit: int | None = None, cursor: str | None = None
+    ) -> ReadDppIdsResponse:
+        request_body = ReadDppIdsRequest(
+            productIdentifiers=product_ids, limit=limit, cursor=cursor
+        )
+        response = self._send("POST", _DPPS_BY_PRODUCT_IDS_PATH, request_body.model_dump_json())
+        payload = _http.require_payload(response)
+        _http.require_field(payload, "dppIdentifiers", "payload.dppIdentifiers")
+        return ReadDppIdsResponse.model_validate(payload)
+
+    def update_dpp_by_id(self, dpp_id: str, partial_dpp: Any) -> T:
+        body = json.dumps(partial_dpp)
+        response = self._send("PATCH", self._dpp_path(dpp_id), body)
+        return self._decode_dpp_payload(response)
+
+    def delete_dpp_by_id(self, dpp_id: str) -> DeleteDppResponse:
+        response = self._send("DELETE", self._dpp_path(dpp_id), None)
+        return DeleteDppResponse(statusCode=response.statusCode, messages=response.messages)
+
+    # --- fine-granular elements -------------------------------------------------
+    def read_data_element(self, dpp_id: str, element_path: str) -> Any:
+        response = self._send("GET", self._data_element_path(dpp_id, element_path), None)
+        return _http.require_payload(response)
+
+    def update_data_element(self, dpp_id: str, element_path: str, payload: Any) -> Any:
+        body = json.dumps({"payload": payload})
+        response = self._send("PATCH", self._data_element_path(dpp_id, element_path), body)
+        return _http.require_payload(response)
+
+    # --- internals --------------------------------------------------------------
+    def _send(self, method: str, path: str, body: str | None) -> Any:
+        return _http.request_api(self._client, method, _http.resolve(self._base_url, path), body)
+
+    def _serialize(self, dpp: T) -> str:
+        try:
+            json_str = self._codec.to_json(dpp)
+        except Exception as exc:  # noqa: BLE001 - re-raised as a client error
+            raise DppMappingClientError("DPP serialization failed before request") from exc
+        if json_str is None:
+            raise DppMappingClientError("codec returned null JSON")
+        return json_str
+
+    def _decode_dpp_payload(self, response: Any) -> T:
+        payload = _http.require_payload(response)
+        payload_json = json.dumps(payload)
+        try:
+            return self._codec.from_json(payload_json)
+        except Exception as exc:  # noqa: BLE001 - re-raised as a client error
+            raise DppMappingClientError("DPP deserialization failed after response") from exc
+
+    @staticmethod
+    def _dpp_path(dpp_id: str) -> str:
+        return _DPPS_PATH + "/" + _http.encode_segment(dpp_id)
+
+    @classmethod
+    def _data_element_path(cls, dpp_id: str, element_path: str) -> str:
+        return cls._dpp_path(dpp_id) + "/elements/" + _http.encode_segment(element_path)

dpp_sdk/core/__init__.py

@@ -0,0 +1,38 @@
+"""Reusable core DPP model, validation, and identifiers.
+
+Port of `dppsdk.core.*` from ../dpp-sdk-platform/dpp-datamodel/dpp-core.
+"""
+
+from .errors import DppError, DppMappingError, DppValidationError
+from .model import (
+    Address,
+    Contact,
+    Documentation,
+    Dpp,
+    DppCore,
+    Email,
+    Nameplate,
+    Organization,
+    OrganizationRole,
+    PassportMetadata,
+    Telephone,
+)
+from .validation import validate_dpp_core
+
+__all__ = [
+    "Address",
+    "Contact",
+    "Documentation",
+    "Dpp",
+    "DppCore",
+    "DppError",
+    "DppMappingError",
+    "DppValidationError",
+    "Email",
+    "Nameplate",
+    "Organization",
+    "OrganizationRole",
+    "PassportMetadata",
+    "Telephone",
+    "validate_dpp_core",
+]

dpp_sdk/core/errors.py

@@ -0,0 +1,21 @@
+"""Exception hierarchy for the DPP datamodel.
+
+Mirrors the Java SDK's split between mapping/transport failures and semantic
+validation failures. Construction-time (structural) failures surface as
+``pydantic.ValidationError``; the semantic validators in
+:mod:`dpp_sdk.core.validation` raise :class:`DppValidationError`.
+"""
+
+from __future__ import annotations
+
+
+class DppError(Exception):
+    """Base class for all datamodel errors raised by the SDK."""
+
+
+class DppValidationError(DppError):
+    """Raised when a DPP fails a semantic validation rule (fail-fast)."""
+
+
+class DppMappingError(DppError):
+    """Raised when a DPP cannot be serialized to or parsed from JSON."""