exist-shell 0.1.0__py3-none-any.whl

exist_shell/xquery.py

@@ -0,0 +1,267 @@
+"""XQuery preprocessing pipeline and local validator support."""
+
+import shutil
+import subprocess
+import tempfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass
+class ValidatorResult:
+    """Result from a local XQuery validator run.
+
+    Attributes:
+        ok: True if the query is valid (or no validator was found).
+        error: Human-readable error message, or None when ok is True.
+    """
+
+    ok: bool
+    error: str | None
+
+
+class XQueryValidator(Protocol):
+    """Interface that every validator wrapper must implement."""
+
+    name: str
+
+    @classmethod
+    def probe(cls) -> "XQueryValidator | None":
+        """Find the validator binary and return a ready instance, or None if not installed.
+
+        Returns:
+            An initialised validator bound to the discovered binary, or None.
+        """
+        ...
+
+    def validate(self, code: str) -> ValidatorResult:
+        """Validate XQuery source code.
+
+        Args:
+            code: XQuery source code to validate.
+
+        Returns:
+            ValidatorResult with ok=True on success, or ok=False with an error message.
+        """
+        ...
+
+
+class BasexValidator:
+    """Validator wrapper for BaseX (https://basex.org).
+
+    BaseX accepts ``INSPECT XQUERY <file>`` via its command-line client.
+    A parse error causes a non-zero exit code and the error text on stderr.
+    """
+
+    name = "basex"
+
+    def __init__(self, binary: str) -> None:
+        """Initialise with a known-good path to the basex binary."""
+        self._binary = binary
+
+    @classmethod
+    def probe(cls) -> "BasexValidator | None":
+        """Find the basex binary on PATH and return a bound instance, or None.
+
+        Returns:
+            BasexValidator bound to the discovered binary, or None if not found.
+        """
+        binary = shutil.which("basex")
+        return cls(binary) if binary else None
+
+    def validate(self, code: str) -> ValidatorResult:
+        """Validate XQuery by running it through basex in parse-only mode.
+
+        Args:
+            code: XQuery source code to validate.
+
+        Returns:
+            ValidatorResult indicating success or the first reported error.
+        """
+        with tempfile.NamedTemporaryFile(suffix=".xq", delete=False, mode="w", encoding="utf-8") as f:
+            f.write(code)
+            tmp = f.name
+        try:
+            result = subprocess.run(
+                [self._binary, "-c", f"INSPECT XQUERY {tmp}"],
+                capture_output=True,
+                text=True,
+            )
+        finally:
+            Path(tmp).unlink(missing_ok=True)
+        if result.returncode == 0:
+            return ValidatorResult(ok=True, error=None)
+        detail = (result.stderr or result.stdout).strip()
+        return ValidatorResult(ok=False, error=detail or "validation failed")
+
+
+class SaxonValidator:
+    """Validator wrapper for Saxon (https://www.saxonica.com).
+
+    Looks for a ``saxon`` wrapper script on PATH (the standard install name on
+    most package managers).  Saxon is invoked with ``-q:<file>``; a non-zero
+    exit code signals a parse or static error.
+    """
+
+    name = "saxon"
+
+    def __init__(self, binary: str) -> None:
+        """Initialise with a known-good path to the saxon binary."""
+        self._binary = binary
+
+    @classmethod
+    def probe(cls) -> "SaxonValidator | None":
+        """Find the saxon binary on PATH and return a bound instance, or None.
+
+        Returns:
+            SaxonValidator bound to the discovered binary, or None if not found.
+        """
+        binary = shutil.which("saxon")
+        return cls(binary) if binary else None
+
+    def validate(self, code: str) -> ValidatorResult:
+        """Validate XQuery by running it through Saxon.
+
+        Args:
+            code: XQuery source code to validate.
+
+        Returns:
+            ValidatorResult indicating success or the first reported error.
+        """
+        with tempfile.NamedTemporaryFile(suffix=".xq", delete=False, mode="w", encoding="utf-8") as f:
+            f.write(code)
+            tmp = f.name
+        try:
+            result = subprocess.run(
+                [self._binary, f"-q:{tmp}"],
+                capture_output=True,
+                text=True,
+            )
+        finally:
+            Path(tmp).unlink(missing_ok=True)
+        if result.returncode == 0:
+            return ValidatorResult(ok=True, error=None)
+        detail = (result.stderr or result.stdout).strip()
+        return ValidatorResult(ok=False, error=detail or "validation failed")
+
+
+# Registry of known validator classes in preference order.
+_VALIDATORS: list[type[BasexValidator] | type[SaxonValidator]] = [
+    BasexValidator,
+    SaxonValidator,
+]
+
+_VALIDATORS_BY_NAME: dict[str, type[BasexValidator] | type[SaxonValidator]] = {
+    cls.name: cls for cls in _VALIDATORS
+}
+
+
+def list_validators() -> list[tuple[str, str | None]]:
+    """Return each known validator paired with its installed path, or None.
+
+    Returns:
+        List of ``(name, path)`` tuples; path is None when not installed.
+    """
+    return [(cls.name, shutil.which(cls.name)) for cls in _VALIDATORS]
+
+
+def validate_locally(code: str, *, validator: str | None = None) -> ValidatorResult:
+    """Validate XQuery using the first locally available validator.
+
+    When ``validator`` is given, that specific validator is required; the call
+    fails if it is unknown or not installed.  When omitted, the first installed
+    validator in the registry is used.  If none are installed, returns ok=True
+    so the caller can proceed without blocking.
+
+    Args:
+        code: XQuery source code to validate.
+        validator: Name of the validator to use, or None for auto-discovery.
+
+    Returns:
+        ValidatorResult from the chosen or first available validator.
+    """
+    if validator is not None:
+        cls = _VALIDATORS_BY_NAME.get(validator)
+        if cls is None:
+            known = ", ".join(_VALIDATORS_BY_NAME)
+            return ValidatorResult(ok=False, error=f"unknown validator '{validator}'; known: {known}")
+        v = cls.probe()
+        if v is None:
+            return ValidatorResult(ok=False, error=f"validator '{validator}' is not installed")
+        return v.validate(code)
+    for cls in _VALIDATORS:
+        v = cls.probe()
+        if v is not None:
+            return v.validate(code)
+    return ValidatorResult(ok=True, error=None)
+
+
+# ---------------------------------------------------------------------------
+# Preprocessing pipeline
+# ---------------------------------------------------------------------------
+
+
+def _ensure_version(code: str) -> str:
+    """Prepend ``xquery version "3.1";`` if no version declaration is present.
+
+    Args:
+        code: XQuery source code.
+
+    Returns:
+        Code with a version declaration at the top.
+    """
+    if "xquery version" in code.lower():
+        return code
+    return 'xquery version "3.1";\n' + code
+
+
+def _ensure_functx(code: str) -> str:
+    """Add the functx module import when ``functx:`` is used but not declared.
+
+    Args:
+        code: XQuery source code.
+
+    Returns:
+        Code with the functx import inserted after the version declaration,
+        or unchanged if functx is already imported or not referenced.
+    """
+    if "functx:" not in code:
+        return code
+    if "namespace functx" in code:
+        return code
+    # No "at" hint: eXist resolves the module from its package registry by URI.
+    # A file-path hint would override registry lookup and fail unless the file
+    # happens to exist at that path relative to the query context.
+    import_line = 'import module namespace functx = "http://www.functx.com";\n'
+    lines = code.splitlines(keepends=True)
+    for i, line in enumerate(lines):
+        if line.lower().startswith("xquery version"):
+            lines.insert(i + 1, import_line)
+            return "".join(lines)
+    return import_line + code
+
+
+# Ordered list of transformations applied by preprocess().
+_PIPELINE: list[Callable[[str], str]] = [
+    _ensure_version,
+    _ensure_functx,
+]
+
+
+def preprocess(code: str) -> str:
+    """Apply all preprocessing transformations to XQuery source code.
+
+    Transformations are applied in pipeline order.  Each step is a pure
+    ``str -> str`` function.
+
+    Args:
+        code: Raw XQuery source code.
+
+    Returns:
+        Preprocessed XQuery source code.
+    """
+    for step in _PIPELINE:
+        code = step(code)
+    return code

exist_shell-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: exist-shell
+Version: 0.1.0
+Summary: Command-line tool to interact with eXist-db via REST
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.10.0; sys_platform == 'win32'
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: tomlkit>=0.15.0
+Requires-Dist: typer>=0.26.7

exist_shell-0.1.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+exist_shell/__init__.py,sha256=flpc-GRUnIfinblX5UP4xNX8KgBhTfcE2iGysGPSNR8,157
+exist_shell/cache.py,sha256=MDxIG9wEzMek30rI52-WR7DI0NLBpU5e2tzhrEb6Enw,5734
+exist_shell/completions.py,sha256=U8i3-K1-0LOZrQ7PCaGMO6LkGaItWwBmf82aiAmEflQ,7733
+exist_shell/config.py,sha256=_N9X9NOFsP5f-h6q2Mxh7P4XY9iFk3apZFhbNx3LHoI,7580
+exist_shell/exceptions.py,sha256=EpbkKT58LiLOd-meP1e050vnwRDYfwEYgLpVbn5SWSc,2068
+exist_shell/main.py,sha256=g4PjS7HOCgc_17DUbhAIMCuxV5wftm79lNG3klFlhbk,2745
+exist_shell/models.py,sha256=U2R4_m8gZ-A5EIduw1RWiZr1xlK8FwWdsWJnCwKo5dI,1315
+exist_shell/utils.py,sha256=mEex6Ity1MvepAWER3xJ2XLMiieQwMDK-3tg_YaTHTM,5904
+exist_shell/xquery.py,sha256=lTf9dRJ1B9N_6nWiiK2CsGSVaTowysM5xTjnKjh4L5E,8492
+exist_shell/client/__init__.py,sha256=JHAxs_UZBp_JEN_TXwWp4RV-qSL13WK4k4HjYnzRBJM,616
+exist_shell/client/_base.py,sha256=5NfH53K_L2QXMh55DU0znY6ZvYgBCLfayUfrzZ2E9fo,2012
+exist_shell/client/_collections.py,sha256=jQ50CHQTFGN0yTCiQhDuJv6M0-q9LSnDyA1BfRft6EU,6082
+exist_shell/client/_documents.py,sha256=eHJJVvjJsjMD8_wqHfDssuBxKt2Q-hKn6pzE0L-BZFg,5030
+exist_shell/client/_groups.py,sha256=eVdRaz6TdB9E18w0gJauOTcoFliPU9JFBeMN3jBILqQ,4108
+exist_shell/client/_permissions.py,sha256=-Ht2gC8rh5w4MPKTos3xgCJMgi4oFopxgnZsZ5ZECgA,5805
+exist_shell/client/_queries.py,sha256=UG7ljT3iy_n1jyz65_q8JWYvHtVcD6StxxAMOvuZ5p8,1316
+exist_shell/client/_users.py,sha256=ka4DlaSQdmUF1fIm3eHTHjR0S1WaVLWl1XQACc5H4Ss,5825
+exist_shell/commands/__init__.py,sha256=UqPqFwJczCmPqINpy7Ve6f096l4L-s7tnvi_Wht9Q_c,32
+exist_shell/commands/cat.py,sha256=IFpXFyU2vsgvcEUyVzHYCivBnJr06QLyRzW7LAFbcLM,1688
+exist_shell/commands/chmod.py,sha256=nSHd70aDoNTbFrbKY9gV4JTs62H6KpdV7fWrL3-lu4o,8297
+exist_shell/commands/chown.py,sha256=TXcFZ6n5KnZX2o1m3Ep07sTkjEz0MrG90D0fhKOnHag,4614
+exist_shell/commands/collection.py,sha256=psbOkSCR6k1OzS4pLYZTK7UJ2kKW4kmyeZjlIaslBqo,7011
+exist_shell/commands/cp.py,sha256=utSBUHgyI32JjiPgSP67DJdBnX4PkIvxHYIBrhHcwVI,4749
+exist_shell/commands/edit.py,sha256=YoqCwkwaJzGhxv-Hd6_4Jkbn5xiFeGhAdsUvdD5frIY,3011
+exist_shell/commands/exec.py,sha256=KDKYcmZT1Wo3s5-l1Ik_P58qXwhafSHfXNBdjEgtQUE,2549
+exist_shell/commands/group.py,sha256=quHtG-YrA_jFawkb_jS2LrvobX6CNrg3fPvMgYtCEKE,7137
+exist_shell/commands/ls.py,sha256=vbV0v7CY9cubDgLE7V_w71TzTGRrgDIXXQDV_hqbFf0,2593
+exist_shell/commands/mkdir.py,sha256=uEmQwaWdhMi14SFYP8JHFWl5MuiAyhutPGm3CfW9v2E,848
+exist_shell/commands/mv.py,sha256=PtVd0XJE0Rqmae_fEeU9R-sNdsrQqv3Q0NULlScuUcU,4584
+exist_shell/commands/put.py,sha256=xxOG14s4lwsdLYIFwNVG7Dv0QjUJRYKzjrWhZrWT9Wk,2330
+exist_shell/commands/rm.py,sha256=YYbdgEQJL9y9Jx9z-Yo1ZgAMpr2kaNLeH723_Pp2DQ0,854
+exist_shell/commands/server.py,sha256=36cRqH6GIhE2arf-Y794FWoUO61Xh3o9u0KHXnTjiZw,4104
+exist_shell/commands/sync.py,sha256=pYAIEdrg-iJ770pLww57NMTxjqKs_AP9Vez4APe1SDo,27666
+exist_shell/commands/user.py,sha256=ib6fW9s-6bwYRLKHHXHfXfzP8nkiKORVjx3_xwY2S5c,12295
+exist_shell-0.1.0.dist-info/METADATA,sha256=S4EimEwRV-mFlKonz9vr4z0kFklUf0IfuZeP5ktgNF4,321
+exist_shell-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+exist_shell-0.1.0.dist-info/entry_points.txt,sha256=qP6IBfiEW6WXxFDqiTB56DsYAVwIF7nRCluB8iMwta8,46
+exist_shell-0.1.0.dist-info/RECORD,,

exist_shell-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

exist_shell-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+exsh = exist_shell.main:app