urban-json-elastic 0.1.0__tar.gz

urban_json_elastic-0.1.0/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_elastic-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: urban-json-elastic
+Version: 0.1.0
+Summary: Plugin urban-json : recherche Elasticsearch (esconnect / essearch).
+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,elasticsearch,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 :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: urban-json
+Requires-Dist: elasticsearch>=8
+Dynamic: license-file
+
+# urban-json-elastic
+
+Plugin [urban-json](https://github.com/gaelgael5/Jslt) : recherche **Elasticsearch**
+depuis les templates, via le client officiel `elasticsearch`.
+
+## Installation
+
+```bash
+pip install urban-json-elastic      # tire urban-json et le client elasticsearch
+```
+
+`urban-json` découvre le plugin automatiquement via les entry points (`urban_json.functions`).
+
+## Utilisation
+
+```python
+from urban_json import JsltTemplate
+
+tpl = JsltTemplate.parse('''
+{
+  "es:": esconnect("https://localhost:9200", $.api_key),
+  "docs": [ {
+    "$source": essearch(es:, "products", { "match": { "category": "book" } }, 50),
+    "nom": $.title, "prix": $.price
+  } ]
+}
+''')
+```
+
+- `esconnect(hosts, api_key, username, password, verify_certs)` → descripteur de
+  connexion (à stocker dans une variable).
+- `essearch(connection, index, query, size)` → liste des documents trouvés
+  (le `_source` de chaque hit). `query` est une clause du DSL Elasticsearch
+  (`match_all` si absente).
+
+## Sécurité
+
+`essearch` interroge un cluster Elasticsearch réel. Les identifiants (api_key /
+mot de passe) transitent par le descripteur de connexion : traitez-les comme des
+secrets côté template.
+
+## Licence
+
+Apache-2.0.

urban_json_elastic-0.1.0/README.md

@@ -0,0 +1,44 @@
+# urban-json-elastic
+
+Plugin [urban-json](https://github.com/gaelgael5/Jslt) : recherche **Elasticsearch**
+depuis les templates, via le client officiel `elasticsearch`.
+
+## Installation
+
+```bash
+pip install urban-json-elastic      # tire urban-json et le client elasticsearch
+```
+
+`urban-json` découvre le plugin automatiquement via les entry points (`urban_json.functions`).
+
+## Utilisation
+
+```python
+from urban_json import JsltTemplate
+
+tpl = JsltTemplate.parse('''
+{
+  "es:": esconnect("https://localhost:9200", $.api_key),
+  "docs": [ {
+    "$source": essearch(es:, "products", { "match": { "category": "book" } }, 50),
+    "nom": $.title, "prix": $.price
+  } ]
+}
+''')
+```
+
+- `esconnect(hosts, api_key, username, password, verify_certs)` → descripteur de
+  connexion (à stocker dans une variable).
+- `essearch(connection, index, query, size)` → liste des documents trouvés
+  (le `_source` de chaque hit). `query` est une clause du DSL Elasticsearch
+  (`match_all` si absente).
+
+## Sécurité
+
+`essearch` interroge un cluster Elasticsearch réel. Les identifiants (api_key /
+mot de passe) transitent par le descripteur de connexion : traitez-les comme des
+secrets côté template.
+
+## Licence
+
+Apache-2.0.

urban_json_elastic-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "urban-json-elastic"
+dynamic = ["version"]
+description = "Plugin urban-json : recherche Elasticsearch (esconnect / essearch)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Gael Beard", email = "gaelgael5@gmail.com" }]
+keywords = ["json", "transform", "template", "jslt", "elasticsearch", "plugin"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+    "Typing :: Typed",
+]
+dependencies = [
+    "urban-json",
+    "elasticsearch>=8",
+]
+
+[project.urls]
+Homepage = "https://github.com/gaelgael5/Jslt"
+Repository = "https://github.com/gaelgael5/Jslt"
+
+# Découverte automatique par urban-json : installer ce paquet suffit à exposer les fonctions.
+[project.entry-points."urban_json.functions"]
+elastic = "urban_json_elastic:register"
+
+[tool.setuptools.dynamic]
+version = { attr = "urban_json_elastic.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+urban_json_elastic = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]

urban_json_elastic-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

urban_json_elastic-0.1.0/src/urban_json_elastic/__init__.py

@@ -0,0 +1,112 @@
+"""Plugin jslt : recherche Elasticsearch (``esconnect`` / ``essearch``).
+
+Deux fonctions de template, dans l'esprit du couple ``connectsql`` / ``readsql`` :
+
+* ``esconnect(hosts, api_key, username, password, verify_certs)`` → descripteur de
+  connexion (à stocker dans une variable) ;
+* ``essearch(connection, index, query, size)`` → liste des documents trouvés
+  (le ``_source`` de chaque hit).
+
+Client : `elasticsearch` (client officiel). Importé **paresseusement** pour que la
+découverte/introspection du plugin ne force pas l'import du client.
+
+Découvert automatiquement par ``jslt`` via l'entry point ``urban_json.functions``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__version__ = "0.1.0"
+
+__all__ = ["execute_esconnect", "execute_essearch", "register"]
+
+
+def _build_client(connection: dict) -> Any:
+    """Construit le client Elasticsearch depuis un descripteur. Point d'injection (tests)."""
+    from elasticsearch import Elasticsearch
+
+    kwargs: dict[str, Any] = {"hosts": connection.get("hosts")}
+    if connection.get("api_key"):
+        kwargs["api_key"] = connection["api_key"]
+    if connection.get("basic_auth"):
+        kwargs["basic_auth"] = tuple(connection["basic_auth"])
+    if "verify_certs" in connection:
+        kwargs["verify_certs"] = connection["verify_certs"]
+    return Elasticsearch(**kwargs)
+
+
+def execute_esconnect(
+    ctx: Any,
+    hosts: Any = None,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    verify_certs: bool = True,
+) -> dict:
+    """Crée un descripteur de connexion Elasticsearch (port esprit ``connectsql``).
+
+    Args:
+        hosts: URL (ou liste d'URL) du/des nœud(s) Elasticsearch.
+        api_key: clé d'API (optionnelle).
+        username / password: authentification basique (optionnelle).
+        verify_certs: vérifie les certificats TLS (défaut ``True``).
+
+    Returns:
+        Un descripteur à passer à :func:`execute_essearch`.
+    """
+    if not hosts:
+        raise ValueError("esconnect: hosts est requis")
+    descriptor: dict[str, Any] = {"hosts": hosts, "verify_certs": verify_certs}
+    if api_key:
+        descriptor["api_key"] = api_key
+    if username is not None and password is not None:
+        descriptor["basic_auth"] = [username, password]
+    return descriptor
+
+
+def execute_essearch(
+    ctx: Any,
+    connection: Any = None,
+    index: str | None = None,
+    query: Any = None,
+    size: int | None = None,
+) -> list:
+    """Exécute une recherche et renvoie les documents (``_source`` des hits).
+
+    Args:
+        connection: descripteur issu de :func:`execute_esconnect`.
+        index: index (ou motif d'index) à interroger.
+        query: clause de requête (DSL Elasticsearch) ; ``match_all`` si absente.
+        size: nombre maximum de résultats (défaut du serveur si absent).
+
+    Returns:
+        La liste des ``_source`` des documents trouvés.
+    """
+    if not isinstance(connection, dict) or "hosts" not in connection:
+        raise ValueError("essearch: connection doit être le descripteur de esconnect")
+    if not index:
+        raise ValueError("essearch: index est requis")
+
+    search_kwargs: dict[str, Any] = {"index": index, "query": query or {"match_all": {}}}
+    if size is not None:
+        search_kwargs["size"] = size
+
+    client = _build_client(connection)
+    response = client.search(**search_kwargs)
+    hits = response["hits"]["hits"]
+    return [hit.get("_source") for hit in hits]
+
+
+def register(registry: Any) -> None:
+    """Enregistre les fonctions du plugin dans un registre jslt (entry point)."""
+    registry.register(
+        "esconnect",
+        execute_esconnect,
+        description="Crée un descripteur de connexion Elasticsearch.",
+    )
+    registry.register(
+        "essearch",
+        execute_essearch,
+        description="Recherche Elasticsearch -> liste des documents (_source des hits).",
+    )

urban_json_elastic-0.1.0/src/urban_json_elastic.egg-info/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: urban-json-elastic
+Version: 0.1.0
+Summary: Plugin urban-json : recherche Elasticsearch (esconnect / essearch).
+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,elasticsearch,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 :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: urban-json
+Requires-Dist: elasticsearch>=8
+Dynamic: license-file
+
+# urban-json-elastic
+
+Plugin [urban-json](https://github.com/gaelgael5/Jslt) : recherche **Elasticsearch**
+depuis les templates, via le client officiel `elasticsearch`.
+
+## Installation
+
+```bash
+pip install urban-json-elastic      # tire urban-json et le client elasticsearch
+```
+
+`urban-json` découvre le plugin automatiquement via les entry points (`urban_json.functions`).
+
+## Utilisation
+
+```python
+from urban_json import JsltTemplate
+
+tpl = JsltTemplate.parse('''
+{
+  "es:": esconnect("https://localhost:9200", $.api_key),
+  "docs": [ {
+    "$source": essearch(es:, "products", { "match": { "category": "book" } }, 50),
+    "nom": $.title, "prix": $.price
+  } ]
+}
+''')
+```
+
+- `esconnect(hosts, api_key, username, password, verify_certs)` → descripteur de
+  connexion (à stocker dans une variable).
+- `essearch(connection, index, query, size)` → liste des documents trouvés
+  (le `_source` de chaque hit). `query` est une clause du DSL Elasticsearch
+  (`match_all` si absente).
+
+## Sécurité
+
+`essearch` interroge un cluster Elasticsearch réel. Les identifiants (api_key /
+mot de passe) transitent par le descripteur de connexion : traitez-les comme des
+secrets côté template.
+
+## Licence
+
+Apache-2.0.

urban_json_elastic-0.1.0/src/urban_json_elastic.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/urban_json_elastic/__init__.py
+src/urban_json_elastic/py.typed
+src/urban_json_elastic.egg-info/PKG-INFO
+src/urban_json_elastic.egg-info/SOURCES.txt
+src/urban_json_elastic.egg-info/dependency_links.txt
+src/urban_json_elastic.egg-info/entry_points.txt
+src/urban_json_elastic.egg-info/requires.txt
+src/urban_json_elastic.egg-info/top_level.txt
+tests/test_essearch.py

urban_json_elastic-0.1.0/src/urban_json_elastic.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

urban_json_elastic-0.1.0/src/urban_json_elastic.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[urban_json.functions]
+elastic = urban_json_elastic:register

urban_json_elastic-0.1.0/src/urban_json_elastic.egg-info/requires.txt

@@ -0,0 +1,2 @@
+urban-json
+elasticsearch>=8

urban_json_elastic-0.1.0/src/urban_json_elastic.egg-info/top_level.txt

@@ -0,0 +1 @@
+urban_json_elastic

urban_json_elastic-0.1.0/tests/test_essearch.py

@@ -0,0 +1,99 @@
+"""Tests du plugin urban-json-elastic (``esconnect`` / ``essearch``).
+
+Aucun serveur Elasticsearch requis : on injecte un faux client via le point
+d'injection ``_build_client``. Couvre : descripteur de connexion, recherche +
+extraction des ``_source``, requête par défaut (match_all), paramètre size,
+erreurs, découverte entry point, usage en template.
+"""
+
+from __future__ import annotations
+
+import pytest
+from urban_json import FunctionRegistry, JsltTemplate
+
+import urban_json_elastic
+from urban_json_elastic import execute_esconnect, execute_essearch, register
+
+
+class _FakeClient:
+    def __init__(self, hits):
+        self._hits = hits
+        self.calls = []
+
+    def search(self, **kwargs):
+        self.calls.append(kwargs)
+        return {"hits": {"hits": [{"_source": h} for h in self._hits]}}
+
+
+@pytest.fixture
+def fake_es(monkeypatch):
+    """Installe un faux client ; renvoie l'instance pour inspecter les appels."""
+    client = _FakeClient([{"title": "A", "price": 10}, {"title": "B", "price": 20}])
+    monkeypatch.setattr(urban_json_elastic, "_build_client", lambda connection: client)
+    return client
+
+
+def test_esconnect_descriptor() -> None:
+    cx = execute_esconnect(None, "https://localhost:9200", api_key="k")
+    assert cx == {"hosts": "https://localhost:9200", "verify_certs": True, "api_key": "k"}
+
+
+def test_esconnect_basic_auth() -> None:
+    cx = execute_esconnect(None, "https://es:9200", username="u", password="p")
+    assert cx["basic_auth"] == ["u", "p"]
+
+
+def test_esconnect_requires_hosts() -> None:
+    with pytest.raises(ValueError, match="hosts"):
+        execute_esconnect(None)
+
+
+def test_essearch_returns_sources(fake_es) -> None:
+    cx = {"hosts": "https://es:9200"}
+    docs = execute_essearch(None, cx, "products", {"match": {"category": "book"}})
+    assert docs == [{"title": "A", "price": 10}, {"title": "B", "price": 20}]
+
+
+def test_essearch_default_query_is_match_all(fake_es) -> None:
+    execute_essearch(None, {"hosts": "x"}, "products")
+    assert fake_es.calls[0]["query"] == {"match_all": {}}
+
+
+def test_essearch_passes_index_and_size(fake_es) -> None:
+    execute_essearch(None, {"hosts": "x"}, "products", {"match_all": {}}, size=50)
+    call = fake_es.calls[0]
+    assert call["index"] == "products"
+    assert call["size"] == 50
+
+
+def test_essearch_requires_descriptor() -> None:
+    with pytest.raises(ValueError, match="descripteur"):
+        execute_essearch(None, "nope", "products")
+
+
+def test_essearch_requires_index(fake_es) -> None:
+    with pytest.raises(ValueError, match="index"):
+        execute_essearch(None, {"hosts": "x"}, None)
+
+
+def test_register_into_custom_registry() -> None:
+    reg = FunctionRegistry()
+    register(reg)
+    assert "esconnect" in reg and "essearch" in reg
+
+
+def test_discovered_via_entry_point() -> None:
+    from urban_json import default_registry, load_plugins
+
+    load_plugins(default_registry)
+    assert "esconnect" in default_registry and "essearch" in default_registry
+
+
+def test_in_template(fake_es) -> None:
+    template = (
+        '{ "es:": esconnect("https://es:9200"),'
+        '  "docs": [ { "$source": essearch(es:, "products"), "n": $.title } ] }'
+    )
+    assert JsltTemplate.parse(template).transform({}) == {
+        "docs": [{"n": "A"}, {"n": "B"}]
+    }