Metadata-Version: 2.4
Name: ads-facturx
Version: 0.6.17
Summary: Génération, validation et assemblage de factures électroniques Factur-X / EN 16931 en Python.
License-Expression: MIT
Author: antoineducoulombier
Author-email: antoine.ducoulombier@alchimiedatasolutions.com
Requires-Python: >=3.10,<4
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: factur-x (>=3.15,<4.0)
Requires-Dist: pydantic (>=2.12.5,<3.0.0)
Requires-Dist: reportlab (>=4.4.9,<5.0.0)
Requires-Dist: saxonche (>=12.9.0,<13.0.0)
Description-Content-Type: text/markdown

<h1 align="center">eFacturePy — <code>ads-facturx</code></h1>

<p align="center">
  <em>Génération, validation et assemblage de factures électroniques <b>Factur-X / EN 16931</b> en Python.</em>
</p>

<p align="center">
  <img alt="Python" src="https://img.shields.io/badge/python-%E2%89%A53.12-blue">
  <img alt="Version" src="https://img.shields.io/badge/ads--facturx-0.6.16-success">
  <img alt="Build" src="https://img.shields.io/badge/build-poetry-60A5FA">
  <img alt="Status" src="https://img.shields.io/badge/status-active-brightgreen">
</p>

---

## 🧭 Sommaire

- [À propos](#-à-propos)
- [Fonctionnalités](#-fonctionnalités)
- [Architecture du dépôt](#-architecture-du-dépôt)
- [Installation](#-installation)
- [Démarrage rapide](#-démarrage-rapide)
- [API publique](#-api-publique)
- [Modèle de données](#-modèle-de-données)
- [Documentation détaillée](#-documentation-détaillée)
- [Validation EN 16931](#-validation-en-16931)
- [Dépendances](#-dépendances)
- [Auteur](#-auteur)

---

## 📖 À propos

**eFacturePy** est le dépôt de travail du package Python **[`ads-facturx`](./ads_facturx)**, un outil qui permet de :

- produire un **XML Cross Industry Invoice** conforme au profil `urn:cen.eu:en16931:2017` ;
- générer le **PDF/A-3** associé à l’aide de [ReportLab](https://www.reportlab.com/) ;
- **embarquer** ce XML dans le PDF pour obtenir une **Factur-X** valide (via [`factur-x`](https://pypi.org/project/factur-x/)) ;
- **valider** la facture via XSD (EN16931) et **Schematron** (moteur [SaxonC-HE](https://pypi.org/project/saxonche/)).

---

## ✨ Fonctionnalités

- ✅ Génération d’un XML Factur-X / EN 16931 à partir d’un `dict` métier
- ✅ Génération d’un PDF de facture (template par défaut + logo personnalisable)
- ✅ Fusion PDF + XML → fichier Factur-X conforme
- ✅ Validation **XSD** (profil `en16931`)
- ✅ Validation **Schematron** via XSLT précompilé (SaxonC)
- ✅ Modèles **Pydantic v2** pour typer et valider les données métier

---

## 🏗️ Architecture du dépôt

```text
eFacturePy/
├─ ads_facturx/              # Package distribué sur PyPI
│  ├─ Builders/              # Génération XML + PDF + Factur-X
│  ├─ Validators/            # XSD + Schematron (XSLT EN16931-CII)
│  ├─ models/                # Schémas Pydantic (DevisData, Invoice, …)
│  ├─ Samples/               # Jeu de données et XML de référence
│  └─ tests/                 # Tests unitaires pytest
├─ eFacturePy/               # Sorties d’exemple (PDF/XML générés)
├─ archive/                  # Ressources brutes : XSD, XSL, Schematron, Saxon
├─ dist/                     # Wheels et sdist historiques                   
├─ pyproject.toml            # Configuration Poetry
└─ poetry.lock
```

---

## 📦 Installation

Depuis PyPI :

```bash
pip install ads-facturx
```

> **Prérequis :** Python **≥ 3.12**. SaxonC-HE est installé automatiquement via la dépendance `saxonche`.

---

## 🚀 Démarrage rapide

Pipeline complet : validation → XML → contrôles XSD/Schematron → PDF → Factur-X.

```python
from ads_facturx import (
    DevisData,
    export_xml, write_xml_from_string,
    xml_check_xsd, xml_check_schematron,
    export_pdf, generate_facturx,
)

# 1. Données métier (dict) → modèle validé
data = {...}                                      # voir docs/pdf/examples/sample_data.py
validated = DevisData.model_validate(data)

DESTINATION = "eFacturePy"
invoice_name = validated.invoice.name

# 2. XML EN 16931
xml_string = export_xml(validated)
xml_path   = write_xml_from_string(
    xml_string=xml_string,
    destination_folder=DESTINATION,
    file_name=invoice_name,
)

# 3. Validation XSD + Schematron
xml_check_xsd(xml_string)
report = xml_check_schematron(xml_path=xml_path)
print(report)

# 4. PDF (template par défaut)
export_pdf(
    title=invoice_name,
    output_path=f"{DESTINATION}/{invoice_name}.pdf",
    data=validated,
)

# 5. PDF + XML → Factur-X
generate_facturx(
    file_name=f"{invoice_name}.pdf",
    destination_folder=DESTINATION,
    xml=xml_string,
)
```

> Un jeu de données complet, validable tel quel par `DevisData`, est fourni
> dans [`docs/pdf/examples/sample_data.py`](./docs/pdf/examples/sample_data.py).

---

## 🔌 API publique

Exposée via `from ads_facturx import ...` (cf. [`ads_facturx/__init__.py`](./ads_facturx/__init__.py)).

**Pipeline principal**

| Symbole                   | Rôle                                                                 |
|---------------------------|----------------------------------------------------------------------|
| `DevisData`               | Modèle Pydantic v2 d'entrée (validation EN 16931).                   |
| `export_xml(validated)`   | Construit la chaîne XML CII profil `en16931`.                        |
| `write_xml_from_string`   | Sérialise l'XML sur disque (`destination_folder`, `file_name`).      |
| `xml_check_xsd`           | Valide l'XML avec le XSD `facturx` / niveau `en16931`.               |
| `xml_check_schematron`    | Applique les règles Schematron EN16931-CII via SaxonC.               |
| `export_pdf`              | Génère le PDF de facture (ReportLab — template par défaut ou custom). |
| `generate_facturx`        | Embarque le XML dans le PDF pour produire la Factur-X finale.        |

**Briques pour personnaliser le PDF** (détails dans la [doc PDF](./docs/pdf/README.md))

`Template` · `ParagraphComponent` · `SpacerComponent` · `PageBreakComponent` ·
`BoxComponent` · `TableComponent` · `KeepInFrameComponent` · `DiyComponent` ·
`Header` · `Footer` · `TextElement` · `CenteredText` · `ImageElement` ·
`HorizontalLine` · `Theme` · `TableStyles` · `FontName` ·
`TableConfig` · `TableColumn` · `TableBox` · `ParagraphConfig` ·
`KeepInFrameConfig` · `FormatText` · `FormatDate` · `ExtraRow` ·
`ExtraRowCell` · `DocConfig` · `mm` · `A4` · `colors`.

---

## 🧾 Modèle de données

Schémas **Pydantic v2** dans [`ads_facturx/models`](./ads_facturx/models) :
`DevisData` (racine), `Partner`, `Address`, `Invoice`, `InvoiceLine`,
`InvoiceSummary`, `Footer`, plus les énumérations normatives
(`CountryCode`, `CurrencyCode`, `UnitCode`, `VatCategory`).

`DevisData.model_validate(data)` applique les contraintes EN 16931 critiques
(formats de dates `YYYYMMDD`, codes pays/devise/unité, type TVA, …).

Détail des champs et exemple JSON complet :
[`docs/pdf/03-input-data.md`](./docs/pdf/03-input-data.md).

---

## 📚 Documentation détaillée

La génération PDF dispose de sa propre documentation, en 12 sections
progressives :

➡ **[`docs/pdf/README.md`](./docs/pdf/README.md)** — table des matières.

Au menu : quickstart, mental model, schéma `DevisData`, construction de
templates, catalogue de composants, personnalisation (style / config),
header & footer, composants DIY, défauts fournis, cookbook, erreurs
courantes, référence API.

Tous les exemples sont **exécutables** :

```bash
python docs/pdf/examples/run_examples.py
# → PDFs écrits dans docs/pdf/examples/out/
```

---

## ✅ Validation EN 16931

- **XSD** : `xml_check_xsd` s’appuie sur `factur-x` (`flavor="facturx"`, `level="en16931"`).
- **Schematron** : `xml_check_schematron` exécute `Validators/xslt/EN16931-CII-validation.xslt` avec SaxonC et renvoie la liste des `failed-assert` (id, location, message).

---

## 📚 Dépendances

`factur-x`, `saxonche`, `pydantic`, `reportlab` (voir [`pyproject.toml`](./pyproject.toml) et [`poetry.lock`](./poetry.lock)).

## 👤 Auteur

**Antoine Ducoulombier** — [Alchimie Data Solutions](http://www.alchimiedatasolutions.com) · `antoine.ducoulombier@alchimiedatasolutions.com`

