Metadata-Version: 2.5
Name: entirius-django-atlas
Version: 2.1.0
Summary: External product data engine for Entirius: procurement, price monitoring and enrichment sources in one pipeline
Project-URL: Homepage, https://docs.entirius.com/
Project-URL: Documentation, https://github.com/entirius/entirius-django-atlas/tree/develop/docs
Project-URL: Repository, https://github.com/entirius/entirius-django-atlas
Project-URL: Changelog, https://github.com/entirius/entirius-django-atlas/blob/develop/CHANGELOG.md
Project-URL: Issues, https://github.com/entirius/entirius-django-atlas/issues
Author: Entirius
Maintainer-email: Piotr Brzozowski <piotrb@entirius.com>, Paweł Kiełt <cptshooter12@gmail.com>, Mateusz Baran <mateuszbaranpv@gmail.com>, Michał Kloczkowski <michal@kloczkowski.pl>
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: django,ecommerce,entirius,price-monitoring,procurement,product-data
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 :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Requires-Dist: celery>=5.3
Requires-Dist: django>=5.0
Requires-Dist: djangorestframework-simplejwt>=5.3
Requires-Dist: djangorestframework>=3.14
Requires-Dist: drf-spectacular>=0.27
Requires-Dist: entirius-django-pim>=3.0.0
Requires-Dist: entirius-django-regional>=2.0.1
Requires-Dist: entirius-django-utils>=2.0.0
Requires-Dist: lxml>=5.0
Requires-Dist: pydantic>=2.0
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: lookup
Requires-Dist: entirius-django-lookup>=0.1.0; (python_version >= '3.12') and extra == 'lookup'
Provides-Extra: qms
Requires-Dist: entirius-django-qms>=4.0.0; extra == 'qms'
Provides-Extra: test
Requires-Dist: dj-database-url; extra == 'test'
Requires-Dist: factory-boy; extra == 'test'
Requires-Dist: psycopg[binary]; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-django; extra == 'test'
Description-Content-Type: text/markdown

# entirius-django-atlas

A Django module that brings external product data into Entirius, the open-source modular ecommerce platform.
One pipeline serves three kinds of sources: `procurement` (suppliers whose products are pushed to the catalog),
`monitoring` (competitor prices) and `enrichment` (extra product data). Only procurement sources write to the
catalog; the other two are read-only observers.

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

## What it does

- Keeps a registry of sources, their feeds and credentials, with XML feed and scraper connectors.
- Imports source products on a cron schedule and maps attributes and categories through mapping profiles.
- Runs a review and approval workflow, then pushes approved procurement products to the catalog once and
  refreshes cost, quantity and physical attributes on later imports.
- Matches source products to existing catalog products by EAN and selects a primary source per product.
- Records every observation in an append-only log and every field change in an audit log.
- Exposes an admin API (JWT, Pydantic schemas, OpenAPI) for the CMS.

## Installation

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

Optional extras: `entirius-django-atlas[qms]` (stock writes to the warehouse module),
`entirius-django-atlas[lookup]` (registers atlas as a provider of the product lookup module; Python 3.12 or newer).

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

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

Optional settings (`ATLAS_*`: image download, body-size caps, the private-host guard, scraper callback signing)
are defined with their defaults in
https://github.com/entirius/entirius-django-atlas/blob/develop/src/django_atlas/settings.py

## Quick start

```python
from django_atlas.services.observation_service import get_observations

# newest observation per source for one SKU
prices = get_observations("SKU-1", "monitoring", latest_per_source=True)
```

The admin API is mounted under `api/atlas/v2/admin/`.

## Requirements

- Python 3.11 or newer, Django 5.0 or newer.
- PostgreSQL (the observation queries use `DISTINCT ON`).
- A Celery worker consuming the `atlas_default`, `atlas_images` and `atlas_results` queues.
- Entirius packages pulled in: `entirius-django-utils`, `entirius-django-regional`, `entirius-django-pim`.

## Documentation

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

## Part of Entirius

This module runs inside the Entirius backend service (Volkanos) and feeds the product catalog and the pricing engine.

- 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-pricefighter,
  https://github.com/entirius/entirius-django-lookup

## Development

```shell
make install     # sync dependencies (uv, incl. extras)
make check       # lint + format check (ruff)
make test        # test suite (pytest + pytest-django, needs PostgreSQL via DATABASE_URL)
```

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

## License

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