Metadata-Version: 2.4
Name: extensible-django-commerce
Version: 1.0.0
Summary: Basic yet highly extensible requirements for commerce in django.
Author-email: Alireza Tabatabaeian <alireza.tabatabaeian@gmail.com>
Project-URL: Homepage, https://github.com/Alireza-Tabatabaeian/django-commerce
Project-URL: Issues, https://github.com/Alireza-Tabatabaeian/django-commerce/issues
Keywords: django,commerce,cart,offsite payment gateway,extensibility
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: Django>=4.2
Requires-Dist: django-plugin-system>=2.0.8
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-django>=4.8.0; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: django-stubs>=5.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"

# Django Commerce

A lightweight and extensible commerce foundation for Django projects.

`django-commerce` provides reusable commerce primitives such as products, carts, orders, transactions, and pluggable offsite payment gateways — designed to integrate cleanly with modular Django architectures and plugin-based systems.

This package is built on top of [django-plugin-system](https://github.com/Alireza-Tabatabaeian/django-plugin-system).

CAUTION: The package has been changed signifactly and README does not guide well right now. Will be modified in near future.

---

# Features

* Base product abstraction
* Shopping cart system
* Order management
* Transaction tracking
* Extensible offsite payment gateway architecture
* Plugin-based payment providers
* Designed for reusable Django applications

---

# Installation

Install using pip:

```bash
pip install django-commerce
```

Add applications to your `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...

    'django_plugin_system',

    'django_commerce.product',
    'django_commerce.cart',
    'django_commerce.order',
    'django_commerce.transaction',
    'django_commerce.offsite_payment_gateway',
]
```

Run migrations:

```bash
python manage.py migrate
```

---

# Package Structure

```text
django_commerce/
├── product/
├── cart/
├── order/
├── transaction/
└── offsite_payment_gateway/
```

---

# Base Product

The package provides a reusable `BaseProduct` model abstraction that can be extended in your own project.

Example:

```python
from django.db import models
from django_commerce.product.models import BaseProduct


class Product(BaseProduct):
    description = models.TextField()
```

---

# Offsite Payment Gateway

The package includes an abstract offsite payment gateway system that allows developers to integrate external payment providers such as:

* Zarinpal
* Stripe Checkout
* PayPal
* Mollie
* Any redirect-based payment provider

To create a custom gateway, extend `AbstractOffsitePaymentGateway`.

---

# Creating a Payment Gateway

Example:

```python
from django.http import HttpRequest

from django_commerce.offsite_payment_gateway.models import (
    AbstractOffsitePaymentGateway
)


class ZarinpalGateway(AbstractOffsitePaymentGateway):
    name = 'zarinpal'
    _gateway_base_url = 'https://sandbox.zarinpal.com'

    def get_payment_gateway(self, order):
        transaction = self.create_transaction(order)

        callback = self.callback_url(transaction)

        return f'{self._gateway_base_url}/start/{transaction.id}?callback={callback}'

    def verify_payment(self, transaction, callback_request: HttpRequest) -> bool:
        authority = callback_request.GET.get('Authority')

        if not authority:
            return False

        # Verify payment using provider API
        # ...

        transaction.is_verified = True
        transaction.save()

        return True
```

---

# Registering Gateway Plugins

Gateways are designed to work with the plugin system.

Example registration:

```python
from django_plugin_system import register_plugin

from .gateway import ZarinpalGateway


register_plugin(
    manager='django_commerce.offsite_payment_gateway',
    title='Zarinpal Gateway',
    plugin=ZarinpalGateway,
)
```

---

# Payment Callback View

The package provides a callback endpoint handler for payment verification.

Example URL configuration:

```python
from django.urls import path

from django_commerce.offsite_payment_gateway.views import callback_view


urlpatterns = [
    path(
        'payment-callback/<int:transaction_id>',
        callback_view,
        name='payment_callback'
    ),
]
```

After the payment provider redirects the user back to your application, the callback view:

1. Loads the related transaction
2. Resolves the payment gateway plugin
3. Calls `verify_payment`
4. Verifies and finalizes the transaction

---

# Transactions

Each payment attempt creates a `Transaction` object associated with:

* Order
* Payment plugin
* Verification state

This makes payment tracking and auditing easier across multiple providers.

---

# Design Goals

This package focuses on:

* Reusability
* Extensibility
* Minimal assumptions
* Plugin-oriented architecture
* Separation of concerns

It is intended to act as a commerce foundation rather than a complete e-commerce platform.

---

# Development

Clone the repository:

```bash
git clone <repository-url>
```

Install in editable mode:

```bash
pip install -e .
```

Run migrations from the development project:

```bash
python manage.py migrate
```

---

# License

MIT License
