XML et XSD

Écriture

Écriture de messages HPRIM XML.

Entrée : un dictionnaire imbriqué au format xmltodict, c'est-à-dire le même format que celui que produit la lecture (read_hprimxml) :

• les attributs et les éléments enfants sont des clés du même dictionnaire (préfixe @ accepté mais facultatif) : c'est le XSD qui tranche ;
• un élément répété est une liste ;
• un élément à contenu simple portant des attributs utilise la clé #text.

L'ordre des clés n'a pas d'importance : les enfants sont émis dans l'ordre du XSD.

HprimWriteError

Bases: ValueError

to_xml

to_xml(
    tree: dict,
    *,
    version: str | None = None,
    xmlns: str | None = HPRIM_NS,
    encoding: str = "UTF-8",
    pretty: bool = True,
    drop_empty: bool = True,
    strict: bool = True,
    validate_xsd: str | bool = False,
) -> bytes

Sérialise un message HPRIM XML à partir d'un dictionnaire.

Les enfants sont émis dans l'ordre du XSD, quel que soit l'ordre des clés ; le XSD décide aussi si une clé est un attribut ou un élément.

Parameters:

Name	Type	Description	Default
tree	dict	dictionnaire {racine: {...}} au format xmltodict.	required
version	str | None	version du schéma (voir to_element).	None
xmlns	str | None	HPRIM_NS (défaut) ; None : aucune déclaration ; "" : écrit xmlns="" littéralement sur la racine.	HPRIM_NS
encoding	str	encodage du fichier (UTF-8 par défaut).	'UTF-8'
pretty	bool	indentation (deux espaces, mise en forme de libxml2).	True
drop_empty	bool	voir to_element.	True
strict	bool	voir to_element.	True
validate_xsd	str | bool	False, "warn" ou "error" (True équivaut à "error").	False

Returns:

Type	Description
bytes	Le contenu XML, déclaration comprise.

Raises:

Type	Description
HprimWriteError	structure incompatible ou, avec validate_xsd="error", message non conforme au XSD.

write_xml

write_xml(
    tree: dict, path: str | Path, **kwargs: Any
) -> Path

Écrit un message HPRIM XML dans un fichier.

Parameters:

Name	Type	Description	Default
tree	dict	dictionnaire {racine: {...}}.	required
path	str | Path	fichier de sortie.	required
**kwargs	Any	options de to_xml.	{}

Returns:

Type	Description
Path	Le chemin écrit.

to_element

to_element(
    tree: dict,
    *,
    version: str | None = None,
    xmlns: str | None = HPRIM_NS,
    drop_empty: bool = True,
    strict: bool = True,
) -> ET._Element

Construit l'élément racine lxml à partir d'un dictionnaire {racine: {...}}.

Parameters:

Name	Type	Description	Default
tree	dict	dictionnaire au format xmltodict (celui de parse_xml).	required
version	str | None	version du schéma. Par défaut l'attribut version du message, sinon 2.4. Si renseignée, elle remplace aussi l'attribut.	None
xmlns	str | None	namespace à déclarer ; None ou "" : pas de namespace.	HPRIM_NS
drop_empty	bool	supprime les éléments et attributs vides (None, "", NaN), sauf les éléments complexes obligatoires du XSD.	True
strict	bool	lève une erreur si une clé ne correspond à rien dans le XSD (sinon simple avertissement).	True

Returns:

Type	Description
_Element	L'élément racine lxml.

Raises:

Type	Description
HprimWriteError	structure incompatible avec le XSD.

Lecture

Lecture XML -> dictionnaire (format accepté par to_xml), guidée par le XSD.

Par rapport à xmltodict : - un élément répétable selon le XSD est toujours une liste (même avec 1 seul élément) ; - les valeurs sont typées d'après le XSD : date, datetime, time, int (le reste en str ; les attributs restent en str) ; - le namespace, quel qu'il soit (ou son absence), est ignoré.

parse_xml

parse_xml(
    source: str | Path | bytes,
    *,
    version: str | None = None,
    typed: bool = True,
) -> dict

Lit un message HPRIM XML en dictionnaire {racine: {...}}.

Lecture guidée par le XSD : les éléments répétables sont toujours des listes et les valeurs sont typées (date, datetime, time, int ; le reste et les attributs en texte). Le namespace est ignoré. Le résultat est accepté tel quel par to_xml.

Parameters:

Name	Type	Description	Default
source	str | Path | bytes	chemin de fichier ou contenu (bytes).	required
version	str | None	schéma à utiliser ; par défaut l'attribut version du message.	None
typed	bool	False pour garder toutes les valeurs en texte.	True

Returns:

Type	Description
dict	Le message sous forme de dictionnaire.

Validation et schémas

Introspection et validation des schémas HPRIM XML vendorisés.

L'écriture s'appuie sur le XSD pour deux choses que le tabulaire ne porte pas : - l'ordre des éléments enfants (xsd:sequence) ; - la distinction attribut / élément pour une même clé de dictionnaire.

HPRIM_NS module-attribute

HPRIM_NS = 'http://www.hprim.org/hprimXML'

validate

validate(
    xml: bytes | _Element | _ElementTree,
    version: str | None = None,
) -> list[str]

Valide un message contre le XSD de sa version.

La variante de schéma (avec ou sans namespace) est choisie d'après le XML lui-même.

Parameters:

Name	Type	Description	Default
xml	bytes | _Element | _ElementTree	contenu (bytes), élément ou arbre lxml.	required
version	str | None	version du schéma ; par défaut l'attribut version du message.	None

Returns:

Type	Description
list[str]	La liste des erreurs, vide si le message est conforme.

available_versions

available_versions() -> list[str]