unspsc-fr 0.1.0__tar.gz

unspsc_fr-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+__pycache__/
+.DS_Store
+python/dist/
+*.egg-info/

unspsc_fr-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: unspsc-fr
+Version: 0.1.0
+Summary: UNSPSC v26 bilingue EN/FR : lookup, hiérarchie et recherche floue sur la nomenclature des marchés publics
+Project-URL: Homepage, https://github.com/codebysaadbouh/unspsc-fr
+Project-URL: Source, https://github.com/codebysaadbouh/unspsc-fr
+Author: Saadbouh
+License-Expression: MIT
+Keywords: bilingual,classification,marchés publics,procurement,unspsc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Natural Language :: French
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# unspsc-fr
+
+La nomenclature **UNSPSC v26** bilingue EN/FR, requêtable en Python : lookup de codes,
+navigation hiérarchique et recherche plein texte insensible aux accents.
+
+Données : 149 849 produits, 21 706 traductions françaises sourcées (gouvernement du
+Canada). Détails, couverture et licences :
+[github.com/codebysaadbouh/unspsc-fr](https://github.com/codebysaadbouh/unspsc-fr).
+
+## Installation
+
+```bash
+pip install unspsc-fr
+```
+
+La base SQLite (~88 Mo) est téléchargée au premier usage puis mise en cache
+(`~/.cache/unspsc-fr/`). Pour utiliser une base locale : variable d'environnement
+`UNSPSC_FR_DB` ou `UNSPSC(db_path=...)`.
+
+## Usage
+
+```python
+from unspsc_fr import UNSPSC
+
+u = UNSPSC()
+
+u.get(10101501)
+# Entry(code=10101501, level='commodity', title_en='Cats', title_fr='Chats', …)
+# .title → 'Chats' (repli automatique sur l'anglais si non traduit)
+
+u.search("béton", lang="fr")             # plein texte, accents ignorés
+u.search("cemen", lang="en")             # préfixe : saisie incrémentale
+u.children()                              # les 58 segments
+u.children(10101500)                      # produits d'une classe
+u.ancestors(10101501)                     # segment > famille > classe
+```
+
+## CLI
+
+```bash
+unspsc-fr get 10101501
+unspsc-fr search "ciment" --lang fr
+unspsc-fr children 10100000
+unspsc-fr ancestors 10101501 --json
+```
+
+## Licences
+
+Code MIT. Codeset © UNDP (UNSPSC®) ; traductions françaises sous Licence du
+gouvernement ouvert – Canada. Voir le
+[NOTICE](https://github.com/codebysaadbouh/unspsc-fr/blob/main/NOTICE) du dépôt.

unspsc_fr-0.1.0/README.md

@@ -0,0 +1,51 @@
+# unspsc-fr
+
+La nomenclature **UNSPSC v26** bilingue EN/FR, requêtable en Python : lookup de codes,
+navigation hiérarchique et recherche plein texte insensible aux accents.
+
+Données : 149 849 produits, 21 706 traductions françaises sourcées (gouvernement du
+Canada). Détails, couverture et licences :
+[github.com/codebysaadbouh/unspsc-fr](https://github.com/codebysaadbouh/unspsc-fr).
+
+## Installation
+
+```bash
+pip install unspsc-fr
+```
+
+La base SQLite (~88 Mo) est téléchargée au premier usage puis mise en cache
+(`~/.cache/unspsc-fr/`). Pour utiliser une base locale : variable d'environnement
+`UNSPSC_FR_DB` ou `UNSPSC(db_path=...)`.
+
+## Usage
+
+```python
+from unspsc_fr import UNSPSC
+
+u = UNSPSC()
+
+u.get(10101501)
+# Entry(code=10101501, level='commodity', title_en='Cats', title_fr='Chats', …)
+# .title → 'Chats' (repli automatique sur l'anglais si non traduit)
+
+u.search("béton", lang="fr")             # plein texte, accents ignorés
+u.search("cemen", lang="en")             # préfixe : saisie incrémentale
+u.children()                              # les 58 segments
+u.children(10101500)                      # produits d'une classe
+u.ancestors(10101501)                     # segment > famille > classe
+```
+
+## CLI
+
+```bash
+unspsc-fr get 10101501
+unspsc-fr search "ciment" --lang fr
+unspsc-fr children 10100000
+unspsc-fr ancestors 10101501 --json
+```
+
+## Licences
+
+Code MIT. Codeset © UNDP (UNSPSC®) ; traductions françaises sous Licence du
+gouvernement ouvert – Canada. Voir le
+[NOTICE](https://github.com/codebysaadbouh/unspsc-fr/blob/main/NOTICE) du dépôt.

unspsc_fr-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "unspsc-fr"
+version = "0.1.0"
+description = "UNSPSC v26 bilingue EN/FR : lookup, hiérarchie et recherche floue sur la nomenclature des marchés publics"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Saadbouh" }]
+keywords = ["unspsc", "procurement", "marchés publics", "classification", "bilingual"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Natural Language :: French",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business",
+]
+
+[project.urls]
+Homepage = "https://github.com/codebysaadbouh/unspsc-fr"
+Source = "https://github.com/codebysaadbouh/unspsc-fr"
+
+[project.scripts]
+unspsc-fr = "unspsc_fr.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/unspsc_fr"]

unspsc_fr-0.1.0/src/unspsc_fr/__init__.py

@@ -0,0 +1,200 @@
+"""unspsc-fr : la nomenclature UNSPSC bilingue EN/FR, requêtable en Python.
+
+    from unspsc_fr import UNSPSC
+
+    u = UNSPSC()                        # télécharge la base au premier usage
+    u.get(10101501)                     # Entry(code=10101501, title='Chats', …)
+    u.search("ciment", lang="fr")       # recherche plein texte, accents ignorés
+    u.children(10101500)                # produits de la classe
+    u.ancestors(10101501)               # segment > famille > classe
+"""
+from __future__ import annotations
+
+import os
+import sqlite3
+from dataclasses import dataclass
+from typing import Optional
+
+from . import db as _db
+
+__version__ = "0.1.0"
+__all__ = ["UNSPSC", "Entry", "__version__"]
+
+LEVELS = ("segment", "family", "class", "commodity")
+_TABLE = {
+    "segment": ("segments", "segment_code"),
+    "family": ("families", "family_code"),
+    "class": ("classes", "class_code"),
+    "commodity": ("commodities", "commodity_code"),
+}
+
+
+@dataclass(frozen=True)
+class Entry:
+    code: int
+    level: str
+    title_en: str
+    title_fr: Optional[str]
+    definition_en: Optional[str] = None
+
+    @property
+    def title(self) -> str:
+        """Titre français, repli anglais si non traduit."""
+        return self.title_fr or self.title_en
+
+    @property
+    def is_translated(self) -> bool:
+        return self.title_fr is not None
+
+
+def level_of(code: int) -> str:
+    """Niveau déduit de la forme du code (XX000000 → segment, etc.).
+
+    Attention : quelques codes existent à deux niveaux dans le codeset UNDP
+    (ex. 26132000 est une classe ET un produit) ; cette fonction retourne le
+    niveau le plus haut. ``UNSPSC.get`` accepte un ``level`` explicite.
+    """
+    if code % 1_000_000 == 0:
+        return "segment"
+    if code % 10_000 == 0:
+        return "family"
+    if code % 100 == 0:
+        return "class"
+    return "commodity"
+
+
+def parent_code(code: int, level: str) -> Optional[int]:
+    if level == "segment":
+        return None
+    divisor = {"family": 1_000_000, "class": 10_000, "commodity": 100}[level]
+    return code // divisor * divisor
+
+
+class UNSPSC:
+    def __init__(self, db_path: "str | os.PathLike | None" = None):
+        self._con: sqlite3.Connection = _db.connect(db_path)
+
+    # -- lookup ---------------------------------------------------------
+
+    def get(self, code: int, level: Optional[str] = None) -> Optional[Entry]:
+        """L'entrée pour un code, ou None. ``level`` lève l'ambiguïté des
+        rares codes présents à deux niveaux."""
+        code = int(code)
+        for lv in [level] if level else self._levels_for(code):
+            table, pk = _TABLE[lv]
+            row = self._con.execute(
+                f"""
+                SELECT t.{pk} AS code, t.title_en, t.definition_en, fr.title AS title_fr
+                FROM {table} t
+                LEFT JOIN translations fr
+                       ON fr.code = t.{pk} AND fr.level = ? AND fr.lang = 'fr'
+                WHERE t.{pk} = ?
+                """,
+                (lv, code),
+            ).fetchone()
+            if row:
+                return Entry(row["code"], lv, row["title_en"], row["title_fr"],
+                             row["definition_en"])
+        return None
+
+    def _levels_for(self, code: int) -> list[str]:
+        first = level_of(code)
+        # essaie d'abord le niveau canonique, puis les niveaux plus profonds
+        # pour les codes ambigus
+        return [first] + [lv for lv in LEVELS[LEVELS.index(first) + 1:]]
+
+    # -- hiérarchie -----------------------------------------------------
+
+    def children(self, code: Optional[int] = None) -> list[Entry]:
+        """Les enfants directs d'un code ; sans argument, les 58 segments."""
+        if code is None:
+            return self._select("segment", "1=1", ())
+        level = level_of(int(code))
+        child = {"segment": "family", "family": "class", "class": "commodity"}.get(level)
+        if child is None:
+            return []
+        table, pk = _TABLE[child]
+        parent_col = _TABLE[level][1]
+        return self._select(child, f"t.{parent_col} = ?", (int(code),))
+
+    def ancestors(self, code: int, level: Optional[str] = None) -> list[Entry]:
+        """Du segment jusqu'au parent direct (exclut le code lui-même)."""
+        entry = self.get(code, level)
+        if entry is None:
+            return []
+        chain: list[Entry] = []
+        current = parent_code(entry.code, entry.level)
+        current_level = entry.level
+        while current is not None:
+            current_level = LEVELS[LEVELS.index(current_level) - 1]
+            parent = self.get(current, current_level)
+            if parent:
+                chain.append(parent)
+            current = parent_code(current, current_level)
+        return list(reversed(chain))
+
+    def _select(self, level: str, where: str, params: tuple) -> list[Entry]:
+        table, pk = _TABLE[level]
+        rows = self._con.execute(
+            f"""
+            SELECT t.{pk} AS code, t.title_en, t.definition_en, fr.title AS title_fr
+            FROM {table} t
+            LEFT JOIN translations fr
+                   ON fr.code = t.{pk} AND fr.level = ? AND fr.lang = 'fr'
+            WHERE {where} ORDER BY t.{pk}
+            """,
+            (level, *params),
+        ).fetchall()
+        return [Entry(r["code"], level, r["title_en"], r["title_fr"],
+                      r["definition_en"]) for r in rows]
+
+    # -- recherche ------------------------------------------------------
+
+    def search(
+        self,
+        query: str,
+        lang: Optional[str] = None,
+        level: Optional[str] = None,
+        limit: int = 20,
+    ) -> list[Entry]:
+        """Recherche plein texte (FTS5, insensible aux accents), classée par
+        pertinence. ``lang``/``level`` restreignent la recherche ; le dernier
+        mot est traité en préfixe pour permettre la saisie incrémentale."""
+        tokens = [t for t in query.split() if t.strip('"*')]
+        if not tokens:
+            return []
+        fts_query = " ".join(f'"{t}"' for t in tokens[:-1]) + f' "{tokens[-1]}" *'
+        conditions, params = ["translations_fts MATCH ?"], [fts_query.strip()]
+        if lang:
+            conditions.append("lang = ?")
+            params.append(lang)
+        if level:
+            conditions.append("level = ?")
+            params.append(level)
+        rows = self._con.execute(
+            f"""
+            SELECT code, level FROM translations_fts
+            WHERE {' AND '.join(conditions)}
+            ORDER BY bm25(translations_fts) LIMIT ?
+            """,
+            (*params, limit),
+        ).fetchall()
+        results, seen = [], set()
+        for r in rows:
+            key = (r["code"], r["level"])
+            if key in seen:
+                continue
+            seen.add(key)
+            entry = self.get(r["code"], r["level"])
+            if entry:
+                results.append(entry)
+        return results
+
+    def close(self) -> None:
+        self._con.close()
+
+    def __enter__(self) -> "UNSPSC":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()

unspsc_fr-0.1.0/src/unspsc_fr/cli.py

@@ -0,0 +1,77 @@
+"""CLI : unspsc-fr get|search|children|ancestors."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import UNSPSC, Entry, __version__
+
+
+def fmt(entry: Entry, as_json: bool) -> str:
+    if as_json:
+        return json.dumps(
+            {
+                "code": entry.code,
+                "level": entry.level,
+                "title_en": entry.title_en,
+                "title_fr": entry.title_fr,
+            },
+            ensure_ascii=False,
+        )
+    mark = "" if entry.is_translated else "  [EN]"
+    return f"{entry.code}  {entry.level:<9}  {entry.title}{mark}"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="unspsc-fr",
+        description="Nomenclature UNSPSC bilingue EN/FR en ligne de commande",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--json", action="store_true", help="sortie JSON (une ligne par entrée)")
+    parser.add_argument("--db", help="chemin vers la base SQLite (sinon cache/téléchargement)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_get = sub.add_parser("get", help="détail d'un code")
+    p_get.add_argument("code", type=int)
+
+    p_search = sub.add_parser("search", help="recherche plein texte")
+    p_search.add_argument("query")
+    p_search.add_argument("--lang", choices=["en", "fr"], help="restreindre à une langue")
+    p_search.add_argument("--level", choices=["segment", "family", "class", "commodity"])
+    p_search.add_argument("--limit", type=int, default=20)
+
+    p_children = sub.add_parser("children", help="enfants directs (sans code : les segments)")
+    p_children.add_argument("code", type=int, nargs="?")
+
+    p_anc = sub.add_parser("ancestors", help="chaîne segment > famille > classe d'un code")
+    p_anc.add_argument("code", type=int)
+
+    args = parser.parse_args(argv)
+    u = UNSPSC(db_path=args.db)
+
+    if args.command == "get":
+        entry = u.get(args.code)
+        if entry is None:
+            print(f"Code inconnu : {args.code}", file=sys.stderr)
+            return 1
+        print(fmt(entry, args.json))
+        if not args.json and entry.definition_en:
+            print(f"  {entry.definition_en}")
+        return 0
+
+    if args.command == "search":
+        entries = u.search(args.query, lang=args.lang, level=args.level, limit=args.limit)
+    elif args.command == "children":
+        entries = u.children(args.code)
+    else:
+        entries = u.ancestors(args.code)
+
+    for entry in entries:
+        print(fmt(entry, args.json))
+    return 0 if entries else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

unspsc_fr-0.1.0/src/unspsc_fr/db.py

@@ -0,0 +1,96 @@
+"""Localisation, téléchargement et préparation de la base SQLite.
+
+La base (~88 Mo) n'est pas embarquée dans le wheel : elle est téléchargée depuis
+la release GitHub au premier usage puis mise en cache. Ordre de résolution :
+
+1. chemin passé explicitement à ``UNSPSC(db_path=...)``
+2. variable d'environnement ``UNSPSC_FR_DB``
+3. cache local (``$XDG_CACHE_HOME/unspsc-fr`` ou ``~/.cache/unspsc-fr``),
+   téléchargé si absent
+"""
+from __future__ import annotations
+
+import os
+import sqlite3
+import sys
+import urllib.request
+from pathlib import Path
+
+DATA_VERSION = "v26.0801"
+DB_FILENAME = "unspsc-bilingue.sqlite"
+DB_URL = (
+    "https://github.com/codebysaadbouh/unspsc-fr/releases/download/"
+    f"{DATA_VERSION}/{DB_FILENAME}"
+)
+
+
+def cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    return Path(base) / "unspsc-fr" / DATA_VERSION
+
+
+def resolve_db_path(db_path: str | os.PathLike | None = None) -> Path:
+    if db_path is not None:
+        path = Path(db_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Base SQLite introuvable : {path}")
+        return path
+    env = os.environ.get("UNSPSC_FR_DB")
+    if env:
+        path = Path(env)
+        if not path.exists():
+            raise FileNotFoundError(f"UNSPSC_FR_DB pointe vers un fichier absent : {path}")
+        return path
+    cached = cache_dir() / DB_FILENAME
+    if not cached.exists():
+        download(cached)
+    return cached
+
+
+def download(dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_suffix(".tmp")
+    print(
+        f"Téléchargement de la base UNSPSC {DATA_VERSION} (~88 Mo) vers {dest} …",
+        file=sys.stderr,
+    )
+    with urllib.request.urlopen(DB_URL) as resp, tmp.open("wb") as out:
+        while chunk := resp.read(1 << 20):
+            out.write(chunk)
+    tmp.rename(dest)
+
+
+def connect(db_path: str | os.PathLike | None = None) -> sqlite3.Connection:
+    """Ouvre la base et s'assure que l'index plein texte existe."""
+    path = resolve_db_path(db_path)
+    con = sqlite3.connect(path)
+    con.row_factory = sqlite3.Row
+    ensure_fts(con)
+    return con
+
+
+def ensure_fts(con: sqlite3.Connection) -> None:
+    """Construit l'index FTS5 des libellés à la première ouverture.
+
+    ``remove_diacritics 2`` rend la recherche insensible aux accents
+    (« electricite » trouve « électricité »).
+    """
+    exists = con.execute(
+        "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'translations_fts'"
+    ).fetchone()
+    if exists:
+        return
+    con.executescript(
+        """
+        CREATE VIRTUAL TABLE translations_fts USING fts5(
+            title,
+            code UNINDEXED,
+            level UNINDEXED,
+            lang UNINDEXED,
+            tokenize = "unicode61 remove_diacritics 2"
+        );
+        INSERT INTO translations_fts (title, code, level, lang)
+        SELECT title, code, level, lang FROM translations;
+        """
+    )
+    con.commit()

unspsc_fr-0.1.0/tests/conftest.py

@@ -0,0 +1,7 @@
+import os
+from pathlib import Path
+
+DIST_DB = Path(__file__).resolve().parents[2] / "dist" / "unspsc-bilingue.sqlite"
+
+if "UNSPSC_FR_DB" not in os.environ and DIST_DB.exists():
+    os.environ["UNSPSC_FR_DB"] = str(DIST_DB)

unspsc_fr-0.1.0/tests/test_unspsc.py

@@ -0,0 +1,79 @@
+"""Tests contre la base réelle : UNSPSC_FR_DB doit pointer vers le SQLite
+(par défaut ../dist/unspsc-bilingue.sqlite via conftest)."""
+import pytest
+
+from unspsc_fr import UNSPSC, level_of, parent_code
+
+
+@pytest.fixture(scope="module")
+def u():
+    with UNSPSC() as u:
+        yield u
+
+
+def test_level_of():
+    assert level_of(10000000) == "segment"
+    assert level_of(10100000) == "family"
+    assert level_of(10101500) == "class"
+    assert level_of(10101501) == "commodity"
+
+
+def test_parent_code():
+    assert parent_code(10101501, "commodity") == 10101500
+    assert parent_code(10101500, "class") == 10100000
+    assert parent_code(10100000, "family") == 10000000
+    assert parent_code(10000000, "segment") is None
+
+
+def test_get_translated(u):
+    entry = u.get(10101501)
+    assert entry.title == "Chats"
+    assert entry.title_en == "Cats"
+    assert entry.is_translated
+
+
+def test_get_fallback_en(u):
+    # segment 57000000 : seul segment sans traduction française
+    entry = u.get(57000000)
+    assert entry.title_fr is None
+    assert entry.title == entry.title_en
+
+
+def test_get_unknown(u):
+    assert u.get(99999999) is None
+
+
+def test_ambiguous_code_both_levels(u):
+    # 26132000 existe comme classe ET comme produit dans le codeset UNDP
+    assert u.get(26132000, level="class").level == "class"
+    assert u.get(26132000, level="commodity").level == "commodity"
+    assert u.get(26132000).level == "class"  # niveau canonique d'abord
+
+
+def test_children_and_segments(u):
+    assert len(u.children()) == 58
+    kittens = u.children(10101500)
+    assert any(e.code == 10101501 for e in kittens)
+    assert u.children(10101501) == []
+
+
+def test_ancestors(u):
+    chain = u.ancestors(10101501)
+    assert [e.level for e in chain] == ["segment", "family", "class"]
+    assert chain[-1].code == 10101500
+
+
+def test_search_accent_insensitive(u):
+    hits = u.search("electricite", lang="fr")
+    assert hits, "la recherche sans accents doit trouver « électricité »"
+    assert any("électri" in (e.title_fr or "").lower() for e in hits)
+
+
+def test_search_prefix(u):
+    hits = u.search("cha", lang="fr", limit=50)
+    assert hits  # saisie incrémentale : préfixe sur le dernier mot
+
+
+def test_search_level_filter(u):
+    hits = u.search("cats", lang="en", level="commodity")
+    assert all(e.level == "commodity" for e in hits)