elastro-client 1.2.2__tar.gz → 1.2.4__tar.gz

{elastro_client-1.2.2 → elastro_client-1.2.4}/MANIFEST.in

@@ -11,4 +11,5 @@ include .coveragerc
 global-exclude *.pyc
 global-exclude __pycache__
 global-exclude *.so
-global-exclude .DS_Store 
+global-exclude .DS_Store
+recursive-include elastro/gui *

{elastro_client-1.2.2/elastro_client.egg-info → elastro_client-1.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: elastro-client
-Version: 1.2.2
+Version: 1.2.4
 Summary: A comprehensive Python library for Elasticsearch management with both programmatic and CLI interfaces
 Author: Austin Jorgensen
 License-Expression: MIT
@@ -9,11 +9,14 @@ Project-URL: Repository, https://github.com/Fremen-Labs/elastro
 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: Operating System :: OS Independent
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Database
-Requires-Python: >=3.8
+Requires-Python: <3.14,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: elasticsearch<9.0.0,>=8.18.0
@@ -24,6 +27,8 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: colorlog>=6.0.0
 Requires-Dist: rich>=10.0.0
 Requires-Dist: rich-click>=1.7.0
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: uvicorn>=0.30.0
 Provides-Extra: test
 Requires-Dist: pytest>=7.0.0; extra == "test"
 Requires-Dist: pytest-cov>=3.0.0; extra == "test"
@@ -68,18 +73,42 @@ The library offers both a programmatic API and a command-line interface for seam
 
 ## Installation
 
+### Global CLI Installation (Recommended)
+
+To heavily simplify installation across all operating systems and elegantly check your Python compatibility, run our automated `install.sh` via curl:
+
+```bash
+# Safely check your python version and install the elastro CLI globally
+curl -sSfL https://raw.githubusercontent.com/Fremen-Labs/elastro/main/install.sh | bash
+```
+
+Alternatively, if you already have pipx installed and your Python version is compatible (>=3.9, <3.14):
+
 ```bash
-pip install elastro
+# Manual installation via pipx
+pipx install elastro-client
+
+# Upgrade later
+pipx upgrade elastro-client
 ```
 
-Or from source:
+### Library Installation (For Development)
+
+If you are using Elastro as a library in your Python project:
 
 ```bash
-git clone https://github.com/Fremen-Labs/elastro.git
-cd elastro
-pip install -e .
+# Using a virtual environment
+python3 -m venv venv
+source venv/bin/activate
+pip install elastro-client
 ```
 
+### Troubleshooting: "externally-managed-environment"
+
+If you see an `externally-managed-environment` error when running `pip install`, it means your OS (like macOS with Homebrew) prevents system-wide package installation.
+
+**Solution:** Use `pipx` (above) or a virtual environment. Do not use `--break-system-packages` unless you are certain of the consequences.
+
 ## Basic Usage
 
 ### Client Connection
@@ -169,6 +198,9 @@ print(results)
 # Initialize configuration
 elastro config init
 
+# Launch the Elastro Local Web GUI
+elastro gui
+
 # Create an index
 elastro index create products --shards 3 --replicas 1
 
@@ -186,6 +218,21 @@ elastro doc index products --id 1 --file ./product.json
 
 # Search documents
 elastro doc search products --term category=laptop
+
+# View cluster health and routing allocation
+elastro cluster health
+elastro cluster allocation
+
+# Manage ingest pipelines
+elastro ingest list
+elastro ingest simulate my-pipeline --docs ./docs.json
+
+# Manage native realm security users and roles
+elastro security users list
+elastro security roles create my-role --privileges "monitor,manage"
+
+# View long-running cluster tasks
+elastro tasks list --detailed
 ```
 
 ### ILM (Index Lifecycle Management)

{elastro_client-1.2.2 → elastro_client-1.2.4}/README.md

@@ -30,18 +30,42 @@ The library offers both a programmatic API and a command-line interface for seam
 
 ## Installation
 
+### Global CLI Installation (Recommended)
+
+To heavily simplify installation across all operating systems and elegantly check your Python compatibility, run our automated `install.sh` via curl:
+
+```bash
+# Safely check your python version and install the elastro CLI globally
+curl -sSfL https://raw.githubusercontent.com/Fremen-Labs/elastro/main/install.sh | bash
+```
+
+Alternatively, if you already have pipx installed and your Python version is compatible (>=3.9, <3.14):
+
 ```bash
-pip install elastro
+# Manual installation via pipx
+pipx install elastro-client
+
+# Upgrade later
+pipx upgrade elastro-client
 ```
 
-Or from source:
+### Library Installation (For Development)
+
+If you are using Elastro as a library in your Python project:
 
 ```bash
-git clone https://github.com/Fremen-Labs/elastro.git
-cd elastro
-pip install -e .
+# Using a virtual environment
+python3 -m venv venv
+source venv/bin/activate
+pip install elastro-client
 ```
 
+### Troubleshooting: "externally-managed-environment"
+
+If you see an `externally-managed-environment` error when running `pip install`, it means your OS (like macOS with Homebrew) prevents system-wide package installation.
+
+**Solution:** Use `pipx` (above) or a virtual environment. Do not use `--break-system-packages` unless you are certain of the consequences.
+
 ## Basic Usage
 
 ### Client Connection
@@ -131,6 +155,9 @@ print(results)
 # Initialize configuration
 elastro config init
 
+# Launch the Elastro Local Web GUI
+elastro gui
+
 # Create an index
 elastro index create products --shards 3 --replicas 1
 
@@ -148,6 +175,21 @@ elastro doc index products --id 1 --file ./product.json
 
 # Search documents
 elastro doc search products --term category=laptop
+
+# View cluster health and routing allocation
+elastro cluster health
+elastro cluster allocation
+
+# Manage ingest pipelines
+elastro ingest list
+elastro ingest simulate my-pipeline --docs ./docs.json
+
+# Manage native realm security users and roles
+elastro security users list
+elastro security roles create my-role --privileges "monitor,manage"
+
+# View long-running cluster tasks
+elastro tasks list --detailed
 ```
 
 ### ILM (Index Lifecycle Management)

elastro_client-1.2.4/docs/commands_reference.md

@@ -0,0 +1,101 @@
+# Elastro CLI Commands Reference
+
+The Elastro CLI provides a robust feature set for managing your Elasticsearch cluster operations safely and efficiently. This guide details each primary command group, its associated subcommands, what they do, and why they are important for your workflow.
+
+---
+
+## 1. `config`
+**Purpose**: Manage local configuration and connection profiles.
+**Why it's important**: Centralizing connection strings, credentials, and API keys ensures you don't accidentally leak secrets or push them to version control. It also enables rapid context-switching between dev, staging, and production environments.
+
+- **`profile`**: Switch or define which configuration profile is actively used by Elastro.
+- **`set`**: Set individual configuration values securely within the active profile.
+
+---
+
+## 2. `gui`
+**Purpose**: Launch the Elastro Local Web GUI.
+**Why it's important**: Sometimes the CLI isn't enough to visualize complex index metrics or health statuses. The fully autonomous local GUI acts as a single pane of glass, allowing you to quickly spot cluster degradation (yellow/red indices) and manage your instances without deploying heavy Kibana stacks.
+
+- **`elastro gui`**: Starts a secure, detached background server and immediately opens the web dashboard in your browser with a unique, one-time authentication token.
+
+---
+
+## 3. `index`
+**Purpose**: Manage Elasticsearch indices.
+**Why it's important**: Indices are the foundational storage mechanism of Elasticsearch. Proper index management ensures that your data is correctly sharded, optimally routed, and easily purged.
+
+- **`wizard`**: Interactive wizard for creating indices using "Certified Engineer" optimized recipes (highly recommended).
+- **`list`** / **`find`**: Filter and list indices, displaying vital statistics like size, document counts, and health status.
+- **`create`** / **`delete`**: Safely deploy mapped index schemas or purge indices entirely.
+- **`get`** / **`exists`**: Query the exact structure, mappings, and existence of a target index.
+- **`update`**: Inject dynamic settings updates into live indices.
+- **`close`** / **`open`**: Freeze indices to save cluster memory footprint, and thaw them later for searching.
+
+---
+
+## 4. `doc`
+**Purpose**: Manage Elasticsearch documents.
+**Why it's important**: While indexing logs via beats is common, debugging mapping errors or orchestrating CRUD operations manually is a critical administrative function. The `doc` commands let you easily ingest, query, and mutate specific records directly from the terminal.
+
+- **`bulk`**: Perform high-throughput bulk insertion of documents from NDJSON payloads.
+- **`search`**: Execute direct search queries against your indexes for ad-hoc debugging.
+- **`index`**: Insert a new specific document or overwrite an existing one.
+- **`get`**: Retrieve a document by its ID to examine its exact structured payload.
+- **`update`**: Perform partial updates to an existing document without full replacement.
+- **`delete`**: Remove an individual document.
+
+---
+
+## 5. `datastream`
+**Purpose**: Manage Elasticsearch datastreams.
+**Why it's important**: Data streams are the modern, scalable approach to handling time-series data (like logs and metrics). Elastro abstracts the complexities of backing indices so you can manage the continuous stream elegantly.
+
+- **`create`**: Establish a new datastream (requires a matching index template).
+- **`list`** / **`get`** / **`exists`**: Discover and inspect streaming channels.
+- **`stats`**: Retrieve detailed volumetric and performance statistics about your streams.
+- **`delete`**: Teardown deprecated datastreams.
+
+---
+
+## 6. `template`
+**Purpose**: Manage index and component templates.
+**Why it's important**: Templates guarantee that newly generated rolling indices (or datastreams) automatically inherit the correct shards, replicas, mappings, and lifecycles dynamically, avoiding manual intervention at runtime.
+
+- **`wizard`**: An interactive wizard that makes assembling advanced index schemas from reusable component templates easy.
+- **`create`**: Apply a template JSON manifest to the cluster.
+- **`list`** / **`get`**: Inspect currently active templates.
+- **`delete`**: Purge outdated templates.
+
+---
+
+## 7. `ilm`
+**Purpose**: Manage Index Lifecycle Management (ILM) policies.
+**Why it's important**: Managing the cost of compute versus storage requires aging out data. ILM policies automate the transition of indices through Hot, Warm, Cold, and Delete phases automatically, saving enormous amounts of hardware resources.
+
+- **`wizard`**: Interactively define retention durations, rollover sizes, and phase transitions to build robust lifecycle policies without writing complex JSON.
+- **`create`**: Upload a customized JSON ILM policy.
+- **`list`** / **`get`**: Inspect the policies currently governing your cluster data.
+- **`delete`**: Remove an ILM policy.
+
+---
+
+## 8. `snapshot`
+**Purpose**: Manage Snapshots and Repositories.
+**Why it's important**: Hardware failures, ransomware, or unexpected deletions happen. Standardized cluster snapshotting is the only reliable path to disaster recovery (DR). 
+
+- **`repo`**: Manage the snapshot storage backends (e.g., S3, Azure Blob, or local FS).
+- **`create`**: Trigger a manual snapshot of the cluster or specific indices.
+- **`list`**: View all historical snapshots held in a repository.
+- **`restore`**: Recover your cluster state and data instantly from a previously saved snapshot.
+- **`delete`**: Prune old snapshots to reclaim storage space.
+
+---
+
+## 9. `utils`
+**Purpose**: Miscellaneous utility commands.
+**Why it's important**: Fast access to high-level cluster metrics and organizational operations for general system administration.
+
+- **`health`**: Get a quick snapshot of the cluster's pulse (Green, Yellow, Red) and node availability.
+- **`aliases`**: Inspect index aliases, showing how applications transparently route to underlying indices.
+- **`templates`**: Manage legacy index templates (if supporting older Elasticsearch 7.x clusters).

{elastro_client-1.2.2 → elastro_client-1.2.4}/elastro/__init__.py

@@ -4,7 +4,7 @@ Elasticsearch Management Module.
 A module for managing Elasticsearch operations within a pipeline process.
 """
 
-__version__ = "1.2.2"
+__version__ = "1.2.4"
 
 # Core component imports
 from elastro.core.client import ElasticsearchClient

{elastro_client-1.2.2 → elastro_client-1.2.4}/elastro/advanced/aggregations.py

@@ -14,8 +14,9 @@ class AggregationBuilder:
         """Initialize an empty aggregation builder."""
         self._aggregations: Dict[str, Dict[str, Any]] = {}
 
-    def terms(self, name: str, field: str, size: int = 10,
-              min_doc_count: Optional[int] = None) -> "AggregationBuilder":
+    def terms(
+        self, name: str, field: str, size: int = 10, min_doc_count: Optional[int] = None
+    ) -> "AggregationBuilder":
         """Add a terms aggregation.
 
         Args:
@@ -34,8 +35,9 @@ class AggregationBuilder:
         self._aggregations[name] = {"terms": agg}
         return self
 
-    def date_histogram(self, name: str, field: str, interval: str,
-                       format: Optional[str] = None) -> "AggregationBuilder":
+    def date_histogram(
+        self, name: str, field: str, interval: str, format: Optional[str] = None
+    ) -> "AggregationBuilder":
         """Add a date_histogram aggregation.
 
         Args:
@@ -65,15 +67,12 @@ class AggregationBuilder:
         Returns:
             Self for method chaining
         """
-        self._aggregations[name] = {
-            "histogram": {
-                "field": field,
-                "interval": interval
-            }
-        }
+        self._aggregations[name] = {"histogram": {"field": field, "interval": interval}}
         return self
 
-    def range(self, name: str, field: str, ranges: List[Dict[str, Any]]) -> "AggregationBuilder":
+    def range(
+        self, name: str, field: str, ranges: List[Dict[str, Any]]
+    ) -> "AggregationBuilder":
         """Add a range aggregation.
 
         Args:
@@ -84,12 +83,7 @@ class AggregationBuilder:
         Returns:
             Self for method chaining
         """
-        self._aggregations[name] = {
-            "range": {
-                "field": field,
-                "ranges": ranges
-            }
-        }
+        self._aggregations[name] = {"range": {"field": field, "ranges": ranges}}
         return self
 
     def avg(self, name: str, field: str) -> "AggregationBuilder":
@@ -157,7 +151,9 @@ class AggregationBuilder:
         self._aggregations[name] = {"cardinality": {"field": field}}
         return self
 
-    def nested_agg(self, parent_name: str, child_builder: "AggregationBuilder") -> "AggregationBuilder":
+    def nested_agg(
+        self, parent_name: str, child_builder: "AggregationBuilder"
+    ) -> "AggregationBuilder":
         """Add nested aggregations to a parent aggregation.
 
         Args:

{elastro_client-1.2.2 → elastro_client-1.2.4}/elastro/advanced/query_builder.py

@@ -14,7 +14,13 @@ class QueryBuilder:
         """Initialize an empty query builder."""
         self._query: Dict[str, Any] = {}
 
-    def match(self, field: str, value: Any, operator: str = "or", fuzziness: Optional[str] = None) -> "QueryBuilder":
+    def match(
+        self,
+        field: str,
+        value: Any,
+        operator: str = "or",
+        fuzziness: Optional[str] = None,
+    ) -> "QueryBuilder":
         """Create a match query.
 
         Args:
@@ -26,7 +32,9 @@ class QueryBuilder:
         Returns:
             Self for method chaining
         """
-        match_query: Dict[str, Any] = {"match": {field: {"query": value, "operator": operator}}}
+        match_query: Dict[str, Any] = {
+            "match": {field: {"query": value, "operator": operator}}
+        }
         if fuzziness:
             match_query["match"][field]["fuzziness"] = fuzziness
 
@@ -44,14 +52,7 @@ class QueryBuilder:
         Returns:
             Self for method chaining
         """
-        self._query = {
-            "match_phrase": {
-                field: {
-                    "query": value,
-                    "slop": slop
-                }
-            }
-        }
+        self._query = {"match_phrase": {field: {"query": value, "slop": slop}}}
         return self
 
     def term(self, field: str, value: Any) -> "QueryBuilder":
@@ -80,8 +81,14 @@ class QueryBuilder:
         self._query = {"terms": {field: values}}
         return self
 
-    def range(self, field: str, gte: Optional[Any] = None, lte: Optional[Any] = None,
-              gt: Optional[Any] = None, lt: Optional[Any] = None) -> "QueryBuilder":
+    def range(
+        self,
+        field: str,
+        gte: Optional[Any] = None,
+        lte: Optional[Any] = None,
+        gt: Optional[Any] = None,
+        lt: Optional[Any] = None,
+    ) -> "QueryBuilder":
         """Create a range query.
 
         Args:
@@ -188,7 +195,9 @@ class BoolQueryBuilder:
             self._must.append(query)
         return self
 
-    def must_not(self, query: Union[QueryBuilder, Dict[str, Any]]) -> "BoolQueryBuilder":
+    def must_not(
+        self, query: Union[QueryBuilder, Dict[str, Any]]
+    ) -> "BoolQueryBuilder":
         """Add a must_not clause to the bool query.
 
         Args:

{elastro_client-1.2.2 → elastro_client-1.2.4}/elastro/advanced/scroll.py

@@ -2,14 +2,18 @@
 
 from typing import Any, Callable, Dict, Generator, List, Optional, Union
 from elasticsearch import Elasticsearch
+from elasticsearch import Elasticsearch
+from elastro.core.logger import get_logger
+
+logger = get_logger(__name__)
 
 
 class ScrollHelper:
     """Helper for managing Elasticsearch scroll searches.
 
-Scroll searches allow retrieving large numbers of documents from Elasticsearch
-    that would otherwise exceed result size limits. This helper simplifies the
-    process of initializing and maintaining scroll contexts.
+    Scroll searches allow retrieving large numbers of documents from Elasticsearch
+        that would otherwise exceed result size limits. This helper simplifies the
+        process of initializing and maintaining scroll contexts.
     """
 
     def __init__(self, client: Elasticsearch) -> None:
@@ -20,9 +24,14 @@ Scroll searches allow retrieving large numbers of documents from Elasticsearch
         """
         self._client = client
 
-    def scroll(self, index: str, query: Dict[str, Any],
-               scroll_timeout: str = "1m", size: int = 1000,
-               source_fields: Optional[List[str]] = None) -> Generator[Dict[str, Any], None, None]:
+    def scroll(
+        self,
+        index: str,
+        query: Dict[str, Any],
+        scroll_timeout: str = "1m",
+        size: int = 1000,
+        source_fields: Optional[List[str]] = None,
+    ) -> Generator[List[Dict[str, Any]], None, None]:
         """Perform a scroll search and yield batches of results.
 
         Args:
@@ -40,11 +49,7 @@ Scroll searches allow retrieving large numbers of documents from Elasticsearch
             body["_source"] = source_fields
 
         # Initialize scroll
-        resp = self._client.search(
-            index=index,
-            body=body,
-            scroll=scroll_timeout
-        )
+        resp = self._client.search(index=index, body=body, scroll=scroll_timeout)
 
         # Get the scroll ID
         scroll_id = resp.get("_scroll_id")
@@ -56,10 +61,7 @@ Scroll searches allow retrieving large numbers of documents from Elasticsearch
                 yield batch
 
                 # Continue scrolling
-                resp = self._client.scroll(
-                    scroll_id=scroll_id,
-                    scroll=scroll_timeout
-                )
+                resp = self._client.scroll(scroll_id=scroll_id, scroll=scroll_timeout)
 
                 # Update scroll_id as it may change
                 scroll_id = resp.get("_scroll_id")
@@ -75,14 +77,18 @@ Scroll searches allow retrieving large numbers of documents from Elasticsearch
             if scroll_id:
                 try:
                     self._client.clear_scroll(scroll_id=scroll_id)
-                except Exception:
-                    # Log but don't raise
-                    pass
-
-    def process_all(self, index: str, query: Dict[str, Any],
-                    processor: Callable[[Dict[str, Any]], None],
-                    scroll_timeout: str = "1m", size: int = 1000,
-                    source_fields: Optional[List[str]] = None) -> int:
+                except Exception as e:
+                    logger.warning(f"Failed to clear scroll context: {str(e)}")
+
+    def process_all(
+        self,
+        index: str,
+        query: Dict[str, Any],
+        processor: Callable[[Dict[str, Any]], None],
+        scroll_timeout: str = "1m",
+        size: int = 1000,
+        source_fields: Optional[List[str]] = None,
+    ) -> int:
         """Process all matching documents with a callback function.
 
         Args:
@@ -103,7 +109,7 @@ Scroll searches allow retrieving large numbers of documents from Elasticsearch
             query=query,
             scroll_timeout=scroll_timeout,
             size=size,
-            source_fields=source_fields
+            source_fields=source_fields,
         ):
             for doc in batch:
                 processor(doc)
@@ -111,10 +117,15 @@ Scroll searches allow retrieving large numbers of documents from Elasticsearch
 
         return total_processed
 
-    def collect_all(self, index: str, query: Dict[str, Any],
-                    scroll_timeout: str = "1m", size: int = 1000,
-                    source_fields: Optional[List[str]] = None,
-                    max_documents: Optional[int] = None) -> List[Dict[str, Any]]:
+    def collect_all(
+        self,
+        index: str,
+        query: Dict[str, Any],
+        scroll_timeout: str = "1m",
+        size: int = 1000,
+        source_fields: Optional[List[str]] = None,
+        max_documents: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
         """Collect all matching documents into a single list.
 
         Warning: This can consume a lot of memory for large result sets.
@@ -130,7 +141,7 @@ Scroll searches allow retrieving large numbers of documents from Elasticsearch
         Returns:
             List of all matching documents
         """
-        all_docs = []
+        all_docs: List[Dict[str, Any]] = []
         docs_collected = 0
 
         for batch in self.scroll(
@@ -138,7 +149,7 @@ Scroll searches allow retrieving large numbers of documents from Elasticsearch
             query=query,
             scroll_timeout=scroll_timeout,
             size=size,
-            source_fields=source_fields
+            source_fields=source_fields,
         ):
             if max_documents is not None:
                 remaining = max_documents - docs_collected

{elastro_client-1.2.2 → elastro_client-1.2.4}/elastro/cli/art.py

@@ -14,10 +14,13 @@ ELASTRO_ART = r"""
 ```
 """
 
+
 def get_banner() -> str:
     return ELASTRO_ART
 
-def print_banner():
+
+def print_banner() -> None:
     from rich.console import Console
+
     console = Console()
     console.print(ELASTRO_ART, style="bold blue")