Onixlib

Bibliothèque Python souveraine pour lire, parser et produire des fichiers ONIX

onixlib est une bibliothèque Python souveraine pour lire, parser et produire des fichiers ONIX — le standard d'échange de métadonnées du monde du livre.

Elle fournit des façades ergonomiques sur les structures ONIX 3.0, un parser streaming adapté aux grands fichiers de distribution, et un système de registre de versions extensible.

Sommaire

• Onixlib
  • Sommaire
  • Installation
  • Démarrage rapide
    • Lire un fichier ONIX (streaming)
    • Lire un fichier ONIX (chargement complet)
    • Construire et sérialiser une notice ONIX
  • Référence des façades
    • parse(source, version=None) — générateur
    • Product
    • Notice
    • Header
    • DescriptiveDetail
    • CollateralDetail
    • PublishingDetail
    • ProductSupply / SupplyDetail / Price
    • Contributor
  • Gestion des versions ONIX
  • Ajouter une nouvelle version ONIX
    • 1 — Déclarer la source XSD
    • 2 — Générer les classes Python
    • 3 — Enregistrer la nouvelle version
    • 4 — Utiliser la nouvelle version
  • Développement
    • Pré-requis
    • Cibles Makefile

Installation

pip install onixlib

Prérequis : Python ≥ 3.11.

Démarrage rapide

Lire un fichier ONIX (streaming)

parse() est un générateur qui désérialise chaque <Product> indépendamment, sans jamais charger l'ensemble du fichier en mémoire — recommandé pour les flux de distribution volumineux.

from onixlib import parse

for product in parse("notice.xml"):
    print(product.isbn, product.title)

    # Contributeurs
    if product.author:
        print("Auteur :", product.author.full_name)
    for c in product.contributors:
        print(f"  {c.role.value} — {c.full_name}")

    # Description et couverture
    if product.collateral:
        print("Description :", product.collateral.description)
        print("Couverture   :", product.collateral.cover_url)

    # Date de publication et éditeur
    if product.publishing:
        print("Date  :", product.publishing.publication_date)
        print("Marque:", product.publishing.imprint_name)

    # Prix
    for ps in product.product_supply:
        for price in ps.prices:
            print(f"  {price.amount} {price.currency} (type {price.price_type})")

La version ONIX est auto-détectée à partir de l'attribut release de la racine XML. Pour forcer une version :

for product in parse("notice.xml", version="3.0"):
    ...

Lire un fichier ONIX (chargement complet)

from onixlib import Notice

notice = Notice.parse_full("notice.xml")

print(notice.header.sender_name)
print(notice.header.sent_datetime)

for product in notice.products:
    print(product.isbn, product.title)

Construire et sérialiser une notice ONIX

from onixlib import Notice, Product, ContributorRole

# Produit
product = Product.new(isbn="9782070360024", title="Du côté de chez Swann")

author = product.add_contributor(role=ContributorRole.A01)
author.first_name = "Marcel"
author.last_name  = "PROUST"

# Notice complète
notice = Notice.new(sender_name="MON_EDITEUR", sent_datetime="20260428T000000Z")
notice.add_product(product)

xml = notice.to_xml()
print(xml)

Référence des façades

Toutes les classes suivantes s'importent directement depuis onixlib :

from onixlib import (
    parse, Notice, Product,
    Header, DescriptiveDetail, CollateralDetail,
    PublishingDetail, ProductSupply, SupplyDetail, Price,
    RelatedMaterial, RelatedProduct, RelatedWork,
    Contributor, ContributorRole,
)

parse(source, version=None) — générateur

Retourne un générateur de Product.

Product

Façade centrale sur un bloc <Product> ONIX.

Notice

Façade sur la notice ONIX complète (<ONIXMessage>).

Header

DescriptiveDetail

CollateralDetail

PublishingDetail

ProductSupply / SupplyDetail / Price

for ps in product.product_supply:
    for sd in ps.supply_details:
        print(sd.supplier_name, sd.availability)
        for price in sd.prices:
            print(price.amount, price.currency, price.price_type)

Contributor

ContributorRole est l'enum List17 ONIX : ContributorRole.A01, ContributorRole.B06, etc.

Gestion des versions ONIX

onixlib intègre un registre de versions extensible. La version 3.0 est enregistrée par défaut.

from onixlib import available_releases

print(available_releases())  # ['3.0']

Le parser auto-détecte la version depuis l'attribut release de la racine XML.

Ajouter une nouvelle version ONIX

Lorsque EDItEUR publie une nouvelle version des XSD (ex. ONIX 3.1), voici le processus complet pour l'intégrer.

1 — Déclarer la source XSD

Dans xsd_sources.toml, ajouter une entrée :

[versions."3.1"]
source      = "https://www.editeur.org/files/ONIX%203/ONIX_3-1_reference_XSD.zip"
description = "ONIX 3.1 — prochaine version de référence (EDItEUR)"

2 — Générer les classes Python

make generate VERSION=3.1
# ou, pour forcer le re-téléchargement des XSD :
make generate-force VERSION=3.1

Cela produit src/onixlib/models/generated/v3_1.py via xsdata.

3 — Enregistrer la nouvelle version

Dans src/onixlib/models/versions.py, ajouter en bas du fichier :

from .generated import v3_1 as _v3_1

register(VersionInfo(
    release="3.1",
    namespace="http://www.editeur.org/onix/3.1/reference",
    module=_v3_1,
    message_class=_v3_1.Onixmessage,
    product_class=_v3_1.Product,
))

4 — Utiliser la nouvelle version

# Auto-détection depuis release="3.1" dans le XML
for product in parse("notice_3_1.xml"):
    ...

# Ou explicitement :
notice = Notice.parse_full("notice_3_1.xml", version="3.1")

Les versions antérieures ("3.0") restent disponibles sans modification.

Développement

Pré-requis

python -m venv venv
source venv/bin/activate
make install-dev

Cibles Makefile

Rémi Verschuur · Audit IO · 2026