python-sendparcel 0.1.0__tar.gz

python_sendparcel-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run ty check
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --extra dev --python ${{ matrix.python-version }}
+      - run: uv run pytest tests/ --cov=sendparcel --cov-report=xml -v
+      - uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

python_sendparcel-0.1.0/.github/workflows/ecosystem-smoke.yml

@@ -0,0 +1,38 @@
+name: Ecosystem smoke
+
+on:
+  workflow_dispatch:
+
+jobs:
+  smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Setup Python
+        run: uv python install 3.12
+
+      - name: Install core
+        run: uv sync --extra dev
+
+      - name: Smoke plugin discovery
+        run: |
+          uv run python - <<'PY'
+          from sendparcel.provider import BaseProvider
+          from sendparcel.registry import registry
+
+          class SmokeProvider(BaseProvider):
+              slug = "smoke"
+              display_name = "Smoke"
+
+              async def create_shipment(self, **kwargs):
+                  return {}
+
+          registry.register(SmokeProvider)
+          assert registry.get_by_slug("smoke") is SmokeProvider
+          print("plugin discovery smoke ok")
+          PY

python_sendparcel-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

python_sendparcel-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.ty/
+.coverage
+coverage.xml
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store

python_sendparcel-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff
+        name: ruff
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]
+      - id: ruff-format
+        name: ruff-format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+      - id: check-toml
+        name: check-toml
+        entry: uv run check-toml
+        language: system
+        types: [toml]
+      - id: check-yaml
+        name: check-yaml
+        entry: uv run check-yaml
+        language: system
+        types: [yaml]
+      - id: end-of-file-fixer
+        name: end-of-file-fixer
+        entry: uv run end-of-file-fixer
+        language: system
+        types: [text]
+      - id: trailing-whitespace
+        name: trailing-whitespace
+        entry: uv run trailing-whitespace-fixer
+        language: system
+        types: [text]
+      - id: ty
+        name: ty
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false

python_sendparcel-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# 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.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.1.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to python-sendparcel
+
+Thank you for considering a contribution to `python-sendparcel` — the
+framework-agnostic core of the sendparcel ecosystem.
+
+## Prerequisites
+
+- Python 3.12 or later
+- [uv](https://docs.astral.sh/uv/) package manager
+
+## Development setup
+
+1. Clone the repository and navigate to the `python-sendparcel` directory.
+2. Install the project with dev dependencies:
+
+```bash
+uv sync --extra dev
+```
+
+## Running tests
+
+Tests use **pytest** with **pytest-asyncio** (`asyncio_mode = "auto"`).
+
+```bash
+uv run pytest tests/ -q
+```
+
+Always run tests through `uv run` so the correct virtualenv is used.
+
+## Linting and formatting
+
+The project uses **ruff** for both linting and formatting:
+
+```bash
+uv run ruff check src tests
+uv run ruff format --check src tests
+```
+
+Static type checking is done with **ty**:
+
+```bash
+uv run --extra dev ty check
+```
+
+## Code style
+
+- All code, comments, docstrings, and messages **must be in English**.
+- Keep APIs **async-first**.
+- Use `anyio` for async primitives and async/sync bridging points.
+- Imports belong at the **top of the file** (PEP 8). Inline imports are
+  only acceptable to break a verified circular import, with a comment
+  explaining the reason.
+- Follow the ruff rule set configured in `pyproject.toml`
+  (`E`, `W`, `F`, `I`, `N`, `UP`, `B`, `A`, `SIM`, `RUF`).
+
+## Pull request process
+
+1. Fork the repository and create a feature branch from `main`.
+2. Make your changes in small, focused commits.
+3. Ensure all quality checks pass (tests, linting, formatting, type checks).
+4. Open a pull request against `main` with a clear description of your
+   changes.
+
+## Commit messages
+
+- Use the **imperative mood** ("Add feature", not "Added feature").
+- Keep the subject line concise (72 characters or fewer).
+- Reference related issues when applicable (e.g., `Fix #42`).
+
+## Ecosystem rules
+
+- Keep APIs async-first.
+- Use `anyio` for async primitives and async/sync bridging points.
+- Preserve plugin compatibility with `python-sendparcel` core contracts —
+  framework adapters (`django-sendparcel`, `fastapi-sendparcel`,
+  `litestar-sendparcel`) depend on stable public interfaces.
+- Any change to a public API must be reflected in the adapter packages.

python_sendparcel-0.1.0/LICENSE

@@ -0,0 +1,10 @@
+
+MIT License
+
+Copyright (c) 2025, Dominik Kozaczko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.