python-sendparcel 0.1.0__tar.gz → 0.1.1__tar.gz

{python_sendparcel-0.1.0 → python_sendparcel-0.1.1}/.gitignore

@@ -25,6 +25,10 @@ dist/
 # IDE
 .vscode/
 .idea/
+.sisyphus/
 
 # OS
 .DS_Store
+
+# uv
+uv.lock

python_sendparcel-0.1.1/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: python-sendparcel
+Version: 0.1.1
+Summary: Framework-agnostic parcel shipping core for Python.
+Project-URL: Homepage, https://github.com/sendparcel/python-sendparcel
+Project-URL: Documentation, https://python-sendparcel.readthedocs.io/
+Project-URL: Repository, https://github.com/sendparcel/python-sendparcel
+Project-URL: Changelog, https://github.com/sendparcel/python-sendparcel/blob/main/CHANGELOG.md
+Project-URL: Issue Tracker, https://github.com/sendparcel/python-sendparcel/issues
+Author-email: Dominik Kozaczko <dominik@kozaczko.info>
+License: MIT
+License-File: LICENSE
+Keywords: delivery,logistics,parcel,sendparcel,shipping
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: all
+Requires-Dist: django-sendparcel>=0.1.0; extra == 'all'
+Requires-Dist: fastapi-sendparcel>=0.1.0; extra == 'all'
+Requires-Dist: litestar-sendparcel>=0.1.0; extra == 'all'
+Requires-Dist: python-sendparcel-cli>=0.1.0; extra == 'all'
+Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'all'
+Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'all'
+Provides-Extra: cli
+Requires-Dist: python-sendparcel-cli>=0.1.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: pre-commit-hooks>=6.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: ty>=0.0.16; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django-sendparcel>=0.1.0; extra == 'django'
+Provides-Extra: dpdpl
+Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'dpdpl'
+Provides-Extra: dummy
+Provides-Extra: fastapi
+Requires-Dist: fastapi-sendparcel>=0.1.0; extra == 'fastapi'
+Provides-Extra: frameworks
+Requires-Dist: django-sendparcel>=0.1.0; extra == 'frameworks'
+Requires-Dist: fastapi-sendparcel>=0.1.0; extra == 'frameworks'
+Requires-Dist: litestar-sendparcel>=0.1.0; extra == 'frameworks'
+Provides-Extra: inpost
+Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'inpost'
+Provides-Extra: litestar
+Requires-Dist: litestar-sendparcel>=0.1.0; extra == 'litestar'
+Provides-Extra: providers
+Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'providers'
+Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'providers'
+Description-Content-Type: text/markdown
+
+# python-sendparcel
+
+Framework-agnostic parcel shipping core for Python.
+
+> Alpha notice: `0.1.1` is still unstable. The API can change fast because the
+> ecosystem is still being cleaned up.
+
+## What it is
+
+- Provider-agnostic shipment orchestration with a single core flow.
+- Explicit shipment metadata persistence: `id`, `status`, `provider`, `external_id`, `tracking_number`.
+- Label payloads are operation results, not persisted shipment fields.
+- One normalized provider update contract for both callbacks and polling.
+- Runtime-checkable `Shipment` and `ShipmentRepository` protocols so adapters can use their own models.
+
+## Core contract
+
+- `ShipmentFlow.create_shipment(...) -> CreateShipmentOutcome`
+- `ShipmentFlow.create_label(...) -> CreateLabelOutcome`
+- `ShipmentFlow.handle_callback(...) -> ShipmentUpdateOutcome`
+- `ShipmentFlow.fetch_and_update_status(...) -> ShipmentUpdateOutcome`
+- `ShipmentFlow.cancel_shipment(...) -> bool`
+
+`CreateShipmentOutcome` and `CreateLabelOutcome` return label payloads when available.
+The shipment object never stores label bytes or a persisted `label_url` in the core contract.
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+from decimal import Decimal
+
+import anyio
+
+from sendparcel import ShipmentFlow
+from sendparcel.types import AddressInfo, ParcelInfo
+
+
+@dataclass
+class MyShipment:
+    id: str
+    status: str = "new"
+    provider: str = ""
+    external_id: str = ""
+    tracking_number: str = ""
+
+
+class InMemoryRepository:
+    def __init__(self) -> None:
+        self._store: dict[str, MyShipment] = {}
+        self._counter = 0
+
+    async def get_by_id(self, shipment_id: str) -> MyShipment:
+        return self._store[shipment_id]
+
+    async def create(self, **kwargs) -> MyShipment:
+        self._counter += 1
+        shipment = MyShipment(
+            id=str(self._counter),
+            status=str(kwargs.get("status", "new")),
+            provider=str(kwargs.get("provider", "")),
+        )
+        self._store[shipment.id] = shipment
+        return shipment
+
+    async def save(self, shipment: MyShipment) -> MyShipment:
+        self._store[shipment.id] = shipment
+        return shipment
+
+
+async def main() -> None:
+    flow = ShipmentFlow(repository=InMemoryRepository())
+
+    created = await flow.create_shipment(
+        "dummy",
+        sender_address=AddressInfo(
+            name="Sender Co.",
+            line1="Marszalkowska 1",
+            city="Warsaw",
+            postal_code="00-001",
+            country_code="PL",
+        ),
+        receiver_address=AddressInfo(
+            name="Jan Kowalski",
+            line1="Dluga 10",
+            city="Gdansk",
+            postal_code="80-001",
+            country_code="PL",
+        ),
+        parcels=[ParcelInfo(weight_kg=Decimal("2.5"))],
+    )
+
+    print(created.shipment.status)
+    print(created.shipment.external_id)
+    print(created.shipment.tracking_number)
+
+    labelled = await flow.create_label(created.shipment)
+    print(labelled.label.get("url"))
+
+
+anyio.run(main)
+```
+
+## Provider model
+
+- `BaseProvider.create_shipment(...)` returns `ShipmentCreateResult`.
+- `BaseProvider.confirmation_method` defaults to `ConfirmationMethod.NONE`.
+- `LabelProvider.create_label(...)` returns `LabelInfo`.
+- `PushCallbackProvider.handle_callback(...)` returns `ShipmentUpdateResult`.
+- `PullStatusProvider.fetch_shipment_status(...)` returns `ShipmentUpdateResult`.
+- `CancellableProvider.cancel_shipment(...)` returns `bool`.
+
+Use `ConfirmationMethod.PUSH` only with `PushCallbackProvider` and
+`ConfirmationMethod.PULL` only with `PullStatusProvider`.
+
+The core owns shipment state transitions. Providers translate carrier responses
+into normalized results.
+
+## Installation
+
+```bash
+pip install python-sendparcel
+```
+
+With `uv`:
+
+```bash
+uv add python-sendparcel
+```
+
+## Extras
+
+- `django`
+- `fastapi`
+- `litestar`
+- `inpost`
+- `dpdpl`
+- `cli`
+- `frameworks`
+- `providers`
+- `all`
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src tests
+uv run mypy src tests
+```

python_sendparcel-0.1.1/README.md

@@ -0,0 +1,150 @@
+# python-sendparcel
+
+Framework-agnostic parcel shipping core for Python.
+
+> Alpha notice: `0.1.1` is still unstable. The API can change fast because the
+> ecosystem is still being cleaned up.
+
+## What it is
+
+- Provider-agnostic shipment orchestration with a single core flow.
+- Explicit shipment metadata persistence: `id`, `status`, `provider`, `external_id`, `tracking_number`.
+- Label payloads are operation results, not persisted shipment fields.
+- One normalized provider update contract for both callbacks and polling.
+- Runtime-checkable `Shipment` and `ShipmentRepository` protocols so adapters can use their own models.
+
+## Core contract
+
+- `ShipmentFlow.create_shipment(...) -> CreateShipmentOutcome`
+- `ShipmentFlow.create_label(...) -> CreateLabelOutcome`
+- `ShipmentFlow.handle_callback(...) -> ShipmentUpdateOutcome`
+- `ShipmentFlow.fetch_and_update_status(...) -> ShipmentUpdateOutcome`
+- `ShipmentFlow.cancel_shipment(...) -> bool`
+
+`CreateShipmentOutcome` and `CreateLabelOutcome` return label payloads when available.
+The shipment object never stores label bytes or a persisted `label_url` in the core contract.
+
+## Quick start
+
+```python
+from dataclasses import dataclass
+from decimal import Decimal
+
+import anyio
+
+from sendparcel import ShipmentFlow
+from sendparcel.types import AddressInfo, ParcelInfo
+
+
+@dataclass
+class MyShipment:
+    id: str
+    status: str = "new"
+    provider: str = ""
+    external_id: str = ""
+    tracking_number: str = ""
+
+
+class InMemoryRepository:
+    def __init__(self) -> None:
+        self._store: dict[str, MyShipment] = {}
+        self._counter = 0
+
+    async def get_by_id(self, shipment_id: str) -> MyShipment:
+        return self._store[shipment_id]
+
+    async def create(self, **kwargs) -> MyShipment:
+        self._counter += 1
+        shipment = MyShipment(
+            id=str(self._counter),
+            status=str(kwargs.get("status", "new")),
+            provider=str(kwargs.get("provider", "")),
+        )
+        self._store[shipment.id] = shipment
+        return shipment
+
+    async def save(self, shipment: MyShipment) -> MyShipment:
+        self._store[shipment.id] = shipment
+        return shipment
+
+
+async def main() -> None:
+    flow = ShipmentFlow(repository=InMemoryRepository())
+
+    created = await flow.create_shipment(
+        "dummy",
+        sender_address=AddressInfo(
+            name="Sender Co.",
+            line1="Marszalkowska 1",
+            city="Warsaw",
+            postal_code="00-001",
+            country_code="PL",
+        ),
+        receiver_address=AddressInfo(
+            name="Jan Kowalski",
+            line1="Dluga 10",
+            city="Gdansk",
+            postal_code="80-001",
+            country_code="PL",
+        ),
+        parcels=[ParcelInfo(weight_kg=Decimal("2.5"))],
+    )
+
+    print(created.shipment.status)
+    print(created.shipment.external_id)
+    print(created.shipment.tracking_number)
+
+    labelled = await flow.create_label(created.shipment)
+    print(labelled.label.get("url"))
+
+
+anyio.run(main)
+```
+
+## Provider model
+
+- `BaseProvider.create_shipment(...)` returns `ShipmentCreateResult`.
+- `BaseProvider.confirmation_method` defaults to `ConfirmationMethod.NONE`.
+- `LabelProvider.create_label(...)` returns `LabelInfo`.
+- `PushCallbackProvider.handle_callback(...)` returns `ShipmentUpdateResult`.
+- `PullStatusProvider.fetch_shipment_status(...)` returns `ShipmentUpdateResult`.
+- `CancellableProvider.cancel_shipment(...)` returns `bool`.
+
+Use `ConfirmationMethod.PUSH` only with `PushCallbackProvider` and
+`ConfirmationMethod.PULL` only with `PullStatusProvider`.
+
+The core owns shipment state transitions. Providers translate carrier responses
+into normalized results.
+
+## Installation
+
+```bash
+pip install python-sendparcel
+```
+
+With `uv`:
+
+```bash
+uv add python-sendparcel
+```
+
+## Extras
+
+- `django`
+- `fastapi`
+- `litestar`
+- `inpost`
+- `dpdpl`
+- `cli`
+- `frameworks`
+- `providers`
+- `all`
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src tests
+uv run mypy src tests
+```

python_sendparcel-0.1.1/docs/compatibility-matrix.md

@@ -0,0 +1,25 @@
+# Ecosystem compatibility matrix
+
+| Package | Type | Depends on `python-sendparcel` |
+|---|---|---|
+| python-sendparcel-inpost | Provider | >=0.1.1 |
+| python-sendparcel-dpdpl | Provider | >=0.1.1 |
+| django-sendparcel | Framework adapter | >=0.1.1 |
+| fastapi-sendparcel | Framework adapter | >=0.1.1 |
+| litestar-sendparcel | Framework adapter | >=0.1.1 |
+
+## Plugin discovery
+
+The ecosystem entry point group is: `sendparcel.providers`.
+
+The reference `dummy` provider is built into `python-sendparcel`.
+
+### Available provider plugins
+
+| Entry point | Provider class | Package |
+|---|---|---|
+| `dummy` | `sendparcel.providers.dummy:DummyProvider` | `python-sendparcel` (built-in) |
+| `inpost_locker` | `sendparcel_inpost.providers:InPostLockerProvider` | `python-sendparcel-inpost` |
+| `inpost_courier` | `sendparcel_inpost.providers:InPostCourierProvider` | `python-sendparcel-inpost` |
+| `dpd_standard` | `sendparcel_dpdpl.providers.standard:DPDStandardProvider` | `python-sendparcel-dpdpl` |
+| `dpd_pickup` | `sendparcel_dpdpl.providers.pickup:DPDPickupProvider` | `python-sendparcel-dpdpl` |

{python_sendparcel-0.1.0 → python_sendparcel-0.1.1}/docs/conf.py

@@ -9,7 +9,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
 project = "python-sendparcel"
 copyright = "2025, Dominik Kozaczko"
 author = "Dominik Kozaczko"
-release = "0.1.0"
+release = "0.1.1"
 
 extensions = [
     "sphinx.ext.autodoc",

python_sendparcel-0.1.1/docs/getting-started.md

@@ -0,0 +1,115 @@
+# Getting started
+
+## Installation
+
+Requires Python 3.12+.
+
+```bash
+pip install python-sendparcel
+```
+
+With `uv`:
+
+```bash
+uv add python-sendparcel
+```
+
+## Core ideas
+
+- `Shipment` and `ShipmentRepository` are protocols. Bring your own models.
+- Providers translate carrier APIs into normalized core results.
+- `ShipmentFlow` owns orchestration and status transitions.
+- Labels are returned from operations and are not persisted by the core contract.
+- Callback and polling paths share the same normalized update shape.
+
+## Minimal example
+
+```python
+from dataclasses import dataclass
+from decimal import Decimal
+
+import anyio
+
+from sendparcel import ShipmentFlow
+from sendparcel.types import AddressInfo, ParcelInfo
+
+
+@dataclass
+class MyShipment:
+    id: str
+    status: str = "new"
+    provider: str = ""
+    external_id: str = ""
+    tracking_number: str = ""
+
+
+class InMemoryRepository:
+    def __init__(self) -> None:
+        self._store: dict[str, MyShipment] = {}
+        self._counter = 0
+
+    async def get_by_id(self, shipment_id: str) -> MyShipment:
+        return self._store[shipment_id]
+
+    async def create(self, **kwargs) -> MyShipment:
+        self._counter += 1
+        shipment = MyShipment(
+            id=str(self._counter),
+            status=str(kwargs.get("status", "new")),
+            provider=str(kwargs.get("provider", "")),
+        )
+        self._store[shipment.id] = shipment
+        return shipment
+
+    async def save(self, shipment: MyShipment) -> MyShipment:
+        self._store[shipment.id] = shipment
+        return shipment
+
+
+async def main() -> None:
+    flow = ShipmentFlow(repository=InMemoryRepository())
+    created = await flow.create_shipment(
+        "dummy",
+        sender_address=AddressInfo(
+            name="Sender Co.",
+            line1="Marszalkowska 1",
+            city="Warsaw",
+            postal_code="00-001",
+            country_code="PL",
+        ),
+        receiver_address=AddressInfo(
+            name="Jan Kowalski",
+            line1="Dluga 10",
+            city="Gdansk",
+            postal_code="80-001",
+            country_code="PL",
+        ),
+        parcels=[ParcelInfo(weight_kg=Decimal("2.5"))],
+    )
+
+    print(created.shipment.status)
+    print(created.shipment.external_id)
+    print(created.shipment.tracking_number)
+
+    label = await flow.create_label(created.shipment)
+    print(label.label.get("url"))
+
+
+anyio.run(main)
+```
+
+## Provider configuration
+
+```python
+flow = ShipmentFlow(
+    repository=repo,
+    config={
+        "mycarrier": {
+            "api_key": "sk_live_...",
+            "sandbox": True,
+        },
+    },
+)
+```
+
+Providers access settings with `self.get_setting("api_key")`.

{python_sendparcel-0.1.0 → python_sendparcel-0.1.1}/docs/index.md

@@ -9,7 +9,7 @@ communication, and plugin discovery.
 
 ```{admonition} Alpha notice
 :class: warning
-This project is at version **0.1.0**. The public API may change between minor
+This project is at version **0.1.1**. The public API may change between minor
 releases until 1.0 is reached. Pin your dependency accordingly.
 ```
 
@@ -17,9 +17,9 @@ releases until 1.0 is reached. Pin your dependency accordingly.
 
 - **Provider plugin system** — register carriers via entry points or manually; auto-discovered at first use.
 - **Shipment domain types** — strict TypedDicts (`AddressInfo`, `ParcelInfo`, `LabelInfo`, and more).
-- **9-state finite state machine** — `NEW` through `DELIVERED`, plus `CANCELLED`, `FAILED`, and `RETURNED`, with guarded transitions.
+- **Explicit transition rules** — `NEW` through `DELIVERED`, plus `CANCELLED`, `FAILED`, and `RETURNED`, with core-owned status transitions.
 - **ShipmentFlow orchestrator** — async workflow for creating shipments, fetching labels, handling callbacks, polling status, and cancelling.
-- **Runtime protocols** — `Order`, `Shipment`, and `ShipmentRepository` are `@runtime_checkable`; bring your own models and persistence.
+- **Runtime protocols** — `Shipment` and `ShipmentRepository` are `@runtime_checkable`; bring your own models and persistence.
 - **Built-in DummyProvider** — deterministic reference provider for testing and local development.
 - **Async-first** — the entire runtime is async, powered by [anyio](https://anyio.readthedocs.io/).
 
@@ -30,9 +30,9 @@ native models, views/routes, and repository implementations:
 
 | Package | Framework |
 |---|---|
-| [django-sendparcel](https://github.com/sendparcel/django-sendparcel) | Django |
-| [fastapi-sendparcel](https://github.com/sendparcel/fastapi-sendparcel) | FastAPI |
-| [litestar-sendparcel](https://github.com/sendparcel/litestar-sendparcel) | Litestar |
+| [django-sendparcel](https://github.com/python-sendparcel/django-sendparcel) | Django |
+| [fastapi-sendparcel](https://github.com/python-sendparcel/fastapi-sendparcel) | FastAPI |
+| [litestar-sendparcel](https://github.com/python-sendparcel/litestar-sendparcel) | Litestar |
 
 Install adapters via extras: `pip install python-sendparcel[django]`,
 `[fastapi]`, `[litestar]`, `[frameworks]`, or `[all]`.

python_sendparcel-0.1.1/docs/installation-matrix.md

@@ -0,0 +1,28 @@
+# Installation matrix
+
+## Compatibility policy
+
+- Ecosystem packages follow semantic versioning.
+- `python-sendparcel` is the compatibility anchor.
+- Provider plugins and adapters should depend on `python-sendparcel>=0.1.1`.
+- All ecosystem packages are async-first and use `anyio`.
+
+## Current matrix
+
+| Package | Version | Requires |
+|---|---:|---|
+| python-sendparcel | 0.1.1 | Python 3.12+, anyio>=4.0 |
+| python-sendparcel-inpost | 0.1.1 | python-sendparcel>=0.1.1, httpx>=0.27.0, anyio>=4.0 |
+| python-sendparcel-dpdpl | 0.1.1 | python-sendparcel>=0.1.1, httpx>=0.27.0, anyio>=4.0 |
+| django-sendparcel | 0.1.0 | python-sendparcel>=0.1.1, Django>=5.2, anyio>=4.0 |
+| fastapi-sendparcel | 0.1.0 | python-sendparcel>=0.1.1, FastAPI>=0.115, anyio>=4.0 |
+| litestar-sendparcel | 0.1.0 | python-sendparcel>=0.1.1, Litestar>=2.0, anyio>=4.0 |
+
+## Recommended bundles
+
+- `python-sendparcel` already includes the built-in `dummy` provider.
+- `python-sendparcel[inpost]` for the InPost ShipX provider.
+- `python-sendparcel[dpdpl]` for the DPD Poland provider.
+- `python-sendparcel[providers]` for bundled provider extras.
+- `python-sendparcel[frameworks]` for all framework adapters.
+- `python-sendparcel[all]` for core + all framework adapters.

python_sendparcel-0.1.1/docs/plans/2026-02-17-order-optional.md

@@ -0,0 +1,21 @@
+# Make Order Optional — Implementation Plan
+
+**Goal:** Decouple `Order` from the `Shipment` protocol and flow, making it an optional convenience.
+
+**Architecture:** Remove `order: Order` from `Shipment` protocol. `ShipmentFlow.create_shipment()` takes explicit address/parcel params. Add `create_shipment_from_order()` convenience. `BaseProvider.create_shipment()` receives address/parcel data as explicit params.
+
+**Tech Stack:** Python 3.12+, asyncio, runtime_checkable protocols, TypedDict
+
+## Tasks
+
+1. Core protocols — Remove order from Shipment
+2. Core flow — New create_shipment + create_shipment_from_order
+3. Core provider — Explicit params on BaseProvider.create_shipment
+4. Core tests — Update all fixtures and flow tests
+5. DPD provider — Read from params not self.shipment.order
+6. InPost provider — Read from params not self.shipment.order
+7. CLI package — Remove order from CLIShipment
+8. Django wrapper — Update adapter, keep OrderModelMixin
+9. FastAPI wrapper — Support both order-based and direct creation
+10. Litestar wrapper — Same as FastAPI changes
+11. Documentation updates