"""The help system: topics, the option reference, examples and the man page. ``sr help`` is a real manual, not a flag dump. It is organised in *topics* (``sr help topics`` lists them), each topic is either * **static prose** — written once here, wrapped to the terminal width, or * **generated** — the option reference, environment variables, exit codes and the command list are rendered from :mod:`sr.options` and :mod:`sr.exit_codes`, so they can never contradict the parser. Everything is also available as JSON (``sr help --json``), as a man page (``tools/build_manpage.py`` uses the same renderer) and as ``--help-all``. """ from __future__ import annotations import os import subprocess import sys import textwrap from collections.abc import Callable from dataclasses import dataclass, field from pathlib import Path from typing import Any from .cli import exit_code_reference from .console import Console, Verbosity, make_console from .context import Context from .errors import UsageError from .exit_codes import DESCRIPTIONS, ExitCode from .options import BY_FLAG, BY_NAME, GROUPS, OPTIONS, OptionKind, OptionSpec from .registry import PROG, SUBCOMMAND_ALIASES, SUBCOMMANDS, usage_of from .version import __version__ #: Topic registry: ``name → (title, renderer)``. Order defines the index. TOPIC_ORDER: tuple[str, ...] = ( "intro", "quickstart", "install", "commands", "options", "matching", "targets", "backup", "rollback", "sessions", "rename", "interactive", "json", "env", "config", "update", "shell", "exit-codes", "performance", "troubleshooting", "examples", "recipes", "architecture", "development", "security", "compat", "license", ) @dataclass(slots=True) class Topic: """One help topic.""" name: str title: str summary: str body: Callable[..., str] = field(default_factory=lambda: (lambda *_args: "")) aliases: tuple[str, ...] = () def _topic_registry() -> dict[str, Topic]: registry: dict[str, Topic] = {} for name, title, summary, renderer, aliases in _TOPIC_SPECS: registry[name] = Topic(name=name, title=title, summary=summary, body=renderer, aliases=aliases) for alias in aliases: registry[alias] = registry[name] return registry # --------------------------------------------------------------------------- # Public API # --------------------------------------------------------------------------- def show_help( *, topic: str | None, parser: Any = None, subcommand: str | None = None, stream: Any = None, console: Console | None = None, as_json: bool = False, no_pager: bool = False, ) -> int: """Render one topic (or the overview) to ``stream``.""" out = stream if stream is not None else sys.stdout view = console or make_console(verbosity=Verbosity.NORMAL, color=None, fmt="text", out=out, err=sys.stderr) if topic is None and subcommand: text = command_help(subcommand, parser=parser) elif topic is None: text = overview() else: text = render_topic(topic, parser=parser) if as_json: view.emit_json(help_document(topic or subcommand or "overview", text)) return int(ExitCode.OK) _emit(text, view, use_pager=not no_pager) return int(ExitCode.OK) def cmd_help(context: Context) -> int: """``sr help [TOPIC|--option|command]``.""" from .cli import build_parser # lazy: avoids the cli ↔ help_system cycle args = context.args parser = build_parser() topic = getattr(args, "topic", None) # `sr help --max-count` arrives as `--option max-count` (see cli._rewrite_help_topic) option_topic = getattr(args, "option", None) if option_topic: topic = f"--{str(option_topic).lstrip('-')}" as_json = bool(getattr(args, "json", False)) no_pager = bool(getattr(args, "no_pager", False)) or context.console.machine_readable if getattr(args, "all", False): text = help_all_text(parser) if as_json: context.console.emit_json(help_document("all", text)) else: _emit(text, context.console, use_pager=not no_pager) return int(ExitCode.OK) if topic in (None, "", "topics"): text = topics_index() if topic == "topics" else overview() if as_json: context.console.emit_json(help_document(topic or "overview", text, index=True)) else: _emit(text, context.console, use_pager=not no_pager) return int(ExitCode.OK) text = render_topic(str(topic), parser=parser) if as_json: context.console.emit_json(help_document(str(topic), text)) else: _emit(text, context.console, use_pager=not no_pager) return int(ExitCode.OK) def render_topic(topic: str, *, parser: Any = None) -> str: """Render one topic by name, command name or ``--flag``.""" normalized = str(topic).strip() registry = _topic_registry() if normalized.startswith("-"): return option_help(normalized) if normalized in registry: entry = registry[normalized] return _format_topic(entry) for name, _aliases, _summary in SUBCOMMANDS: if normalized == name or (normalized in SUBCOMMAND_ALIASES and SUBCOMMAND_ALIASES[normalized] == name): return command_help(name, parser=parser) if normalized.replace("-", "_") in BY_NAME: return option_help(f"--{normalized.replace('_', '-')}") known = ", ".join(TOPIC_ORDER) raise UsageError( f"unknown help topic {topic!r}", hint=f"run `sr help topics`; available: {known}", ) def help_document(topic: str, text: str, *, index: bool = False) -> dict[str, Any]: """Machine-readable help payload for ``--json`` consumers.""" document: dict[str, Any] = { "program": PROG, "version": __version__, "topic": topic, "text": text, } if index: document["topics"] = [ {"name": name, "title": _title(name), "summary": _summary(name)} for name in TOPIC_ORDER ] document["commands"] = [ {"name": name, "aliases": list(aliases), "summary": summary} for name, aliases, summary in SUBCOMMANDS ] document["options"] = [ { "name": spec.name, "flags": list(spec.flag_names()), "kind": spec.kind, "group": spec.group, "default": spec.default, "env": spec.env_var, "help": spec.help, "choices": list(spec.choices), "commands": list(spec.commands), } for spec in OPTIONS ] document["exit_codes"] = {str(int(code)): DESCRIPTIONS[int(code)] for code in ExitCode} return document def help_all(parser: Any, stream: Any) -> int: """Print the whole manual (``sr --help-all``).""" text = help_all_text(parser) console = make_console(verbosity=Verbosity.NORMAL, color=None, fmt="text", out=stream, err=sys.stderr) _emit(text, console, use_pager=False) return int(ExitCode.OK) def help_all_text(parser: Any = None) -> str: """The whole manual as one document (``sr --help-all``, man page source).""" parts = [overview(), topics_index(), commands_reference(), options_reference(), exit_codes_section()] for name in TOPIC_ORDER: if name in {"intro", "commands", "options"}: continue entry = _topic_registry().get(name) if entry is None: continue parts.append(_format_topic(entry)) return "\n\n".join(parts).rstrip() + "\n" def print_version(stream: Any) -> None: """``sr --version`` — version plus provenance and update hints.""" from .commands.update import DEFAULT_REPO, detect_installation installation = detect_installation() lines = [ f"{PROG} {__version__}", "", f"Python : {sys.version.split()[0]} ({sys.executable})", f"Platform : {sys.platform} {os.uname().machine if hasattr(os, 'uname') else ''}".rstrip(), f"Install : {installation.kind} — {installation.details or installation.executable}", f"Package : {installed_root()}", f"Repository : https://github.com/{DEFAULT_REPO}", "License : MIT", "", "Run `sr update --check` to look for a newer release,", "`sr doctor` to verify the installation, `sr help` for the manual.", ] stream.write("\n".join(lines) + "\n") def overview() -> str: """The screen a new user sees first.""" width = _width() body = f"""{PROG} {__version__} — safe, auditable search & replace for source trees {PROG} rewrites text across many files and keeps a journal of everything it did, so any run can be inspected, diffed and undone. Matching is literal by default, one engine does the counting and the replacing, and nothing is written until the whole tree has been scanned. QUICK START {PROG} replace "old" "new" -p '*.py' edit in place (creates a session) {PROG} find "old" -p '*.py' where does it occur? {PROG} diff "old" "new" -p '*.py' what exactly would change? {PROG} replace "old" "new" --dry-run count and preview, write nothing {PROG} rollback undo the last run {PROG} sessions list the recorded runs {PROG} rename ".txt" ".md" -p '*.txt' rename files by pattern {PROG} update --check is there a newer release? {PROG} doctor verify this installation COMMANDS """ for name, aliases, summary in SUBCOMMANDS: alias_text = f" ({', '.join(aliases)})" if aliases else "" body += f" {name:<11}{alias_text:<16} {summary}\n" body += f""" Every command takes -h/--help: `{PROG} replace --help`. Bare invocations are shortcuts for replace: `{PROG} "*.py" "old" "new"`. THE HELP SYSTEM {PROG} help this overview {PROG} help topics every topic, one line each {PROG} help one topic (options, matching, backup, update …) {PROG} help full help for a subcommand {PROG} help --