Metadata-Version: 2.4
Name: python-sendparcel-inpost
Version: 0.2.0
Summary: InPost ShipX provider for python-sendparcel.
Project-URL: Homepage, https://github.com/python-sendparcel/python-sendparcel-inpost
Project-URL: Repository, https://github.com/python-sendparcel/python-sendparcel-inpost
Project-URL: Changelog, https://github.com/python-sendparcel/python-sendparcel-inpost/blob/main/CHANGELOG.md
Project-URL: Issue Tracker, https://github.com/python-sendparcel/python-sendparcel-inpost/issues
Author-email: Dominik Kozaczko <dominik@kozaczko.info>
License: MIT
License-File: LICENSE
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'
Requires-Dist: ty>=0.0.1a11; 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
```
