Metadata-Version: 2.5
Name: entirius-django-regional
Version: 2.1.0
Summary: Regional reference data for Entirius: Country, Currency and Language models with a read-only admin API
Project-URL: Homepage, https://docs.entirius.com/
Project-URL: Documentation, https://github.com/entirius/entirius-django-regional/tree/develop/docs
Project-URL: Repository, https://github.com/entirius/entirius-django-regional
Project-URL: Changelog, https://github.com/entirius/entirius-django-regional/blob/develop/CHANGELOG.md
Project-URL: Issues, https://github.com/entirius/entirius-django-regional/issues
Author: Entirius
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: countries,currencies,django,ecommerce,entirius,languages
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 :: Localization
Requires-Python: >=3.11
Requires-Dist: django>=4.2
Requires-Dist: djangorestframework-simplejwt>=5.3
Requires-Dist: djangorestframework>=3.14
Requires-Dist: drf-spectacular>=0.27
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
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'
Description-Content-Type: text/markdown

# entirius-django-regional

A Django module with regional reference data for Entirius, the open-source modular ecommerce platform: countries, currencies and languages.
Other modules point their foreign keys at these tables; the data ships as a fixture and a read-only admin API lists it.

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

## What it does

- Provides the `Country`, `Currency` and `Language` models keyed by ISO codes.
- Seeds countries with dialling prefixes, currency symbols and default currencies in its migration.
- Ships the `regional-defaults` fixture as the place where reference data is changed.
- Keeps country rows read-only: `Country.save()` raises, changes go through the fixture and migrations.
- Lists languages, currencies and countries over a read-only admin API under `/api/regional/v2/admin/`.

## Installation

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

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

# urls.py
urlpatterns = [
    path("", include("django_regional.urls")),
]
```

```shell
python manage.py migrate
python manage.py loaddata regional-defaults   # optional: the defaults fixture
```

The module has no settings of its own.

## Quick start

```python
from django_regional.models import Country, Currency, Language

country = Country.getFromIso2("PL")       # country codes are stored upper-case
language = Language.getFromIso2("pl")     # language codes are stored lower-case
currency = Currency.getFromiso3("PLN")
```

## Requirements

- Python 3.11 or newer, Django 4.2 or newer.
- Django REST Framework, `djangorestframework-simplejwt`, `pydantic`, `drf-spectacular`, `pyyaml`.
- No other Entirius packages.

## Documentation

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

## Part of Entirius

This module runs inside the Entirius backend service (Volkanos) as the shared source of countries, currencies and languages.

- 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-pim, https://github.com/entirius/entirius-django-email, https://github.com/entirius/entirius-django-accounts

## Development

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

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

## License

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