python-sendparcel-inpost 0.1.1__tar.gz → 0.1.2__tar.gz

python_sendparcel_inpost-0.1.2/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: python-sendparcel-inpost
+Version: 0.1.2
+Summary: InPost ShipX provider for python-sendparcel.
+Author-email: Dominik Kozaczko <dominik@kozaczko.info>
+License: MIT
+Keywords: inpost,parcel,sendparcel,shipping,shipx
+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
+Requires-Dist: python-sendparcel>=0.1.1
+Provides-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: respx>=0.22.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-sendparcel-inpost
+
+InPost ShipX provider package for the `python-sendparcel` ecosystem.
+
+> Alpha notice: this package tracks the still-changing `python-sendparcel` core.
+
+## What it provides
+
+- `InPostLockerProvider` for locker shipments
+- `InPostCourierProvider` for courier shipments
+- `ShipXClient` for direct async ShipX API access
+- ShipX-to-sendparcel status normalization helpers
+
+## Contract
+
+This package follows the cleaned core contract:
+
+- `create_shipment(...) -> ShipmentCreateResult`
+- `create_label(...) -> LabelInfo`
+- `handle_callback(...) -> ShipmentUpdateResult`
+- `fetch_shipment_status(...) -> ShipmentUpdateResult`
+- `cancel_shipment(...) -> bool`
+
+Providers do not mutate shipment state directly. They translate ShipX responses into normalized results that the core flow applies.
+
+## Installation
+
+```bash
+uv add python-sendparcel-inpost
+```
+
+or:
+
+```bash
+pip install python-sendparcel-inpost
+```
+
+## Configuration
+
+| Key | Type | Description |
+|---|---|---|
+| `token` | `str` | ShipX API bearer token |
+| `organization_id` | `int` | ShipX organization ID |
+| `sandbox` | `bool` | Use sandbox API |
+| `base_url` | `str` | Optional API base override |
+| `timeout` | `float` | Request timeout in seconds |
+
+## Status normalization
+
+ShipX statuses are normalized to sendparcel shipment statuses.
+
+- recognized ShipX statuses produce `{"status": ...}`
+- tracking numbers are included when available
+- unknown ShipX statuses do not invent fake sendparcel statuses
+
+That means callback and polling updates can safely return only tracking data when ShipX introduces a new status the mapper does not know yet.
+
+## Labels
+
+Labels are returned as payloads.
+
+- PDF labels are returned as base64 content in `LabelInfo["content_base64"]`
+- no label URL is persisted by the core contract
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src tests
+uv run mypy src tests
+```

python_sendparcel_inpost-0.1.2/README.md

@@ -0,0 +1,72 @@
+# python-sendparcel-inpost
+
+InPost ShipX provider package for the `python-sendparcel` ecosystem.
+
+> Alpha notice: this package tracks the still-changing `python-sendparcel` core.
+
+## What it provides
+
+- `InPostLockerProvider` for locker shipments
+- `InPostCourierProvider` for courier shipments
+- `ShipXClient` for direct async ShipX API access
+- ShipX-to-sendparcel status normalization helpers
+
+## Contract
+
+This package follows the cleaned core contract:
+
+- `create_shipment(...) -> ShipmentCreateResult`
+- `create_label(...) -> LabelInfo`
+- `handle_callback(...) -> ShipmentUpdateResult`
+- `fetch_shipment_status(...) -> ShipmentUpdateResult`
+- `cancel_shipment(...) -> bool`
+
+Providers do not mutate shipment state directly. They translate ShipX responses into normalized results that the core flow applies.
+
+## Installation
+
+```bash
+uv add python-sendparcel-inpost
+```
+
+or:
+
+```bash
+pip install python-sendparcel-inpost
+```
+
+## Configuration
+
+| Key | Type | Description |
+|---|---|---|
+| `token` | `str` | ShipX API bearer token |
+| `organization_id` | `int` | ShipX organization ID |
+| `sandbox` | `bool` | Use sandbox API |
+| `base_url` | `str` | Optional API base override |
+| `timeout` | `float` | Request timeout in seconds |
+
+## Status normalization
+
+ShipX statuses are normalized to sendparcel shipment statuses.
+
+- recognized ShipX statuses produce `{"status": ...}`
+- tracking numbers are included when available
+- unknown ShipX statuses do not invent fake sendparcel statuses
+
+That means callback and polling updates can safely return only tracking data when ShipX introduces a new status the mapper does not know yet.
+
+## Labels
+
+Labels are returned as payloads.
+
+- PDF labels are returned as base64 content in `LabelInfo["content_base64"]`
+- no label URL is persisted by the core contract
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src tests
+uv run mypy src tests
+```

{python_sendparcel_inpost-0.1.1 → python_sendparcel_inpost-0.1.2}/docs/configuration.md

@@ -80,10 +80,10 @@ Both providers implement the full `BaseProvider` interface:
 |---|---|
 | `create_shipment(**kwargs)` | Create a shipment in ShipX |
 | `create_label(**kwargs)` | Download shipping label (PDF by default) |
-| `fetch_shipment_status(**kwargs)` | Poll ShipX API for current status |
+| `fetch_shipment_status(**kwargs)` | Poll ShipX API and return `ShipmentUpdateResult` |
 | `cancel_shipment(**kwargs)` | Cancel the shipment (returns `True`/`False`) |
 | `verify_callback(data, headers, **kwargs)` | Verify webhook source IP |
-| `handle_callback(data, headers, **kwargs)` | Process webhook payload |
+| `handle_callback(data, headers, **kwargs)` | Normalize webhook payload into `ShipmentUpdateResult` |
 
 ## ShipXClient
 
@@ -173,7 +173,8 @@ ShipX uses 24 internal statuses. These are mapped to 8 sendparcel statuses:
 | `RETURNED` | `returned_to_sender` |
 | `FAILED` | `rejected_by_receiver`, `undelivered`, `oversized`, `missing`, `claim_created` |
 
-Unrecognized statuses return `None` from `map_shipx_status()`.
+Unrecognized statuses return `None` from `map_shipx_status()`. Use
+`build_shipment_update()` to keep tracking data even when a status is unknown.
 
 ## Error handling
 
@@ -206,9 +207,8 @@ the `X-Forwarded-For` header (first entry). Invalid or missing IPs raise
 }
 ```
 
-The `handle_callback` method extracts the status and maps it to a sendparcel
-status using `map_shipx_status()`. The actual FSM transition is handled by
-`ShipmentFlow`.
+The `handle_callback` method normalizes ShipX payloads into
+`ShipmentUpdateResult`. The core flow applies transitions.
 
 ## Enums
 

{python_sendparcel_inpost-0.1.1 → python_sendparcel_inpost-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-sendparcel-inpost"
-version = "0.1.1"
+version = "0.1.2"
 description = "InPost ShipX provider for python-sendparcel."
 readme = "README.md"
 license = { text = "MIT" }
@@ -18,7 +18,7 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules",
   "Typing :: Typed",
 ]
-dependencies = ["python-sendparcel>=0.1.0", "httpx>=0.27.0", "anyio>=4.0"]
+dependencies = ["python-sendparcel>=0.1.1", "httpx>=0.27.0", "anyio>=4.0"]
 
 [project.optional-dependencies]
 dev = [

{python_sendparcel_inpost-0.1.1 → python_sendparcel_inpost-0.1.2}/src/sendparcel_inpost/providers/courier.py

@@ -19,12 +19,12 @@ from sendparcel.types import (
     LabelInfo,
     ParcelInfo,
     ShipmentCreateResult,
-    ShipmentStatusResponse,
+    ShipmentUpdateResult,
 )
 
 from sendparcel_inpost.client import ShipXClient
 from sendparcel_inpost.exceptions import ShipXAPIError
-from sendparcel_inpost.status_mapping import map_shipx_status
+from sendparcel_inpost.status_mapping import build_shipment_update
 from sendparcel_inpost.types import ShipXAddress, ShipXPeer
 
 logger = logging.getLogger(__name__)
@@ -256,23 +256,28 @@ class InPostCourierProvider(
         data: dict[str, Any],
         headers: dict[str, Any],
         **kwargs: Any,
-    ) -> None:
+    ) -> ShipmentUpdateResult:
         """Process InPost webhook payload."""
         payload = data.get("payload", {})
-        shipx_status = payload.get("status", "")
-        sendparcel_status = map_shipx_status(shipx_status)
-        if sendparcel_status:
+        shipx_status = str(payload.get("status", ""))
+        tracking_number = str(payload.get("tracking_number", ""))
+        update = build_shipment_update(
+            shipx_status,
+            tracking_number=tracking_number,
+        )
+        if update:
             logger.info(
                 "InPost webhook: %s -> %s (shipment %s)",
                 shipx_status,
-                sendparcel_status,
+                update,
                 payload.get("shipment_id"),
             )
+        return update
 
     async def fetch_shipment_status(
         self,
         **kwargs: Any,
-    ) -> ShipmentStatusResponse:
+    ) -> ShipmentUpdateResult:
         """Fetch current status from ShipX API."""
         shipment_id = int(self.shipment.external_id)
 
@@ -284,11 +289,9 @@ class InPostCourierProvider(
         finally:
             await client.close()
 
-        shipx_status = response.get("status", "")
-        sendparcel_status = map_shipx_status(shipx_status)
-
-        return ShipmentStatusResponse(
-            status=sendparcel_status.value if sendparcel_status else None,
+        return build_shipment_update(
+            str(response.get("status", "")),
+            tracking_number=str(response.get("tracking_number", "")),
         )
 
     async def cancel_shipment(self, **kwargs: Any) -> bool:

{python_sendparcel_inpost-0.1.1 → python_sendparcel_inpost-0.1.2}/src/sendparcel_inpost/providers/locker.py

@@ -19,12 +19,12 @@ from sendparcel.types import (
     LabelInfo,
     ParcelInfo,
     ShipmentCreateResult,
-    ShipmentStatusResponse,
+    ShipmentUpdateResult,
 )
 
 from sendparcel_inpost.client import ShipXClient
 from sendparcel_inpost.exceptions import ShipXAPIError
-from sendparcel_inpost.status_mapping import map_shipx_status
+from sendparcel_inpost.status_mapping import build_shipment_update
 from sendparcel_inpost.types import ShipXAddress, ShipXPeer
 
 logger = logging.getLogger(__name__)
@@ -269,27 +269,31 @@ class InPostLockerProvider(
         data: dict[str, Any],
         headers: dict[str, Any],
         **kwargs: Any,
-    ) -> None:
+    ) -> ShipmentUpdateResult:
         """Process InPost webhook payload.
 
-        The actual FSM transition is handled by ShipmentFlow.
-        This method extracts and normalizes the status.
+        The core flow applies transitions. Providers only normalize payloads.
         """
         payload = data.get("payload", {})
-        shipx_status = payload.get("status", "")
-        sendparcel_status = map_shipx_status(shipx_status)
-        if sendparcel_status:
+        shipx_status = str(payload.get("status", ""))
+        tracking_number = str(payload.get("tracking_number", ""))
+        update = build_shipment_update(
+            shipx_status,
+            tracking_number=tracking_number,
+        )
+        if update:
             logger.info(
                 "InPost webhook: %s -> %s (shipment %s)",
                 shipx_status,
-                sendparcel_status,
+                update,
                 payload.get("shipment_id"),
             )
+        return update
 
     async def fetch_shipment_status(
         self,
         **kwargs: Any,
-    ) -> ShipmentStatusResponse:
+    ) -> ShipmentUpdateResult:
         """Fetch current status from ShipX API."""
         shipment_id = int(self.shipment.external_id)
 
@@ -299,11 +303,9 @@ class InPostLockerProvider(
         finally:
             await client.close()
 
-        shipx_status = response.get("status", "")
-        sendparcel_status = map_shipx_status(shipx_status)
-
-        return ShipmentStatusResponse(
-            status=sendparcel_status.value if sendparcel_status else None,
+        return build_shipment_update(
+            str(response.get("status", "")),
+            tracking_number=str(response.get("tracking_number", "")),
         )
 
     async def cancel_shipment(self, **kwargs: Any) -> bool:

{python_sendparcel_inpost-0.1.1 → python_sendparcel_inpost-0.1.2}/src/sendparcel_inpost/status_mapping.py

@@ -1,6 +1,7 @@
 """ShipX status to sendparcel status mapping."""
 
 from sendparcel.enums import ShipmentStatus
+from sendparcel.types import ShipmentUpdateResult
 
 SHIPX_TO_SENDPARCEL_STATUS: dict[str, ShipmentStatus] = {
     # CREATED
@@ -44,3 +45,19 @@ def map_shipx_status(shipx_status: str) -> ShipmentStatus | None:
     Returns None if the status is not recognized.
     """
     return SHIPX_TO_SENDPARCEL_STATUS.get(shipx_status)
+
+
+def build_shipment_update(
+    shipx_status: str,
+    *,
+    tracking_number: str = "",
+) -> ShipmentUpdateResult:
+    """Build a normalized sendparcel update from ShipX data."""
+
+    update: ShipmentUpdateResult = {}
+    mapped_status = map_shipx_status(shipx_status)
+    if mapped_status is not None:
+        update["status"] = mapped_status.value
+    if tracking_number:
+        update["tracking_number"] = tracking_number
+    return update

{python_sendparcel_inpost-0.1.1 → python_sendparcel_inpost-0.1.2}/tests/test_courier_provider.py

@@ -53,7 +53,6 @@ class _FakeShipment:
     provider: str = "inpost_courier"
     external_id: str = ""
     tracking_number: str = ""
-    label_url: str = ""
 
 
 class TestCourierProviderClassVars:
@@ -112,7 +111,7 @@ class TestCourierCreateShipment:
             )
 
         assert result["external_id"] == "888"
-        assert result["tracking_number"] == "TRACK888"
+        assert result.get("tracking_number") == "TRACK888"
 
         call_kwargs = mock_client.create_shipment.call_args
         payload = call_kwargs.kwargs["payload"]
@@ -203,10 +202,34 @@ class TestCourierFetchStatus:
                 return_value={
                     "id": 888,
                     "status": "taken_by_courier",
+                    "tracking_number": "TRACK888",
                 },
             )
             mock_client.close = AsyncMock()
 
             result = await provider.fetch_shipment_status()
 
-        assert result["status"] == ShipmentStatus.IN_TRANSIT
+        assert result.get("status") == ShipmentStatus.IN_TRANSIT.value
+        assert result.get("tracking_number") == "TRACK888"
+
+
+class TestCourierHandleCallback:
+    async def test_extracts_status_and_tracking_number(self) -> None:
+        shipment = _FakeShipment()
+        provider = InPostCourierProvider(shipment, config={})
+
+        update = await provider.handle_callback(
+            data={
+                "payload": {
+                    "shipment_id": 888,
+                    "status": "taken_by_courier",
+                    "tracking_number": "TRACK888",
+                },
+            },
+            headers={},
+        )
+
+        assert update == {
+            "status": ShipmentStatus.IN_TRANSIT.value,
+            "tracking_number": "TRACK888",
+        }

{python_sendparcel_inpost-0.1.1 → python_sendparcel_inpost-0.1.2}/tests/test_enums.py

@@ -5,10 +5,16 @@ from sendparcel_inpost.enums import ShipXParcelTemplate, ShipXService
 
 class TestShipXService:
     def test_locker_standard(self) -> None:
-        assert ShipXService.INPOST_LOCKER_STANDARD == "inpost_locker_standard"
+        assert (
+            ShipXService.INPOST_LOCKER_STANDARD.value
+            == "inpost_locker_standard"
+        )
 
     def test_inpost_courier_standard(self) -> None:
-        assert ShipXService.INPOST_COURIER_STANDARD == "inpost_courier_standard"
+        assert (
+            ShipXService.INPOST_COURIER_STANDARD.value
+            == "inpost_courier_standard"
+        )
 
     def test_is_str_enum(self) -> None:
         assert isinstance(ShipXService.INPOST_LOCKER_STANDARD, str)
@@ -16,10 +22,10 @@ class TestShipXService:
 
 class TestShipXParcelTemplate:
     def test_small(self) -> None:
-        assert ShipXParcelTemplate.SMALL == "small"
+        assert ShipXParcelTemplate.SMALL.value == "small"
 
     def test_medium(self) -> None:
-        assert ShipXParcelTemplate.MEDIUM == "medium"
+        assert ShipXParcelTemplate.MEDIUM.value == "medium"
 
     def test_large(self) -> None:
-        assert ShipXParcelTemplate.LARGE == "large"
+        assert ShipXParcelTemplate.LARGE.value == "large"

{python_sendparcel_inpost-0.1.1 → python_sendparcel_inpost-0.1.2}/tests/test_locker_provider.py

@@ -45,7 +45,6 @@ class _FakeShipment:
     provider: str = "inpost_locker"
     external_id: str = ""
     tracking_number: str = ""
-    label_url: str = ""
 
 
 class TestLockerProviderClassVars:
@@ -105,7 +104,7 @@ class TestLockerCreateShipment:
             )
 
         assert result["external_id"] == "999"
-        assert result["tracking_number"] == "TRACK999"
+        assert result.get("tracking_number") == "TRACK999"
 
         # Verify the payload sent to client
         call_kwargs = mock_client.create_shipment.call_args
@@ -154,7 +153,7 @@ class TestLockerCreateLabel:
             label = await provider.create_label()
 
         assert label["format"] == "PDF"
-        assert label["content_base64"]  # non-empty base64 string
+        assert label.get("content_base64")  # non-empty base64 string
 
 
 class TestLockerFetchStatus:
@@ -174,13 +173,18 @@ class TestLockerFetchStatus:
         ) as mock_get_client:
             mock_client = mock_get_client.return_value
             mock_client.get_shipment = AsyncMock(
-                return_value={"id": 999, "status": "confirmed"},
+                return_value={
+                    "id": 999,
+                    "status": "confirmed",
+                    "tracking_number": "TRACK999",
+                },
             )
             mock_client.close = AsyncMock()
 
             result = await provider.fetch_shipment_status()
 
-        assert result["status"] == ShipmentStatus.LABEL_READY
+        assert result.get("status") == ShipmentStatus.LABEL_READY.value
+        assert result.get("tracking_number") == "TRACK999"
 
 
 class TestLockerCancelShipment:
@@ -260,10 +264,10 @@ class TestLockerVerifyCallback:
 
 
 class TestLockerHandleCallback:
-    async def test_extracts_status(self) -> None:
+    async def test_extracts_status_and_tracking_number(self) -> None:
         shipment = _FakeShipment()
         provider = InPostLockerProvider(shipment, config={})
-        await provider.handle_callback(
+        update = await provider.handle_callback(
             data={
                 "payload": {
                     "shipment_id": 999,
@@ -273,8 +277,30 @@ class TestLockerHandleCallback:
             },
             headers={},
         )
-        # handle_callback should not raise; status resolution
-        # is the flow's responsibility
+
+        assert update == {
+            "status": ShipmentStatus.LABEL_READY.value,
+            "tracking_number": "TRACK999",
+        }
+
+    async def test_unknown_callback_status_returns_tracking_number_only(
+        self,
+    ) -> None:
+        shipment = _FakeShipment()
+        provider = InPostLockerProvider(shipment, config={})
+
+        update = await provider.handle_callback(
+            data={
+                "payload": {
+                    "shipment_id": 999,
+                    "status": "brand_new_status",
+                    "tracking_number": "TRACK999",
+                },
+            },
+            headers={},
+        )
+
+        assert update == {"tracking_number": "TRACK999"}
 
 
 class TestLockerAddressConversion:
@@ -293,11 +319,11 @@ class TestLockerAddressConversion:
             "country_code": "PL",
         }
         peer = provider._address_to_peer(addr)
-        assert peer["first_name"] == "Jan"
-        assert peer["last_name"] == "Kowalski"
-        assert peer["phone"] == "500100200"
-        assert peer["address"]["street"] == "Marszalkowska"
-        assert peer["address"]["post_code"] == "00-001"
+        assert peer.get("first_name") == "Jan"
+        assert peer.get("last_name") == "Kowalski"
+        assert peer.get("phone") == "500100200"
+        assert peer.get("address", {}).get("street") == "Marszalkowska"
+        assert peer.get("address", {}).get("post_code") == "00-001"
 
     def test_converts_legacy_name_to_first_last(self) -> None:
         shipment = _FakeShipment()
@@ -312,6 +338,6 @@ class TestLockerAddressConversion:
             "country_code": "PL",
         }
         peer = provider._address_to_peer(addr)
-        assert peer["first_name"] == "Jan"
-        assert peer["last_name"] == "Kowalski"
-        assert peer["address"]["street"] == "Marszalkowska 1"
+        assert peer.get("first_name") == "Jan"
+        assert peer.get("last_name") == "Kowalski"
+        assert peer.get("address", {}).get("street") == "Marszalkowska 1"

{python_sendparcel_inpost-0.1.1 → python_sendparcel_inpost-0.1.2}/tests/test_status_mapping.py

@@ -5,6 +5,7 @@ from sendparcel.enums import ShipmentStatus
 
 from sendparcel_inpost.status_mapping import (
     SHIPX_TO_SENDPARCEL_STATUS,
+    build_shipment_update,
     map_shipx_status,
 )
 
@@ -55,3 +56,33 @@ class TestStatusMapping:
         for shipx, sendparcel in SHIPX_TO_SENDPARCEL_STATUS.items():
             assert isinstance(shipx, str)
             assert isinstance(sendparcel, ShipmentStatus)
+
+
+class TestBuildShipmentUpdate:
+    def test_returns_normalized_status_and_tracking_number(self) -> None:
+        update = build_shipment_update(
+            "confirmed",
+            tracking_number="TRACK123",
+        )
+
+        assert update == {
+            "status": ShipmentStatus.LABEL_READY.value,
+            "tracking_number": "TRACK123",
+        }
+
+    def test_returns_tracking_number_without_status_for_unknown_mapping(
+        self,
+    ) -> None:
+        update = build_shipment_update(
+            "brand_new_shipx_status",
+            tracking_number="TRACK999",
+        )
+
+        assert update == {"tracking_number": "TRACK999"}
+
+    def test_returns_empty_update_for_unknown_status_without_tracking_number(
+        self,
+    ) -> None:
+        update = build_shipment_update("brand_new_shipx_status")
+
+        assert update == {}