Metadata-Version: 2.5
Name: entirius-django-utils
Version: 2.3.0
Summary: Shared Django utilities for Entirius modules: base models, DRF API helpers, admin tools, AI toolbox client
Project-URL: Homepage, https://docs.entirius.com/
Project-URL: Documentation, https://github.com/entirius/entirius-django-utils/tree/develop/docs
Project-URL: Repository, https://github.com/entirius/entirius-django-utils
Project-URL: Changelog, https://github.com/entirius/entirius-django-utils/blob/develop/CHANGELOG.md
Project-URL: Issues, https://github.com/entirius/entirius-django-utils/issues
Author: Entirius
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: admin,django,drf,ecommerce,entirius,utilities
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: celery-once>=3.0
Requires-Dist: django-filter>=23.5
Requires-Dist: django>=4.2
Requires-Dist: djangorestframework>=3.14
Requires-Dist: entirius-django-regional>=2.0.0
Requires-Dist: entirius-py-idx-normalizator>=2.0.0
Requires-Dist: entirius-py-process-logger>=2.0.0
Requires-Dist: httpx>=0.27
Requires-Dist: marshmallow>=3.19
Requires-Dist: pydantic>=2.0
Requires-Dist: python-slugify>=8.0
Requires-Dist: webargs>=8.3
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-django; extra == 'test'
Requires-Dist: respx>=0.21; extra == 'test'
Provides-Extra: unfold
Requires-Dist: django-unfold; extra == 'unfold'
Description-Content-Type: text/markdown

# entirius-django-utils

Shared Django building blocks for the modules of Entirius, the open-source modular ecommerce platform.
Abstract base models, DRF API helpers, admin base classes, text tools and an AI toolbox client live here, so
every module builds on the same foundations.

[![PyPI](https://img.shields.io/pypi/v/entirius-django-utils.svg)](https://pypi.org/project/entirius-django-utils/)
[![Python](https://img.shields.io/pypi/pyversions/entirius-django-utils.svg)](https://pypi.org/project/entirius-django-utils/)
[![License: MPL-2.0](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](https://github.com/entirius/entirius-django-utils/blob/develop/LICENSE)

## What it does

- Abstract base models and manager helpers shared by every Entirius module.
- DRF helpers: request parsing, filtering, pagination and the structured v2 error handling.
- Admin base classes, text, slug and translation helpers.
- A base for worker management commands with locking.
- A typed client for the AI toolbox (completions, model catalogue, error mapping to DRF responses).

## Installation

```shell
uv add entirius-django-utils
pip install entirius-django-utils
```

Optional extra: `entirius-django-utils[unfold]` (django-unfold admin theme).

```python
INSTALLED_APPS = [
    ...
    "django_regional",
    "django_utils",
]
```

The toolbox client needs `AI_TOOLBOX_BASE_URL`, `AI_TOOLBOX_API_KEY` and `AI_TOOLBOX_CHANNEL`; the settings
reference is https://github.com/entirius/entirius-django-utils/blob/develop/docs/toolbox-client.md.

## Quick start

```python
from django_utils.toolbox import CompletionRequest, Message, ToolboxClient

# settings: AI_TOOLBOX_BASE_URL = "https://toolbox.example.com"
with ToolboxClient() as client:
    response = client.complete(
        CompletionRequest(
            model="fake-chat",
            messages=[Message(role="user", content="Say hi as JSON")],
            json_schema={"type": "object"},
        )
    )
```

## Requirements

- Python 3.11 or newer, Django 4.2 or newer.
- Entirius packages pulled in: `entirius-django-regional`, `entirius-py-idx-normalizator`,
  `entirius-py-process-logger`.

## Documentation

- Module docs: https://github.com/entirius/entirius-django-utils/tree/develop/docs
- Entirius documentation: https://docs.entirius.com/
- Changelog: https://github.com/entirius/entirius-django-utils/blob/develop/CHANGELOG.md

## Part of Entirius

Every module of the Entirius backend service (Volkanos) depends on this package.

- Backend service: https://github.com/entirius/entirius-service-volkanos
- Docker harness: https://github.com/entirius/entirius-zeno
- Sibling modules: https://github.com/entirius/entirius-django-regional, https://github.com/entirius/entirius-django-utils-translator

## Development

```shell
make install     # sync dependencies (uv)
make check       # lint + format check (ruff)
make test        # test suite (pytest + pytest-django)
```

Development and agent instructions: https://github.com/entirius/entirius-django-utils/blob/develop/AGENTS.md

## License

Mozilla Public License 2.0 (MPL-2.0) — see https://github.com/entirius/entirius-django-utils/blob/develop/LICENSE.
