exist-shell 0.1.0__tar.gz → 0.1.2__tar.gz

{exist_shell-0.1.0 → exist_shell-0.1.2}/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## unreleased
 
+## 0.1.2 - 2026-06-23
+
+### Documentation
+
+- Document installing `exsh` from PyPI (`uv tool install`, `pipx install`, `uvx --from`); the existing `git+https://...` instructions are kept as an alternative for tracking unreleased commits
+
+## 0.1.1 - 2026-06-23
+
+### Fixes
+
+- Complete PyPI project metadata: `readme`, `license` (MIT), `authors`, `classifiers`, `project.urls`, and `keywords` were all missing, leaving the 0.1.0 PyPI listing with no description, license, or links
+- Add `LICENSE` file (MIT)
+
 ## 0.1.0 - 2026-06-23
 
 ### Commands

exist_shell-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alberto Simões
+
+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.

exist_shell-0.1.2/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.4
+Name: exist-shell
+Version: 0.1.2
+Summary: Command-line tool to interact with eXist-db via REST
+Project-URL: Homepage, https://github.com/ambs/exist-shell
+Project-URL: Repository, https://github.com/ambs/exist-shell
+Project-URL: Documentation, https://ambs.github.io/exist-shell/
+Project-URL: Issues, https://github.com/ambs/exist-shell/issues
+Project-URL: Changelog, https://github.com/ambs/exist-shell/blob/main/CHANGELOG.md
+Author-email: Alberto Simões <ambs@zbr.pt>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,exist-db,xml,xquery
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+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
+Description-Content-Type: text/markdown
+
+# exsh — eXist-db Shell
+
+[![Tests](https://github.com/ambs/exist-shell/actions/workflows/tests.yml/badge.svg)](https://github.com/ambs/exist-shell/actions/workflows/tests.yml)
+[![Coverage](https://codecov.io/gh/ambs/exist-shell/graph/badge.svg)](https://codecov.io/gh/ambs/exist-shell)
+[![e2e](https://github.com/ambs/exist-shell/actions/workflows/e2e.yml/badge.svg)](https://github.com/ambs/exist-shell/actions/workflows/e2e.yml)
+[![Ruff](https://github.com/ambs/exist-shell/actions/workflows/ruff.yml/badge.svg)](https://github.com/ambs/exist-shell/actions/workflows/ruff.yml)
+[![ty](https://github.com/ambs/exist-shell/actions/workflows/ty.yml/badge.svg)](https://github.com/ambs/exist-shell/actions/workflows/ty.yml)
+[![docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://ambs.github.io/exist-shell/)
+
+A command-line tool to interact with an [eXist-db](https://exist-db.org) server via its REST API. Designed for shell scripting and pipe-friendly workflows.
+
+## Requirements
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+
+## Installation
+
+Install system-wide with `uv tool`:
+
+```bash
+uv tool install exist-shell
+```
+
+Or with `pipx`:
+
+```bash
+pipx install exist-shell
+```
+
+This places `exsh` on your `PATH`. Verify with:
+
+```bash
+exsh --version
+```
+
+To uninstall:
+
+```bash
+uv tool uninstall exist-shell
+```
+
+### Run without installing
+
+```bash
+uvx --from exist-shell exsh --version
+```
+
+`uvx` fetches the package into a temporary, cached environment and runs it — handy for one-off use or trying out a new release.
+
+### Install from git
+
+To track an unreleased commit instead of a PyPI release:
+
+```bash
+uv tool install git+https://github.com/ambs/exist-shell
+```
+
+## Configuration
+
+### Add a server
+
+```bash
+exsh server add localhost --port 8080 --user admin
+```
+
+A nickname is derived from the hostname by default (e.g. `localhost`). Override with `--nick`.
+
+### Add an existing collection
+
+```bash
+exsh collection add mydata@localhost
+```
+
+This registers the `/db/mydata` collection on the `localhost` server under the nick `mydata`.
+
+### Create and register a new collection
+
+```bash
+exsh collection new mydata@localhost
+```
+
+Creates `/db/mydata` on the server and registers it in one step. If the collection already exists, it prints a message and exits without modifying the config. Use `--nick` to register it under a different name:
+
+```bash
+exsh collection new mydata@localhost --nick md
+```
+
+List configured servers and collections:
+
+```bash
+exsh server ls
+exsh collection ls
+```
+
+Configuration is stored at `~/.config/exsh/config.toml`.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `exsh ls <nick>[:<path>]` | List subcollections and documents at a path |
+| `exsh cat <nick>:<path>` | Print a document to stdout |
+| `exsh put <file> <nick>:<path>` | Upload a local file to a collection |
+| `exsh cp <src> <dst>` | Copy a document (local ↔ remote or remote ↔ remote) |
+| `exsh edit <nick>:<path>` | Open a document in `$EDITOR`, re-upload if changed |
+| `exsh rm <nick>:<path>...` | Delete one or more documents |
+| `exsh mkdir <nick>:<path>` | Create a collection |
+| `exsh sync <local> <nick>[:<path>]` | Push a local folder to a remote collection |
+| `exsh sync <nick>[:<path>] <local>` | Pull a remote collection to a local folder |
+| `exsh exec <nick>[:<path>]` | Execute an XQuery script on a server |
+| `exsh server add <host>` | Register a server |
+| `exsh server ls` | List registered servers |
+| `exsh server rm <nick>` | Remove a server (and its collections) |
+| `exsh server rename <old> <new>` | Rename a server nick (updates collection references) |
+| `exsh collection add <name>[@<server>]` | Register an existing collection |
+| `exsh collection new <name>[@<server>]` | Create a collection on the server and register it |
+| `exsh collection ls` | List registered collections |
+| `exsh collection rm <nick>` | Remove a collection from the config |
+| `exsh user ls [@server]` | List user accounts and their groups |
+| `exsh user add <user[@server]>` | Create a user account (prompts for password) |
+| `exsh user rm <user[@server]>` | Remove a user account |
+| `exsh user info <user[@server]>` | Show user account details |
+| `exsh group ls [@server]` | List groups and their members |
+| `exsh group add <group[@server]>` | Create a group |
+| `exsh group rm <group[@server]>` | Remove a group |
+| `exsh chown <spec> <nick>:<path>` | Change owner and/or group of a document or collection |
+| `exsh chmod <mode> <nick>:<path>` | Change POSIX permissions of a document or collection |
+
+### Examples
+
+```bash
+# List the root of a collection
+exsh ls mydata
+
+# List a subdirectory
+exsh ls mydata:reports/2025
+
+# Print a document
+exsh cat mydata:reports/2025/summary.xml
+
+# Upload a file
+exsh put report.xml mydata:reports/2025/report.xml
+
+# Copy from remote to local
+exsh cp mydata:reports/2025/report.xml ./report.xml
+
+# Edit in place
+exsh edit mydata:reports/2025/report.xml
+
+# Delete a document
+exsh rm mydata:reports/2025/old.xml
+
+# Delete multiple documents
+exsh rm mydata:reports/2025/a.xml mydata:reports/2025/b.xml
+
+# Create a subcollection
+exsh mkdir mydata:reports/2026
+
+# Execute an XQuery script from a file
+exsh exec mydata:/ -f query.xq
+
+# Execute an XQuery script from stdin
+echo 'count(collection("/db/mydata"))' | exsh exec mydata:/
+
+# Execute without local preprocessing
+exsh exec mydata:/ --no-fix -f query.xq
+
+# List locally available XQuery validators
+exsh exec --list-validators
+
+# Push a local folder to the server (only transfers changed files)
+exsh sync ./reports mydata:reports
+
+# Pull a remote collection to a local folder
+exsh sync mydata:reports ./reports
+
+# Preview what would be transferred without doing it
+exsh sync --dry-run ./reports mydata:reports
+
+# Push and remove files on the server that no longer exist locally
+exsh sync --delete ./reports mydata:reports
+
+# Change owner and group of a document
+exsh chown alice:editors mydata:reports/annual.xml
+
+# Recursively reassign a collection tree
+exsh chown -R alice mydata:reports
+
+# Set permissions with octal mode
+exsh chmod 0644 mydata:reports/annual.xml
+
+# Add execute permission for the owner
+exsh chmod u+x mydata:scripts/run.xq
+
+# Recursively set permissions for a collection
+exsh chmod -R 0644 mydata:data
+```
+
+## Sync
+
+`exsh sync` transfers only files that have changed, using a local manifest stored at `~/.cache/exsh/sync/`. Direction is inferred from the argument order: local-first means push, remote-first means pull.
+
+**Change detection:**
+- **Push**: SHA-256 hash of the local file is compared against the manifest. Same-size edits are caught.
+- **Pull**: `last_modified` timestamp from the eXist listing is compared against the manifest.
+
+**Conflicts** (both sides changed since last sync) are reported and skipped — use `--force` to override.
+
+**Options:**
+
+| Flag | Effect |
+|------|--------|
+| `--force` / `-f` | Transfer all files, bypassing change detection |
+| `--dry-run` / `-n` | Show what would happen without transferring |
+| `--delete` | Remove files and empty folders on the destination that no longer exist on the source |
+| `--verbose` / `-v` | Also print unchanged (skipped) files |
+| `--checkpoint-every N` | Flush the manifest every N files (default: 100); allows interrupted syncs to resume near the point of failure |
+
+## Shell completion
+
+Generate and install tab-completion for your shell:
+
+```bash
+# bash
+exsh --install-completion bash
+
+# zsh
+exsh --install-completion zsh
+
+# fish
+exsh --install-completion fish
+```
+
+## Development
+
+```bash
+git clone https://github.com/ambs/exist-shell
+cd exist-shell
+uv sync
+exsh --help
+```
+
+Run checks:
+
+```bash
+make checks   # lint, type-check, and tests
+make test     # tests only
+```

{exist_shell-0.1.0 → exist_shell-0.1.2}/README.md

@@ -19,7 +19,13 @@ A command-line tool to interact with an [eXist-db](https://exist-db.org) server
 Install system-wide with `uv tool`:
 
 ```bash
-uv tool install git+https://github.com/ambs/exist-shell
+uv tool install exist-shell
+```
+
+Or with `pipx`:
+
+```bash
+pipx install exist-shell
 ```
 
 This places `exsh` on your `PATH`. Verify with:
@@ -34,6 +40,22 @@ To uninstall:
 uv tool uninstall exist-shell
 ```
 
+### Run without installing
+
+```bash
+uvx --from exist-shell exsh --version
+```
+
+`uvx` fetches the package into a temporary, cached environment and runs it — handy for one-off use or trying out a new release.
+
+### Install from git
+
+To track an unreleased commit instead of a PyPI release:
+
+```bash
+uv tool install git+https://github.com/ambs/exist-shell
+```
+
 ## Configuration
 
 ### Add a server

{exist_shell-0.1.0 → exist_shell-0.1.2}/docs/api.md

@@ -4,6 +4,14 @@
 
 ## Installation
 
+```bash
+pip install exist-shell
+# or with uv
+uv add exist-shell
+```
+
+To track an unreleased commit instead of a PyPI release:
+
 ```bash
 pip install git+https://github.com/ambs/exist-shell
 # or with uv

{exist_shell-0.1.0 → exist_shell-0.1.2}/docs/index.md

@@ -21,7 +21,7 @@
 
 ```bash
 # 1. Install
-uv tool install git+https://github.com/ambs/exist-shell
+uv tool install exist-shell
 
 # 2. Register your server
 exsh server add localhost --port 8080 --user admin

{exist_shell-0.1.0 → exist_shell-0.1.2}/docs/installation.md

@@ -7,10 +7,16 @@
 
 ## Install as a tool
 
-The recommended way is to install `exsh` as a uv tool so it is available system-wide:
+The recommended way is to install `exsh` from PyPI as a uv tool so it is available system-wide:
 
 ```bash
-uv tool install git+https://github.com/ambs/exist-shell
+uv tool install exist-shell
+```
+
+Or with `pipx`:
+
+```bash
+pipx install exist-shell
 ```
 
 Verify the installation:
@@ -19,6 +25,14 @@ Verify the installation:
 exsh --version
 ```
 
+## Run without installing
+
+```bash
+uvx --from exist-shell exsh --version
+```
+
+`uvx` runs the command in a temporary, cached environment without installing it permanently — useful for trying out `exsh` or running a one-off command.
+
 ## Upgrade
 
 ```bash
@@ -31,6 +45,14 @@ uv tool upgrade exist-shell
 uv tool uninstall exist-shell
 ```
 
+## Install from git
+
+To install an unreleased commit instead of the latest PyPI release:
+
+```bash
+uv tool install git+https://github.com/ambs/exist-shell
+```
+
 ## Install from a local clone
 
 If you want to develop or test from source:

exist_shell-0.1.2/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "exist-shell"
+version = "0.1.2"
+description = "Command-line tool to interact with eXist-db via REST"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Alberto Simões", email = "ambs@zbr.pt" },
+]
+keywords = ["exist-db", "xml", "xquery", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Utilities",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.26.7",
+    "httpx>=0.27",
+    "pydantic>=2.13.4",
+    "tomlkit>=0.15.0",
+    "platformdirs>=4.10.0; sys_platform == 'win32'",
+]
+
+[project.urls]
+Homepage = "https://github.com/ambs/exist-shell"
+Repository = "https://github.com/ambs/exist-shell"
+Documentation = "https://ambs.github.io/exist-shell/"
+Issues = "https://github.com/ambs/exist-shell/issues"
+Changelog = "https://github.com/ambs/exist-shell/blob/main/CHANGELOG.md"
+
+[project.scripts]
+exsh = "exist_shell.main:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/exist_shell"]
+
+[tool.ruff.lint]
+select = ["D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "pytest-httpx>=0.30",
+    "ruff>=0.15.16",
+    "ty>=0.0.46",
+]

{exist_shell-0.1.0 → exist_shell-0.1.2}/uv.lock

@@ -157,7 +157,7 @@ toml = [
 
 [[package]]
 name = "exist-shell"
-version = "0.1.0"
+version = "0.1.2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

exist_shell-0.1.0/PKG-INFO

@@ -1,10 +0,0 @@
-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/pyproject.toml

@@ -1,37 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "exist-shell"
-version = "0.1.0"
-description = "Command-line tool to interact with eXist-db via REST"
-requires-python = ">=3.11"
-dependencies = [
-    "typer>=0.26.7",
-    "httpx>=0.27",
-    "pydantic>=2.13.4",
-    "tomlkit>=0.15.0",
-    "platformdirs>=4.10.0; sys_platform == 'win32'",
-]
-
-[project.scripts]
-exsh = "exist_shell.main:app"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/exist_shell"]
-
-[tool.ruff.lint]
-select = ["D"]
-
-[tool.ruff.lint.pydocstyle]
-convention = "google"
-
-[dependency-groups]
-dev = [
-    "pytest>=8",
-    "pytest-cov>=5",
-    "pytest-httpx>=0.30",
-    "ruff>=0.15.16",
-    "ty>=0.0.46",
-]