python-getpaid-core 3.0.0a3__tar.gz → 3.0.1__tar.gz

{python_getpaid_core-3.0.0a3 → python_getpaid_core-3.0.1}/.github/workflows/ci.yml

@@ -29,5 +29,8 @@ jobs:
       - name: Lint with ruff
         run: uv run ruff check .
 
+      - name: Audit dependencies
+        run: uv run pip-audit --strict
+
       - name: Run tests
         run: uv run pytest --tb=short

python_getpaid_core-3.0.1/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history needed for version detection
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: pip install uv
+
+      # Version is read from __init__.py (dynamic via hatch)
+      - name: Detect version from __init__.py
+        id: get-version
+        run: |
+          init_py=$(grep -A2 '\[tool\.hatch\.version\]' pyproject.toml | grep '^path\s*=' | head -1 | sed -E "s/path\s*=\s*['\"]([^'\"]+)['\"].*/\1/")
+          version=$(grep '__version__' "$init_py" | head -1 | sed -E "s/.*= ['\"]([^'\"]+)['\"].*/\1/")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Check if tag already exists
+        id: check-tag
+        run: |
+          tag="v${{ steps.get-version.outputs.version }}"
+          if git rev-parse "$tag" >/dev/null 2>&1; then
+            echo "already_tagged=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "already_tagged=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Tag new version
+        if: steps.check-tag.outputs.already_tagged == 'false'
+        run: |
+          tag="v${{ steps.get-version.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$tag" -m "Release $tag"
+          git push origin "$tag"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package on PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+
+      - name: Publish the release notes
+        if: steps.check-tag.outputs.already_tagged == 'false'
+        uses: release-drafter/release-drafter@v5.20.0
+        with:
+          publish: true
+          name: v${{ steps.get-version.outputs.version }}
+          tag: v${{ steps.get-version.outputs.version }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{python_getpaid_core-3.0.0a3 → python_getpaid_core-3.0.1}/.gitignore

@@ -6,6 +6,7 @@
 /.pytype/
 /dist/
 /docs/_build/
+/_build/
 /src/*.egg-info/
 __pycache__/
 /.idea/

python_getpaid_core-3.0.1/Makefile

@@ -0,0 +1,28 @@
+.PHONY: test test-bench lint type-check audit clean
+
+PYTHON ?= .venv/bin/python
+
+test:             ## Run all tests (unit + benchmarks)
+	$(PYTHON) -m pytest
+
+test-bench:       ## Run benchmarks only
+	$(PYTHON) -m pytest tests/test_benchmarks.py --benchmark-only --benchmark-min-rounds=10 --benchmark-sort=mean
+
+test-bench-save:  ## Run benchmarks and save results
+	$(PYTHON) -m pytest tests/test_benchmarks.py --benchmark-only --benchmark-autosave --benchmark-sort=mean
+
+test-bench-compare:  ## Compare current benchmarks against saved baseline
+	$(PYTHON) -m pytest tests/test_benchmarks.py --benchmark-only --benchmark-compare=0
+
+lint:             ## Run ruff linter
+	$(PYTHON) -m ruff check src tests
+
+type-check:       ## Run type checker
+	$(PYTHON) -m ty check src
+
+audit:            ## Audit dependencies for vulnerabilities
+	$(PYTHON) -m pip-audit
+
+clean:            ## Remove build artifacts and caches
+	rm -rf .pytest_cache .benchmarks .coverage htmlcov build dist *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

{python_getpaid_core-3.0.0a3 → python_getpaid_core-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-getpaid-core
-Version: 3.0.0a3
+Version: 3.0.1
 Summary: Framework-agnostic payment processing core.
 Project-URL: Homepage, https://github.com/django-getpaid/python-getpaid-core
 Project-URL: Repository, https://github.com/django-getpaid/python-getpaid-core
@@ -9,7 +9,7 @@ Project-URL: Changelog, https://github.com/django-getpaid/python-getpaid-core/re
 Author-email: Dominik Kozaczko <dominik@kozaczko.info>
 License: MIT
 License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
@@ -18,9 +18,6 @@ Classifier: Topic :: Office/Business :: Financial
 Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: anyio>=4.0
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: transitions>=0.9.0
 Description-Content-Type: text/markdown
 
 # python-getpaid-core

python_getpaid_core-3.0.1/docs/changelog.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## v3.0.1 (2026-06-05)
+
+### Notes
+
+- Version bump to coordinate with `django-getpaid` v3.0.1, which replaced
+  enum inheritance with composition to support Python 3.14's stricter
+  `EnumType._check_for_existing_members_` check. No changes to core enums
+  themselves — the breaking change was in the Django adapter's wrapper classes.
+
+---
+
+## v3.0.0 (2026-06-04)
+
+Major stable release — framework-agnostic payment processing core.
+
+### Breaking Changes
+
+- Complete rewrite as a framework-agnostic library, no longer coupled to Django
+- `django-fsm` dependency removed — replaced by runtime FSM via `transitions`
+- Requires Python 3.12+
+- `can_proceed()` replaced by `may_trigger()`
+
+### Features
+
+- Payment status enum (`PaymentStatus`) with 9 states matching django-getpaid v2 values
+- Fraud status enum (`FraudStatus`) with 4 states
+- Backend method and confirmation method enums
+- `BaseProcessor` abstract class for payment gateway plugins
+- Semantic payment and fraud update engine
+- Transition validation with `InvalidTransitionError`
+- Provider metadata merging and callback idempotency tracking
+- `PluginRegistry` with entry-point discovery and manual registration
+- Runtime-checkable protocols: `Payment`, `Order`, `PaymentRepository`
+- Dataclass response types: `BuyerInfo`, `ItemInfo`, `ChargeResult`,
+  `PaymentUpdate`, `RefundResult`, `TransactionResult`
+- Structured exception hierarchy with `context` support
+
+---
+
+## v0.1.0 (2026-02-13)
+
+Initial release — extracted from django-getpaid v2 and redesigned as a
+framework-agnostic library.
+
+### Features
+
+- Payment status enum (`PaymentStatus`) with 9 states matching django-getpaid v2
+  values for backward compatibility
+- Fraud status enum (`FraudStatus`) with 4 states
+- Backend method and confirmation method enums
+- `BaseProcessor` abstract class for payment gateway plugins
+- Semantic payment and fraud update engine
+- Transition validation with `InvalidTransitionError`
+- Provider metadata merging and callback idempotency tracking
+- `PluginRegistry` with entry-point discovery and manual registration
+- Runtime-checkable protocols: `Payment`, `Order`, `PaymentRepository`
+- Dataclass response types: `BuyerInfo`, `ItemInfo`, `ChargeResult`,
+  `PaymentUpdate`, `RefundResult`, `TransactionResult`
+- Structured exception hierarchy with `context` support

{python_getpaid_core-3.0.0a3 → python_getpaid_core-3.0.1}/pyproject.toml

@@ -9,7 +9,7 @@ authors = [
 ]
 requires-python = '>=3.12'
 classifiers = [
-    'Development Status :: 3 - Alpha',
+    'Development Status :: 5 - Production/Stable',
     'Intended Audience :: Developers',
     'License :: OSI Approved :: MIT License',
     'Programming Language :: Python :: 3.12',
@@ -18,11 +18,7 @@ classifiers = [
     'Topic :: Office/Business :: Financial :: Point-Of-Sale',
     'Typing :: Typed',
 ]
-dependencies = [
-    'transitions>=0.9.0',
-    'httpx>=0.27.0',
-    'anyio>=4.0',
-]
+dependencies = []
 
 [dependency-groups]
 dev = [
@@ -37,6 +33,8 @@ dev = [
     "myst-parser>=4.0.1",
     "pre-commit-hooks>=6.0.0",
     "ty>=0.0.16",
+    "pip-audit>=2.7.0",
+    "pytest-benchmark>=5.0.0",
 ]
 
 [project.urls]
@@ -91,7 +89,7 @@ ignore = [
 ]
 
 [tool.ruff.lint.per-file-ignores]
-'tests/**' = ['TC001', 'RUF012']
+'tests/**' = ['TC001', 'RUF012', 'E501']
 
 [tool.ruff.lint.isort]
 force-single-line = true

{python_getpaid_core-3.0.0a3 → python_getpaid_core-3.0.1}/src/getpaid_core/__init__.py

@@ -1,6 +1,6 @@
 """Getpaid Core -- framework-agnostic payment processing."""
 
-__version__ = "3.0.0a3"
+__version__ = "3.0.1"
 
 from getpaid_core.enums import BackendMethod
 from getpaid_core.enums import ConfirmationMethod

{python_getpaid_core-3.0.0a3 → python_getpaid_core-3.0.1}/src/getpaid_core/flow.py

@@ -1,9 +1,12 @@
 """Payment flow orchestrator."""
 
+from collections.abc import Callable
 from decimal import Decimal
 from typing import Any
 
 from getpaid_core.enums import PaymentEvent
+from getpaid_core.enums import PaymentStatus
+from getpaid_core.exceptions import InvalidTransitionError
 from getpaid_core.fsm import apply_payment_update
 from getpaid_core.protocols import Order
 from getpaid_core.protocols import Payment
@@ -17,6 +20,9 @@ from getpaid_core.types import TransactionResult
 from getpaid_core.validators import run_validators
 
 
+OperationValidator = Callable[[dict[str, Any]], dict[str, Any]]
+
+
 class PaymentFlow:
     """Core payment processing orchestrator."""
 
@@ -24,16 +30,19 @@ class PaymentFlow:
         self,
         repository: PaymentRepository,
         config: dict[str, dict[str, Any]] | None = None,
-        validators: list | None = None,
+        validators: list[OperationValidator] | None = None,
         registry: PluginRegistry | None = None,
     ) -> None:
         self.repository = repository
-        self.config = config or {}
-        self.validators = validators or []
+        self.config: dict[str, dict[str, Any]] = config or {}
+        self.validators: list[OperationValidator] = validators or []
         self.registry = registry or default_registry
 
     async def create_payment(
-        self, order: Order, backend_slug: str, **kwargs
+        self,
+        order: Order,
+        backend_slug: str,
+        **kwargs: Any,
     ) -> Payment:
         """Create a new payment for an order."""
         self.registry.get_by_slug(backend_slug)
@@ -48,7 +57,11 @@ class PaymentFlow:
         )
         return payment
 
-    async def prepare(self, payment: Payment, **kwargs) -> TransactionResult:
+    async def prepare(
+        self,
+        payment: Payment,
+        **kwargs: Any,
+    ) -> TransactionResult:
         """Prepare a payment for processing."""
         context = self._run_operation_validators(
             operation="prepare",
@@ -71,9 +84,9 @@ class PaymentFlow:
     async def handle_callback(
         self,
         payment: Payment,
-        data: dict,
-        headers: dict,
-        **kwargs,
+        data: dict[str, Any],
+        headers: dict[str, str],
+        **kwargs: Any,
     ) -> None:
         """Handle an incoming PUSH callback from the gateway."""
         context = self._run_operation_validators(
@@ -93,7 +106,10 @@ class PaymentFlow:
         apply_payment_update(payment, update)
         await self.repository.save(payment)
 
-    async def fetch_and_update_status(self, payment: Payment) -> Payment:
+    async def fetch_and_update_status(
+        self,
+        payment: Payment,
+    ) -> Payment:
         """PULL flow: fetch status from gateway and update."""
         context = self._run_operation_validators(
             operation="fetch_status",
@@ -102,6 +118,8 @@ class PaymentFlow:
         )
         processor = self.get_processor(payment)
         update = await processor.fetch_payment_status(**context["kwargs"])
+        if update is None:
+            return payment
         apply_payment_update(payment, update)
         await self.repository.save(payment)
         return payment
@@ -110,7 +128,7 @@ class PaymentFlow:
         self,
         payment: Payment,
         amount: Decimal | None = None,
-        **kwargs,
+        **kwargs: Any,
     ) -> ChargeResult:
         """Charge a pre-authorized payment."""
         context = self._run_operation_validators(
@@ -118,6 +136,16 @@ class PaymentFlow:
             payment=payment,
             kwargs={"amount": amount, **kwargs},
         )
+        # Validate precondition before calling processor (avoids
+        # unnecessary API calls when the payment is not chargeable).
+        if payment.status not in {
+            PaymentStatus.PRE_AUTH,
+            PaymentStatus.IN_CHARGE,
+        }:
+            raise InvalidTransitionError(
+                f"Cannot charge payment in {payment.status!r} status. "
+                "Payment must be PRE_AUTH or IN_CHARGE."
+            )
         processor = self.get_processor(payment)
         result = await processor.charge(**context["kwargs"])
         if result.success:
@@ -136,13 +164,22 @@ class PaymentFlow:
             await self.repository.save(payment)
         return result
 
-    async def release_lock(self, payment: Payment, **kwargs) -> Decimal:
+    async def release_lock(
+        self,
+        payment: Payment,
+        **kwargs: Any,
+    ) -> Decimal:
         """Release a pre-authorized lock."""
         context = self._run_operation_validators(
             operation="release_lock",
             payment=payment,
             kwargs=dict(kwargs),
         )
+        if payment.status != PaymentStatus.PRE_AUTH:
+            raise InvalidTransitionError(
+                f"Cannot release lock for payment in {payment.status!r} "
+                "status. Payment must be PRE_AUTH."
+            )
         processor = self.get_processor(payment)
         amount = await processor.release_lock(**context["kwargs"])
         apply_payment_update(
@@ -156,7 +193,7 @@ class PaymentFlow:
         self,
         payment: Payment,
         amount: Decimal | None = None,
-        **kwargs,
+        **kwargs: Any,
     ) -> RefundResult:
         """Start a refund."""
         context = self._run_operation_validators(
@@ -164,6 +201,15 @@ class PaymentFlow:
             payment=payment,
             kwargs={"amount": amount, **kwargs},
         )
+        if payment.status not in {
+            PaymentStatus.PAID,
+            PaymentStatus.PARTIAL,
+            PaymentStatus.REFUND_STARTED,
+        }:
+            raise InvalidTransitionError(
+                f"Cannot start refund for payment in {payment.status!r} "
+                "status. Payment must be PAID, PARTIAL, or REFUND_STARTED."
+            )
         processor = self.get_processor(payment)
         result = await processor.start_refund(**context["kwargs"])
         apply_payment_update(
@@ -176,7 +222,11 @@ class PaymentFlow:
         await self.repository.save(payment)
         return result
 
-    async def cancel_refund(self, payment: Payment, **kwargs) -> bool:
+    async def cancel_refund(
+        self,
+        payment: Payment,
+        **kwargs: Any,
+    ) -> bool:
         """Cancel an in-progress refund."""
         context = self._run_operation_validators(
             operation="cancel_refund",
@@ -193,11 +243,17 @@ class PaymentFlow:
             await self.repository.save(payment)
         return success
 
-    def get_processor(self, payment: Payment):
+    def get_processor(
+        self,
+        payment: Payment,
+    ) -> Any:
         """Instantiate the processor for a payment."""
         processor_class = self.registry.get_by_slug(payment.backend)
         backend_config = self.config.get(payment.backend, {})
         return processor_class(payment, config=backend_config)
 
-    def _run_operation_validators(self, **context):
+    def _run_operation_validators(
+        self,
+        **context: Any,
+    ) -> dict[str, Any]:
         return run_validators(context, validators=self.validators)

{python_getpaid_core-3.0.0a3 → python_getpaid_core-3.0.1}/src/getpaid_core/fsm.py

@@ -1,6 +1,9 @@
 """State engine for payment and fraud lifecycle transitions."""
 
+from copy import deepcopy
+from dataclasses import dataclass
 from decimal import Decimal
+from typing import Any
 
 from getpaid_core.enums import FraudEvent
 from getpaid_core.enums import FraudStatus
@@ -11,6 +14,18 @@ from getpaid_core.protocols import Payment
 from getpaid_core.types import PaymentUpdate
 
 
+@dataclass(frozen=True)
+class PaymentSnapshot:
+    status: str
+    amount_paid: Decimal
+    amount_locked: Decimal
+    amount_refunded: Decimal
+    external_id: str | None
+    fraud_status: str
+    fraud_message: str
+    provider_data: dict[str, Any] | None
+
+
 def _ensure_provider_data(payment: Payment) -> dict:
     provider_data = getattr(payment, "provider_data", None)
     if provider_data is None:
@@ -48,9 +63,13 @@ def _merge_provider_data(payment: Payment, provider_data: dict) -> None:
     _ensure_provider_data(payment).update(provider_data)
 
 
-def _set_paid_amount(payment: Payment, paid_amount: Decimal | None) -> None:
-    if paid_amount is None:
-        paid_amount = payment.amount_required
+def _set_paid_amount(payment: Payment, paid_amount: Decimal) -> None:
+    """Set paid amount. Raises if paid_amount exceeds amount_required."""
+    if paid_amount > payment.amount_required:
+        raise InvalidTransitionError(
+            f"Paid amount {paid_amount} exceeds amount_required "
+            f"{payment.amount_required}."
+        )
     previous_paid = payment.amount_paid
     next_paid = max(previous_paid, paid_amount)
     increment = next_paid - previous_paid
@@ -66,6 +85,11 @@ def _set_refunded_amount(
 ) -> None:
     if refunded_amount is None:
         refunded_amount = payment.amount_paid
+    if refunded_amount > payment.amount_paid:
+        raise InvalidTransitionError(
+            f"Refunded amount {refunded_amount} exceeds amount_paid "
+            f"{payment.amount_paid}."
+        )
     payment.amount_refunded = max(payment.amount_refunded, refunded_amount)
 
 
@@ -88,6 +112,33 @@ def _active_paid_status(payment: Payment) -> PaymentStatus:
     return PaymentStatus.PREPARED
 
 
+def _snapshot_payment_state(payment: Payment) -> PaymentSnapshot:
+    return PaymentSnapshot(
+        status=payment.status,
+        amount_paid=payment.amount_paid,
+        amount_locked=payment.amount_locked,
+        amount_refunded=payment.amount_refunded,
+        external_id=payment.external_id,
+        fraud_status=payment.fraud_status,
+        fraud_message=payment.fraud_message,
+        provider_data=deepcopy(getattr(payment, "provider_data", None)),
+    )
+
+
+def _restore_payment_state(payment: Payment, snapshot: PaymentSnapshot) -> None:
+    payment.status = snapshot.status
+    payment.amount_paid = snapshot.amount_paid
+    payment.amount_locked = snapshot.amount_locked
+    payment.amount_refunded = snapshot.amount_refunded
+    payment.external_id = snapshot.external_id
+    payment.fraud_status = snapshot.fraud_status
+    payment.fraud_message = snapshot.fraud_message
+    if snapshot.provider_data is None:
+        payment.provider_data = {}
+    else:
+        payment.provider_data = snapshot.provider_data
+
+
 def _apply_payment_event(payment: Payment, update: PaymentUpdate) -> None:
     event = update.payment_event
     if event is None:
@@ -107,6 +158,10 @@ def _apply_payment_event(payment: Payment, update: PaymentUpdate) -> None:
             PaymentStatus.PREPARED,
             PaymentStatus.PRE_AUTH,
         }:
+            if update.locked_amount is None:
+                raise InvalidTransitionError(
+                    "LOCKED event requires explicit locked_amount."
+                )
             _set_locked_amount(payment, update.locked_amount)
             payment.status = PaymentStatus.PRE_AUTH
             return
@@ -127,6 +182,10 @@ def _apply_payment_event(payment: Payment, update: PaymentUpdate) -> None:
             raise InvalidTransitionError(
                 f"Cannot capture payment in {status.value!r} status."
             )
+        if update.paid_amount is None:
+            raise InvalidTransitionError(
+                "PAYMENT_CAPTURED event requires explicit paid_amount."
+            )
         _set_paid_amount(payment, update.paid_amount)
         payment.status = _active_paid_status(payment)
         return
@@ -172,6 +231,10 @@ def _apply_payment_event(payment: Payment, update: PaymentUpdate) -> None:
             raise InvalidTransitionError(
                 f"Cannot confirm refund for payment in {status.value!r} status."
             )
+        if update.refunded_amount is None:
+            raise InvalidTransitionError(
+                "REFUND_CONFIRMED event requires explicit refunded_amount."
+            )
         _set_refunded_amount(payment, update.refunded_amount)
         if (
             payment.amount_refunded >= payment.amount_paid
@@ -195,7 +258,7 @@ def _apply_payment_event(payment: Payment, update: PaymentUpdate) -> None:
         )
 
     if event is PaymentEvent.LOCK_RELEASED:
-        if status in {PaymentStatus.PRE_AUTH, PaymentStatus.REFUNDED}:
+        if status is PaymentStatus.PRE_AUTH:
             payment.amount_locked = Decimal("0.00")
             payment.status = PaymentStatus.REFUNDED
             return
@@ -247,15 +310,22 @@ def apply_payment_update(
     if update is None:
         return payment
 
-    if not _record_provider_event(payment, update.provider_event_id):
-        return payment
+    snapshot = _snapshot_payment_state(payment)
+
+    try:
+        if not _record_provider_event(payment, update.provider_event_id):
+            return payment
+
+        if update.external_id is not None:
+            payment.external_id = update.external_id
+        if update.fraud_message is not None:
+            payment.fraud_message = update.fraud_message
 
-    if update.external_id is not None:
-        payment.external_id = update.external_id
-    if update.fraud_message is not None:
-        payment.fraud_message = update.fraud_message
+        _merge_provider_data(payment, update.provider_data)
+        _apply_payment_event(payment, update)
+        _apply_fraud_event(payment, update)
+    except Exception:
+        _restore_payment_state(payment, snapshot)
+        raise
 
-    _merge_provider_data(payment, update.provider_data)
-    _apply_payment_event(payment, update)
-    _apply_fraud_event(payment, update)
     return payment

{python_getpaid_core-3.0.0a3 → python_getpaid_core-3.0.1}/src/getpaid_core/registry.py

@@ -1,5 +1,6 @@
 """Plugin registry for payment backends."""
 
+import threading
 from importlib.metadata import entry_points
 
 from getpaid_core.processor import BaseProcessor
@@ -14,6 +15,7 @@ class PluginRegistry:
     def __init__(self) -> None:
         self._backends: dict[str, type[BaseProcessor]] = {}
         self._discovered = False
+        self._lock = threading.Lock()
 
     def discover(self) -> None:
         """Load all backends registered via entry points."""
@@ -64,7 +66,9 @@ class PluginRegistry:
 
     def _ensure_discovered(self) -> None:
         if not self._discovered:
-            self.discover()
+            with self._lock:
+                if not self._discovered:
+                    self.discover()
 
     def _register_backend(self, processor_class: type[BaseProcessor]) -> None:
         slug = processor_class.slug