exist-shell 0.1.0__py3-none-any.whl

exist_shell/__init__.py

@@ -0,0 +1,5 @@
+"""eXist-db shell — command-line tool to interact with eXist-db via REST."""
+
+from importlib.metadata import version
+
+__version__ = version("exist-shell")

exist_shell/cache.py

@@ -0,0 +1,186 @@
+"""File-based TTL cache for shell completion listings."""
+
+import hashlib
+import json
+import time
+from pathlib import Path
+
+from exist_shell.config import Config
+from exist_shell.models import CollectionEntry, CollectionItem, GroupEntry, ResourceEntry, UserEntry
+
+CACHE_TTL = 5.0
+SERVER_CACHE_TTL = 60.0
+
+
+def _get_cache_dir() -> Path:
+    """Return the completions cache directory, resolved from the active config.
+
+    Returns:
+        Path to the completions cache directory.
+    """
+    return Config.load().resolved_cache_dir() / "completions"
+
+
+def _cache_path(nick: str, dir_path: str) -> Path:
+    """Return the cache file path for a (nick, dir_path) pair.
+
+    Args:
+        nick: Collection nick name.
+        dir_path: Directory path within the collection (e.g. ``/books/``).
+
+    Returns:
+        Path to the cache file.
+    """
+    digest = hashlib.sha256(dir_path.encode()).hexdigest()[:16]
+    return _get_cache_dir() / f"{nick}@{digest}.json"
+
+
+def get_cached(nick: str, dir_path: str) -> list[CollectionItem] | None:
+    """Return a cached directory listing if it exists and is still fresh.
+
+    Args:
+        nick: Collection nick name.
+        dir_path: Directory path within the collection.
+
+    Returns:
+        List of ``CollectionItem`` objects, or ``None`` on cache miss or expiry.
+    """
+    path = _cache_path(nick, dir_path)
+    try:
+        data = json.loads(path.read_text())
+        if time.time() - data["ts"] > CACHE_TTL:
+            return None
+        items: list[CollectionItem] = []
+        for raw in data["items"]:
+            kind = raw.pop("kind")
+            if kind == "collection":
+                items.append(CollectionEntry.model_validate(raw))
+            else:
+                items.append(ResourceEntry.model_validate(raw))
+        return items
+    except Exception:
+        return None
+
+
+def set_cached(nick: str, dir_path: str, items: list[CollectionItem]) -> None:
+    """Write a directory listing to the cache atomically.
+
+    Args:
+        nick: Collection nick name.
+        dir_path: Directory path within the collection.
+        items: List of ``CollectionItem`` objects to cache.
+    """
+    try:
+        _get_cache_dir().mkdir(parents=True, exist_ok=True)
+        serialized = []
+        for item in items:
+            d = item.model_dump()
+            d["kind"] = "collection" if isinstance(item, CollectionEntry) else "resource"
+            serialized.append(d)
+        payload = json.dumps({"ts": time.time(), "items": serialized})
+        cache_path = _cache_path(nick, dir_path)
+        tmp = cache_path.with_suffix(".tmp")
+        tmp.write_text(payload)
+        tmp.rename(cache_path)
+    except Exception:
+        pass
+
+
+def _server_cache_path(server_nick: str, kind: str) -> Path:
+    """Return the cache file path for a (server_nick, kind) pair.
+
+    Args:
+        server_nick: Server nick name.
+        kind: Data kind — ``"users"`` or ``"groups"``.
+
+    Returns:
+        Path to the cache file.
+    """
+    return _get_cache_dir() / f"{server_nick}@{kind}.json"
+
+
+def get_cached_users(server_nick: str) -> list[UserEntry] | None:
+    """Return a cached user list if it exists and is still fresh.
+
+    Args:
+        server_nick: Server nick name.
+
+    Returns:
+        List of ``UserEntry`` objects, or ``None`` on cache miss or expiry.
+    """
+    path = _server_cache_path(server_nick, "users")
+    try:
+        data = json.loads(path.read_text())
+        if time.time() - data["ts"] > SERVER_CACHE_TTL:
+            return None
+        return [UserEntry.model_validate(u) for u in data["items"]]
+    except Exception:
+        return None
+
+
+def set_cached_users(server_nick: str, users: list[UserEntry]) -> None:
+    """Write a user list to the cache atomically.
+
+    Args:
+        server_nick: Server nick name.
+        users: List of ``UserEntry`` objects to cache.
+    """
+    try:
+        _get_cache_dir().mkdir(parents=True, exist_ok=True)
+        payload = json.dumps({"ts": time.time(), "items": [u.model_dump() for u in users]})
+        cache_path = _server_cache_path(server_nick, "users")
+        tmp = cache_path.with_suffix(".tmp")
+        tmp.write_text(payload)
+        tmp.rename(cache_path)
+    except Exception:
+        pass
+
+
+def get_cached_groups(server_nick: str) -> list[GroupEntry] | None:
+    """Return a cached group list if it exists and is still fresh.
+
+    Args:
+        server_nick: Server nick name.
+
+    Returns:
+        List of ``GroupEntry`` objects, or ``None`` on cache miss or expiry.
+    """
+    path = _server_cache_path(server_nick, "groups")
+    try:
+        data = json.loads(path.read_text())
+        if time.time() - data["ts"] > SERVER_CACHE_TTL:
+            return None
+        return [GroupEntry.model_validate(g) for g in data["items"]]
+    except Exception:
+        return None
+
+
+def set_cached_groups(server_nick: str, groups: list[GroupEntry]) -> None:
+    """Write a group list to the cache atomically.
+
+    Args:
+        server_nick: Server nick name.
+        groups: List of ``GroupEntry`` objects to cache.
+    """
+    try:
+        _get_cache_dir().mkdir(parents=True, exist_ok=True)
+        payload = json.dumps({"ts": time.time(), "items": [g.model_dump() for g in groups]})
+        cache_path = _server_cache_path(server_nick, "groups")
+        tmp = cache_path.with_suffix(".tmp")
+        tmp.write_text(payload)
+        tmp.rename(cache_path)
+    except Exception:
+        pass
+
+
+def invalidate(nick: str) -> None:
+    """Delete all cached listings for the given nick.
+
+    Args:
+        nick: Collection nick name whose cache entries should be removed.
+    """
+    try:
+        for f in _get_cache_dir().glob(f"{nick}@*.json"):
+            f.unlink(missing_ok=True)
+    except Exception:
+        pass

exist_shell/client/__init__.py

@@ -0,0 +1,19 @@
+"""HTTP client for the eXist-db REST API."""
+
+from exist_shell.client._collections import CollectionMixin
+from exist_shell.client._documents import DocumentMixin
+from exist_shell.client._groups import GroupMixin
+from exist_shell.client._permissions import PermissionMixin
+from exist_shell.client._users import UserMixin
+
+
+class ExistClient(CollectionMixin, DocumentMixin, UserMixin, GroupMixin, PermissionMixin):
+    """HTTP client scoped to a single eXist-db server.
+
+    Args:
+        server: The server configuration to connect to.
+        timeout: Request timeout in seconds.
+    """
+
+
+__all__ = ["ExistClient"]

exist_shell/client/_base.py

@@ -0,0 +1,65 @@
+"""Base HTTP client — connection setup and low-level helpers."""
+
+from typing import Self
+from urllib.parse import quote
+
+import httpx
+
+from exist_shell.config import Server
+from exist_shell.exceptions import ExistAuthError, ExistConnectionError
+
+
+class ExistClientBase:
+    """Core HTTP plumbing shared by all domain mixins.
+
+    Args:
+        server: The server configuration to connect to.
+        timeout: Request timeout in seconds.
+    """
+
+    def __init__(self, server: Server, timeout: float = 30.0) -> None:
+        """Initialize the client and open an HTTP connection."""
+        self._base = f"http://{server.host}:{server.port}/exist"
+        self._http = httpx.Client(
+            auth=(server.user, server.password.get_secret_value()),
+            timeout=timeout,
+        )
+
+    def _url(self, path: str) -> str:
+        """Build a percent-encoded REST URL for the given eXist path.
+
+        Args:
+            path: Full eXist path starting with /db/ (e.g. /db/myapp/doc.xml).
+
+        Returns:
+            Absolute URL safe to pass to httpx.
+        """
+        return f"{self._base}/rest{quote(path, safe='/')}"
+
+    def check_connection(self) -> None:
+        """Verify connectivity and credentials against the server.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+        """
+        url = f"{self._base}/rest/db"
+        try:
+            r = self._http.get(url)
+        except httpx.RequestError as e:
+            raise ExistConnectionError(url, e) from e
+        if r.status_code == 401:
+            raise ExistAuthError(url)
+        r.raise_for_status()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection."""
+        self._http.close()
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        """Exit the context manager and close the connection."""
+        self.close()

exist_shell/client/_collections.py

@@ -0,0 +1,158 @@
+"""Collections mixin — collection-level operations."""
+
+import xml.etree.ElementTree as ET
+
+import httpx
+
+from exist_shell.client._queries import QueryMixin
+from exist_shell.exceptions import ExistAuthError, ExistConnectionError, ExistNotFoundError, ExistQueryError
+from exist_shell.models import CollectionEntry, CollectionItem, ResourceEntry
+
+_EXIST_NS = "http://exist.sourceforge.net/NS/exist"
+
+
+class CollectionMixin(QueryMixin):
+    """Mixin providing collection-level operations against the eXist REST API."""
+
+    def collection_exists(self, name: str) -> bool:
+        """Check whether a top-level collection exists under /db/.
+
+        Args:
+            name: Collection name (without the /db/ prefix).
+
+        Returns:
+            True if the collection exists, False if 404.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+        """
+        url = self._url(f"/db/{name}")
+        try:
+            r = self._http.get(url)
+        except httpx.RequestError as e:
+            raise ExistConnectionError(url, e) from e
+        if r.status_code == 401:
+            raise ExistAuthError(url)
+        return r.status_code in (200, 207)
+
+    def list_collection(self, path: str) -> list[CollectionItem]:
+        """List subcollections and resources at the given eXist path.
+
+        Args:
+            path: Full eXist path starting with /db/ (e.g. /db/myapp/sub).
+
+        Returns:
+            Ordered list of CollectionEntry and ResourceEntry objects.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistNotFoundError: If the path does not exist.
+        """
+        url = self._url(path)
+        try:
+            r = self._http.get(url)
+        except httpx.RequestError as e:
+            raise ExistConnectionError(url, e) from e
+        if r.status_code == 401:
+            raise ExistAuthError(url)
+        if r.status_code == 404:
+            raise ExistNotFoundError(path)
+        r.raise_for_status()
+        items: list[CollectionItem] = []
+        root = ET.fromstring(r.text)
+        col = root.find(f"{{{_EXIST_NS}}}collection")
+        if col is not None:
+            for el in col.findall(f"{{{_EXIST_NS}}}collection"):
+                items.append(CollectionEntry(
+                    name=el.get("name", ""),
+                    created=el.get("created"),
+                    owner=el.get("owner"),
+                    group=el.get("group"),
+                    permissions=el.get("permissions"),
+                ))
+            for el in col.findall(f"{{{_EXIST_NS}}}resource"):
+                items.append(ResourceEntry(
+                    name=el.get("name", ""),
+                    created=el.get("created"),
+                    last_modified=el.get("last-modified"),
+                    owner=el.get("owner"),
+                    group=el.get("group"),
+                    permissions=el.get("permissions"),
+                    size=int(el.get("size", 0)) or None,
+                    mime_type=el.get("mime-type"),
+                ))
+        return items
+
+    def create_collection(self, path: str) -> None:
+        """Create a collection at the given eXist path.
+
+        Intermediate collections are created automatically if they do not exist.
+
+        Args:
+            path: Full eXist path starting with /db/ (e.g. /db/myapp/newcoll).
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistNotFoundError: If the collection cannot be created.
+        """
+        clean = path.rstrip("/")
+        # fold-left walks each path segment from /db downward, threading the
+        # parent path as the accumulator. xmldb:create-collection is idempotent
+        # (existing collections return their path without error), so intermediate
+        # levels are created only when missing. [1] keeps the path string and
+        # discards the create-collection return value from the sequence.
+        query = (
+            'xquery version "3.1"; '
+            f'let $parts := tokenize("{clean}", "/")[. != ""] '
+            "let $_ := fold-left(tail($parts), \"/\" || head($parts), function($parent, $seg) { "
+            "  let $new := $parent || \"/\" || $seg "
+            "  return ($new, xmldb:create-collection($parent, $seg))[1] "
+            "}) "
+            "return ()"
+        )
+        try:
+            self.execute_query(query, context="/db")
+        except ExistQueryError:
+            raise ExistNotFoundError(path)
+
+    def delete_collection(self, path: str) -> None:
+        """Delete an empty collection at the given eXist path.
+
+        Args:
+            path: Full eXist path starting with /db/ (e.g. /db/myapp/subcol).
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistNotFoundError: If the path does not exist.
+        """
+        url = self._url(path)
+        try:
+            r = self._http.delete(url)
+        except httpx.RequestError as e:
+            raise ExistConnectionError(url, e) from e
+        if r.status_code == 401:
+            raise ExistAuthError(url)
+        if r.status_code == 404:
+            raise ExistNotFoundError(path)
+        r.raise_for_status()
+
+    def is_collection(self, path: str) -> bool:
+        """Return True if path is an existing collection, False if it is a document or absent.
+
+        Args:
+            path: Full eXist path starting with /db/ (e.g. /db/myapp/sub).
+
+        Returns:
+            True when a collection exists at that path, False otherwise.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+        """
+        query = f'xquery version "3.1"; xmldb:collection-available("{path}")'
+        result = self.execute_query(query)
+        return result.strip() == "true"

exist_shell/client/_documents.py

@@ -0,0 +1,134 @@
+"""Documents mixin — document-level operations."""
+
+from pathlib import PurePosixPath
+
+import httpx
+
+from exist_shell.client._queries import QueryMixin
+from exist_shell.exceptions import ExistAuthError, ExistConnectionError, ExistNotFoundError, ExistQueryError
+from exist_shell.models import DocumentResult
+
+
+class DocumentMixin(QueryMixin):
+    """Mixin providing document-level operations against the eXist REST API."""
+
+    def get_document(self, path: str) -> DocumentResult:
+        """Retrieve a document's raw bytes and declared MIME type.
+
+        Args:
+            path: Full eXist path starting with /db/ (e.g. /db/myapp/doc.xml).
+
+        Returns:
+            DocumentResult with the raw content bytes and MIME type string.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistNotFoundError: If the path does not exist.
+        """
+        url = self._url(path)
+        try:
+            r = self._http.get(url)
+        except httpx.RequestError as e:
+            raise ExistConnectionError(url, e) from e
+        if r.status_code == 401:
+            raise ExistAuthError(url)
+        if r.status_code == 404:
+            raise ExistNotFoundError(path)
+        r.raise_for_status()
+        mime_type = r.headers.get("content-type", "application/octet-stream").split(";")[0].strip()
+        return DocumentResult(content=r.content, mime_type=mime_type)
+
+    def put_document(self, path: str, content: bytes, mime_type: str) -> None:
+        """Store a document at the given eXist path.
+
+        Args:
+            path: Full eXist path starting with /db/ (e.g. /db/myapp/doc.xml).
+            content: Raw document bytes.
+            mime_type: MIME type sent as the Content-Type header.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistNotFoundError: If the parent collection does not exist.
+        """
+        url = self._url(path)
+        try:
+            r = self._http.put(url, content=content, headers={"Content-Type": mime_type})
+        except httpx.RequestError as e:
+            raise ExistConnectionError(url, e) from e
+        if r.status_code == 401:
+            raise ExistAuthError(url)
+        if r.status_code == 404:
+            raise ExistNotFoundError(path)
+        r.raise_for_status()
+
+    def delete_document(self, path: str) -> None:
+        """Delete a document at the given eXist path.
+
+        Args:
+            path: Full eXist path starting with /db/ (e.g. /db/myapp/doc.xml).
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistNotFoundError: If the path does not exist.
+        """
+        url = self._url(path)
+        try:
+            r = self._http.delete(url)
+        except httpx.RequestError as e:
+            raise ExistConnectionError(url, e) from e
+        if r.status_code == 401:
+            raise ExistAuthError(url)
+        if r.status_code == 404:
+            raise ExistNotFoundError(path)
+        r.raise_for_status()
+
+    def move_document(self, src_path: str, dst_path: str) -> None:
+        """Move or rename a single document using XQuery.
+
+        Selects the most efficient XQuery call based on the relationship
+        between source and destination:
+
+        - Same parent → ``xmldb:rename``
+        - Different parent, same name → ``xmldb:move``
+        - Different parent, different name → ``xmldb:move`` then ``xmldb:rename``
+
+        Args:
+            src_path: Full eXist path of the source document.
+            dst_path: Full eXist path of the destination document.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistNotFoundError: If the source or destination parent does not exist.
+        """
+        src = PurePosixPath(src_path.rstrip("/"))
+        dst = PurePosixPath(dst_path.rstrip("/"))
+        src_parent = str(src.parent)
+        src_name = src.name
+        dst_parent = str(dst.parent)
+        dst_name = dst.name
+
+        if src_parent == dst_parent:
+            query = (
+                f'xquery version "3.1"; '
+                f'xmldb:rename("{src_parent}", "{src_name}", "{dst_name}")'
+            )
+        elif src_name == dst_name:
+            query = (
+                f'xquery version "3.1"; '
+                f'xmldb:move("{src_parent}", "{dst_parent}", "{src_name}")'
+            )
+        else:
+            query = (
+                f'xquery version "3.1"; '
+                f'let $_ := xmldb:move("{src_parent}", "{dst_parent}", "{src_name}") '
+                f'return xmldb:rename("{dst_parent}", "{src_name}", "{dst_name}")'
+            )
+
+        try:
+            self.execute_query(query)
+        except ExistQueryError as e:
+            raise ExistNotFoundError(src_path) from e

exist_shell/client/_groups.py

@@ -0,0 +1,116 @@
+"""Groups mixin — group management operations."""
+
+import xml.etree.ElementTree as ET
+
+from exist_shell.client._queries import QueryMixin
+from exist_shell.models import GroupEntry
+from exist_shell.utils import xq_escape
+
+
+class GroupMixin(QueryMixin):
+    """Mixin providing group management operations against the eXist REST API."""
+
+    def list_groups(self) -> list[GroupEntry]:
+        """List all groups and their members.
+
+        Returns:
+            List of GroupEntry objects sorted alphabetically by group name.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the XQuery fails.
+        """
+        query = (
+            'xquery version "3.1"; '
+            '<groups>{ '
+            'for $g in sm:list-groups() '
+            'let $members := sm:get-group-members($g) '
+            'order by $g '
+            'return <group name="{$g}" members="{string-join($members, ",")}"/> '
+            '}</groups>'
+        )
+        raw = self.execute_query(query)
+        root = ET.fromstring(raw)
+        result: list[GroupEntry] = []
+        for el in root.findall("group"):
+            members_str = el.get("members", "")
+            members = [m for m in members_str.split(",") if m]
+            result.append(GroupEntry(name=el.get("name", ""), members=members))
+        return result
+
+    def group_exists(self, groupname: str) -> bool:
+        """Check whether a group exists on the server.
+
+        Args:
+            groupname: The group name to check.
+
+        Returns:
+            True if the group exists, False otherwise.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the query fails.
+        """
+        safe = xq_escape(groupname)
+        query = f'xquery version "3.1"; sm:group-exists("{safe}")'
+        return self.execute_query(query).strip() == "true"
+
+    def get_group_members(self, groupname: str) -> list[str]:
+        """Return the list of members belonging to a group.
+
+        Args:
+            groupname: The group name to look up.
+
+        Returns:
+            List of member usernames belonging to the group.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the group does not exist or the query fails.
+        """
+        safe = xq_escape(groupname)
+        query = (
+            'xquery version "3.1"; '
+            f'if (not(sm:group-exists("{safe}"))) '
+            f'then error((), "Group not found: {safe}") '
+            f'else '
+            f'let $members := sm:get-group-members("{safe}") '
+            f'return <members>{{string-join($members, ",")}}</members>'
+        )
+        raw = self.execute_query(query)
+        el = ET.fromstring(raw)
+        members_str = el.text or ""
+        return [m for m in members_str.split(",") if m]
+
+    def create_group(self, groupname: str) -> None:
+        """Create a new group.
+
+        Args:
+            groupname: The group name to create.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the group already exists or the query fails.
+        """
+        safe = xq_escape(groupname)
+        query = f'xquery version "3.1"; sm:create-group("{safe}")'
+        self.execute_query(query)
+
+    def delete_group(self, groupname: str) -> None:
+        """Remove a group from the server.
+
+        Args:
+            groupname: The group name to remove.
+
+        Raises:
+            ExistConnectionError: If the server cannot be reached.
+            ExistAuthError: If the server returns HTTP 401.
+            ExistQueryError: If the group does not exist or the query fails.
+        """
+        safe = xq_escape(groupname)
+        query = f'xquery version "3.1"; sm:remove-group("{safe}")'
+        self.execute_query(query)