python-sendparcel 0.2.0__tar.gz → 0.3.0__tar.gz

python_sendparcel-0.3.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.3.0] - 2026-07-04
+
+### Changed (breaking)
+
+- Unified the five capability trait ABCs (`LabelProvider`,
+  `PushCallbackProvider`, `PullStatusProvider`, `CancellableProvider`)
+  into a single `BaseProvider`; unsupported capabilities raise
+  `ProviderCapabilityError` by default
+- Removed the validator framework; required config fields declared in
+  `config_schema` are now validated automatically at provider
+  construction
+- Callbacks are handled through `CallbackContext`
+  (`verify_callback(ctx)` / `handle_callback(ctx)`)
+- Providers receive their HTTP transport via `transport_factory`
+  injection (`create_provider` wires it)
+
+### Fixed
+
+- Missing `Any` import in `sendparcel.types` made
+  `CallbackContext` annotations unresolvable at runtime
+  (`typing.get_type_hints` raised `NameError`)
+- `ShipmentBatch` created without an explicit registry now uses the
+  global registry singleton, consistent with `ShipmentFlow`
+- `ConcurrentExecutor` now uses anyio primitives and works under the
+  trio backend (previously hardcoded asyncio)
+- Lint and type-check regressions; `ruff check`, `ruff format --check`,
+  `ty check`, and `mypy --strict src` all pass again
+- README quick-start example was missing the `update_fields` repository
+  method required by `create_label`
+- Provider-authoring guide rewritten for the unified `BaseProvider`
+  API (previous examples raised `ImportError`)
+
+### Added
+
+- `PluginRegistry.slugs()` — public, thread-safe accessor for all
+  registered provider slugs
+
+### Removed
+
+- `fastapi` and `litestar` extras from the README (not published)
+- Dead code: `ShipmentStatusResponse` alias, logging compat aliases
+
+## [0.2.0] - 2025-06-05
+
+### Added
+
+- `CallbackContext` for webhook callback handling
+- Transport injection via factory pattern
+- `ConcurrentExecutor` generic concurrency primitive
+- Structured JSON logging helpers
+
+## [0.1.0] - 2025-02-16
+
+### Added
+
+- Provider protocol and plugin registry with entry-point discovery
+- Shipment domain types (`AddressInfo`, `ParcelInfo`, `ShipmentCreateResult`, `LabelInfo`)
+- Finite state machine for shipment lifecycle (`ShipmentStatus` enum with 9 states)
+- Framework-agnostic `ShipmentFlow` orchestrator
+- `BaseProvider` abstract class for provider plugins
+- Built-in `DummyProvider` for testing and development
+- Global and per-provider validator support
+- Async-first runtime powered by `anyio`
+- Full test suite (157 tests)

{python_sendparcel-0.2.0 → python_sendparcel-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-sendparcel
-Version: 0.2.0
+Version: 0.3.0
 Summary: Framework-agnostic parcel shipping core for Python.
 Project-URL: Homepage, https://github.com/python-sendparcel/python-sendparcel
 Project-URL: Repository, https://github.com/python-sendparcel/python-sendparcel
@@ -23,12 +23,13 @@ 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: 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'
+Requires-Dist: django-sendparcel>=0.3.0; extra == 'all'
+Requires-Dist: python-sendparcel-cli>=0.2.0; extra == 'all'
+Requires-Dist: python-sendparcel-dpdpl>=0.1.1; extra == 'all'
+Requires-Dist: python-sendparcel-inpost>=0.3.0; extra == 'all'
+Requires-Dist: python-sendparcel-orlenpaczka>=0.0.1; extra == 'all'
 Provides-Extra: cli
-Requires-Dist: python-sendparcel-cli>=0.1.0; extra == 'cli'
+Requires-Dist: python-sendparcel-cli>=0.2.0; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: pre-commit-hooks>=6.0.0; extra == 'dev'
 Requires-Dist: pre-commit>=4.0; extra == 'dev'
@@ -36,26 +37,30 @@ 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: trio>=0.27; extra == 'dev'
 Requires-Dist: ty>=0.0.16; extra == 'dev'
 Provides-Extra: django
-Requires-Dist: django-sendparcel>=0.1.0; extra == 'django'
+Requires-Dist: django-sendparcel>=0.3.0; extra == 'django'
 Provides-Extra: dpdpl
-Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'dpdpl'
+Requires-Dist: python-sendparcel-dpdpl>=0.1.1; extra == 'dpdpl'
 Provides-Extra: dummy
 Provides-Extra: frameworks
-Requires-Dist: django-sendparcel>=0.1.0; extra == 'frameworks'
+Requires-Dist: django-sendparcel>=0.3.0; extra == 'frameworks'
 Provides-Extra: inpost
-Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'inpost'
+Requires-Dist: python-sendparcel-inpost>=0.3.0; extra == 'inpost'
+Provides-Extra: orlenpaczka
+Requires-Dist: python-sendparcel-orlenpaczka>=0.0.1; extra == 'orlenpaczka'
 Provides-Extra: providers
-Requires-Dist: python-sendparcel-dpdpl>=0.1.0; extra == 'providers'
-Requires-Dist: python-sendparcel-inpost>=0.1.0; extra == 'providers'
+Requires-Dist: python-sendparcel-dpdpl>=0.1.1; extra == 'providers'
+Requires-Dist: python-sendparcel-inpost>=0.3.0; extra == 'providers'
+Requires-Dist: python-sendparcel-orlenpaczka>=0.0.1; 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
+> Alpha notice: `0.3.0` is still unstable. The API can change fast because the
 > ecosystem is still being cleaned up.
 
 ## What it is
@@ -120,6 +125,12 @@ class InMemoryRepository:
         self._store[shipment.id] = shipment
         return shipment
 
+    async def update_fields(self, shipment_id: str, **fields) -> MyShipment:
+        shipment = self._store[shipment_id]
+        for key, value in fields.items():
+            setattr(shipment, key, value)
+        return shipment
+
 
 async def main() -> None:
     flow = ShipmentFlow(repository=InMemoryRepository())
@@ -156,15 +167,20 @@ anyio.run(main)
 
 ## Provider model
 
-- `BaseProvider.create_shipment(...)` returns `ShipmentCreateResult`.
+All providers subclass `BaseProvider`; capability methods raise
+`ProviderCapabilityError` unless overridden:
+
+- `BaseProvider.create_shipment(...)` returns `ShipmentCreateResult` (required).
 - `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`.
+- `BaseProvider.create_label(...)` returns `LabelInfo`.
+- `BaseProvider.verify_callback(ctx)` / `handle_callback(ctx)` return
+  `None` / `ShipmentUpdateResult`.
+- `BaseProvider.fetch_shipment_status(...)` returns `ShipmentUpdateResult`.
+- `BaseProvider.cancel_shipment(...)` returns `bool`.
 
-Use `ConfirmationMethod.PUSH` only with `PushCallbackProvider` and
-`ConfirmationMethod.PULL` only with `PullStatusProvider`.
+Use `ConfirmationMethod.PUSH` only when the callback methods are overridden
+and `ConfirmationMethod.PULL` only when `fetch_shipment_status` is. See
+`docs/provider-authoring.md` for the full guide.
 
 The core owns shipment state transitions. Providers translate carrier responses
 into normalized results.
@@ -184,10 +200,9 @@ uv add python-sendparcel
 ## Extras
 
 - `django`
-- `fastapi`
-- `litestar`
 - `inpost`
 - `dpdpl`
+- `orlenpaczka`
 - `cli`
 - `frameworks`
 - `providers`
@@ -198,6 +213,8 @@ uv add python-sendparcel
 ```bash
 uv sync --extra dev
 uv run pytest
-uv run ruff check src tests
-uv run mypy src tests
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check
+uv run mypy src
 ```

{python_sendparcel-0.2.0 → python_sendparcel-0.3.0}/README.md

@@ -2,7 +2,7 @@
 
 Framework-agnostic parcel shipping core for Python.
 
-> Alpha notice: `0.1.1` is still unstable. The API can change fast because the
+> Alpha notice: `0.3.0` is still unstable. The API can change fast because the
 > ecosystem is still being cleaned up.
 
 ## What it is
@@ -67,6 +67,12 @@ class InMemoryRepository:
         self._store[shipment.id] = shipment
         return shipment
 
+    async def update_fields(self, shipment_id: str, **fields) -> MyShipment:
+        shipment = self._store[shipment_id]
+        for key, value in fields.items():
+            setattr(shipment, key, value)
+        return shipment
+
 
 async def main() -> None:
     flow = ShipmentFlow(repository=InMemoryRepository())
@@ -103,15 +109,20 @@ anyio.run(main)
 
 ## Provider model
 
-- `BaseProvider.create_shipment(...)` returns `ShipmentCreateResult`.
+All providers subclass `BaseProvider`; capability methods raise
+`ProviderCapabilityError` unless overridden:
+
+- `BaseProvider.create_shipment(...)` returns `ShipmentCreateResult` (required).
 - `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`.
+- `BaseProvider.create_label(...)` returns `LabelInfo`.
+- `BaseProvider.verify_callback(ctx)` / `handle_callback(ctx)` return
+  `None` / `ShipmentUpdateResult`.
+- `BaseProvider.fetch_shipment_status(...)` returns `ShipmentUpdateResult`.
+- `BaseProvider.cancel_shipment(...)` returns `bool`.
 
-Use `ConfirmationMethod.PUSH` only with `PushCallbackProvider` and
-`ConfirmationMethod.PULL` only with `PullStatusProvider`.
+Use `ConfirmationMethod.PUSH` only when the callback methods are overridden
+and `ConfirmationMethod.PULL` only when `fetch_shipment_status` is. See
+`docs/provider-authoring.md` for the full guide.
 
 The core owns shipment state transitions. Providers translate carrier responses
 into normalized results.
@@ -131,10 +142,9 @@ uv add python-sendparcel
 ## Extras
 
 - `django`
-- `fastapi`
-- `litestar`
 - `inpost`
 - `dpdpl`
+- `orlenpaczka`
 - `cli`
 - `frameworks`
 - `providers`
@@ -145,6 +155,8 @@ uv add python-sendparcel
 ```bash
 uv sync --extra dev
 uv run pytest
-uv run ruff check src tests
-uv run mypy src tests
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check
+uv run mypy src
 ```

{python_sendparcel-0.2.0 → python_sendparcel-0.3.0}/docs/provider-authoring.md

@@ -17,19 +17,35 @@ mycarrier = "sendparcel_mycarrier.provider:MyCarrierProvider"
 ## Provider contract
 
 Every provider must subclass `sendparcel.provider.BaseProvider`.
+There are no capability trait classes — `BaseProvider` declares every
+capability method, and the unsupported ones raise
+`ProviderCapabilityError` by default. Override only what the carrier
+actually supports.
 
 ### Required
 
 - `create_shipment(sender_address, receiver_address, parcels, **kwargs) -> ShipmentCreateResult`
 
-### Optional traits
+### Optional capability overrides
 
-| Capability | Trait | Return value |
+| Capability | Method to override | Return value |
 |---|---|---|
-| Labels | `LabelProvider` | `LabelInfo` |
-| Webhooks | `PushCallbackProvider` | `ShipmentUpdateResult` |
-| Polling | `PullStatusProvider` | `ShipmentUpdateResult` |
-| Cancellation | `CancellableProvider` | `bool` |
+| Labels | `create_label(**kwargs)` | `LabelInfo` |
+| Webhooks | `verify_callback(ctx)` + `handle_callback(ctx)` | `None` / `ShipmentUpdateResult` |
+| Polling | `fetch_shipment_status(**kwargs)` | `ShipmentUpdateResult` |
+| Cancellation | `cancel_shipment(**kwargs)` | `bool` |
+
+Webhook methods receive a `sendparcel.types.CallbackContext` carrying
+`shipment_id`, `payload`, `headers`, `source_ip`, and `raw_body`.
+
+### Transport
+
+Providers that talk HTTP declare a `transport_factory` classvar
+(`transport_factory(**config) -> transport`). The factory is called by
+`sendparcel.factory.create_provider`, and the built transport is
+available inside the provider via `self._get_client()`. Configuration
+fields are declared in `config_schema`; required fields are validated
+automatically at construction time.
 
 ## Important rule
 
@@ -48,18 +64,20 @@ That means callback and polling implementations should translate carrier payload
 `BaseProvider.confirmation_method` defaults to `ConfirmationMethod.NONE`.
 
 - `NONE` - the provider does not expose shipment updates.
-- `PUSH` - the provider must implement `PushCallbackProvider`.
-- `PULL` - the provider must implement `PullStatusProvider`.
+- `PUSH` - the provider must override `verify_callback` and
+  `handle_callback`.
+- `PULL` - the provider must override `fetch_shipment_status`.
 
-Do not declare `PUSH` or `PULL` unless the provider actually implements the
-matching capability trait.
+Do not declare `PUSH` or `PULL` unless the provider actually overrides the
+matching capability methods.
 
 ## Minimal example
 
 ```python
 from typing import Any, ClassVar
 
-from sendparcel.provider import BaseProvider, LabelProvider
+from sendparcel.enums import LabelFormat
+from sendparcel.provider import BaseProvider
 from sendparcel.types import (
     AddressInfo,
     LabelInfo,
@@ -68,7 +86,7 @@ from sendparcel.types import (
 )
 
 
-class MyCarrierProvider(BaseProvider, LabelProvider):
+class MyCarrierProvider(BaseProvider):
     slug: ClassVar[str] = "mycarrier"
     display_name: ClassVar[str] = "My Carrier"
 
@@ -87,7 +105,7 @@ class MyCarrierProvider(BaseProvider, LabelProvider):
 
     async def create_label(self, **kwargs: Any) -> LabelInfo:
         return LabelInfo(
-            format="PDF",
+            format=LabelFormat.PDF,
             url="https://carrier.example/labels/TRACK-123.pdf",
         )
 ```
@@ -95,16 +113,18 @@ class MyCarrierProvider(BaseProvider, LabelProvider):
 ## Callback and polling example
 
 ```python
-from sendparcel.provider import PullStatusProvider, PushCallbackProvider
-from sendparcel.types import ShipmentUpdateResult
+from sendparcel.enums import ConfirmationMethod
+from sendparcel.types import CallbackContext, ShipmentUpdateResult
+
 
+class StatusProvider(MyCarrierProvider):
+    confirmation_method = ConfirmationMethod.PUSH
 
-class StatusProvider(BaseProvider, PushCallbackProvider, PullStatusProvider):
-    async def verify_callback(self, data, headers, **kwargs) -> None:
+    async def verify_callback(self, ctx: CallbackContext) -> None:
         return None
 
     async def handle_callback(
-        self, data, headers, **kwargs
+        self, ctx: CallbackContext
     ) -> ShipmentUpdateResult:
         return ShipmentUpdateResult(status="in_transit")
 

{python_sendparcel-0.2.0 → python_sendparcel-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-sendparcel"
-version = "0.2.0"
+version = "0.3.0"
 description = "Framework-agnostic parcel shipping core for Python."
 readme = "README.md"
 license = { text = "MIT" }
@@ -28,28 +28,31 @@ dev = [
   "pytest-asyncio>=0.24.0",
   "pytest-cov>=5.0",
   "ruff>=0.9.0",
+  "trio>=0.27",
   "ty>=0.0.16",
 ]
 dummy = []
-django = ["django-sendparcel>=0.1.0"]
+django = ["django-sendparcel>=0.3.0"]
 # fastapi = ["fastapi-sendparcel>=0.1.0"]
 # litestar = ["litestar-sendparcel>=0.1.0"]
-inpost = ["python-sendparcel-inpost>=0.1.0"]
-dpdpl = ["python-sendparcel-dpdpl>=0.1.0"]
-cli = ["python-sendparcel-cli>=0.1.0"]
-providers = ["python-sendparcel-inpost>=0.1.0", "python-sendparcel-dpdpl>=0.1.0"]
+inpost = ["python-sendparcel-inpost>=0.3.0"]
+dpdpl = ["python-sendparcel-dpdpl>=0.1.1"]
+orlenpaczka = ["python-sendparcel-orlenpaczka>=0.0.1"]
+cli = ["python-sendparcel-cli>=0.2.0"]
+providers = ["python-sendparcel-inpost>=0.3.0", "python-sendparcel-dpdpl>=0.1.1", "python-sendparcel-orlenpaczka>=0.0.1"]
 frameworks = [
-  "django-sendparcel>=0.1.0",
+  "django-sendparcel>=0.3.0",
   # "fastapi-sendparcel>=0.1.0",
   # "litestar-sendparcel>=0.1.0",
 ]
 all = [
-  "django-sendparcel>=0.1.0",
+  "django-sendparcel>=0.3.0",
   # "fastapi-sendparcel>=0.1.0",
   # "litestar-sendparcel>=0.1.0",
-  "python-sendparcel-inpost>=0.1.0",
-  "python-sendparcel-dpdpl>=0.1.0",
-  "python-sendparcel-cli>=0.1.0",
+  "python-sendparcel-inpost>=0.3.0",
+  "python-sendparcel-dpdpl>=0.1.1",
+  "python-sendparcel-orlenpaczka>=0.0.1",
+  "python-sendparcel-cli>=0.2.0",
 ]
 
 [project.urls]
@@ -101,6 +104,7 @@ invalid-return-type = "ignore"
 django-sendparcel = { path = "../django-sendparcel", editable = true }
 python-sendparcel-inpost = { path = "../python-sendparcel-inpost", editable = true }
 python-sendparcel-dpdpl = { path = "../python-sendparcel-dpdpl", editable = true }
+python-sendparcel-orlenpaczka = { path = "../python-sendparcel-orlenpaczka", editable = true }
 python-sendparcel-cli = { path = "../python-sendparcel-cli", editable = true }
 
 [tool.coverage.run]

{python_sendparcel-0.2.0 → python_sendparcel-0.3.0}/src/sendparcel/__init__.py

@@ -1,6 +1,6 @@
 """sendparcel core package."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from sendparcel.batch import BatchCreateResult, BatchResult, ShipmentBatch
 from sendparcel.enums import ConfirmationMethod, LabelFormat, ShipmentStatus
@@ -13,18 +13,14 @@ from sendparcel.exceptions import (
     SendParcelException,
     ShipmentNotFoundError,
 )
+from sendparcel.factory import create_provider
 from sendparcel.flow import ShipmentFlow
 from sendparcel.logging import configure_logging, get_logger
-from sendparcel.provider import (
-    BaseProvider,
-    CancellableProvider,
-    LabelProvider,
-    PullStatusProvider,
-    PushCallbackProvider,
-)
+from sendparcel.provider import BaseProvider
 from sendparcel.providers.dummy import DummyProvider
 from sendparcel.registry import registry
 from sendparcel.types import (
+    CallbackContext,
     CreateLabelOutcome,
     CreateShipmentOutcome,
     ShipmentUpdateOutcome,
@@ -35,7 +31,7 @@ __all__ = [
     "BaseProvider",
     "BatchCreateResult",
     "BatchResult",
-    "CancellableProvider",
+    "CallbackContext",
     "CommunicationError",
     "ConfirmationMethod",
     "CreateLabelOutcome",
@@ -44,11 +40,8 @@ __all__ = [
     "InvalidCallbackError",
     "InvalidTransitionError",
     "LabelFormat",
-    "LabelProvider",
     "ProviderCapabilityError",
     "ProviderNotFoundError",
-    "PullStatusProvider",
-    "PushCallbackProvider",
     "SendParcelException",
     "ShipmentBatch",
     "ShipmentFlow",
@@ -58,6 +51,7 @@ __all__ = [
     "ShipmentUpdateResult",
     "__version__",
     "configure_logging",
+    "create_provider",
     "get_logger",
     "registry",
 ]