help2skill 0.1.0__py3-none-any.whl

help2skill/__init__.py

@@ -0,0 +1,243 @@
+"""Make Python CLIs ready for LLM agents.
+
+Generate an LLM-friendly reference (``--llms``) and an Agent Skills ``SKILL.md``
+straight from a Click, Typer or argparse command tree, and catch drift between
+that documentation and the real CLI in CI.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+from typing import Any
+
+from ._argparse import from_argparse
+from ._click import Resolver, default_resolve, from_click, is_click_command
+from .model import Command, Param
+from .privacy import find_machine_paths, redact_home
+from .render import (
+    LLMS_MAX_CHARS,
+    SKILL_MAX_CHARS,
+    default_description,
+    render_index,
+    render_llms,
+    render_markdown,
+    render_skill,
+    usage,
+)
+from .sync import REFERENCE_FILE, Problem, Settings, check, read_settings, skill_parts, update_block
+
+__all__ = [
+    "Command",
+    "Param",
+    "Problem",
+    "Settings",
+    "LLMS_MAX_CHARS",
+    "REFERENCE_FILE",
+    "SKILL_MAX_CHARS",
+    "check",
+    "check_skill_file",
+    "default_description",
+    "default_resolve",
+    "find_machine_paths",
+    "introspect",
+    "redact_home",
+    "render_index",
+    "render_llms",
+    "render_markdown",
+    "read_settings",
+    "render_skill",
+    "update_block",
+    "usage",
+    "write_skill",
+]
+
+__version__ = "0.1.0"
+
+
+# Names a framework falls back to when the real program name is unknown.
+GENERIC_NAMES = frozenset(
+    {"cli", "main", "app", "run", "entry", "entrypoint", "command", "__main__", "__main__.py", "-c"}
+)
+UNNAMED = "__help2skill_unnamed__"
+
+
+def introspect(
+    cli: Any,
+    name: str | None = None,
+    *,
+    resolve: Resolver | None = None,
+    hide_defaults: list[str] | None = None,
+) -> Command:
+    """Build a :class:`Command` tree from a Click command, Typer app or ArgumentParser.
+
+    ``name`` is the program name users type (e.g. ``"mytool"``); pass it when the
+    framework cannot know it, as with Typer apps and ``__main__``-style parsers.
+    ``resolve`` turns lazy placeholder commands into real ones (Click/Typer only);
+    see :func:`default_resolve`. ``hide_defaults`` lists parameters (by name or
+    option string) whose default is computed at run time and must not be written.
+    """
+    cmd = _introspect(cli, name, resolve)
+    if hide_defaults:
+        _hide_defaults(cmd, hide_defaults)
+    return cmd
+
+
+def _introspect(cli: Any, name: str | None, resolve: Resolver | None) -> Command:
+    if isinstance(cli, Command):
+        return cli
+    if isinstance(cli, argparse.ArgumentParser):
+        return from_argparse(cli, name)
+    if hasattr(cli, "registered_commands") and hasattr(cli, "registered_groups"):
+        import typer.main
+
+        cmd = typer.main.get_command(cli)
+        return from_click(cmd, name or getattr(cli.info, "name", None), resolve=resolve)
+    if is_click_command(cli):
+        return from_click(cli, name, resolve=resolve)
+    if callable(cli):
+        raise TypeError(
+            f"{getattr(cli, '__name__', cli)!r} is a function, not a CLI; if it builds the "
+            "parser, pass its result (e.g. build_parser()) instead"
+        )
+    raise TypeError(f"don't know how to introspect {type(cli).__name__}; expected Click, Typer or argparse")
+
+
+def _hide_defaults(cmd: Command, names: list[str]) -> None:
+    wanted = set(names)
+    found: set[str] = set()
+    for node in cmd.walk():
+        for p in node.params:
+            hits = wanted & {p.name, *p.opts, *p.secondary_opts}
+            if hits:
+                if p.default and p.help:
+                    # argparse help often embeds the value: "(default: %(default)s)".
+                    pattern = r"(default:?\s*)" + re.escape(p.default)
+                    p.help = re.sub(pattern, r"\1computed at run time", p.help, flags=re.I)
+                p.default = None
+                found |= hits
+    missing = sorted(wanted - found)
+    if missing:
+        raise ValueError(f"--hide-default: no parameter named {', '.join(missing)}")
+
+
+def program_name(cli: Any, *candidates: str | None, resolve: Resolver | None = None) -> str | None:
+    """First usable program name: the candidates in order, then the CLI's own name.
+
+    Generic names such as ``cli`` or ``main`` (a function name, not what users
+    type) are skipped. Returns ``None`` when nothing better is known.
+    """
+    for candidate in candidates:
+        if candidate:
+            return candidate
+    own = _introspect(cli, None, resolve).name
+    return None if own in GENERIC_NAMES or own == UNNAMED else own
+
+
+def write_skill(
+    cli: Any,
+    path: str | Path,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+    program: str | None = None,
+    max_chars: int | None = None,
+    resolve: Resolver | None = None,
+    hide_defaults: list[str] | None = None,
+) -> Path:
+    """Create ``path`` as a SKILL.md, or refresh only its generated block if it exists.
+
+    ``name`` is the skill name (needed only to create the file). ``program`` is
+    the command users type; it defaults to the value stored in the file, then
+    the CLI's own name, then ``name``. When the full reference is longer than
+    ``max_chars`` (default 30,000; 0 = never), SKILL.md gets a command index and
+    the full reference goes to ``references/commands.md`` next to it, which
+    agents read on demand. Your home directory is replaced by ``~``.
+
+    The settings used are stored in the block's begin marker, so a refresh or
+    a check needs none of them again.
+    """
+    path = Path(path)
+    existing = path.read_text(encoding="utf-8") if path.exists() else None
+    stored = read_settings(existing) if existing else Settings()
+    skill_name = name or (_skill_name(existing) if existing else None)
+    if not skill_name:
+        raise ValueError(f"{path} does not exist yet: pass a skill name to create it")
+    settings = Settings(
+        program=program_name(cli, program, stored.program, resolve=resolve) or skill_name,
+        max_chars=max_chars
+        if max_chars is not None
+        else (stored.max_chars if stored.max_chars is not None else SKILL_MAX_CHARS),
+        hide_defaults=hide_defaults if hide_defaults is not None else stored.hide_defaults,
+    )
+    cmd = introspect(cli, settings.program, resolve=resolve, hide_defaults=settings.hide_defaults)
+    assert settings.max_chars is not None
+    block, reference = skill_parts(cmd, max_chars=settings.max_chars)
+    if existing is not None:
+        text = update_block(existing, block, settings)
+    else:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        text = render_skill(
+            cmd,
+            name=skill_name,
+            description=description or default_description(cmd),
+            block=block,
+            settings=settings,
+        )
+    path.write_text(text, encoding="utf-8")
+    reference_path = path.parent / REFERENCE_FILE
+    if reference is not None:
+        reference_path.parent.mkdir(parents=True, exist_ok=True)
+        reference_path.write_text(reference, encoding="utf-8")
+    elif reference_path.exists():
+        reference_path.unlink()
+    return path
+
+
+def check_skill_file(
+    cli: Any,
+    path: str | Path,
+    *,
+    program: str | None = None,
+    max_chars: int | None = None,
+    resolve: Resolver | None = None,
+    hide_defaults: list[str] | None = None,
+) -> list[Problem]:
+    """Return drift problems between the SKILL.md at ``path`` (and its reference file) and the CLI.
+
+    Settings not passed are read from the file's generated block.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(
+            f"{path} not found (relative paths start from the current directory, {Path.cwd()})"
+        )
+    text = path.read_text(encoding="utf-8")
+    stored = read_settings(text)
+    reference_path = path.parent / REFERENCE_FILE
+    reference = reference_path.read_text(encoding="utf-8") if reference_path.exists() else None
+    prog = program_name(cli, program, stored.program, resolve=resolve) or _skill_name(text)
+    cmd = introspect(
+        cli,
+        prog,
+        resolve=resolve,
+        hide_defaults=hide_defaults if hide_defaults is not None else stored.hide_defaults,
+    )
+    limit = (
+        max_chars
+        if max_chars is not None
+        else (stored.max_chars if stored.max_chars is not None else SKILL_MAX_CHARS)
+    )
+    return check(text, cmd, max_chars=limit, reference=reference)
+
+
+def _skill_name(text: str) -> str | None:
+    if not text.startswith("---"):
+        return None
+    for line in text.splitlines()[1:]:
+        if line.strip() == "---":
+            break
+        if line.startswith("name:"):
+            return line.split(":", 1)[1].strip().strip("\"'") or None
+    return None

help2skill/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

help2skill/_argparse.py

@@ -0,0 +1,173 @@
+"""Introspect ``argparse.ArgumentParser`` trees."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from .model import Command, Param
+
+_FLAG_ACTIONS = (
+    argparse._StoreTrueAction,
+    argparse._StoreFalseAction,
+    argparse._StoreConstAction,
+    argparse._CountAction,
+    argparse._AppendConstAction,
+)
+# The option itself may be repeated.
+_REPEAT_ACTIONS = (
+    argparse._AppendAction,
+    argparse._ExtendAction,
+    argparse._AppendConstAction,
+    argparse._CountAction,
+)
+
+
+def from_argparse(parser: argparse.ArgumentParser, name: str | None = None) -> Command:
+    root_name = name or parser.prog
+    return _build(parser, root_name, [root_name], help_text=None)
+
+
+def _build(parser: argparse.ArgumentParser, name: str, path: list[str], help_text: str | None) -> Command:
+    params: list[Param] = []
+    subcommands: list[Command] = []
+    aliases_of: dict[str, list[str]] = {}
+    for action in parser._actions:
+        if isinstance(action, argparse._HelpAction):
+            continue
+        if isinstance(action, argparse._SubParsersAction):
+            helps = {a.dest: a.help for a in action._choices_actions}
+            primary: dict[int, str] = {}
+            for sub_name, sub_parser in action.choices.items():
+                if id(sub_parser) in primary:  # aliases point at the same parser
+                    aliases_of.setdefault(primary[id(sub_parser)], []).append(sub_name)
+                    continue
+                primary[id(sub_parser)] = sub_name
+                subcommands.append(_build(sub_parser, sub_name, path + [sub_name], helps.get(sub_name)))
+            continue
+        if action.help == argparse.SUPPRESS:
+            continue
+        params.append(_param(action))
+    for sub in subcommands:
+        sub.aliases = aliases_of.get(sub.name, [])
+    description = parser.description or help_text
+    full_help = _clean(description)
+    if parser.epilog and parser.epilog != argparse.SUPPRESS:
+        epilog = parser.epilog.strip()
+        full_help = f"{full_help}\n\n{epilog}" if full_help else epilog
+    return Command(
+        name=name,
+        path=path,
+        help=full_help,
+        short_help=_clean(help_text) or _first_line(description),
+        params=params,
+        subcommands=subcommands,
+        exclusive=_exclusive_groups(parser),
+    )
+
+
+def _exclusive_groups(parser: argparse.ArgumentParser) -> list[tuple[list[str], bool]]:
+    groups = []
+    for group in parser._mutually_exclusive_groups:
+        names = [
+            max(a.option_strings, key=len) if a.option_strings else a.dest.upper()
+            for a in group._group_actions
+            if a.help != argparse.SUPPRESS
+        ]
+        if len(names) > 1:
+            groups.append((names, bool(group.required)))
+    return groups
+
+
+def _param(action: argparse.Action) -> Param:
+    is_option = bool(action.option_strings)
+    is_flag = isinstance(action, _FLAG_ACTIONS) or action.nargs == 0
+    nargs = action.nargs if action.nargs is not None else 1
+    if is_option:
+        multiple = isinstance(action, _REPEAT_ACTIONS)
+        required = action.required
+    else:
+        multiple = nargs in ("*", "+", argparse.REMAINDER) or (isinstance(nargs, int) and nargs > 1)
+        required = nargs not in ("?", "*", argparse.REMAINDER)
+    return Param(
+        name=action.dest,
+        kind="option" if is_option else "argument",
+        opts=list(action.option_strings) if is_option else [action.dest],
+        type="bool" if is_flag else _type_name(action.type),
+        choices=[str(c) for c in action.choices]
+        if action.choices and not _is_range(action.choices)
+        else None,
+        required=bool(required),
+        default=_default(action, is_flag),
+        is_flag=is_flag,
+        multiple=multiple,
+        nargs=nargs,
+        help=_clean(_expand_help(action)),
+        metavar=action.metavar if isinstance(action.metavar, str) else None,
+        value_tokens=None if is_flag else _value_tokens(action, nargs),
+        count=isinstance(action, argparse._CountAction),
+        range=_range_text(action.choices),
+        optional_value=is_option and nargs == "?",
+    )
+
+
+def _value_tokens(action: argparse.Action, nargs: Any) -> list[str] | None:
+    """Tokens for options that take a fixed number (> 1) of values."""
+    if not action.option_strings or not isinstance(nargs, int) or nargs <= 1:
+        return None
+    if isinstance(action.metavar, tuple) and len(action.metavar) == nargs:
+        return list(action.metavar)
+    token = action.metavar if isinstance(action.metavar, str) else _type_name(action.type).upper()
+    return [token] * nargs
+
+
+def _is_range(choices: Any) -> bool:
+    return isinstance(choices, range) and len(choices) > 20
+
+
+def _range_text(choices: Any) -> str | None:
+    if not isinstance(choices, range) or not _is_range(choices) or choices.step != 1:
+        return None
+    return f"{choices.start}<=x<={choices.stop - 1}"
+
+
+def _type_name(t: Any) -> str:
+    if t is None or t is str:
+        return "text"
+    name = getattr(t, "__name__", type(t).__name__)
+    return {"PurePath": "path", "Path": "path", "FileType": "file"}.get(name, name.lower())
+
+
+def _default(action: argparse.Action, is_flag: bool) -> str | None:
+    value = action.default
+    if value is None or value == argparse.SUPPRESS or value == "" or value == []:
+        return None
+    if is_flag and isinstance(
+        action, (argparse._StoreTrueAction, argparse._StoreFalseAction, argparse._CountAction)
+    ):
+        return None
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (list, tuple)):
+        return ", ".join(str(v) for v in value)
+    return str(value)
+
+
+def _expand_help(action: argparse.Action) -> str | None:
+    text = action.help
+    if not text or "%" not in text:
+        return text
+    try:
+        return text % {**vars(action), "prog": "", "default": action.default}
+    except (KeyError, TypeError, ValueError):
+        return text
+
+
+def _first_line(text: str | None) -> str | None:
+    if not text:
+        return None
+    return text.strip().split("\n\n")[0].replace("\n", " ") or None
+
+
+def _clean(text: str | None) -> str | None:
+    return text.strip() if text and text.strip() else None

help2skill/_click.py

@@ -0,0 +1,256 @@
+"""Introspect Click commands, including Typer's vendored Click (Typer >= 0.26).
+
+Everything here is duck-typed: Typer's command classes do not subclass
+``click.Command`` any more, so ``isinstance`` checks would silently miss them.
+"""
+
+from __future__ import annotations
+
+import enum
+import inspect
+import re
+from collections.abc import Callable
+from typing import Any
+
+from .model import Command, Param
+
+# Click marks deprecated commands in their help text; the renderer marks them itself.
+_DEPRECATED_RE = re.compile(r"\s*\(deprecated(?::[^)]*)?\)\s*", re.I)
+
+# Parameters that exist for the human shell, not for the agent.
+INTERNAL_PARAMS = frozenset({"help", "install_completion", "show_completion", "llms"})
+
+# Type names differ between Click versions ("integer range", "int_range"...);
+# normalise them so the output is the same everywhere.
+_TYPE_NAMES = {
+    "str": "text",
+    "string": "text",
+    "integer": "int",
+    "boolean": "bool",
+    "filename": "file",
+    "unprocessed": "text",
+}
+
+
+Resolver = Callable[[Any], Any]
+
+
+def default_resolve(cmd: Any) -> Any:
+    """Load placeholder commands that only build their real command on demand.
+
+    Covers placeholders with a ``materialize()`` method (Hugging Face's ``hf``).
+    Click's documented ``LazyGroup`` pattern needs nothing: it resolves in
+    ``get_command``. Pass your own ``resolve`` for other patterns.
+    """
+    materialize = getattr(cmd, "materialize", None)
+    return materialize() if callable(materialize) else cmd
+
+
+def is_click_command(obj: Any) -> bool:
+    return hasattr(obj, "params") and hasattr(obj, "make_context")
+
+
+def from_click(
+    cmd: Any,
+    name: str | None = None,
+    *,
+    parent_ctx: Any = None,
+    resolve: Resolver | None = None,
+) -> Command:
+    """Build a :class:`Command` tree from a Click (or Typer-built) command."""
+    resolve = resolve or default_resolve
+    cmd = resolve(cmd)
+    info_name = name or cmd.name or "cli"
+    ctx = _make_context(cmd, info_name, parent_ctx)
+    path = (_ctx_path(parent_ctx) if parent_ctx is not None else []) + [info_name]
+    return _build(cmd, info_name, path, ctx, resolve)
+
+
+def from_context(ctx: Any, resolve: Resolver | None = None) -> Command:
+    """Build the tree for the command a live Click context is running."""
+    path = _ctx_path(ctx)
+    return _build(ctx.command, path[-1], path, ctx, resolve or default_resolve)
+
+
+def _build(cmd: Any, name: str, path: list[str], ctx: Any, resolve: Resolver) -> Command:
+    subcommands = []
+    hidden = []
+    # Sorted: Click sorts, recent Typer keeps definition order; sorting keeps the
+    # output identical across versions.
+    for sub_name in sorted(_list_commands(cmd, ctx)):
+        sub = _get_command(cmd, ctx, sub_name)
+        if sub is None:
+            continue
+        if getattr(sub, "hidden", False):
+            hidden.append(sub_name)
+            continue
+        sub = resolve(sub)
+        sub_ctx = _make_context(sub, sub_name, ctx)
+        subcommands.append(_build(sub, sub_name, path + [sub_name], sub_ctx, resolve))
+    help_text = _clean(getattr(cmd, "help", None), strip_deprecated=True)
+    epilog = _clean(getattr(cmd, "epilog", None))
+    if epilog:
+        help_text = f"{help_text}\n\n{epilog}" if help_text else epilog
+    return Command(
+        name=name,
+        path=path,
+        help=help_text,
+        short_help=_short_help(cmd),
+        params=[_param(p) for p in cmd.params if _visible(p)],
+        subcommands=subcommands,
+        deprecated=bool(getattr(cmd, "deprecated", False)),
+        default_command=getattr(cmd, "default_cmd_name", None),
+        hidden_subcommands=hidden,
+    )
+
+
+def _make_context(cmd: Any, info_name: str, parent: Any) -> Any:
+    ctx_class = getattr(cmd, "context_class", None)
+    if ctx_class is None:
+        return None
+    try:
+        return ctx_class(cmd, info_name=info_name, parent=parent)
+    except Exception:  # pragma: no cover - exotic custom contexts
+        return None
+
+
+def _ctx_path(ctx: Any) -> list[str]:
+    parts = []
+    while ctx is not None:
+        parts.append(ctx.info_name or ctx.command.name or "cli")
+        ctx = ctx.parent
+    return parts[::-1]
+
+
+def _list_commands(cmd: Any, ctx: Any) -> list[str]:
+    if hasattr(cmd, "list_commands") and ctx is not None:
+        return list(cmd.list_commands(ctx))
+    return list(getattr(cmd, "commands", {}) or {})
+
+
+def _get_command(cmd: Any, ctx: Any, name: str) -> Any:
+    if hasattr(cmd, "get_command") and ctx is not None:
+        return cmd.get_command(ctx, name)
+    return (getattr(cmd, "commands", {}) or {}).get(name)
+
+
+def _visible(p: Any) -> bool:
+    return not getattr(p, "hidden", False) and p.name not in INTERNAL_PARAMS
+
+
+def _param(p: Any) -> Param:
+    kind = "option" if p.param_type_name == "option" else "argument"
+    ptype = p.type
+    count = bool(getattr(p, "count", False))
+    is_flag = bool(getattr(p, "is_flag", False)) or count
+    envvar = getattr(p, "envvar", None)
+    nargs = p.nargs
+    value_tokens = None
+    if not is_flag:
+        if _is_tuple(ptype):
+            value_tokens = [_value_token(t) for t in ptype.types]
+        elif isinstance(nargs, int) and nargs > 1:
+            value_tokens = [_value_token(ptype)] * nargs
+    choices = getattr(ptype, "choices", None)
+    return Param(
+        name=p.name or "",
+        kind=kind,
+        opts=list(p.opts),
+        secondary_opts=list(getattr(p, "secondary_opts", []) or []),
+        type="bool" if is_flag and not count else type_name(ptype),
+        choices=[str(_plain(c)) for c in choices] if choices and not count else None,
+        required=bool(p.required),
+        default=None if count else _default(p, is_flag),
+        is_flag=is_flag,
+        multiple=bool(getattr(p, "multiple", False)) or nargs == -1 or count,
+        nargs=nargs,
+        envvars=[envvar] if isinstance(envvar, str) else list(envvar or []),
+        help=_clean(getattr(p, "help", None)),
+        metavar=p.metavar,
+        value_tokens=value_tokens,
+        count=count,
+        range=None if count else _range(ptype),
+        case_insensitive=choices is not None and getattr(ptype, "case_sensitive", True) is False,
+        prompts=bool(getattr(p, "prompt", None)),
+        optional_value=bool(getattr(p, "_flag_needs_value", False)),
+    )
+
+
+def type_name(ptype: Any) -> str:
+    """Stable, lowercase name of a Click parameter type."""
+    name = str(getattr(ptype, "name", None) or type(ptype).__name__).lower()
+    name = name.replace("_", " ")
+    if name.endswith(" range"):
+        name = name[: -len(" range")]
+    return _TYPE_NAMES.get(name, name).replace(" ", "_")
+
+
+def _is_tuple(ptype: Any) -> bool:
+    return isinstance(getattr(ptype, "types", None), (list, tuple)) and getattr(ptype, "is_composite", False)
+
+
+def _value_token(ptype: Any) -> str:
+    choices = getattr(ptype, "choices", None)
+    if choices:
+        return "[" + "|".join(str(_plain(c)) for c in choices) + "]"
+    return type_name(ptype).upper()
+
+
+def _range(ptype: Any) -> str | None:
+    if not hasattr(ptype, "min_open"):
+        return None
+    lo, hi = getattr(ptype, "min", None), getattr(ptype, "max", None)
+    lo_op = "<" if ptype.min_open else "<="
+    hi_op = "<" if ptype.max_open else "<="
+    if lo is not None and hi is not None:
+        return f"{lo}{lo_op}x{hi_op}{hi}"
+    if lo is not None:
+        return f"x{'>' if ptype.min_open else '>='}{lo}"
+    if hi is not None:
+        return f"x{hi_op}{hi}"
+    return None
+
+
+def _default(p: Any, is_flag: bool) -> str | None:
+    value = p.default
+    if value is None or callable(value) or type(value).__name__ == "Sentinel":
+        return None
+    if is_flag and value is False and not getattr(p, "secondary_opts", None):
+        return None
+    if isinstance(value, (list, tuple)):
+        if not value:
+            return None
+        return ", ".join(str(_plain(v)) for v in value)
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if value == "":
+        return None
+    return str(_plain(value))
+
+
+def _plain(value: Any) -> Any:
+    return value.value if isinstance(value, enum.Enum) else value
+
+
+def _short_help(cmd: Any) -> str | None:
+    if getattr(cmd, "short_help", None):
+        return _clean(cmd.short_help, strip_deprecated=True)
+    getter = getattr(cmd, "get_short_help_str", None)
+    if getter is None:
+        return None
+    try:
+        text = getter(limit=200)
+    except TypeError:  # pragma: no cover - very old Click
+        text = getter()
+    return _clean(text, strip_deprecated=True)
+
+
+def _clean(text: str | None, *, strip_deprecated: bool = False) -> str | None:
+    if not text:
+        return None
+    # Click's "\b" marks a paragraph that must not be rewrapped; drop it.
+    lines = [line for line in inspect.cleandoc(text).splitlines() if line.strip() != "\b"]
+    text = "\n".join(lines).strip()
+    if strip_deprecated:
+        text = _DEPRECATED_RE.sub(" ", text).strip()
+    return text or None