Add sphinx._cli

Author: AA-Turner

sphinx/_cli/__init__.py

@@ -0,0 +1,196 @@
+"""Base 'sphinx' command.
+
+Subcommands are loaded lazily from the ``_COMMANDS`` table for performance.
+
+All subcommand modules must define three attributes:
+
+- ``parser_description``, a description of the subcommand. The first paragraph
+  is taken as the short description for the command.
+- ``set_up_parser``, a callable taking and returning an ``ArgumentParser``. This
+  function is responsible for adding options and arguments to the subcommand's
+  parser.
+- ``run``, a callable taking parsed arguments and returning an exit code. This
+  function is responsible for running the main body of the subcommand and
+  returning the exit status.
+
+The entire ``sphinx._cli`` namespace is private, only the command line interface
+has backwards-compatability guarantees.
+"""
+
+from __future__ import annotations
+
+import argparse
+import locale
+import sys
+from typing import TYPE_CHECKING
+
+from sphinx._cli.util.colour import disable_colour, enable_colour, terminal_supports_colour
+from sphinx.locale import __, init_console
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator, Sequence
+
+    _PARSER_SETUP = Callable[[argparse.ArgumentParser], argparse.ArgumentParser]
+    _RUNNER = Callable[[argparse.Namespace], int]
+
+    if sys.version_info[:2] > (3, 8):
+        from typing import Protocol
+
+        class _SubcommandModule(Protocol):
+            parser_description: str
+            set_up_parser: _PARSER_SETUP  # takes and returns argument parser
+            run: _RUNNER  # takes parsed args, returns exit code
+    else:
+        from typing import Any as _SubcommandModule
+
+
+# Command name -> import path
+_COMMANDS: dict[str, str] = {
+}
+
+
+class _HelpFormatter(argparse.RawDescriptionHelpFormatter):
+    def _format_usage(self, usage, actions, groups, prefix):
+        if prefix is None:
+            prefix = __('Usage: ')
+        return super()._format_usage(usage, actions, groups, prefix)
+
+    def _format_args(self, action, default_metavar):
+        if action.nargs == argparse.REMAINDER:
+            return __('<command> [<args>]')
+        return super()._format_args(action, default_metavar)
+
+
+class _RootArgumentParser(argparse.ArgumentParser):
+    @staticmethod
+    def _load_subcommands() -> Iterator[tuple[str, str]]:
+        import importlib
+
+        for command, module_name in _COMMANDS.items():
+            module: _SubcommandModule = importlib.import_module(module_name)
+            try:
+                description = module.parser_description
+            except AttributeError:
+                continue
+            else:
+                yield command, description.split('\n\n', 1)[0]
+
+    def format_help(self):
+        formatter = self._get_formatter()
+        formatter.add_usage(self.usage, self._actions, [])
+        formatter.add_text(self.description)
+
+        formatter.start_section(__('Commands'))
+        for command_name, command_desc in self._load_subcommands():
+            formatter.add_argument(argparse.Action((), command_name, help=command_desc))
+        formatter.end_section()
+
+        formatter.start_section(__('Options'))
+        formatter.add_arguments(self._optionals._group_actions)
+        formatter.end_section()
+
+        formatter.add_text(self.epilog)
+        return formatter.format_help()
+
+
+def _create_parser() -> _RootArgumentParser:
+    parser = _RootArgumentParser(
+        prog='sphinx',
+        description=__('   Manage documentation with Sphinx.'),
+        epilog=__('For more information, visit <https://www.sphinx-doc.org/en/master/man/>.'),
+        formatter_class=_HelpFormatter,
+        add_help=False,
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        '--version', '-V',
+        action='store_true',
+        default=argparse.SUPPRESS,
+        help=__('Show the version and exit.'),
+    )
+    parser.add_argument(
+        '--help', '-h', '-?',
+        action='store_true',
+        default=argparse.SUPPRESS,
+        help=__('Show this message and exit.'),
+    )
+
+    parser.add_argument(
+        'COMMAND',
+        nargs='...',
+        metavar=__('<command>'),
+    )
+    return parser
+
+
+def _parse_command(argv: Sequence[str] = ()) -> tuple[str, Sequence[str]]:
+    parser = _create_parser()
+    args = parser.parse_args(argv)
+    command_name, *command_argv = args.COMMAND or ('help',)
+    command_name = command_name.lower()
+
+    # Handle '--version' or '-V' passed to the main command or any subcommand
+    if 'version' in args or {'-V', '--version'}.intersection(command_argv):
+        from sphinx import __display_version__
+        sys.stdout.write(f'sphinx {__display_version__}\n')
+        raise SystemExit(0)
+
+    # Handle '--help' or '-h' passed to the main command (subcommands may have
+    # their own help text)
+    if 'help' in args or command_name == 'help':
+        sys.stdout.write(parser.format_help())
+        raise SystemExit(0)
+
+    if command_name not in _COMMANDS:
+        sys.stderr.write(__(f'sphinx: {command_name!r} is not a sphinx command. '
+                            "See 'sphinx --help'.\n"))
+        raise SystemExit(2)
+
+    if args.colour == 'yes' or (args.colour == 'auto' and terminal_supports_colour()):
+        enable_colour()
+    else:
+        disable_colour()
+
+    return command_name, command_argv
+
+
+def _load_subcommand(command_name: str) -> tuple[str, _PARSER_SETUP, _RUNNER]:
+    import importlib
+
+    module: _SubcommandModule = importlib.import_module(_COMMANDS[command_name])
+    return module.parser_description, module.set_up_parser, module.run
+
+
+def _create_sub_parser(
+    command_name: str,
+    description: str,
+    parser_setup: _PARSER_SETUP,
+) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=f'sphinx {command_name}',
+        description=description,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+    )
+    return parser_setup(parser)
+
+
+def run(argv: Sequence[str] = (), /) -> int:
+    locale.setlocale(locale.LC_ALL, '')
+    init_console()
+
+    argv = argv or sys.argv[1:]
+    try:
+        cmd_name, cmd_argv = _parse_command(argv)
+        cmd_description, set_up_parser, runner = _load_subcommand(cmd_name)
+        cmd_parser = _create_sub_parser(cmd_name, cmd_description, set_up_parser)
+        cmd_args = cmd_parser.parse_args(cmd_argv)
+        return runner(cmd_args)
+    except SystemExit as exc:
+        return exc.code  # type: ignore[return-value]
+    except (Exception, KeyboardInterrupt):
+        return 2
+
+
+if __name__ == '__main__':
+    raise SystemExit(run())