typer-examples 1.1.1__py3-none-any.whl

typer_examples/__init__.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from typing import Callable, Optional
+
+import typer as _typer
+
+from ._hook import install_hook, register_app, set_config
+from ._models import Example, ExamplesConfig
+from .docs import get_all_examples
+
+__all__ = [
+    "example",
+    "install",
+    "configure",
+    "ExamplesConfig",
+    "get_all_examples",
+]
+
+try:
+    __version__ = _pkg_version("typer-examples")
+except PackageNotFoundError:  # source tree, not installed
+    __version__ = "0.0.0.dev0"
+
+
+def example(
+    desc: str,
+    code: str,
+    detail: str = "",
+    **vars: str,
+) -> Callable:
+    ex = Example(desc=desc, code=code, detail=detail, vars=vars)
+
+    def decorator(fn: Callable) -> Callable:
+        if not hasattr(fn, "_typer_examples"):
+            fn._typer_examples = []  # type: ignore[attr-defined]
+        fn._typer_examples.insert(0, ex)  # type: ignore[attr-defined]
+        return fn
+
+    return decorator
+
+
+def install(app: _typer.Typer, config: Optional[ExamplesConfig] = None) -> None:
+    cfg = config or ExamplesConfig()
+    register_app(app, cfg)
+    install_hook()
+
+
+def configure(config: ExamplesConfig) -> None:
+    set_config(config)

typer_examples/_hook.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import weakref
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import click
+
+import typer.rich_utils as _ut
+
+from ._models import ExamplesConfig
+
+_MARKER = "_typer_examples_installed"
+
+_config: ExamplesConfig = ExamplesConfig()
+
+_app_config_map: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary()
+
+
+def get_config() -> ExamplesConfig:
+    return _config
+
+
+def set_config(cfg: ExamplesConfig) -> None:
+    global _config
+    _config = cfg
+
+
+def register_app(app: Any, cfg: ExamplesConfig) -> None:
+    _app_config_map[app] = cfg
+
+
+def _get_config_for_callback(callback: Any) -> ExamplesConfig:
+    original = callback
+    while hasattr(original, "__wrapped__"):
+        original = original.__wrapped__
+
+    for app, cfg in list(_app_config_map.items()):
+        if _app_directly_has_callback(app, original):
+            return cfg
+    return _config
+
+
+def _app_directly_has_callback(app: Any, callback: Any) -> bool:
+    for cmd_info in app.registered_commands:
+        if cmd_info.callback is callback:
+            return True
+    return False
+
+
+def install_hook() -> None:
+    try:
+        import rich  # noqa: F401
+    except ImportError:
+        return
+
+    if getattr(_ut, _MARKER, False):
+        return
+
+    _upstream = _ut.rich_format_help
+
+    def _patched(
+        *, obj: "click.Command", ctx: "click.Context", markup_mode: str
+    ) -> None:
+        _upstream(obj=obj, ctx=ctx, markup_mode=markup_mode)
+        _render_examples(obj, ctx)
+
+    _ut.rich_format_help = _patched  # type: ignore[assignment]
+    setattr(_ut, _MARKER, True)
+
+
+def _render_examples(obj: "click.Command", ctx: "click.Context") -> None:
+    try:
+        from ._renderer import print_examples_panel
+    except ImportError:
+        return
+
+    examples = getattr(getattr(obj, "callback", None), "_typer_examples", None)
+    if not examples:
+        return
+
+    config = _get_config_for_callback(obj.callback)
+    print_examples_panel(examples, obj, ctx, config)

typer_examples/_models.py

@@ -0,0 +1,47 @@
+"""Data models for typer-examples."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Optional, Tuple, Union
+
+
+@dataclass
+class Example:
+    """A single CLI usage example attached to a command.
+
+    Attributes:
+        desc:   Short heading (5-8 words, imperative). Answers: *what is this example for?*
+        code:   The CLI invocation string. May contain ``{placeholder}`` template variables.
+        detail: Optional prose line. Answers: *why or when to use this invocation?*
+        vars:   Per-example template variable overrides (highest priority in resolution chain).
+    """
+
+    desc: str
+    code: str
+    detail: str = ""
+    vars: Dict[str, str] = field(default_factory=dict)
+
+
+# Template var values can be a plain string or a lazy callable(ctx) -> str
+VarValue = Union[str, Callable[..., str]]
+
+
+@dataclass
+class ExamplesConfig:
+    """Global rendering configuration for typer-examples.
+
+    Style fields that are ``None`` are auto-matched to the values Typer itself uses
+    (read from ``typer.rich_utils`` at render time).
+    """
+
+    panel_title: str = "Examples"
+    panel_border_style: Optional[str] = None
+    panel_padding: Optional[Tuple[Any, ...]] = None
+    title_align: Optional[str] = None
+    heading_style: str = "bold"
+    detail_style: str = "dim"
+    syntax_theme: str = "ansi_dark"
+    syntax_highlight: bool = True
+    show_command_prefix: bool = True
+    vars: Dict[str, VarValue] = field(default_factory=dict)

typer_examples/_providers.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import sys
+from typing import Any, Dict
+
+import click
+
+# Click uses a Sentinel singleton (not None) for required args that have no default.
+# We must exclude it from the template-var resolution, otherwise str(Sentinel.UNSET)
+# leaks as a literal "Sentinel.UNSET" placeholder value.
+try:
+    from click.core import Sentinel as _ClickSentinel
+
+    _CLICK_UNSET = _ClickSentinel.UNSET
+except (ImportError, AttributeError):
+    # Older Click versions don't have this sentinel; use a private object that
+    # will never match any real default value.
+    _CLICK_UNSET = object()
+
+
+class _SafeFormatMap(dict):
+    """dict subclass that returns '{key}' for missing keys instead of raising KeyError."""
+
+    def __missing__(self, key: str) -> str:
+        return f"{{{key}}}"
+
+
+def resolve_vars(
+    obj: click.Command,
+    ctx: click.Context,
+    config_vars: Dict[str, Any],
+) -> Dict[str, str]:
+    """Build the template-variable mapping for a single render pass.
+
+    Resolution priority (highest → lowest):
+    1. Auto-fill from ``sys.argv`` positional args before ``--help`` (merged by
+       the renderer after this returns, always wins over per-example kwargs)
+    2. Per-example kwargs (merged by the renderer after this returns)
+    3. App-level ``configure(vars={...})`` — callables evaluated here
+    4. Parameter defaults from the Click command definition
+    """
+    result: Dict[str, str] = {}
+
+    positional_params = [p for p in obj.params if isinstance(p, click.Argument)]
+
+    for param in positional_params:
+        if param.default is not None and param.default is not _CLICK_UNSET:
+            result[param.name] = str(param.default)  # type: ignore[arg-type]
+
+    argv_values = _extract_argv_positionals(obj, ctx)
+    result.update(argv_values)
+
+    for key, val in config_vars.items():
+        if callable(val):
+            try:
+                result[key] = str(val(ctx))
+            except Exception:
+                pass
+        else:
+            result[key] = str(val)
+
+    return result
+
+
+def _extract_argv_positionals(
+    obj: click.Command,
+    ctx: click.Context,
+) -> Dict[str, str]:
+    positional_params = [p for p in obj.params if isinstance(p, click.Argument)]
+    if not positional_params:
+        return {}
+
+    known_subcommands: set[str] = set()
+    c: click.Context | None = ctx
+    while c is not None:
+        if isinstance(c.command, click.Group):
+            known_subcommands.update(c.command.list_commands(c))
+        c = c.parent
+
+    raw_args = list(sys.argv[1:])
+    try:
+        help_idx = next(i for i, a in enumerate(raw_args) if a in ("--help", "-h"))
+        raw_args = raw_args[:help_idx]
+    except StopIteration:
+        pass
+
+    command_path_tokens = ctx.command_path.split()
+    for token in command_path_tokens:
+        if raw_args and raw_args[0] == token:
+            raw_args = raw_args[1:]
+
+    positional_values = [a for a in raw_args if not a.startswith("-") and a not in known_subcommands]
+
+    result: Dict[str, str] = {}
+    for param, value in zip(positional_params, positional_values):
+        result[param.name] = value  # type: ignore[assignment]
+
+    return result
+
+
+def safe_format_map(text: str, vars: Dict[str, str]) -> str:
+    return text.format_map(_SafeFormatMap(vars))

typer_examples/_renderer.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List
+
+if TYPE_CHECKING:
+    import click
+
+from rich.console import Group
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.text import Text
+
+from ._models import Example, ExamplesConfig
+from ._providers import _extract_argv_positionals, resolve_vars, safe_format_map
+
+
+def print_examples_panel(
+    examples: List[Example],
+    obj: "click.Command",
+    ctx: "click.Context",
+    config: ExamplesConfig,
+) -> None:
+    import typer.rich_utils as ut
+
+    console = ut._get_rich_console()  # type: ignore[attr-defined]
+    template_vars = resolve_vars(obj, ctx, config.vars)
+    argv_vars = _extract_argv_positionals(obj, ctx)
+
+    border_style = (
+        config.panel_border_style
+        if config.panel_border_style is not None
+        else getattr(ut, "STYLE_OPTIONS_PANEL_BORDER", "dim")
+    )
+    padding = (
+        config.panel_padding if config.panel_padding is not None else getattr(ut, "STYLE_OPTIONS_TABLE_PADDING", (0, 1))
+    )
+    title_align = config.title_align if config.title_align is not None else getattr(ut, "ALIGN_OPTIONS_PANEL", "left")
+
+    rows = []
+
+    for i, ex in enumerate(examples):
+        merged_vars = {**template_vars, **ex.vars, **argv_vars}
+
+        desc = safe_format_map(ex.desc, merged_vars)
+        code = _build_code(ex.code, obj, ctx, merged_vars, config)
+        detail = safe_format_map(ex.detail, merged_vars) if ex.detail else None
+
+        parts: list = [Text(desc, style=config.heading_style)]
+
+        if detail:
+            parts.append(Text(detail, style=config.detail_style))
+
+        if config.syntax_highlight:
+            parts.append(
+                Syntax(
+                    f"$ {code}",
+                    "bash",
+                    theme=config.syntax_theme,
+                    background_color="default",
+                )
+            )
+        else:
+            parts.append(Text(f"$ {code}"))
+
+        rows.append(Group(*parts))
+
+        if i < len(examples) - 1:
+            rows.append(Text(""))
+
+    console.print(
+        Panel(
+            Group(*rows),
+            padding=padding,
+            border_style=border_style,
+            title=config.panel_title,
+            title_align=title_align,
+        )
+    )
+
+
+def _build_code(
+    code: str,
+    obj: "click.Command",
+    ctx: "click.Context",
+    vars: dict,
+    config: ExamplesConfig,
+) -> str:
+    resolved = safe_format_map(code, vars)
+    if config.show_command_prefix:
+        prefix = ctx.command_path
+        resolved = f"{prefix} {resolved}".strip()
+    return resolved

typer_examples/docs.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+import typer
+
+from ._providers import safe_format_map
+
+
+def get_all_examples(app: typer.Typer) -> Dict[Tuple[str, ...], list]:
+    from ._models import Example
+
+    result: Dict[Tuple[str, ...], List[Example]] = {}
+    _collect(app, path=(), result=result)
+    return result
+
+
+def _collect(
+    app: typer.Typer,
+    path: Tuple[str, ...],
+    result: Dict[Tuple[str, ...], list],
+) -> None:
+    for command_info in app.registered_commands:
+        name = command_info.name or (
+            command_info.callback.__name__.replace("_", "-")
+            if command_info.callback
+            else None
+        )
+        if not name:
+            continue
+        examples = getattr(command_info.callback, "_typer_examples", None)
+        if examples:
+            result[path + (name,)] = list(examples)
+
+    for group_info in app.registered_groups:
+        sub_app = group_info.typer_instance
+        if sub_app is None:
+            continue
+        group_name = group_info.name or ""
+        _collect(sub_app, path + (group_name,) if group_name else path, result)
+
+
+def to_markdown(app: typer.Typer, vars: Optional[Dict[str, str]] = None) -> str:
+    all_examples = get_all_examples(app)
+    lines: List[str] = []
+
+    for path, examples in all_examples.items():
+        command_str = " ".join(path)
+        lines.append(f"## `{command_str}`\n")
+        for ex in examples:
+            lines.append(f"**{ex.desc}**\n")
+            if ex.detail:
+                lines.append(f"{ex.detail}\n")
+            code = (
+                safe_format_map(ex.code, {**vars, **ex.vars})
+                if vars is not None
+                else ex.code
+            )
+            lines.append(f"```bash\n$ {code}\n```\n")
+
+    return "\n".join(lines)
+
+
+def to_rst(app: typer.Typer, vars: Optional[Dict[str, str]] = None) -> str:
+    all_examples = get_all_examples(app)
+    lines: List[str] = []
+
+    for path, examples in all_examples.items():
+        command_str = " ".join(path)
+        heading = f"``{command_str}``"
+        lines.append(heading)
+        lines.append("~" * len(heading))
+        lines.append("")
+
+        for ex in examples:
+            lines.append(f"**{ex.desc}**")
+            lines.append("")
+            if ex.detail:
+                lines.append(ex.detail)
+                lines.append("")
+            lines.append(".. code-block:: bash")
+            lines.append("")
+            code = (
+                safe_format_map(ex.code, {**vars, **ex.vars})
+                if vars is not None
+                else ex.code
+            )
+            lines.append(f"   $ {code}")
+            lines.append("")
+
+    return "\n".join(lines)

typer_examples-1.1.1.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: typer-examples
+Version: 1.1.1
+Summary: Beautiful example rendering for Typer CLI help output
+License: MIT
+License-File: LICENSE
+Keywords: cli,examples,help,rich,typer
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: git-cliff>=2.6; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: typer[all]>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# typer-examples
+
+[![CI](https://github.com/Xieyt/typer-examples/actions/workflows/ci.yml/badge.svg)](https://github.com/Xieyt/typer-examples/actions/workflows/ci.yml)
+[![Typer Compatibility](https://github.com/Xieyt/typer-examples/actions/workflows/typer-compat.yml/badge.svg)](https://github.com/Xieyt/typer-examples/actions/workflows/typer-compat.yml)
+[![Python](https://img.shields.io/badge/python-3.9--3.12-blue)](#compatibility)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](#license)
+
+Attach structured, syntax-highlighted usage examples to [Typer](https://typer.tiangolo.com/) commands. They appear automatically in `--help` output as a Rich panel — no subclassing, no epilog hacks.
+
+```
+ Usage: myapp deploy [OPTIONS] ENV
+
+╭─ Options ──────────────────────────────────────────────────────────╮
+│ --tag    TEXT  Docker image tag to deploy.  [default: latest]      │
+│ --yes          Skip confirmation prompt.                           │
+│ --help         Show this message and exit.                         │
+╰────────────────────────────────────────────────────────────────────╯
+╭─ Examples ─────────────────────────────────────────────────────────╮
+│ Deploy to staging with a pinned tag                                │
+│ Pulls the image, runs migrations, and restarts services.           │
+│ $ myapp deploy staging --tag 1.4.2                                 │
+│                                                                    │
+│ Deploy to production and skip confirmation                         │
+│ Pass --yes in CI pipelines to avoid interactive prompts.           │
+│ $ myapp deploy production --tag 2.0.0 --yes                        │
+╰────────────────────────────────────────────────────────────────────╯
+```
+
+## Installation
+
+```bash
+pip install typer-examples
+# or
+uv add typer-examples
+```
+
+Requires Python ≥ 3.9 and Typer ≥ 0.9.
+
+## Quick start
+
+```python
+import typer
+from typer_examples import example, install
+
+app = typer.Typer()
+install(app)
+
+@app.command()
+@example(
+    "Deploy to staging with a pinned tag",
+    "{env} --tag {version}",
+    env="staging",
+    version="1.4.2",
+    detail="Pulls the image, runs migrations, and restarts services.",
+)
+@example(
+    "Deploy to production and skip confirmation",
+    "{env} --tag {version} --yes",
+    env="production",
+    version="2.0.0",
+    detail="Pass --yes in CI pipelines to avoid interactive prompts.",
+)
+def deploy(env: str, tag: str = typer.Option("latest"), yes: bool = False):
+    ...
+
+if __name__ == "__main__":
+    app()
+```
+
+> **Decorator order**: `@example` must sit *below* `@app.command()` — closest to `def`. This ensures the metadata is attached to the raw function before Typer wraps it.
+
+## Features
+
+- **Decorator-first** — examples live next to the command, not buried in docstrings or epilog strings
+- **Template variables** — `{placeholders}` resolved from per-example kwargs, app-level defaults, `sys.argv`, or Click parameter defaults → [details](docs/template-variables.md)
+- **Per-app config** — each `Typer()` instance gets its own panel title, style theme, and variable defaults → [details](docs/configuration.md)
+- **Docs generation** — export all examples to Markdown or reStructuredText for CI doc pipelines → [API](docs/api.md)
+- **Chain-safe** — composes with `rich-click` and any other `rich_format_help` patch without clobbering
+- **Graceful degradation** — if `rich` is absent, `install()` returns silently with no error
+
+## Documentation
+
+| Topic | |
+|-------|--|
+| [Template variables](docs/template-variables.md) | Resolution chain: per-example → app-level → argv → defaults |
+| [Configuration](docs/configuration.md) | `ExamplesConfig` fields, global config, per-app config for sub-commands |
+| [API reference](docs/api.md) | Full public API with signatures and return types |
+| [How it works](docs/how-it-works.md) | Internal implementation and the `rich_format_help` hook |
+
+## Try the examples
+
+```bash
+# Minimal single-app setup — three commands, each with examples
+uv run python examples/simple.py deploy --help
+uv run python examples/simple.py logs --help
+uv run python examples/simple.py shell --help
+
+# Root app + two sub-apps with independent per-app config
+uv run python examples/app.py deploy --help
+uv run python examples/app.py db migrate --help
+uv run python examples/app.py server start --help
+
+# Static docs generation
+uv run python examples/app.py docs
+uv run python examples/app.py docs --format rst
+```
+
+## Compatibility
+
+| Typer | Python | rich-click |
+|-------|--------|------------|
+| ≥ 0.9 | 3.9 – 3.12 | Supported |
+
+Compatibility is verified daily across all supported Typer × Python combinations in CI.
+
+## License
+
+MIT

typer_examples-1.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+typer_examples/__init__.py,sha256=k2Brsn-ASPNxABZg2jQNwcbsrSLGNUjCuN1-_6-Y_so,1269
+typer_examples/_hook.py,sha256=lsU1Vafm4K0EzpZwGiSjjBVF4y6y0CkOKNdtXvcmXXU,1999
+typer_examples/_models.py,sha256=ZRCng0TGlAZQvGDs2GCsXt-QVG-_WA04Kok51iPamw4,1516
+typer_examples/_providers.py,sha256=fc2WVhzYFzJKgNdDFlFt6pml0ZjLEngkfXR-tehA1wY,3287
+typer_examples/_renderer.py,sha256=OChScZ0UlaWY_d4X0oRVNxZPpxlRxIcwnGqW8mHV-Dg,2599
+typer_examples/docs.py,sha256=OJvea4Kvtx_KJ40GRStosVyASJmUTOzT3C5w_e1NX2E,2723
+typer_examples-1.1.1.dist-info/METADATA,sha256=1P8EVG4AkYs_0S4hFb9UnnFymFZzcYEFt2ST2kY55Eg,6212
+typer_examples-1.1.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+typer_examples-1.1.1.dist-info/licenses/LICENSE,sha256=3gIpJJaVDsJdEq5q2GxKWznSwv1N2Uu2aHkw-17QJfs,1066
+typer_examples-1.1.1.dist-info/RECORD,,

typer_examples-1.1.1.dist-info/WHEEL

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

typer_examples-1.1.1.dist-info/licenses/LICENSE

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