Metadata-Version: 2.5
Name: djangospice-framework
Version: 0.2.0
Summary: Application Runtime Framework for building Django apps.
Project-URL: Homepage, https://github.com/briansimpo/djangospice-framework
Project-URL: Documentation, https://github.com/briansimpo/djangospice-framework#readme
Project-URL: Source, https://github.com/briansimpo/djangospice-framework
Project-URL: Issues, https://github.com/briansimpo/djangospice-framework/issues
Author-email: Brian Simpokolwe <briansimpokolwe@gmail.com>
License: MIT
License-File: LICENSE
Keywords: django,djangospice_framework,framework,modular,runtime
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5
Classifier: Framework :: Django :: 6
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Education
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.12
Requires-Dist: asgiref>=3.8
Requires-Dist: celery>=5.4
Requires-Dist: channels-redis>=4.2
Requires-Dist: channels>=4.1
Requires-Dist: django-celery-beat>=2.6
Requires-Dist: django-filter>=24.0
Requires-Dist: django-import-export>=4.2
Requires-Dist: django-model-utils>=4.5
Requires-Dist: django-tables2>=2.7
Requires-Dist: django>=5.0
Requires-Dist: djangorestframework>=3.15
Requires-Dist: openpyxl>=3.1
Requires-Dist: premailer>=3.10
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: python-slugify>=8.0
Requires-Dist: semver>=3.0
Requires-Dist: setuptools>=80.9
Requires-Dist: tablib[all]>=3.7
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-django; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# djangospice-framework

**Application Runtime Framework for building Django apps**

`djangospice-framework` is the application runtime for building modular Django applications.

It is designed to provide a consistent foundation for building large Django application ecosystems without repeatedly implementing the same infrastructure in every application.

---

## Why djangospice-framework?

Large Django projects often accumulate infrastructure that gets duplicated across applications.

For example, individual applications may independently implement:

* Base models
* Event dispatching
* Job handling
* File handling
* Import/export pipelines
* Realtime broadcasting
* Common service abstractions

djangospice_framework provides these capabilities as a shared runtime.

This gives applications a common architecture and allows modules to remain focused on their actual domain.

### Design goals

djangospice_framework is designed around several principles:

* **Reusable** — common functionality should be implemented once.
* **Modular** — functionality should be composed through independent components.
* **Extensible** — applications should be able to replace or extend framework behavior.
* **Django-native** — use Django's existing ecosystem rather than reinventing it.
* **Developer-friendly** — common application infrastructure should require minimal boilerplate.

---

## Installation

Install djangospice_framework from PyPI:

```bash
pip install djangospice-framework
```

---

## Basic Usage

Once installed, djangospice_framework components can be imported by Django applications and modules.

For example, using the common model infrastructure:

```python
from djangospice_framework.db.models import BaseModel


class Customer(BaseModel):
    name = models.CharField(max_length=255)
```

The exact capabilities available depend on the components being used by the application.

---

# Core Components

`djangospice-framework` is organized around reusable infrastructure rather than business-domain applications.

## Database and Models

Common Django model abstractions provide a consistent foundation for application models.

```python
from djangospice_framework.db.models import BaseModel
```

The database layer is intended to eliminate repetitive model infrastructure while preserving normal Django ORM behavior.

---

## Events

The event system provides a decoupled mechanism for applications to communicate.

Instead of tightly coupling one application component to another, a component can dispatch an event and allow listeners to react to it.

Conceptually:

```text
Application Action
       │
       ▼
     Event
       │
       ├── Listener
       ├── Listener
       └── Listener
```

This allows functionality such as notifications, auditing, integrations, and background processing to be attached without modifying the original application logic.

---

## Broadcasting and Realtime Communication

The runtime provides abstractions for broadcasting application events and data to users or groups.

For example:

```python
Broadcast.everyone(...)
```

or:

```python
Broadcast.user(user, ...)
```

This infrastructure can be used by applications that need realtime updates through WebSockets or other supported transports.

---

## Async Support

The runtime provides common abstractions for asynchronous application functionality.

This allows modules to use async operations where appropriate while keeping common infrastructure in one place.

---

## Files

`djangospice-framework` provides common abstractions for file-related functionality, allowing applications to work with files without repeatedly implementing storage and file-handling patterns.

---

## Imports and Exports

Reusable import/export infrastructure allows applications to implement data exchange consistently.

Typical use cases include:

* CSV imports
* Spreadsheet imports
* Data exports
* Bulk operations
* Integration pipelines

---

# Application Modules

`djangospice-framework` is **not intended to be a standalone business application**.

Instead, it provides the runtime used by applications and modules.

For example:

```text
djangospice-framework
    │
    ├── billing
    ├── notification
    ├── workflow
    ├── documents
    ├── helpdesk
    ├── CRM
    ├── workforce
```

Each application can depend on the common runtime while retaining responsibility for its own domain.

This keeps domain logic out of the framework.

---

# Example

A module can build its domain logic on top of `djangospice-framework`:

```python
from djangospice_framework.db.models import BaseModel


class Invoice(BaseModel):
    number = models.CharField(max_length=50, unique=True)
    amount = models.DecimalField(
        max_digits=12,
        decimal_places=2,
    )
```

The module can then use other `djangospice-framework` infrastructure for events, notifications, UI, HTTP responses, tables, files, and other common functionality.

The result is a module that contains primarily **business/domain logic**, rather than infrastructure boilerplate.

---

# License

This package is licensed under the **MIT License**.

See [LICENSE](LICENSE) for the full license text.
