dpp-sdk 0.1.0__tar.gz

dpp_sdk-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store

dpp_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `dpp-sdk` are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] — Initial release
+
+First public release of the Python port of the Java DPP SDK.
+
+### Added
+- `dpp_sdk.core` — core DPP model, validation, and identifiers (Pydantic v2).
+- `dpp_sdk.dpp4fun` — furniture-specific DPP aggregate, validation, and flat/nested JSON transport.
+- `dpp_sdk.clients` — `httpx`-based HTTP clients for the DPP repository and registry APIs.
+- Packaging: PEP 621 `pyproject.toml`, `src/` layout, `py.typed` marker, sdist + wheel build.
+
+[Unreleased]: https://github.com/CIR4FUN-EU/dpp-sdk-python/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/CIR4FUN-EU/dpp-sdk-python/releases/tag/v0.1.0

dpp_sdk-0.1.0/LICENSE

@@ -0,0 +1,183 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License,
+each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
+no-charge, royalty-free, irrevocable (except as stated in this section) patent
+license to make, have made, use, offer to sell, sell, import, and otherwise
+transfer the Work, where such license applies only to those patent claims
+licensable by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s) with the Work
+to which such Contribution(s) was submitted. If You institute patent litigation
+against any entity (including a cross-claim or counterclaim in a lawsuit)
+alleging that the Work or a Contribution incorporated within the Work
+constitutes direct or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate as of the date
+such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from the
+Source form of the Work, excluding those notices that do not pertain to any part
+of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then
+any Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein shall
+supersede or modify the terms of any separate license agreement you may have
+executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as required
+for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tor t (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to in
+writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any character
+arising as a result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill, work stoppage,
+computer failure or malfunction, or any and all other commercial damages or
+losses), even if such Contributor has been advised of the possibility of such
+damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree to
+indemnify, defend, and hold each Contributor harmless for any liability incurred
+by, or claims asserted against, such Contributor by reason of your accepting any
+such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification within
+third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

dpp_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: dpp-sdk
+Version: 0.1.0
+Summary: Python SDK for Digital Product Passports (DPP) — idiomatic Pydantic v2 port of the Java DPP SDK
+Project-URL: Homepage, https://github.com/CIR4FUN-EU/dpp-sdk-python
+Project-URL: Repository, https://github.com/CIR4FUN-EU/dpp-sdk-python
+Project-URL: Issues, https://github.com/CIR4FUN-EU/dpp-sdk-python/issues
+Project-URL: Changelog, https://github.com/CIR4FUN-EU/dpp-sdk-python/blob/main/CHANGELOG.md
+Project-URL: Reference, https://github.com/CIR4FUN-EU/dpp-sdk-platform
+Author-email: Enno Mueller <ennomueller@online.de>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: digital-product-passport,dpp,prEN-18222,sustainability
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=5.1; extra == 'release'
+Description-Content-Type: text/markdown
+
+# dpp-sdk (Python)
+
+Python SDK for **Digital Product Passports (DPP)** — an idiomatic [Pydantic v2](https://docs.pydantic.dev)
+port of the Java DPP SDK in the sibling repo `../dpp-sdk-platform`.
+
+## Install
+
+```bash
+pip install dpp-sdk
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+```python
+from dpp_sdk import Dpp4Fun, from_json, to_json, validate_dpp4fun
+
+# Parse an incoming passport (accepts both flat and nested JSON shapes)
+dpp = from_json(raw_json)
+
+# Validate against the DPP rule set (raises on violations)
+validate_dpp4fun(dpp)
+
+# Serialize back to the flattened wire JSON
+payload = to_json(dpp)
+```
+
+The `httpx`-based HTTP clients for the DPP repository and registry live in `dpp_sdk.clients`:
+
+```python
+from dpp_sdk.clients import DppRepoClient, DppRegistryClient
+```
+
+See [`docs/PORTING_PLAN.md`](docs/PORTING_PLAN.md) for design notes and
+[`docs/RELEASING.md`](docs/RELEASING.md) for how releases are cut.
+
+## Scope
+
+| Package | Purpose | Java source ported from |
+|---|---|---|
+| `dpp_sdk.core` | Reusable core DPP model, validation, JSON transport | `dpp-datamodel/dpp-core` |
+| `dpp_sdk.dpp4fun` | Furniture-specific DPP aggregate | `dpp-datamodel/dpp4fun` |
+| `dpp_sdk.clients` | HTTP clients for the DPP repository & registry APIs | `dpp-sdk-clients` |
+
+The Spring Boot mock services in `../dpp-sdk-platform/dpp-sdk-demo` are **not** ported; they are
+reused as a conformance oracle for client tests.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest        # tests
+mypy          # type check (strict)
+ruff check .  # lint
+```
+
+## Layout
+
+```
+src/dpp_sdk/
+  core/        # core model + validation
+  dpp4fun/     # furniture aggregate, validation, JSON transport
+  clients/     # repo + registry HTTP clients
+tests/         # pytest suite
+docs/          # PORTING_PLAN.md, RELEASING.md
+```

dpp_sdk-0.1.0/README.md

@@ -0,0 +1,69 @@
+# dpp-sdk (Python)
+
+Python SDK for **Digital Product Passports (DPP)** — an idiomatic [Pydantic v2](https://docs.pydantic.dev)
+port of the Java DPP SDK in the sibling repo `../dpp-sdk-platform`.
+
+## Install
+
+```bash
+pip install dpp-sdk
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+```python
+from dpp_sdk import Dpp4Fun, from_json, to_json, validate_dpp4fun
+
+# Parse an incoming passport (accepts both flat and nested JSON shapes)
+dpp = from_json(raw_json)
+
+# Validate against the DPP rule set (raises on violations)
+validate_dpp4fun(dpp)
+
+# Serialize back to the flattened wire JSON
+payload = to_json(dpp)
+```
+
+The `httpx`-based HTTP clients for the DPP repository and registry live in `dpp_sdk.clients`:
+
+```python
+from dpp_sdk.clients import DppRepoClient, DppRegistryClient
+```
+
+See [`docs/PORTING_PLAN.md`](docs/PORTING_PLAN.md) for design notes and
+[`docs/RELEASING.md`](docs/RELEASING.md) for how releases are cut.
+
+## Scope
+
+| Package | Purpose | Java source ported from |
+|---|---|---|
+| `dpp_sdk.core` | Reusable core DPP model, validation, JSON transport | `dpp-datamodel/dpp-core` |
+| `dpp_sdk.dpp4fun` | Furniture-specific DPP aggregate | `dpp-datamodel/dpp4fun` |
+| `dpp_sdk.clients` | HTTP clients for the DPP repository & registry APIs | `dpp-sdk-clients` |
+
+The Spring Boot mock services in `../dpp-sdk-platform/dpp-sdk-demo` are **not** ported; they are
+reused as a conformance oracle for client tests.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+pytest        # tests
+mypy          # type check (strict)
+ruff check .  # lint
+```
+
+## Layout
+
+```
+src/dpp_sdk/
+  core/        # core model + validation
+  dpp4fun/     # furniture aggregate, validation, JSON transport
+  clients/     # repo + registry HTTP clients
+tests/         # pytest suite
+docs/          # PORTING_PLAN.md, RELEASING.md
+```

dpp_sdk-0.1.0/docs/PORTING_PLAN.md

@@ -0,0 +1,101 @@
+# DPP SDK — Python Port Plan
+
+## Context
+
+This project is the **Python port** of the Java DPP SDK that lives in the sibling repo
+`../dpp-sdk-platform`. That Java SDK is a reference implementation for **Digital Product
+Passports** (draft prEN-18222-aligned). The goal here is to provide *the same functionality*
+as an idiomatic Python SDK.
+
+Scope and fidelity decided with the user:
+- **Cover:** the datamodel (`dpp-core` + `dpp4fun`) **and** the HTTP clients
+  (`dpp-repo-client`, `dpp-registry-client`). **Exclude** the Spring Boot mock services /
+  integration demo (reuse them only as a test oracle, see Verification).
+- **Fidelity:** **idiomatic Python using Pydantic v2** — not a literal 1:1 port.
+
+## Verdict (feasibility)
+
+**High confidence, no architectural blockers.** The Java SDK has no code generation, no
+annotation processors, no Lombok/MapStruct, and **no SAMM/ESMF/Catena-X or RDF/JSON-LD**.
+It is hand-written immutable POJOs, hand-written bidirectional mappers, a validator registry,
+Jackson JSON, and plain HTTP clients — all of which have clean (often simpler) Python
+equivalents.
+
+**Effort:** Java is ~6.9k LOC (datamodel + clients) + ~3.7k test LOC, but much is boilerplate
+Pydantic gives for free. Idiomatic Python should land around **2.5–4k LOC**; realistic budget
+**~4–7 focused weeks** to feature + test parity. Time goes into re-encoding validation rules
+and reproducing the JSON transport contract — not raw translation.
+
+## Why Pydantic collapses most of the work
+
+The Java SDK is layered: immutable **model** → **Builder** → **Validator** (runtime
+`Map<Class,Validator>` registry) → **payload DTO** → **Mapper** → **JsonCodec**. Pydantic v2
+collapses these into one declarative class:
+
+| Java layer | Python (Pydantic v2) |
+|---|---|
+| Immutable model + `private final` + equals/hashCode/toString | `class X(BaseModel)` + `model_config = ConfigDict(frozen=True)` — equality/repr/hash free |
+| Nested static `Builder` + `toBuilder()` | keyword constructor + `model_copy(update=...)` |
+| `Validator<T>` + `ValidationService` registry | `@field_validator` / `@model_validator` on the model |
+| Jackson payload DTO + `@JsonProperty` | same model with `Field(alias=...)`, `populate_by_name=True` |
+| `Mapper.toPayload/toDomain` | `model_dump(by_alias=True)` / `model_validate(...)` |
+| `Dpp4FunJsonCodec` | `model_dump_json()` / `model_validate_json()` |
+
+UUID → `uuid.UUID`, `LocalDate` → `datetime.date`, `OrganizationRole` → `enum.Enum`/`StrEnum`.
+
+## Real challenges (where the time goes)
+
+1. **Flat vs. nested transport (the tricky part).** The Java codec emits *flattened* outbound
+   JSON (lifts `coreDpp`'s passportMetadata/nameplate/documentation to the root) but accepts
+   *both* flat and nested inbound. Implement with a `@model_serializer` for flattening on
+   output and a `@model_validator(mode="before")` to normalize flat-or-nested on input. Pin
+   byte-for-byte wire compatibility with the Java output via golden-file round-trip tests —
+   real consumers depend on the wire shape.
+2. **~20 validators with cross-object/conditional rules** (externalDocumentationLink ⇒
+   documentation required; category ↔ productType case-insensitive contains; mandatory
+   material ⇒ portion > 0; BOM uniqueness by name+reference; update dates not in the future;
+   dimensions present ⇒ unit required). Map to `@model_validator(mode="after")`; transcribe
+   and test each against the Java `VALIDATION_RULES.md`.
+3. **Fail-fast vs. collect-all.** Java throws on first violation (`ValidationException`);
+   Pydantic aggregates all errors into one `ValidationError`. Decide and document the chosen
+   contract (recommend adopting Pydantic's multi-error behavior; note the intentional diff).
+4. **Immutability nuance.** `frozen=True` blocks reassignment but not in-place list mutation.
+   Use `tuple`/`frozenset` for collection fields, or document the trade-off.
+5. **HTTP clients.** `HttpDppRepoClient<T>` is generic over codec+validator and supports
+   fine-grained element updates via **RFC 6902 JSON Patch**. Port with `httpx`; use the
+   `jsonpatch` library; `<T>` → `TypeVar`/`Generic[T]` or a `type[BaseModel]` arg. The API
+   wrapper DTOs (statusCode/payload/messages) become small Pydantic models.
+6. **Packaging.** Ship a proper PyPI package: `pyproject.toml` (PEP 621), `src/` layout,
+   `py.typed` marker, `ruff` + `mypy` + `pytest`. Flatten the Maven 7-module split into one
+   package: `dpp_sdk.core`, `dpp_sdk.dpp4fun`, `dpp_sdk.clients`.
+
+## Execution outline
+
+1. **Package skeleton:** `pyproject.toml`, `src/dpp_sdk/{core,dpp4fun,clients}/`, `py.typed`,
+   ruff/mypy/pytest config.
+2. **Core models** (`dpp_sdk/core/model.py`): Pydantic models for PassportMetadata, Nameplate,
+   Documentation, Organization, Contact, Address, Email, Telephone, DppCore; `OrganizationRole`
+   enum. Field aliases mirror Jackson `@JsonProperty`.
+3. **Core validation:** `@field_validator`/`@model_validator` encoding the core subset of
+   `VALIDATION_RULES.md`.
+4. **dpp4fun models + validation** (`dpp_sdk/dpp4fun/model.py`): Dpp4Fun, ProductClassification,
+   Characteristics, Dimensions, BillOfMaterials/Material/Component/Part, plus cross-object rules.
+5. **Transport:** `@model_serializer` (flatten out) + `@model_validator(mode="before")` (accept
+   flat or nested) on Dpp4Fun, replacing `Dpp4FunJsonCodec`. Provide thin
+   `to_json()/from_json()/from_json_and_validate()` helpers for API familiarity.
+6. **HTTP clients** (`dpp_sdk/clients/`): `httpx`-based `DppRepoClient` / `DppRegistryClient`,
+   generic over a model type; JSON-Patch updates via `jsonpatch`; API-wrapper response models.
+7. **Tests:** port `TestDataFactory`/`CoreTestDataFactory` as pytest fixtures; replicate the
+   Java round-trip, edge-case, inbound-validation, and end-to-end scenario suites.
+
+## Verification
+
+- **Wire compatibility (most important):** capture canonical JSON outputs from the Java SDK for
+  the demo fixtures, commit them as golden files, and assert Python `model_dump_json()` matches
+  (modulo key order). Round-trip both flat and nested inbound payloads.
+- **Validation parity:** for every rule in `VALIDATION_RULES.md`, a passing case and a failing
+  case; assert the failing case raises.
+- **Client parity:** run the Python clients against the existing Java Spring Boot mock
+  repo/registry in `../dpp-sdk-platform/dpp-sdk-demo` (reuse as a conformance oracle, do not
+  port). Exercise create / read / update (JSON Patch) / register flows.
+- `pytest` green, `mypy` clean, `ruff` clean.

dpp_sdk-0.1.0/docs/RELEASING.md

@@ -0,0 +1,106 @@
+# Releasing `dpp-sdk`
+
+This project ships a single PyPI package, `dpp-sdk`, built with
+[hatchling](https://hatch.pypa.io/). Releases are automated with GitHub Actions and
+**PyPI Trusted Publishing** (OIDC) — no API tokens are ever stored.
+
+- Build tool: `python -m build` → `dist/dpp_sdk-X.Y.Z-py3-none-any.whl` + `.tar.gz`
+- Version source of truth: `__version__` in `src/dpp_sdk/__init__.py`
+  (hatchling reads it via `[tool.hatch.version]`)
+- Workflows: `.github/workflows/release.yml` (publish) and `ci.yml` (test gate)
+
+---
+
+## One-time setup (do this once, before the first release)
+
+Trusted Publishing maps a specific GitHub repo + workflow + environment to a PyPI project.
+It must be registered **before** the first upload, while the project name is still unclaimed
+(a "pending publisher").
+
+### 1. Create accounts
+- PyPI: <https://pypi.org/account/register/>
+- TestPyPI (separate account): <https://test.pypi.org/account/register/>
+
+Enable 2FA on both.
+
+### 2. Register the pending publisher on **PyPI**
+Go to <https://pypi.org/manage/account/publishing/> → "Add a new pending publisher" and enter:
+
+| Field | Value |
+|---|---|
+| PyPI Project Name | `dpp-sdk` |
+| Owner | `CIR4FUN-EU` |
+| Repository name | `dpp-sdk-python` |
+| Workflow name | `release.yml` |
+| Environment name | `pypi` |
+
+### 3. Register the pending publisher on **TestPyPI**
+Repeat at <https://test.pypi.org/manage/account/publishing/> with the **same values**, except:
+
+| Field | Value |
+|---|---|
+| Environment name | `testpypi` |
+
+### 4. Create the GitHub Environments
+In the GitHub repo → Settings → Environments, create two environments whose names match
+the workflow:
+- `testpypi`
+- `pypi` — add yourself (`OnneM156`) as a **Required reviewer** so production uploads pause
+  for manual approval.
+
+No secrets are needed in either environment; OIDC handles auth.
+
+---
+
+## Cutting a release
+
+1. Make sure `main` is green (CI passes: ruff, mypy, pytest).
+2. Bump the version in `src/dpp_sdk/__init__.py` (`__version__ = "X.Y.Z"`), following
+   [SemVer](https://semver.org/).
+3. Move the `## [Unreleased]` notes in `CHANGELOG.md` under a new `## [X.Y.Z]` heading and
+   update the compare links at the bottom.
+4. Commit: `git commit -am "Release vX.Y.Z"` and push to `main`.
+5. Tag and push the tag:
+   ```bash
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   ```
+6. The **Release** workflow runs automatically:
+   - builds the sdist + wheel and runs `twine check`,
+   - publishes to **TestPyPI**,
+   - then waits on the `pypi` environment for your approval.
+7. Verify the TestPyPI artifact in a clean environment:
+   ```bash
+   python -m venv /tmp/relcheck && source /tmp/relcheck/bin/activate
+   pip install --index-url https://test.pypi.org/simple/ \
+               --extra-index-url https://pypi.org/simple/ dpp-sdk
+   python -c "import dpp_sdk; print(dpp_sdk.__version__)"
+   ```
+   (The `--extra-index-url` lets `pydantic`/`httpx` resolve from real PyPI, since TestPyPI
+   may not host them.)
+8. Approve the `pypi` environment in the GitHub Actions run → the package publishes to PyPI.
+9. Confirm:
+   ```bash
+   pip install dpp-sdk
+   python -c "import dpp_sdk; from dpp_sdk import Dpp4Fun; print(dpp_sdk.__version__)"
+   ```
+
+> **Note:** a given version can only be uploaded once. If a (Test)PyPI upload of `X.Y.Z`
+> already exists, bump to a new version — you cannot overwrite or re-upload it.
+
+---
+
+## Manual fallback (no CI)
+
+If you ever need to publish from a workstation instead of CI:
+
+```bash
+pip install -e ".[release]"        # installs build + twine
+python -m build                     # -> dist/
+twine check dist/*
+twine upload --repository testpypi dist/*   # dry run
+twine upload dist/*                          # real PyPI
+```
+
+This uses a PyPI API token configured in `~/.pypirc` rather than Trusted Publishing.
+Prefer the tag-driven CI flow above whenever possible.