Add option to hook argparse (#46)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: Schamper

README.md

@@ -34,6 +34,7 @@ Within the reStructuredText files use the `sphinx_argparse_cli` directive that t
 | module                 | the module path to where the parser is defined                                                                                                                                   |
 | func                   | the name of the function that once called with no arguments constructs the parser                                                                                                |
 | prog                   | (optional) the module path to where the parser is defined                                                                                                                        |
+| hook                   | (optional) hook `argparse` to retrieve the parser if `func` uses a parser instead of returning it.                                                                               |
 | title                  | (optional) when provided, overwrites the `<prog> - CLI interface` title added by default and when empty, will not be included                                                    |
 | usage_width            | (optional) how large should usage examples be - defaults to 100 character                                                                                                        |
 | group_title_prefix     | (optional) groups subsections title prefixes, accepts the string `{prog}` as a replacement for the program name - defaults to `{prog}`                                           |
@@ -48,6 +49,16 @@ For example:
   :prog: my-cli-program
 ```
 
+If you have code that creates and uses a parser but does not return it, you can specify the `:hook:` flag:
+
+```rst
+.. sphinx_argparse_cli::
+  :module: a_project.cli
+  :func: main
+  :hook:
+  :prog: my-cli-program
+```
+
 ### Refer to generated content
 
 The tool will register reference links to all anchors. This means that you can use the sphinx `ref` role to refer to

roots/test-hook-fail/conf.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+extensions = ["sphinx_argparse_cli"]
+nitpicky = True

roots/test-hook-fail/index.rst

@@ -0,0 +1,4 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: main
+  :hook:

roots/test-hook-fail/parser.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def main() -> None:
+    parser = ArgumentParser(prog="foo", add_help=False)
+    print(parser)

roots/test-hook/conf.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+extensions = ["sphinx_argparse_cli"]
+nitpicky = True

roots/test-hook/index.rst

@@ -0,0 +1,4 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: main
+  :hook:

roots/test-hook/parser.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser
+
+
+def main() -> None:
+    parser = ArgumentParser(prog="foo", add_help=False)
+    args = parser.parse_args()
+    print(args)

src/sphinx_argparse_cli/_logic.py

@@ -14,7 +14,7 @@
     _SubParsersAction,
 )
 from collections import defaultdict, namedtuple
-from typing import Iterator, cast
+from typing import Any, Iterator, cast
 
 from docutils.nodes import (
     Element,
@@ -32,7 +32,12 @@
     title,
     whitespace_normalize_name,
 )
-from docutils.parsers.rst.directives import positive_int, unchanged, unchanged_required
+from docutils.parsers.rst.directives import (
+    flag,
+    positive_int,
+    unchanged,
+    unchanged_required,
+)
 from docutils.parsers.rst.states import RSTState, RSTStateMachine
 from docutils.statemachine import StringList
 from sphinx.domains.std import StandardDomain
@@ -56,6 +61,7 @@ class SphinxArgparseCli(SphinxDirective):
     option_spec = {
         "module": unchanged_required,
         "func": unchanged_required,
+        "hook": flag,
         "prog": unchanged,
         "title": unchanged,
         "usage_width": positive_int,
@@ -86,10 +92,24 @@ def parser(self) -> ArgumentParser:
         if self._parser is None:
             module_name, attr_name = self.options["module"], self.options["func"]
             parser_creator = getattr(__import__(module_name, fromlist=[attr_name]), attr_name)
-            self._parser = parser_creator()
+            if "hook" in self.options:
+                original_parse_known_args = ArgumentParser.parse_known_args
+                ArgumentParser.parse_known_args = _argparse_parse_known_args_hook  # type: ignore
+                try:
+                    parser_creator()
+                except HookError as hooked:
+                    self._parser = hooked.parser
+                finally:
+                    ArgumentParser.parse_known_args = original_parse_known_args  # type: ignore
+            else:
+                self._parser = parser_creator()
+
+            del sys.modules[module_name]  # no longer needed cleanup
+            if self._parser is None:
+                raise self.error("Failed to hook argparse to get ArgumentParser")
+
             if "prog" in self.options:
                 self._parser.prog = self.options["prog"]
-            del sys.modules[module_name]  # no longer needed cleanup
         return self._parser
 
     def load_sub_parsers(self) -> Iterator[tuple[list[str], str, ArgumentParser]]:
@@ -319,4 +339,13 @@ def load_help_text(help_text: str) -> str:
     return literal_curly_braces
 
 
+class HookError(Exception):
+    def __init__(self, parser: ArgumentParser):
+        self.parser = parser
+
+
+def _argparse_parse_known_args_hook(self: ArgumentParser, *args: Any, **kwargs: Any) -> None:  # noqa: U100
+    raise HookError(self)
+
+
 __all__ = ("SphinxArgparseCli",)

tests/test_logic.py

@@ -58,6 +58,19 @@ def test_complex_as_html(build_outcome: str) -> None:
     assert build_outcome
 
 
+@pytest.mark.sphinx(buildername="html", testroot="hook")
+def test_hook(build_outcome: str) -> None:
+    assert build_outcome
+
+
+@pytest.mark.sphinx(buildername="text", testroot="hook-fail")
+def test_hook_fail(app: SphinxTestApp, warning: StringIO) -> None:
+    app.build()
+    text = (Path(app.outdir) / "index.txt").read_text()
+    assert "Failed to hook argparse to get ArgumentParser" in warning.getvalue()
+    assert text == ""
+
+
 @pytest.mark.sphinx(buildername="text", testroot="prog")
 def test_prog_as_text(build_outcome: str) -> None:
     assert build_outcome == "magic - CLI interface\n*********************\n\n   magic\n"
@@ -124,14 +137,10 @@ def test_ref_prefix_doc(build_outcome: str) -> None:
     assert ref in build_outcome
 
 
-_REF_WARNING_STRING_IO = StringIO()  # could not find any better way to get the warning
-
-
-@pytest.mark.sphinx(buildername="text", testroot="ref-duplicate-label", warning=_REF_WARNING_STRING_IO)
-def test_ref_duplicate_label(build_outcome: tuple[str, str]) -> None:
+@pytest.mark.sphinx(buildername="text", testroot="ref-duplicate-label")
+def test_ref_duplicate_label(build_outcome: tuple[str, str], warning: StringIO) -> None:
     assert build_outcome
-    warnings = _REF_WARNING_STRING_IO.getvalue()
-    assert "duplicate label prog---help" in warnings
+    assert "duplicate label prog---help" in warning.getvalue()
 
 
 @pytest.mark.sphinx(buildername="html", testroot="group-title-prefix-default")