urban-json-xml 0.1.0__py3-none-any.whl

urban_json_xml/__init__.py

@@ -0,0 +1,116 @@
+"""Plugin jslt : lecture de fichiers XML (``loadxml``).
+
+Le moteur .NET n'expose pas de fonction de template ``loadxml`` mais convertit
+XML ↔ JSON via le ``XmlNodeConverter`` (conventions Newtonsoft). Ce plugin porte
+ces **mêmes conventions** sous forme d'une fonction ``loadxml`` :
+
+* un élément devient un objet ;
+* un attribut devient une propriété préfixée par ``@`` ;
+* le texte d'un élément (s'il a aussi des attributs/enfants) va dans ``#text`` ;
+  un élément qui n'a que du texte prend directement cette valeur (chaîne) ;
+* des éléments frères de même nom deviennent un tableau ;
+* l'élément racine est enveloppé : ``<root>…</root>`` → ``{"root": {…}}``.
+
+Les valeurs restent des **chaînes** (comme Newtonsoft : pas de coercition de type).
+
+Sécurité : le XML est analysé avec ``defusedxml`` (entités externes et expansion
+d'entités désactivées — protection XXE / « billion laughs »).
+
+Découvert automatiquement par ``jslt`` via l'entry point ``urban_json.functions``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from defusedxml.ElementTree import parse as _parse
+
+__version__ = "0.1.0"
+
+__all__ = ["execute_loadxml", "register"]
+
+# Clés spéciales, fidèles au XmlNodeConverter (.NET/Newtonsoft).
+_TEXT_KEY = "#text"
+_ATTR_PREFIX = "@"
+
+
+def _local_name(tag: str, strip_namespaces: bool) -> str:
+    """Nom local d'une balise/attribut ``{uri}local`` -> ``local`` (si demandé)."""
+    if strip_namespaces and tag.startswith("{"):
+        return tag.rsplit("}", 1)[-1]
+    return tag
+
+
+def _element_to_obj(
+    element: Any, attribute_prefix: str, text_key: str, strip_namespaces: bool
+) -> Any:
+    """Convertit un élément ElementTree en structure JSON (conventions Newtonsoft)."""
+    children = list(element)
+    attributes = element.attrib
+    text = (element.text or "").strip()
+
+    # Feuille sans attribut ni enfant : la valeur texte directe (ou None si vide).
+    if not children and not attributes:
+        return text if text else None
+
+    obj: dict[str, Any] = {}
+
+    for name, value in attributes.items():
+        obj[attribute_prefix + _local_name(name, strip_namespaces)] = value
+
+    # Regroupe les enfants par nom : les frères homonymes forment un tableau.
+    groups: dict[str, list[Any]] = {}
+    order: list[str] = []
+    for child in children:
+        key = _local_name(child.tag, strip_namespaces)
+        if key not in groups:
+            groups[key] = []
+            order.append(key)
+        groups[key].append(_element_to_obj(child, attribute_prefix, text_key, strip_namespaces))
+    for key in order:
+        values = groups[key]
+        obj[key] = values[0] if len(values) == 1 else values
+
+    if text:
+        obj[text_key] = text
+
+    return obj
+
+
+def execute_loadxml(
+    ctx: Any,
+    source_path: str | None = None,
+    attribute_prefix: str = _ATTR_PREFIX,
+    text_key: str = _TEXT_KEY,
+    strip_namespaces: bool = True,
+) -> dict:
+    """Lit un fichier XML et le convertit en JSON (conventions Newtonsoft).
+
+    Args:
+        source_path: chemin du fichier XML (absolu ou relatif au répertoire courant).
+        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``).
+
+    Returns:
+        Un objet ``{nom_racine: contenu}`` reflétant l'arbre XML.
+    """
+    if not source_path:
+        raise ValueError("loadxml: source_path est requis")
+
+    tree = _parse(source_path)
+    root = tree.getroot()
+    return {
+        _local_name(root.tag, strip_namespaces): _element_to_obj(
+            root, attribute_prefix, text_key, strip_namespaces
+        )
+    }
+
+
+def register(registry: Any) -> None:
+    """Enregistre les fonctions du plugin dans un registre jslt (entry point)."""
+    registry.register(
+        "loadxml",
+        execute_loadxml,
+        description="Lit un fichier XML et le convertit en JSON (conventions Newtonsoft).",
+    )

urban_json_xml-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: urban-json-xml
+Version: 0.1.0
+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
+
+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.

urban_json_xml-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+urban_json_xml/__init__.py,sha256=s6cT5WESvLJNiTLlDZ02yQ3VsXKi4hX2Dr1hmQKU56g,4043
+urban_json_xml/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+urban_json_xml-0.1.0.dist-info/licenses/LICENSE,sha256=LdXMQzg0w6hrGI_vhgHsmOLKcHTkyF5PyUXkP9fV7mA,1068
+urban_json_xml-0.1.0.dist-info/METADATA,sha256=0ANjqKNIfaYkpMK0M2vWti4StxRi3fpgD1jKWrpUy0k,3223
+urban_json_xml-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+urban_json_xml-0.1.0.dist-info/entry_points.txt,sha256=d3TJ5yC7q8cRB1Tze6PUL3BDVcRqdAvuPR5q37OnDXE,53
+urban_json_xml-0.1.0.dist-info/top_level.txt,sha256=tcM6fpfAE-AeUSuA8JgKu_AfR5q-jMt6wSGFi5zFe14,15
+urban_json_xml-0.1.0.dist-info/RECORD,,

urban_json_xml-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

urban_json_xml-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[urban_json.functions]
+xml = urban_json_xml:register

urban_json_xml-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 black beard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

urban_json_xml-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+urban_json_xml