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

urban_json_csv/__init__.py

@@ -0,0 +1,202 @@
+"""Plugin jslt : lecture de fichiers CSV (``loadcsv``, ``loadmcsv``).
+
+Port de ``Bb.CustomServices.ServiceCsv.ExecuteLoadCsvSource`` du .NET. Fournit la
+fonction de template ``loadcsv`` qui lit un fichier CSV et renvoie un tableau
+d'objets JSON (une entrée par ligne), et ``loadmcsv`` (CSV multi-enregistrements
+hiérarchique, port de ``ServicesMultiCsv`` — voir :mod:`urban_json_csv.mcsv`).
+
+Ce paquet est découvert automatiquement par ``jslt`` via le groupe d'entry points
+``urban_json.functions`` (il suffit de l'installer). Il peut aussi être enregistré
+explicitement : ``from urban_json_csv import register; register(mon_registre)``.
+
+Écarts volontaires vs .NET (documentés) :
+
+* La résolution de chemin du .NET (``ctx.Configuration.ResolveFile``) n'existe pas
+  dans le portage cœur : ``source_path`` est ouvert tel quel (absolu ou relatif au
+  répertoire courant). Le BOM éventuel est retiré (``utf-8-sig``).
+* Les types ``decimal``/``long`` du .NET deviennent ``float``/``int`` (types JSON
+  Python). La détection de type (bool / entier / décimal / chaîne) est fidèle.
+"""
+
+from __future__ import annotations
+
+import csv as _csv
+import unicodedata
+from typing import Any
+
+from .mcsv import execute_loadmcsv
+
+__version__ = "0.1.0"
+
+__all__ = ["execute_loadcsv", "execute_loadmcsv", "register"]
+
+
+def _sanitize_header(name: str) -> str:
+    """Assainit un nom de colonne (port de ``ServiceCsv.GetLabel``).
+
+    Même intention que le .NET (alphanumérique conservé, accents -> ASCII,
+    espaces/quotes -> ``_``, underscores multiples réduits), mais via la
+    normalisation Unicode (NFKD) plutôt qu'une table figée : tous les accents sont
+    traités uniformément (le .NET avait une table incomplète, p.ex. ``Â`` manquant).
+    """
+    decomposed = unicodedata.normalize("NFKD", name)
+    out: list[str] = []
+    for char in decomposed:
+        if unicodedata.combining(char):
+            continue  # supprime les diacritiques (accents)
+        if char.isascii() and char.isalnum():
+            out.append(char)
+        elif char in (" ", "'", '"'):
+            out.append("_")
+        # tout autre caractère est supprimé
+    label = "".join(out)
+    while "___" in label:
+        label = label.replace("___", "_")
+    return label.replace("__", "_")
+
+
+#: Sentinelle interne : la cellule doit être omise de l'objet résultat.
+_DROP = object()
+
+
+def _coerce(raw: Any, exclude_null_and_empty: bool) -> Any:
+    """Coerce une cellule CSV en valeur JSON (port de ``ServiceCsv.GetValue``).
+
+    Retourne la sentinelle :data:`_DROP` si la valeur doit être omise (null/vide
+    avec ``exclude_null_and_empty``).
+    """
+    if raw is None:
+        return _DROP if exclude_null_and_empty else None
+
+    text = raw.strip()
+    low = text.lower()
+
+    if low == "":
+        return _DROP if exclude_null_and_empty else ""
+
+    if low == "true":
+        return True
+    if low == "false":
+        return False
+
+    # Détection numérique : commence par '-' ou un chiffre (fidèle au .NET).
+    first = low[0]
+    if first == "-" or first.isdigit():
+        is_int = False
+        is_decimal = False
+        for index, char in enumerate(low):
+            if index == 0 and char == "-":
+                continue
+            if char.isdigit():
+                is_int = True
+            elif is_int and char == ".":
+                is_decimal = True
+            else:
+                break
+        if is_decimal:
+            try:
+                return float(text)
+            except ValueError:
+                pass
+        elif is_int:
+            try:
+                value = int(text)
+            except ValueError:
+                value = None
+            # Garde-fou .NET (l.ToString() == v) : on ne coerce pas "007".
+            if value is not None and str(value) == text:
+                return value
+
+    # Chaîne : valeur d'origine (déjà rognée), casse conservée.
+    return text
+
+
+def execute_loadcsv(
+    ctx: Any,
+    source_path: str | None = None,
+    has_header: bool = True,
+    separator: str = ";",
+    quote: str = '"',
+    escape: str = "\\",
+    excluded_columns: str | None = None,
+    exclude_null_and_empty: bool = False,
+) -> list:
+    """Lit un fichier CSV et renvoie un tableau d'objets (port de ``loadcsv``).
+
+    Args:
+        source_path: chemin du fichier CSV (absolu ou relatif au répertoire courant).
+        has_header: la 1re ligne porte les noms de colonnes (sinon ``Column0``…).
+        separator: séparateur de champs (défaut ``;``).
+        quote: caractère de citation (défaut ``"``).
+        escape: caractère d'échappement (défaut ``\\``).
+        excluded_columns: noms de colonnes à exclure, séparés par ``separator``.
+        exclude_null_and_empty: omet les cellules nulles/vides (et les lignes qui
+            n'auraient plus aucune valeur).
+
+    Returns:
+        La liste des lignes, chacune sous forme de dict colonne -> valeur typée.
+    """
+    if not source_path:
+        raise ValueError("loadcsv: source_path est requis")
+
+    delimiter = separator[0] if separator else ";"
+    quotechar = quote[0] if quote else '"'
+    escapechar = escape[0] if escape else None
+
+    excluded: set[str] = set()
+    if excluded_columns:
+        excluded = {c for c in excluded_columns.split(delimiter) if c}
+
+    with open(source_path, newline="", encoding="utf-8-sig") as handle:
+        reader = _csv.reader(
+            handle, delimiter=delimiter, quotechar=quotechar, escapechar=escapechar
+        )
+        rows = list(reader)
+
+    if not rows:
+        return []
+
+    if has_header:
+        raw_headers = rows[0]
+        data_rows = rows[1:]
+    else:
+        raw_headers = [f"Column{i}" for i in range(len(rows[0]))]
+        data_rows = rows
+
+    # (nom_brut, nom_assaini) par colonne ; l'exclusion compare le nom brut (.NET).
+    columns = [
+        (raw, raw if not has_header else _sanitize_header(raw)) for raw in raw_headers
+    ]
+
+    result: list[dict] = []
+    for row in data_rows:
+        obj: dict[str, Any] = {}
+        for index, (raw_name, label) in enumerate(columns):
+            if raw_name in excluded:
+                continue
+            cell = row[index] if index < len(row) else None
+            value = _coerce(cell, exclude_null_and_empty)
+            if value is _DROP:
+                continue
+            obj[label] = value
+        if obj or not exclude_null_and_empty:
+            result.append(obj)
+    return result
+
+
+def register(registry: Any) -> None:
+    """Enregistre les fonctions du plugin dans un registre jslt.
+
+    Point d'entrée déclaré via l'entry point ``urban_json.functions`` (découverte
+    automatique) et utilisable manuellement.
+    """
+    registry.register(
+        "loadcsv",
+        execute_loadcsv,
+        description="Lit un fichier CSV et renvoie un tableau d'objets.",
+    )
+    registry.register(
+        "loadmcsv",
+        execute_loadmcsv,
+        description="Lit un CSV multi-enregistrements hiérarchique et le convertit en arbre JSON.",
+    )

urban_json_csv/mcsv.py

@@ -0,0 +1,187 @@
+"""Lecture de CSV multi-enregistrements (``loadmcsv``).
+
+Port de ``Bb.CustomServices.ServicesMultiCsv.LoadMultiCsv`` + la bibliothèque
+``Bb.MultiCsv`` (lexer, règles d'indentation, blocs, visiteur JSON).
+
+Format de fichier (``;``-délimité) :
+
+* ``#DEF;<schema>:<NOM>;col1;col2;…`` — définit les colonnes du type ``NOM`` ;
+* ``#END`` — fin du fichier ;
+* ``#CLE;v1;v2`` — métadonnée ``CLE`` (valeurs jointes par ``;``) ;
+* ligne de données : 1er champ = type d'enregistrement, puis les valeurs des
+  colonnes définies par le ``#DEF`` correspondant.
+
+Un ``rule_payload`` ``"PARENT:ENF1|ENF2; AUTRE:…"`` (règles séparées par ``;``)
+décrit la **hiérarchie** : un bloc dont le nom est enfant du parent courant s'y
+imbrique, sinon il remonte. Le résultat JSON groupe les enfants homonymes en
+tableaux ; ``loadmcsv`` ajoute un objet ``_metadatas`` (nom de fichier, encodage,
+métadonnées du fichier).
+
+Écarts volontaires vs .NET (documentés) :
+
+* **Encodage** : lecture en ``utf-8`` (comme le .NET, qui lit en UTF-8 malgré sa
+  détection Ude) ; ``_encodingFile``/``_encodingFileBody`` rapportent ``utf-8``.
+* **Dernier champ** : le .NET ignore le dernier champ de chaque ligne (il suppose
+  un ``;`` final). Le portage mappe les colonnes par position jusqu'au nombre de
+  colonnes déclarées — tolérant au ``;`` final comme à son absence.
+* Noms de types et de règles comparés en **majuscules** (le .NET met les libellés
+  en majuscules ; on fait de même côté règles pour éviter les surprises de casse).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+__all__ = ["execute_loadmcsv"]
+
+
+class _Block:
+    """Un enregistrement : nom de type, champs (colonne→valeur), sous-blocs."""
+
+    __slots__ = ("fields", "name", "subs")
+
+    def __init__(self, name: str, fields: dict[str, str]) -> None:
+        self.name = name
+        self.fields = fields
+        self.subs: list[_Block] = []
+
+
+def _parse_rules(payload: str | None) -> dict[str, set[str]]:
+    """Parse le DSL de règles ``"PARENT:ENF1|ENF2; …"`` (port d'``IndentationRules``)."""
+    rules: dict[str, set[str]] = {}
+    for rule in (payload or "").strip().split(";"):
+        rule = rule.strip()
+        if not rule or ":" not in rule:
+            continue
+        key, children = rule.split(":", 1)
+        kids = {c.strip().upper() for c in children.split("|") if c.strip()}
+        rules.setdefault(key.strip().upper(), set()).update(kids)
+    return rules
+
+
+def _read_blocks(path: str, encoding: str) -> tuple[list[_Block], dict[str, str]]:
+    """Lit le fichier en blocs de données + métadonnées (port du ``Lexer``)."""
+    headers: dict[str, list[str]] = {}
+    metadata: dict[str, str] = {}
+    blocks: list[_Block] = []
+
+    with open(path, encoding=encoding, newline="") as handle:
+        for raw in handle:
+            line = raw.rstrip("\r\n")
+            if line == "":
+                continue
+            fields = line.split(";")
+            tag = fields[0]
+
+            if tag.startswith("#"):
+                if tag == "#DEF":
+                    # fields[1] = "<schema>:<NOM>" ; fields[2:] = colonnes
+                    name = fields[1].split(":")[-1].strip().upper() if len(fields) > 1 else ""
+                    headers[name] = [c.strip() for c in fields[2:] if c.strip()]
+                elif tag == "#END":
+                    break
+                else:
+                    metadata[tag[1:]] = ";".join(fields[1:]).strip(";")
+                continue
+
+            name = tag.strip().upper()
+            columns = headers.get(name)
+            field_map: dict[str, str] = {}
+            if columns:
+                for index, column in enumerate(columns):
+                    field_map[column] = fields[index + 1] if index + 1 < len(fields) else ""
+            blocks.append(_Block(name, field_map))
+
+    return blocks, metadata
+
+
+def _build_tree(blocks: list[_Block], rules: dict[str, set[str]]) -> list[_Block]:
+    """Construit l'arbre de blocs par pile (port de ``FileReader.Read``)."""
+    if not blocks:
+        return []
+
+    def embedded(parent: _Block, child: _Block) -> bool:
+        return child.name in rules.get(parent.name, ())
+
+    stack: list[_Block] = [blocks[0]]
+    for current in blocks[1:]:
+        parent = stack[-1]
+        if embedded(parent, current):
+            parent.subs.append(current)
+            stack.append(current)
+        else:
+            parent = stack.pop()
+            while stack and not embedded(parent, current):
+                parent = stack.pop()
+            parent.subs.append(current)
+            stack.append(parent)
+            stack.append(current)
+
+    items: list[_Block] = []
+    while stack:
+        current = stack.pop()
+        if not stack or all(current is not sub for sub in stack[-1].subs):
+            items.append(current)
+    return items
+
+
+def _to_json(block: _Block, seen: set[int], ignore_empty: bool) -> dict[str, Any]:
+    """Convertit un bloc en objet JSON (port de ``JsonVisitor``)."""
+    result: dict[str, Any] = {}
+    for sub in block.subs:
+        array = result.setdefault(sub.name, [])
+        if id(sub) not in seen:
+            seen.add(id(sub))
+            array.append(_to_json(sub, seen, ignore_empty))
+    for key, value in block.fields.items():
+        if not ignore_empty or value != "":
+            result[key] = value
+    return result
+
+
+def execute_loadmcsv(
+    ctx: Any,
+    source_path: str | None = None,
+    rule_payload: str | None = None,
+    encoding: str = "utf-8-sig",
+    ignore_empty: bool = False,
+) -> Any:
+    """Lit un CSV multi-enregistrements et le convertit en arbre JSON (port ``loadmcsv``).
+
+    Args:
+        source_path: chemin du fichier.
+        rule_payload: règles d'imbrication ``"PARENT:ENF1|ENF2; …"``.
+        encoding: encodage de lecture (défaut ``utf-8-sig``, retire le BOM).
+        ignore_empty: omet les propriétés vides.
+
+    Returns:
+        ``None`` si aucun enregistrement, l'objet racine s'il y en a un seul,
+        sinon la liste des objets racines. Chaque racine porte ``_metadatas``.
+    """
+    if not source_path:
+        raise ValueError("loadmcsv: source_path est requis")
+
+    blocks, metadata = _read_blocks(source_path, encoding)
+    rules = _parse_rules(rule_payload)
+    items = _build_tree(blocks, rules)
+
+    meta_obj: dict[str, Any] = {
+        "_filename": os.path.abspath(source_path),
+        "_encodingFile": "utf-8",
+        "_encodingFileBody": "utf-8",
+    }
+    meta_obj.update(metadata)
+
+    seen: set[int] = set()
+    datas: list[Any] = []
+    for block in items:
+        obj = _to_json(block, seen, ignore_empty)
+        obj["_metadatas"] = meta_obj
+        datas.append(obj)
+
+    if not datas:
+        return None
+    if len(datas) == 1:
+        return datas[0]
+    return datas

urban_json_csv-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: urban-json-csv
+Version: 0.1.0
+Summary: Plugin urban-json : lecture de fichiers CSV (fonction de template loadcsv).
+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,csv,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
+Dynamic: license-file
+
+# urban-json-csv
+
+Plugin [urban-json](https://github.com/gaelgael5/Jslt) : lecture de fichiers **CSV**
+dans les templates, via la fonction `loadcsv`. Port de
+`Bb.CustomServices.ServiceCsv` (.NET).
+
+## Installation
+
+```bash
+pip install urban-json-csv      # tire urban-json en dépendance
+```
+
+Rien d'autre à faire : `urban-json` découvre le plugin automatiquement via les entry
+points (`urban_json.functions`). `loadcsv` devient utilisable dans les templates.
+
+## Utilisation
+
+```python
+from urban_json import JsltTemplate
+
+# people.csv :
+#   name;age;active
+#   Alice;30;true
+#   Bob;25;false
+tpl = JsltTemplate.parse('[ { "$source": loadcsv("people.csv"), "n": $.name, "a": $.age } ]')
+tpl.transform({})
+# -> [{'n': 'Alice', 'a': 30}, {'n': 'Bob', 'a': 25}]
+```
+
+`loadcsv` renvoie un tableau d'objets (une entrée par ligne) ; il s'enchaîne donc
+naturellement avec une boucle `$source`, un filtre `?(...)`, etc.
+
+## Signature
+
+```
+loadcsv(source_path, has_header=true, separator=";", quote="\"", escape="\\",
+        excluded_columns=null, exclude_null_and_empty=false)
+```
+
+| Paramètre | Rôle |
+|---|---|
+| `source_path` | chemin du fichier CSV (absolu ou relatif au répertoire courant) |
+| `has_header` | la 1re ligne porte les noms de colonnes (sinon `Column0`, `Column1`…) |
+| `separator` | séparateur de champs (défaut `;`) |
+| `quote` | caractère de citation (défaut `"`) |
+| `escape` | caractère d'échappement (défaut `\`) |
+| `excluded_columns` | noms de colonnes à exclure, séparés par `separator` |
+| `exclude_null_and_empty` | omet les cellules nulles/vides |
+
+### Typage des valeurs
+
+Les cellules sont coercées comme en .NET : `true`/`false` → booléen,
+entiers/décimaux → nombres, le reste → chaîne (les entêtes sont assainis :
+accents → ASCII, espaces → `_`).
+
+## `loadmcsv` — CSV multi-enregistrements hiérarchique
+
+Port de `ServicesMultiCsv` : un fichier `;`-délimité où chaque ligne est préfixée
+par un **type d'enregistrement**, les colonnes de chaque type étant déclarées par
+des lignes `#DEF`. Un `rule_payload` décrit la **hiérarchie**.
+
+```
+#DEF;CATALOG;id;name
+#DEF;BOOK;code;title
+CATALOG;1;Librairie
+BOOK;a;Alpha
+BOOK;b;Beta
+#END
+```
+
+```python
+from urban_json import JsltTemplate
+JsltTemplate.parse(
+    '[ { "$source": selectmany(loadmcsv("catalog.mcsv", "CATALOG:BOOK"), $.BOOK.*), "t": $.title } ]'
+).transform({})
+# -> [{'t': 'Alpha'}, {'t': 'Beta'}]
+```
+
+`loadmcsv(source_path, rule_payload, encoding, ignore_empty)` :
+- `rule_payload` : règles `"PARENT:ENF1|ENF2; …"` (séparées par `;`). Un bloc dont
+  le nom est enfant du parent courant s'y imbrique, sinon il remonte.
+- Les enfants homonymes deviennent un **tableau** ; chaque racine porte un objet
+  `_metadatas` (nom de fichier, encodage, métadonnées `#clé` du fichier).
+- Lignes `#DEF;<schema>:<NOM>;col…` (colonnes), `#clé;…` (métadonnée), `#END` (fin).
+
+Écarts assumés vs .NET : lecture `utf-8` ; mappage des colonnes par position
+tolérant au `;` final (le .NET l'exige) ; noms de types comparés en majuscules.
+
+## Licence
+
+Apache-2.0.

urban_json_csv-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+urban_json_csv/__init__.py,sha256=rjcBsVpGzfvyuilkK5-FWrEMPKVRkHgn90hr2w_JxeI,7000
+urban_json_csv/mcsv.py,sha256=HiCNgl-rKHTuR4lG1WhLD88H9NeYhCXoXo_BF9vg7m4,6796
+urban_json_csv/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+urban_json_csv-0.1.0.dist-info/licenses/LICENSE,sha256=LdXMQzg0w6hrGI_vhgHsmOLKcHTkyF5PyUXkP9fV7mA,1068
+urban_json_csv-0.1.0.dist-info/METADATA,sha256=c-x-cmVx1x8MVfQlqC_UBsoIeq-tx1PzeopoWYx6PiA,4198
+urban_json_csv-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+urban_json_csv-0.1.0.dist-info/entry_points.txt,sha256=U3FWKPHVQ1MniD9Ukg8H7-z69TWtkBq8op5BVWLRtFk,53
+urban_json_csv-0.1.0.dist-info/top_level.txt,sha256=HvN15nMA_4voCRcD50sblM93GM04fECJs8-Es-JdhVw,15
+urban_json_csv-0.1.0.dist-info/RECORD,,

urban_json_csv-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_csv-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[urban_json.functions]
+csv = urban_json_csv:register

urban_json_csv-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_csv-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+urban_json_csv