pyclifer 0.4.1__tar.gz

pyclifer-0.4.1/.claude/CLAUDE.md

@@ -0,0 +1,243 @@
+# Code Style Rules
+
+Rules for Claude Code when writing or modifying code in this repository.
+
+## Type Hints
+
+Use **PEP 585 built-in generics** (Python 3.10+) — do NOT import from `typing` for these:
+
+```python
+# Correct
+def foo(items: list[str], mapping: dict[str, Any]) -> str | None: ...
+
+
+# Wrong
+from typing import List, Dict, Optional
+
+
+def foo(items: List[str], mapping: Dict[str, Any]) -> Optional[str]: ...
+```
+
+Always annotate return types. Use `Any` from `typing` when genuinely dynamic.
+`Callable`, `Union` (when needed), and `TYPE_CHECKING` still come from `typing`.
+
+## Docstrings
+
+**Google style**, required on all public classes, methods, functions, and nested functions.
+Private helpers (`_name`) use a single-line docstring only if the purpose is not obvious from the name.
+
+```python
+def my_function(value: str, count: int = 1) -> list[str]:
+    """Short imperative description (no period at the end for one-liners).
+
+    Longer explanation if needed. Omit if the one-liner is enough.
+
+    Args:
+        value: Description of value.
+        count: Description of count.
+
+    Returns:
+        Description of the return value.
+
+    Raises:
+        ValueError: When the value is empty.
+    """
+```
+
+- First line: imperative mood, no trailing period, fits on one line.
+- Blank line between summary and `Args:` / `Returns:` / `Raises:` sections.
+- Do NOT include type information in `Args:` / `Returns:` — it is already in the signature.
+- No `Methods:` section in class docstrings — method docstrings are self-contained.
+
+### Markup: plain text only
+
+Docstrings must use **plain prose** — no reStructuredText or Sphinx markup.
+
+```python
+# Wrong — reStructuredText syntax
+"""Do something with ctx.meta.
+
+:param name: The name.
+:type name: str
+:returns: The result.
+:rtype: str
+"""
+
+# Wrong — double-backtick / cross-reference markup
+"""Store value in ``ctx.meta``. See :class:`~pyclifer.Response`."""
+
+# Wrong — directive blocks
+"""Example:
+
+.. code-block:: bash
+
+    myapp hello
+"""
+
+# Correct — plain text, inline code with single backticks only in narrative prose
+"""Store value in ctx.meta."""
+```
+
+Allowed: single backticks `` ` `` inside narrative prose when referring to code names.
+Forbidden: `` `` `` (double backtick), `:param:`, `:type:`, `:rtype:`, `:class:`, `:func:`,
+`:meth:`, `.. directive::`.
+
+## Imports
+
+PEP 8 order with a blank line between groups:
+
+```python
+# 1. Standard library
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable, TYPE_CHECKING
+
+# 2. Third-party
+import click_extra
+from rich.console import Console
+
+# 3. Local (relative preferred inside the package)
+from .mixins import OutputFormatMixin
+from pyclifer.core.output import Response
+```
+
+- Prefer `from x import y` over `import x.y`.
+- **Prefer `click_extra` over `click` directly** — `click_extra` re-exports the full Click API
+  (`Context`, `Parameter`, `get_current_context`, etc.) and is the declared project dependency.
+  Never `import click` when `click_extra` provides the same symbol.
+- Use **lazy imports** (inside the function body) only to break circular dependencies — always
+  add a comment explaining why.
+
+## Naming
+
+| Kind                  | Convention           | Example                    |
+|-----------------------|----------------------|----------------------------|
+| Module / file         | `snake_case`         | `rich_help_config.py`      |
+| Class                 | `PascalCase`         | `HandleResponseMixin`      |
+| Function / method     | `snake_case`         | `configure_rich_logging()` |
+| Private method / attr | `_single_underscore` | `_apply_click_group()`     |
+| Constant              | `UPPER_SNAKE`        | `PYCLIFER_LOG_LEVELS`        |
+
+Never use double-underscore (`__dunder`) for private names — reserve those for Python protocol
+methods.
+
+## Classes
+
+- **Mixin inheritance order**: mixins first, concrete base class last.
+
+```python
+class PycliferRichGroup(HandleResponseMixin, GlobalOptionsMixin, RichGroup):
+```
+
+- Use `@dataclass` for configuration / data-holding objects (`GroupConfig`, `Response`).
+- Avoid no-op `__post_init__` bodies.
+
+## Decorator Ordering on Commands
+
+Top to bottom: registration decorator → framework/option decorators → `@pass_cli_context`
+or `@click.pass_context` → function.
+
+```python
+@app.command()  # registers with group
+@output_filter_option()  # custom pyclifer decorators
+@returns_response  # closest to function
+@option("--name", default="world")  # click options
+@pass_cli_context  # always last before def (or @click.pass_context in cli.py)
+def hello(ctx, name): ...
+```
+
+Note: `@click.pass_context` is used only in `cli.py` to build `ctx.obj`. Everywhere else,
+use `pass_cli_context` (generated by `make_pass_decorator`) for typed context access.
+
+## Exception Handling
+
+- Catch specific exception types; avoid bare `except Exception` unless you log and re-raise
+  or have a documented reason.
+- When catching multiple types, list them as a tuple with a comment explaining each.
+- Raise `RuntimeError` for programming errors (missing callbacks, invalid state).
+- Raise `ValueError` for bad input.
+
+## Code quality
+
+Every change must pass `ruff check` and `ruff format` before being committed. Run both on the
+affected files before declaring a task done:
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+Fix all reported issues — do not suppress warnings with `# noqa` unless the rule is genuinely
+inapplicable and the reason is documented on the same line.
+
+## Tests
+
+- One test file per source module, mirroring the `src/` layout under `tests/`.
+- Test classes: `Test<Subject>` (e.g., `TestOutputFilterOption`).
+- Test methods: `test_<what_is_being_tested>` — descriptive, no abbreviations.
+- Use `pytest.raises(ExcType, match="…")` — always include a `match` pattern.
+- Prefer `MagicMock` over `Mock`; use `@patch` for module-level targets.
+- Do not assert on mock call count unless the count itself is the behavior under test.
+- Target 100% branch coverage for every module touched by a change. If a branch is genuinely
+  untestable (e.g., a defensive guard for an impossible state), mark it with `# pragma: no cover`
+  and add a comment explaining why.
+
+## File placement
+
+Code must go in the file that matches its kind — never mix concerns across modules:
+
+| Kind                                          | File                      |
+|-----------------------------------------------|---------------------------|
+| Decorators (`@app_group`, `@command`, …)      | `core/decorators.py`      |
+| Click subclasses, config dataclasses          | `core/classes.py`         |
+| Reusable mixin classes                        | `core/mixins/`            |
+| `BaseContext` and context helpers             | `core/context.py`         |
+| `Response`, `OperationResult`, output helpers | `core/output/`            |
+| `BaseRenderer`, `ResponseRenderer` Protocol   | `core/output/renderer.py` |
+| `BaseInterface` and `respond()` machinery     | `core/interfaces/base.py` |
+| Logging helpers, `get_logger`                 | `core/log/`               |
+
+When adding a new class or function, pick the file whose existing contents are the closest
+match. If none fits, create a new module rather than placing it in a nearby but wrong one.
+
+The API docs in `docs/api/` mirror this structure — a symbol documented in the wrong page
+(e.g., a class from `classes.py` appearing in `decorators.md`) is a bug:
+
+| Doc page            | What belongs there                                                                                  |
+|---------------------|-----------------------------------------------------------------------------------------------------|
+| `api/decorators.md` | The four decorators + `returns_response` + `output_filter_option`                                   |
+| `api/classes.md`    | `PycliferOption`, `PycliferGroup`, `CustomConfigOption`, `PycliferTimerOption` and any new Click subclass |
+| `api/mixins.md`     | All mixin classes from `core/mixins/`                                                               |
+| `api/context.md`    | `BaseContext` and context helpers                                                                   |
+| `api/output.md`     | `Response`, `OperationResult`, tables, `BaseRenderer`, `ResponseRenderer`                           |
+| `api/interfaces.md` | `BaseInterface` and `respond()` machinery                                                           |
+| `api/logging.md`    | Logging helpers and `get_logger`                                                                    |
+
+## Documentation
+
+- Every new `docs/*.md` page must be added to the `nav` section of `mkdocs.yml` in the same
+  commit. Never create a documentation page without registering it.
+
+## Git Workflow
+
+- Always create a feature branch (`feat/<name>`) before starting implementation of a spec or
+  any non-trivial change. Do this before touching the first file.
+- After merging into `main`, delete the feature branch immediately.
+- Never push or merge without the user's explicit validation.
+
+### Commit message format
+
+Every commit must follow this exact structure:
+
+```
+<gitmoji> <type>(<scope>): <imperative summary>
+
+- bullet describing why / what changed
+- bullet for each meaningful change
+```
+
+- **gitmoji**: coherent with the type (`✨` feat, `🐛` fix, `♻️` refactor, `📝` docs, `✅` test, `🔧` chore, etc.)
+- **type**: `feat`, `fix`, `refactor`, `perf`, `docs`, `style`, `test`, `chore`, `ci`, `build`
+- **scope**: optional, use the module name (e.g. `tables`, `decorators`, `log`)
+- **summary**: imperative mood, ≤50 chars, no trailing period
+- **body**: bullet list, each item explains *why* not just *what*; omit if summary is self-explanatory

pyclifer-0.4.1/.claude/specs/archived/2026-06-01-deps-upgrade-fr.md

@@ -0,0 +1,279 @@
+# Mise à jour des dépendances : click-extra, rich-click, rich
+
+> **Pour les agents :** SUB-SKILL REQUIS : Utiliser superpowers:subagent-driven-development (recommandé) ou superpowers:executing-plans pour exécuter ce plan tâche par tâche. Les étapes utilisent la syntaxe checkbox (`- [ ]`) pour le suivi.
+
+**Objectif :** Monter `click-extra` 7.16.1→7.18.0, `rich` 13.9.4→15.0.0, `rich-click` 1.9.7→1.9.8 sans régression.
+
+**Architecture :** Simple montée de version — aucun changement de code source attendu. Les trois mises à jour sont couplées : click-extra 7.17.0+ tire Click 8.4.1 (contre 8.3.3 actuellement), et rich-click 1.9.8 a été publié précisément pour corriger la compatibilité avec Click 8.4.x. Les trois doivent arriver ensemble. La contrainte `rich>=13.0` autorise déjà la 15.x ; seules les bornes minimales changent.
+
+**Stack :** uv, pytest, ruff, click-extra, rich, rich-click, click (transitif)
+
+---
+
+## Audit des breaking changes (pré-recherche, ne pas sauter)
+
+### rich 13.9.4 → 15.0.0
+
+| Version | Breaking change | Impact sur pyclifer |
+|---------|----------------|-----------------|
+| 14.0.0 | `NO_COLOR=` (vide) ne désactive plus les couleurs ; avant, toute présence de la variable suffisait | Aucun test ni CI ne définit `NO_COLOR=` — confirmé par grep |
+| 14.0.0 | `FORCE_COLOR=` (vide) — même règle | Idem — aucun impact |
+| 15.0.0 | Python 3.8 abandonné | pyclifer requiert ≥3.10 — aucun impact |
+
+Aucune API supprimée ou renommée utilisée par pyclifer (`Console`, `Panel`, `Table`, `RichHandler`, `Live`, `Status`, `Prompt`, `Rule`, `Syntax`, `Text`, `box` — tous inchangés).
+
+Effets visuels (pas des breaking changes, mais observables) :
+- Fond du titre des `Panel` corrigé (14.1.0) — les panneaux s'afficheront plus correctement
+- L'imbrication de `Live` est maintenant autorisée (14.1.0)
+
+### click-extra 7.16.1 → 7.18.0
+
+| Symbole supprimé | Utilisé dans pyclifer ? | Verdict |
+|-----------------|----------------------|---------|
+| Module `click_extra.themes` | Non | Sûr |
+| Constantes `DARK`, `DRACULA`, `LIGHT`, `MONOKAI`, `NORD`, `SOLARIZED_DARK` | Non | Sûr |
+| Attribut `default_theme` | Non — pyclifer utilise déjà `get_default_theme()` dans `core/log/formatters.py:5` | Sûr |
+| Constantes pré-rendues `OK`, `KO` | Non | Sûr |
+| Attribut `ctx.telemetry` | Non | Sûr |
+| Callback `disable_colors` sur `ColorOption` | Non | Sûr |
+| **Chemins de sous-modules** `click_extra.jobs`, `click_extra.timer` supprimés | `TimerOption` est utilisé (`classes.py:11`, `decorators.py:113`) mais importé via `from click_extra import TimerOption` (racine) — pas via le chemin de sous-module supprimé. | Sûr |
+| `ValueError` au chargement de `--config` → maintenant `SystemExit` | Aucun test n'exerce ce chemin d'erreur | Sûr |
+
+Upgrade transitif : Click 8.3.3 → 8.4.1 (requis par click-extra 7.17.0+). Aucune suppression d'API Click 8.4.x n'affecte pyclifer.
+
+### rich-click 1.9.7 → 1.9.8
+
+Uniquement un correctif : répare le mécanisme de patching de rich-click cassé par Click 8.4.0. **Doit être mis à jour en même temps que click-extra.**
+
+---
+
+## Fichiers à modifier
+
+| Fichier | Changement |
+|---------|-----------|
+| `pyproject.toml` | Monter trois bornes minimales de dépendances |
+| `uv.lock` | Régénéré automatiquement par `uv sync` |
+
+Aucun changement de fichier source ou de test prévu. Si un test échoue après la mise à jour, une tâche de correction est ajoutée à ce moment-là.
+
+---
+
+## Tâche 1 : Établir la baseline (les tests passent sur les versions actuelles)
+
+**Fichiers :** (lecture seule)
+
+- [ ] **Étape 1 : Lancer la suite de tests complète sur les versions actuelles**
+
+```bash
+python -m pytest tests/ -v
+```
+
+Attendu : tous les tests passent. Si des tests échouent avant la mise à jour, stop — les corriger séparément d'abord.
+
+- [ ] **Étape 2 : Enregistrer les versions installées pour le message de commit**
+
+```bash
+pip show click-extra rich rich-click | grep -E "Name:|Version:"
+```
+
+Sortie attendue (actuelle) :
+```
+Name: click-extra
+Version: 7.16.1
+Name: rich
+Version: 13.9.4
+Name: rich-click
+Version: 1.9.7
+```
+
+---
+
+## Tâche 2 : Mettre à jour les contraintes de version dans pyproject.toml
+
+**Fichiers :**
+- Modifier : `pyproject.toml` lignes 12–14
+
+Mise à jour des bornes minimales vers les versions testées, pour que `uv sync --resolution lowest` reste sur des versions connues et stables.
+
+- [ ] **Étape 1 : Modifier les trois lignes de dépendances**
+
+Dans `pyproject.toml`, remplacer :
+
+```toml
+    "click-extra>=7.16.1,<8.0.0",
+    "rich>=13.0",
+    "rich-click>=1.9.7,<2.0.0",
+```
+
+par :
+
+```toml
+    "click-extra>=7.18.0,<8.0.0",
+    "rich>=15.0.0",
+    "rich-click>=1.9.8,<2.0.0",
+```
+
+- [ ] **Étape 2 : Vérifier la modification**
+
+```bash
+grep -E "click-extra|rich-click|rich" pyproject.toml
+```
+
+Attendu :
+```
+    "click-extra>=7.18.0,<8.0.0",
+    "rich>=15.0.0",
+    "rich-click>=1.9.8,<2.0.0",
+```
+
+---
+
+## Tâche 3 : Installer les dépendances mises à jour
+
+**Fichiers :** `uv.lock` (régénéré automatiquement)
+
+- [ ] **Étape 1 : Synchroniser avec les nouvelles contraintes**
+
+```bash
+uv sync --extra dev,docs
+```
+
+Attendu : uv résout et installe click-extra 7.18.0, rich 15.0.0, rich-click 1.9.8, et click 8.4.1 (transitif). Aucune erreur.
+
+- [ ] **Étape 2 : Confirmer les versions installées**
+
+```bash
+pip show click-extra rich rich-click click | grep -E "Name:|Version:"
+```
+
+Attendu :
+```
+Name: click
+Version: 8.4.1
+Name: click-extra
+Version: 7.18.0
+Name: rich
+Version: 15.0.0
+Name: rich-click
+Version: 1.9.8
+```
+
+---
+
+## Tâche 4 : Lancer la suite de tests complète sur les nouvelles versions
+
+**Fichiers :** (lecture seule)
+
+- [ ] **Étape 1 : Lancer tous les tests**
+
+```bash
+python -m pytest tests/ -v
+```
+
+Attendu : tous les tests passent, couverture ≥80%.
+
+Si un test échoue → aller à la Tâche 5. Si tout passe → aller directement à la Tâche 6.
+
+---
+
+## Tâche 5 : Corriger les échecs de tests (conditionnelle — uniquement si la Tâche 4 a des échecs)
+
+Sauter entièrement si la Tâche 4 passe.
+
+Catégories d'échecs probables et corrections :
+
+**A. Test qui vérifie le rendu exact d'un `Panel`**
+
+Cause : rich 14.1.0 a corrigé le style du fond du titre des `Panel` — la sortie rendue peut différer.
+
+Correction : mettre à jour la chaîne attendue dans l'assertion pour correspondre à la nouvelle sortie (correcte).
+
+Motif à rechercher :
+```bash
+grep -rn "Panel\|panel" tests/ | grep -i "assert\|expect"
+```
+
+**B. Test qui vérifie `click.UsageError` depuis `help` sur une sous-commande inconnue**
+
+Cause : click-extra 7.17.0 a changé `HelpCommand` pour lever `click.NoSuchCommand` au lieu de `click.UsageError`.
+
+Correction :
+```python
+# Avant
+with pytest.raises(click.UsageError, match="No such command"):
+
+# Après
+with pytest.raises(click.exceptions.NoSuchCommand, match="..."):
+```
+
+**C. Test qui vérifie `ValueError` au chargement de `--config`**
+
+Cause : click-extra 7.18.0 a changé les erreurs de chargement de config de `ValueError` en `SystemExit`.
+
+Correction :
+```python
+# Avant
+with pytest.raises(ValueError, match="..."):
+
+# Après
+with pytest.raises(SystemExit):
+```
+
+Après chaque correction :
+```bash
+python -m pytest tests/ -v
+```
+
+Lancer ruff avant de committer :
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+---
+
+## Tâche 6 : Vérification du linting
+
+- [ ] **Étape 1 : Lancer ruff**
+
+```bash
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+Attendu : aucune erreur, aucun reformatage nécessaire.
+
+---
+
+## Tâche 7 : Commit
+
+- [ ] **Étape 1 : Stager les fichiers modifiés**
+
+```bash
+git add pyproject.toml uv.lock
+# Si la Tâche 5 a tourné, ajouter aussi : git add <fichiers de tests corrigés>
+```
+
+- [ ] **Étape 2 : Créer le commit**
+
+```bash
+git commit -m "$(cat <<'EOF'
+🔧 chore(deps): upgrade click-extra, rich, rich-click
+
+- click-extra 7.16.1 → 7.18.0 (tire Click 8.3.3 → 8.4.1 transitivement)
+- rich 13.9.4 → 15.0.0 (abandonne Python 3.8 ; pyclifer requiert 3.10+)
+- rich-click 1.9.7 → 1.9.8 (corrige la régression de compatibilité Click 8.4.x)
+EOF
+)"
+```
+
+---
+
+## Checklist de relecture
+
+- [x] Les trois packages couverts avec des numéros de version précis
+- [x] Breaking changes recherchés et mappés sur la surface de pyclifer
+- [x] Upgrade couplé (click-extra + rich-click + montée Click transitive) documenté
+- [x] Tâche de correction conditionnelle (Tâche 5) couvre les trois catégories d'échecs les plus probables
+- [x] Aucun placeholder — chaque étape a des commandes exactes et une sortie attendue
+- [x] Message de commit respecte le format du projet défini dans `.claude/CLAUDE.md`