charisma-cli 0.1.2__py3-none-any.whl

charisma_cli/watcher.py

@@ -0,0 +1,223 @@
+"""Watchdog observer, stability debounce, and file classification for allure-results."""
+
+import os
+from pathlib import Path
+from queue import PriorityQueue
+from threading import Timer
+
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers import Observer
+
+from charisma_cli.config import Config
+from charisma_cli.models import FileCategory, FileEvent
+
+_TWO_MB = 2 * 1024 * 1024
+_STABILITY_SECONDS = 0.5
+
+
+def classify_file(filename: str) -> FileCategory | None:
+    """Classify a filename into a FileCategory or None if excluded.
+
+    Args:
+        filename: The base filename (not full path).
+
+    Returns:
+        FileCategory.RESULT for *-result.json,
+        FileCategory.CONTAINER for *-container.json,
+        FileCategory.ATTACHMENT for all other valid files,
+        None for excluded files (dot-prefix or .tmp suffix).
+    """
+    if filename.startswith("."):
+        return None
+    if filename.endswith(".tmp"):
+        return None
+    if filename.endswith("-result.json"):
+        return FileCategory.RESULT
+    if filename.endswith("-container.json"):
+        return FileCategory.CONTAINER
+    return FileCategory.ATTACHMENT
+
+
+def should_skip(path: Path, config: Config) -> bool:
+    """Check whether a file should be skipped based on size.
+
+    Args:
+        path: Path to the file on disk.
+        config: Resolved CLI configuration.
+
+    Returns:
+        True if the file exceeds 2MB and skip_too_big is enabled.
+    """
+    if not config.skip_too_big:
+        return False
+    return path.stat().st_size > _TWO_MB
+
+
+class _StabilityHandler(FileSystemEventHandler):
+    """Debounces filesystem events, enqueuing files after 500ms of stability."""
+
+    def __init__(self, queue: PriorityQueue, config: Config) -> None:
+        super().__init__()
+        self._queue = queue
+        self._config = config
+        self._timers: dict[str, Timer] = {}
+
+    def on_created(self, event: FileSystemEvent) -> None:
+        """Handle file creation events."""
+        if not event.is_directory:
+            self._handle_event(event.src_path)
+
+    def on_modified(self, event: FileSystemEvent) -> None:
+        """Handle file modification events."""
+        if not event.is_directory:
+            self._handle_event(event.src_path)
+
+    def _handle_event(self, src_path: str) -> None:
+        """Reset the stability timer for a file path."""
+        path = Path(src_path)
+        filename = path.name
+
+        category = classify_file(filename)
+        if category is None:
+            return
+
+        # Cancel existing timer for this path
+        existing = self._timers.get(src_path)
+        if existing is not None:
+            existing.cancel()
+
+        # Set a new timer that enqueues after stability period
+        timer = Timer(_STABILITY_SECONDS, self._enqueue, args=(path, category))
+        timer.daemon = True
+        self._timers[src_path] = timer
+        timer.start()
+
+    def _enqueue(self, path: Path, category: FileCategory) -> None:
+        """Enqueue a file event after stability check passes."""
+        # Remove from timer dict
+        self._timers.pop(str(path), None)
+
+        # Check file still exists and size at enqueue time
+        try:
+            if should_skip(path, self._config):
+                return
+        except (OSError, FileNotFoundError):
+            return  # File was deleted between debounce and enqueue
+
+        self._queue.put(FileEvent(path=path, category=category))
+
+    def cancel_all(self) -> None:
+        """Cancel all pending timers."""
+        for timer in self._timers.values():
+            timer.cancel()
+        self._timers.clear()
+
+    def flush_pending(self) -> None:
+        """Immediately enqueue all files currently in debounce windows.
+
+        Called after subprocess exit to ensure no result files are lost due
+        to pending debounce timers. Cancels all timers and enqueues their
+        associated files directly.
+        """
+        # Snapshot and clear timers atomically
+        pending = dict(self._timers)
+        self._timers.clear()
+
+        for src_path, timer in pending.items():
+            timer.cancel()
+            path = Path(src_path)
+            filename = path.name
+
+            category = classify_file(filename)
+            if category is None:
+                continue
+
+            try:
+                if should_skip(path, self._config):
+                    continue
+            except (OSError, FileNotFoundError):
+                continue
+
+            self._queue.put(FileEvent(path=path, category=category))
+
+
+class ResultsWatcher:
+    """Watches the allure-results directory for new files using watchdog.
+
+    Creates the directory if it doesn't exist, observes file creation/modification,
+    debounces events for 500ms of stability, then enqueues FileEvent objects
+    into the provided PriorityQueue.
+    """
+
+    def __init__(self, results_dir: str, queue: PriorityQueue, config: Config) -> None:
+        self._results_dir = results_dir
+        self._queue = queue
+        self._config = config
+        self._handler = _StabilityHandler(queue, config)
+        self._observer = Observer()
+
+    def start(self) -> None:
+        """Create the results directory and start observing for file events."""
+        os.makedirs(self._results_dir, exist_ok=True)
+        self._observer.schedule(self._handler, self._results_dir, recursive=False)
+        self._observer.start()
+
+    def stop(self) -> None:
+        """Stop the observer and cancel all pending stability timers."""
+        self._observer.stop()
+        self._observer.join()
+        self._handler.cancel_all()
+
+    def flush_pending(self) -> None:
+        """Flush all files currently in debounce windows into the queue.
+
+        Should be called BEFORE stop() when you want to capture all pending
+        files rather than discard them.
+        """
+        self._handler.flush_pending()
+
+    def final_scan(self, already_seen: set[str] | None = None) -> int:
+        """Scan the results directory and enqueue any files not already processed.
+
+        Performs a one-time sweep of all files in the results directory,
+        enqueuing any that pass classification and size checks. This catches
+        files that the filesystem watcher may have missed entirely (e.g., written
+        between watcher setup and observation start, or during high-throughput
+        bursts that overwhelm OS event buffers).
+
+        Args:
+            already_seen: Optional set of absolute path strings that were
+                already enqueued. Files in this set are skipped.
+
+        Returns:
+            Number of new files enqueued by this scan.
+        """
+        results_path = Path(self._results_dir)
+        if not results_path.exists():
+            return 0
+
+        enqueued = 0
+        seen = already_seen or set()
+
+        for filepath in results_path.iterdir():
+            if not filepath.is_file():
+                continue
+
+            abs_path = str(filepath.resolve())
+            if abs_path in seen:
+                continue
+
+            category = classify_file(filepath.name)
+            if category is None:
+                continue
+
+            try:
+                if should_skip(filepath, self._config):
+                    continue
+            except (OSError, FileNotFoundError):
+                continue
+
+            self._queue.put(FileEvent(path=filepath, category=category))
+            enqueued += 1
+
+        return enqueued

charisma_cli-0.1.2.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: charisma-cli
+Version: 0.1.2
+Summary: CLI tool that watches allure-results and streams test results + attachments to Charisma.
+Author: Charisma Team
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: click<9.0,>=8.0
+Requires-Dist: httpx<1.0,>=0.24
+Requires-Dist: watchdog<5.0,>=3.0
+Provides-Extra: dev
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: pytest<10.0,>=7.0; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# charisma-cli
+
+CLI tool that watches an `allure-results` directory during test execution and streams results + attachments to the Charisma ingestion API in real time.
+
+## Installation
+
+```bash
+pip install charisma-cli
+```
+
+No token, no index URL — works on any laptop and in any CI. The package is published to public PyPI; the Charisma repo itself stays private (only this client wheel is public).
+
+For local development from a checkout of the repo:
+
+```bash
+pip install -e packages/charisma-cli
+```
+
+<details>
+<summary>Alternative: install from the GitHub Packages registry (PyOCI)</summary>
+
+Also published to GitHub Packages via [PyOCI](https://pyoci.com) (requires a GitHub token with `read:packages`) — useful for a build not yet on PyPI:
+
+```bash
+pip install charisma-cli \
+  --index-url "https://__token__:$GITHUB_TOKEN@pyoci.com/ghcr.io/align-QCOE/"
+```
+
+</details>
+
+## Publishing (maintainers)
+
+Releases publish to public PyPI automatically from the merge-queue workflow using a **PyPI API token**.
+
+> Trusted publishing (OIDC) is not used because this repo runs on **GitHub Enterprise Server**, whose OIDC issuer PyPI does not trust. A stored API token is required instead.
+
+One-time setup (done once by a PyPI project owner):
+
+1. Sign in to [PyPI](https://pypi.org) with the team-owned account (2FA enabled).
+2. Go to **Account settings → API tokens → Add API token**. Scope it to the `charisma-cli` project once the project exists; for the very first publish use an account-scoped token, then re-scope it to the project afterward.
+3. Copy the token (starts with `pypi-`).
+4. In the GitHub Enterprise repo, add it as an Actions secret named **`PYPI_API_TOKEN`** (org-level secret recommended so both packages share it).
+5. Bump `version` in `pyproject.toml` and merge — the workflow builds and publishes on the next release.
+
+Rotate the token periodically and store it in the team secret manager.
+
+## Usage
+
+```bash
+export CHARISMA_ENDPOINT=https://charisma.company.com
+export CHARISMA_TOKEN=<your-service-token>
+export CHARISMA_PROJECT_ID=my-project
+
+charismactl watch --results allure-results -- uv run pytest -n 4 tests/
+```
+
+## Environment Variables
+
+| Variable              | Required | Description                                        |
+| --------------------- | -------- | -------------------------------------------------- |
+| `CHARISMA_ENDPOINT`   | Yes      | Base URL of the Charisma API                       |
+| `CHARISMA_TOKEN`      | Yes      | Service or CI bearer token                         |
+| `CHARISMA_PROJECT_ID` | Yes      | Project alias for result routing                   |
+| `CHARISMA_RESULTS`    | No       | Path to allure-results (default: `allure-results`) |
+
+## Flags
+
+| Flag             | Description                                  |
+| ---------------- | -------------------------------------------- |
+| `--results PATH` | Allure results directory (overrides env var) |
+| `--project ID`   | Project alias (overrides env var)            |
+| `--silent`       | Don't fail pipeline if upload errors occur   |
+| `--skip-too-big` | Skip result files larger than 2MB            |

charisma_cli-0.1.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+charisma_cli/__init__.py,sha256=cA_-La2crYdATs-1IgSAd1gCUH7-C1Zy5wIPiMFhQag,91
+charisma_cli/config.py,sha256=hEBIcteuwLDPTRRTtRvFcXsuY4lECXlZUgXGGHkH5VE,2649
+charisma_cli/main.py,sha256=AkSV7DXo80kot0yeNjj3hFHg331OO9z4I9Zo4FT6lKw,6812
+charisma_cli/models.py,sha256=w3_CsTl53KO02OH2V5BwxatxJj2ucTvMh1gCN_ScwH4,2148
+charisma_cli/parser.py,sha256=kMOBKtGO269G-v-Ypeq6vVN1XlZ28veM1KCPHxvKmEI,5083
+charisma_cli/retry.py,sha256=9bwza5kT1tOCJoGEGG_e5ZGnnDNa5oDw7XtlGsdmY-4,595
+charisma_cli/subprocess_mgr.py,sha256=0pq30J7owbqMUAa_Py9HUzA9KNvVh_5y4scH2N1tHs4,1994
+charisma_cli/uploader.py,sha256=sZjKXU9WEuuPOOl3Rj8mNsij2nYZ3jfbr7A8HoyuKyQ,19156
+charisma_cli/watcher.py,sha256=a7m5Yf_7gYx0Z7G275N33dYBbr3R0cXiMBeRwUviz4w,7436
+charisma_cli-0.1.2.dist-info/METADATA,sha256=VEJZQtRd2YPKeFO94g91-MCaOWuNVEkGrtxQdf27jUQ,4079
+charisma_cli-0.1.2.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+charisma_cli-0.1.2.dist-info/entry_points.txt,sha256=O41ZogN9NRFfnEZNHIM1C72-jhlcFnRWqC1D8zZTby0,54
+charisma_cli-0.1.2.dist-info/RECORD,,

charisma_cli-0.1.2.dist-info/WHEEL

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

charisma_cli-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+charismactl = charisma_cli.main:cli