Metadata-Version: 2.4
Name: urban-json-xml
Version: 0.1.1
Summary: Plugin urban-json : lecture de fichiers XML (fonction de template loadxml).
Author-email: Gael Beard <gaelgael5@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/gaelgael5/Jslt
Project-URL: Repository, https://github.com/gaelgael5/Jslt
Keywords: json,transform,template,jslt,xml,plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: urban-json
Requires-Dist: defusedxml>=0.7
Dynamic: license-file

# urban-json-xml

*Français · [English](https://github.com/gaelgael5/Jslt/blob/main/packages/urban-json-xml/README.en.md)*

Plugin [urban-json](https://github.com/gaelgael5/Jslt) : lecture de fichiers **XML**
dans les templates, via la fonction `loadxml`. Suit les conventions XML↔JSON du
`XmlNodeConverter` (.NET/Newtonsoft).

## Installation

```bash
pip install urban-json-xml      # tire urban-json et defusedxml en dépendances
```

`urban-json` découvre le plugin automatiquement via les entry points (`urban_json.functions`) :
`loadxml` devient utilisable dans les templates.

## Utilisation

```python
from urban_json import JsltTemplate

# catalog.xml :
#   <catalog>
#     <book id="1"><title>A</title></book>
#     <book id="2"><title>B</title></book>
#   </catalog>
tpl = JsltTemplate.parse('[ { "$source": select(loadxml("catalog.xml"), $.catalog.book), "t": $.title } ]')
tpl.transform({})
# -> [{'t': 'A'}, {'t': 'B'}]
```

`loadxml` renvoie un objet ; on navigue dedans avec `select`/`selectmany` (fonctions
du cœur) avant d'alimenter une boucle `$source`, un filtre `?(...)`, etc.

## Conventions de conversion (Newtonsoft)

| XML | JSON |
|---|---|
| `<a>v</a>` | `{"a": "v"}` |
| `<a x="1">v</a>` | `{"a": {"@x": "1", "#text": "v"}}` |
| `<a/>` | `{"a": null}` |
| `<a><b>1</b><b>2</b></a>` | `{"a": {"b": ["1", "2"]}}` (frères homonymes → tableau) |

- Attributs → propriétés préfixées par `@`.
- Texte d'un élément mixte → clé `#text`.
- Les valeurs restent des **chaînes** (comme Newtonsoft, pas de coercition).

## Signature

```
loadxml(source_path, attribute_prefix="@", text_key="#text", strip_namespaces=true)
```

| Paramètre | Rôle |
|---|---|
| `source_path` | chemin du fichier XML |
| `attribute_prefix` | préfixe des propriétés issues d'attributs (défaut `@`) |
| `text_key` | clé portant le texte d'un élément mixte (défaut `#text`) |
| `strip_namespaces` | réduit `{uri}local` au nom local (défaut `true`) |

## Sécurité

Le XML est analysé avec [`defusedxml`](https://pypi.org/project/defusedxml/) :
entités externes et expansion d'entités désactivées (protection XXE /
« billion laughs »).

## Licence

Apache-2.0.
