solrctl 0.5.0__tar.gz

solrctl-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Baer, Sächsische Landesbibliothek - Staats- und Universitätsbibliothek Dresden (SLUB)
+
+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.

solrctl-0.5.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: solrctl
+Version: 0.5.0
+Summary: CLI-Tool zur Verwaltung von Apache Solr 9.x – Cores tauschen, Status abfragen, Konfiguration einsehen
+Author-email: Thomas Baer <thomas.baer@slub-dresden.de>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+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 :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Dist: click>=8.1
+Requires-Dist: loguru>=0.7
+Provides-Extra: prefect
+Requires-Dist: prefect==3.6.19; extra == "prefect"
+Requires-Dist: python-dotenv>=1.0; extra == "prefect"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-env>=1.1; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: pysolr>=3.10; extra == "dev"
+Dynamic: license-file
+
+# solrctl
+
+CLI-Tool zur Verwaltung von Apache Solr 9.x – ohne Downtime Cores tauschen, Status abfragen, Konfiguration einsehen.
+
+## Installation
+
+```bash
+uv tool install solrctl
+```
+
+Oder aus dem Checkout:
+
+```bash
+uv pip install -e .
+```
+
+## CLI-Befehle
+
+```bash
+# Solr erreichbar?
+solrctl ping
+
+# Cores anzeigen
+solrctl core list
+
+# Core-Infos (Pfade, Dokumentanzahl, Größe)
+solrctl core info <name>
+
+# solrconfig.xml abrufen
+solrctl core config <name>
+
+# Schema als XML abrufen
+solrctl core schema <name>
+
+# Core-Swap (unterbrechungsfrei)
+solrctl core swap --source <neuer_core> --target <aktiver_core>
+
+# Core löschen
+solrctl core delete <name> [--delete-index]
+
+# Alias-Operationen (SolrCloud)
+solrctl alias list
+solrctl alias swap --alias <name> --collection <ziel>
+solrctl alias delete <name>
+```
+
+Alle Befehle akzeptieren globale Optionen:
+
+```bash
+--solr-url   Basis-URL der Solr-Instanz (Default: http://localhost:8983, Env: SOLR_URL)
+--user       Basic-Auth Benutzername (Env: SOLR_USER)
+--password   Basic-Auth Passwort (Env: SOLR_PASSWORD)
+```
+
+## Voraussetzungen
+
+- Python 3.11+
+- Zugriff auf eine Solr 9.x Instanz (Standalone für Core-Befehle, SolrCloud für Alias-Befehle)
+
+## Lokale Entwicklung
+
+```bash
+# Abhängigkeiten inkl. Dev- und Prefect-Extras installieren
+uv sync --all-extras
+
+# Tests ausführen
+uv run pytest
+
+# CLI lokal ausführen
+uv run solrctl --help
+```
+
+### Docker-basiertes Test-Setup
+
+```bash
+docker compose up -d
+solrctl --solr-url http://localhost:8983 ping
+```
+
+## Prefect-Integration
+
+solrctl liefert optionale Prefect-Tasks und -Flows für automatisierte Pipelines. Die Prefect-Abhängigkeiten werden nicht standardmäßig installiert:
+
+```bash
+uv pip install -e ".[prefect]"
+```
+
+Verfügbare Tasks und Flows:
+
+| Modul | Beschreibung |
+|---|---|
+| `solrctl.tasks.core_swap` | Task: Core-Swap mit Retries |
+| `solrctl.tasks.alias_swap` | Task: Alias-Swap mit Retries |
+| `solrctl.tasks.cleanup` | Task: Optionales Löschen alter Cores/Collections |
+| `solrctl.flows.swap_flow` | Flow: Kompletter Swap inkl. optionalem Cleanup |
+
+Lokaler Testlauf:
+
+```bash
+uv run python -m solrctl.flows.swap_flow
+```
+
+## Projektstruktur
+
+```
+src/
+  solrctl/
+    cli.py              # Click-CLI
+    client.py           # SolrClient (HTTP-API-Wrapper)
+    tasks/               # Prefect-Tasks (optional)
+      alias_swap.py
+      core_swap.py
+      cleanup.py
+    flows/               # Prefect-Flows (optional)
+      swap_flow.py
+tests/
+docs/
+  idea.md
+  plan.md
+  technical.md
+```
+
+## Weitere Dokumentation
+
+- [`docs/plan.md`](docs/plan.md) – Ausführungsplan und aktueller Status
+- [`docs/technical.md`](docs/technical.md) – Architekturentscheidungen
+
+## KI-Unterstützung
+
+Dieses Projekt wurde mit Unterstützung von KI-Tools (Large Language Models) entwickelt. Code-Struktur, Implementierung und Dokumentation wurden dabei unterstützt durch automatiserte Vorschläge. Alle Entscheidungen wurden vom Entwickler geprüft und bestätigt. Transparenz über den Entwicklungsprozess ist uns wichtig.

solrctl-0.5.0/README.md

@@ -0,0 +1,130 @@
+# solrctl
+
+CLI-Tool zur Verwaltung von Apache Solr 9.x – ohne Downtime Cores tauschen, Status abfragen, Konfiguration einsehen.
+
+## Installation
+
+```bash
+uv tool install solrctl
+```
+
+Oder aus dem Checkout:
+
+```bash
+uv pip install -e .
+```
+
+## CLI-Befehle
+
+```bash
+# Solr erreichbar?
+solrctl ping
+
+# Cores anzeigen
+solrctl core list
+
+# Core-Infos (Pfade, Dokumentanzahl, Größe)
+solrctl core info <name>
+
+# solrconfig.xml abrufen
+solrctl core config <name>
+
+# Schema als XML abrufen
+solrctl core schema <name>
+
+# Core-Swap (unterbrechungsfrei)
+solrctl core swap --source <neuer_core> --target <aktiver_core>
+
+# Core löschen
+solrctl core delete <name> [--delete-index]
+
+# Alias-Operationen (SolrCloud)
+solrctl alias list
+solrctl alias swap --alias <name> --collection <ziel>
+solrctl alias delete <name>
+```
+
+Alle Befehle akzeptieren globale Optionen:
+
+```bash
+--solr-url   Basis-URL der Solr-Instanz (Default: http://localhost:8983, Env: SOLR_URL)
+--user       Basic-Auth Benutzername (Env: SOLR_USER)
+--password   Basic-Auth Passwort (Env: SOLR_PASSWORD)
+```
+
+## Voraussetzungen
+
+- Python 3.11+
+- Zugriff auf eine Solr 9.x Instanz (Standalone für Core-Befehle, SolrCloud für Alias-Befehle)
+
+## Lokale Entwicklung
+
+```bash
+# Abhängigkeiten inkl. Dev- und Prefect-Extras installieren
+uv sync --all-extras
+
+# Tests ausführen
+uv run pytest
+
+# CLI lokal ausführen
+uv run solrctl --help
+```
+
+### Docker-basiertes Test-Setup
+
+```bash
+docker compose up -d
+solrctl --solr-url http://localhost:8983 ping
+```
+
+## Prefect-Integration
+
+solrctl liefert optionale Prefect-Tasks und -Flows für automatisierte Pipelines. Die Prefect-Abhängigkeiten werden nicht standardmäßig installiert:
+
+```bash
+uv pip install -e ".[prefect]"
+```
+
+Verfügbare Tasks und Flows:
+
+| Modul | Beschreibung |
+|---|---|
+| `solrctl.tasks.core_swap` | Task: Core-Swap mit Retries |
+| `solrctl.tasks.alias_swap` | Task: Alias-Swap mit Retries |
+| `solrctl.tasks.cleanup` | Task: Optionales Löschen alter Cores/Collections |
+| `solrctl.flows.swap_flow` | Flow: Kompletter Swap inkl. optionalem Cleanup |
+
+Lokaler Testlauf:
+
+```bash
+uv run python -m solrctl.flows.swap_flow
+```
+
+## Projektstruktur
+
+```
+src/
+  solrctl/
+    cli.py              # Click-CLI
+    client.py           # SolrClient (HTTP-API-Wrapper)
+    tasks/               # Prefect-Tasks (optional)
+      alias_swap.py
+      core_swap.py
+      cleanup.py
+    flows/               # Prefect-Flows (optional)
+      swap_flow.py
+tests/
+docs/
+  idea.md
+  plan.md
+  technical.md
+```
+
+## Weitere Dokumentation
+
+- [`docs/plan.md`](docs/plan.md) – Ausführungsplan und aktueller Status
+- [`docs/technical.md`](docs/technical.md) – Architekturentscheidungen
+
+## KI-Unterstützung
+
+Dieses Projekt wurde mit Unterstützung von KI-Tools (Large Language Models) entwickelt. Code-Struktur, Implementierung und Dokumentation wurden dabei unterstützt durch automatiserte Vorschläge. Alle Entscheidungen wurden vom Entwickler geprüft und bestätigt. Transparenz über den Entwicklungsprozess ist uns wichtig.

solrctl-0.5.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "solrctl"
+version = "0.5.0"
+description = "CLI-Tool zur Verwaltung von Apache Solr 9.x – Cores tauschen, Status abfragen, Konfiguration einsehen"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    {name = "Thomas Baer", email = "thomas.baer@slub-dresden.de"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+    "click>=8.1",
+    "loguru>=0.7",
+]
+
+[project.optional-dependencies]
+prefect = [
+    "prefect==3.6.19",
+    "python-dotenv>=1.0",
+]
+dev = [
+    "pytest>=8.2",
+    "pytest-asyncio>=0.23",
+    "pytest-env>=1.1",
+    "respx>=0.21",
+    "pytest-cov>=5.0",
+    "pysolr>=3.10",
+]
+
+[project.scripts]
+solrctl = "solrctl.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+env = [
+    "PREFECT_API_URL=",
+]

solrctl-0.5.0/setup.cfg

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

solrctl-0.5.0/src/solrctl/cli.py

@@ -0,0 +1,231 @@
+"""solrctl CLI – Verwaltung von Solr-Cores und Aliases."""
+
+from __future__ import annotations
+
+import click
+from loguru import logger
+
+from solrctl.client import SolrClient, SolrClientError
+
+
+class SolrContext:
+    """Hält den SolrClient für die Laufzeit des CLI-Aufrufs."""
+
+    def __init__(self, solr_url: str, auth: tuple[str, str] | None) -> None:
+        self.client = SolrClient(solr_url, auth=auth)
+
+    def close(self) -> None:
+        self.client.close()
+
+
+pass_solr_ctx = click.make_pass_decorator(SolrContext)
+
+
+def _handle_error(exc: SolrClientError) -> None:
+    click.secho(f"Fehler: {exc}", fg="red", err=True)
+    raise SystemExit(1)
+
+
+@click.group()
+@click.option(
+    "--solr-url",
+    envvar="SOLR_URL",
+    default="http://localhost:8983",
+    show_default=True,
+    help="Basis-URL der Solr-Instanz.",
+)
+@click.option(
+    "--user", envvar="SOLR_USER", default=None, help="Basic-Auth Benutzername."
+)
+@click.option(
+    "--password", envvar="SOLR_PASSWORD", default=None, help="Basic-Auth Passwort."
+)
+@click.pass_context
+def cli(
+    ctx: click.Context, solr_url: str, user: str | None, password: str | None
+) -> None:
+    """solrctl – Verwaltung von Solr-Cores und Aliases."""
+    auth = (user, password) if user and password else None
+    ctx.obj = SolrContext(solr_url, auth)
+
+
+@cli.command()
+@pass_solr_ctx
+def ping(ctx: SolrContext) -> None:
+    """Prüft, ob Solr erreichbar ist."""
+    if ctx.client.ping():
+        click.echo("Solr erreichbar.")
+    else:
+        click.secho("Solr NICHT erreichbar.", fg="red", err=True)
+        raise SystemExit(1)
+
+
+# ── core ──────────────────────────────────────────────────────────
+
+
+@cli.group()
+def core() -> None:
+    """Standalone Core-Operationen."""
+
+
+@core.command("list")
+@pass_solr_ctx
+def core_list(ctx: SolrContext) -> None:
+    """Listet alle vorhandenen Cores auf."""
+    try:
+        cores = ctx.client.list_cores()
+    except SolrClientError as exc:
+        _handle_error(exc)
+        return
+
+    if not cores:
+        click.echo("Keine Cores gefunden.")
+        return
+    for name in cores:
+        click.echo(name)
+
+
+@core.command()
+@click.option("--source", required=True, help="Name des neuen Cores (frische Daten).")
+@click.option(
+    "--target", required=True, help="Name des aktiven Cores (wird getauscht)."
+)
+@pass_solr_ctx
+def swap(ctx: SolrContext, source: str, target: str) -> None:
+    """Tauscht zwei Solr-Cores (CoreAdmin SWAP-Action)."""
+    logger.info("Swap: '{}' <-> '{}'", target, source)
+    try:
+        ctx.client.swap_cores(target, source)
+        click.secho(f"Swap erfolgreich: '{target}' <-> '{source}'.", fg="green")
+    except SolrClientError as exc:
+        _handle_error(exc)
+
+
+@core.command()
+@click.argument("name")
+@click.option("--delete-index", is_flag=True, help="Index-Daten auf Disk löschen.")
+@pass_solr_ctx
+def delete(ctx: SolrContext, name: str, delete_index: bool) -> None:
+    """Löscht (unload) einen Solr-Core."""
+    try:
+        ctx.client.unload_core(name, delete_index=delete_index)
+        click.secho(f"Core '{name}' gelöscht.", fg="green")
+    except SolrClientError as exc:
+        _handle_error(exc)
+
+
+@core.command("info")
+@click.argument("name")
+@pass_solr_ctx
+def core_info(ctx: SolrContext, name: str) -> None:
+    """Zeigt detaillierte Informationen zu einem Core an."""
+    try:
+        info = ctx.client.get_core_info(name)
+    except SolrClientError as exc:
+        _handle_error(exc)
+        return
+
+    click.echo(f"Core:         {info.get('name', name)}")
+    click.echo(f"InstanceDir:  {info.get('instanceDir')}")
+    click.echo(f"DataDir:      {info.get('dataDir')}")
+    click.echo(f"Config:       {info.get('config')}")
+    click.echo(f"Schema:       {info.get('schema')}")
+    click.echo(f"StartTime:    {info.get('startTime')}")
+    uptime = info.get("uptime", 0)
+    click.echo(f"Uptime:       {uptime // 1000}s")
+
+    index = info.get("index", {})
+    if index:
+        click.echo()
+        click.secho("Index:", bold=True)
+        click.echo(f"  numDocs:      {index.get('numDocs')}")
+        click.echo(f"  maxDoc:       {index.get('maxDoc')}")
+        click.echo(f"  deletedDocs:  {index.get('deletedDocs')}")
+        click.echo(f"  segments:     {index.get('segmentCount')}")
+        click.echo(f"  size:         {index.get('size')}")
+        click.echo(f"  lastModified: {index.get('lastModified')}")
+
+
+@core.command("config")
+@click.argument("name")
+@pass_solr_ctx
+def core_config(ctx: SolrContext, name: str) -> None:
+    """Gibt die solrconfig.xml eines Cores als XML aus."""
+    try:
+        config_xml = ctx.client.get_core_config(name)
+    except SolrClientError as exc:
+        _handle_error(exc)
+        return
+    click.echo(config_xml)
+
+
+@core.command("schema")
+@click.argument("name")
+@pass_solr_ctx
+def core_schema(ctx: SolrContext, name: str) -> None:
+    """Gibt das Schema eines Cores als XML aus."""
+    try:
+        schema_xml = ctx.client.get_core_schema(name)
+    except SolrClientError as exc:
+        _handle_error(exc)
+        return
+    click.echo(schema_xml)
+
+
+# ── alias ─────────────────────────────────────────────────────────
+
+
+@cli.group()
+def alias() -> None:
+    """SolrCloud Alias-Operationen."""
+
+
+@alias.command("list")
+@pass_solr_ctx
+def alias_list(ctx: SolrContext) -> None:
+    """Listet alle Aliases auf."""
+    try:
+        aliases = ctx.client.list_aliases()
+    except SolrClientError as exc:
+        _handle_error(exc)
+        return
+
+    if not aliases:
+        click.echo("Keine Aliases gefunden.")
+        return
+    for alias_name, collection in aliases.items():
+        click.echo(f"{alias_name} -> {collection}")
+
+
+@alias.command()
+@click.option("--alias", required=True, help="Name des Alias.")
+@click.option("--collection", required=True, help="Ziel-Collection.")
+@pass_solr_ctx
+def swap(ctx: SolrContext, alias: str, collection: str) -> None:
+    """Setzt einen Alias auf eine neue Collection um."""
+    try:
+        ctx.client.create_or_update_alias(alias, collection)
+        click.secho(f"Alias '{alias}' -> '{collection}' gesetzt.", fg="green")
+    except SolrClientError as exc:
+        _handle_error(exc)
+
+
+@alias.command()
+@click.argument("name")
+@pass_solr_ctx
+def delete(ctx: SolrContext, name: str) -> None:
+    """Löscht einen Alias."""
+    try:
+        ctx.client.delete_alias(name)
+        click.secho(f"Alias '{name}' gelöscht.", fg="green")
+    except SolrClientError as exc:
+        _handle_error(exc)
+
+
+def main() -> None:
+    """Einstiegspunkt für die CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()