From 0acbca3af173b96b5897161b1dcd32606db87006 Mon Sep 17 00:00:00 2001
From: bastimeyer <mail@bastimeyer.de>
Date: Fri, 9 Feb 2024 01:22:55 +0100
Subject: [PATCH] docs: fix custom ext_argparse Sphinx extension

- Move the `parser_helper()` function from `streamlink_cli.main`
  into the `streamlink_cli._parser` module
- Refactor `ext_argparse` and set default import paths
- Update import path in `build-shell-completions.sh`

Unfortunately, the `streamlink_cli._parser` module can't be excluded
from the sdist/wheel distributions, as packagers might build
shell completions from the installed `streamlink_cli` package
instead of using the pre-built shell completions included in the sdist
or building them from an editable install.
---
 docs/_man.rst                     |  2 --
 docs/cli.rst                      |  2 --
 docs/ext_argparse.py              | 32 +++++++++++++++++++++----------
 script/build-shell-completions.sh |  2 +-
 src/streamlink_cli/_parser.py     | 16 ++++++++++++++++
 src/streamlink_cli/main.py        |  7 -------
 6 files changed, 39 insertions(+), 22 deletions(-)
 create mode 100644 src/streamlink_cli/_parser.py

diff --git a/docs/_man.rst b/docs/_man.rst
index 8c7cda11..9e85856d 100644
--- a/docs/_man.rst
+++ b/docs/_man.rst
@@ -31,8 +31,6 @@ Options
 -------
 
 .. argparse::
-    :module: streamlink_cli.main
-    :attr: parser_helper
 
 
 Bugs
diff --git a/docs/cli.rst b/docs/cli.rst
index d1550990..130382b2 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -24,5 +24,3 @@ Command-line usage
 
 
 .. argparse::
-    :module: streamlink_cli.main
-    :attr: parser_helper
diff --git a/docs/ext_argparse.py b/docs/ext_argparse.py
index 098c7533..05150187 100644
--- a/docs/ext_argparse.py
+++ b/docs/ext_argparse.py
@@ -9,12 +9,14 @@ Inspired by sphinxcontrib.autoprogram but with a few differences:
 
 import argparse
 import re
+from importlib import import_module
 from textwrap import dedent
 
 from docutils import nodes
 from docutils.parsers.rst import Directive
 from docutils.parsers.rst.directives import unchanged
 from docutils.statemachine import ViewList
+from sphinx.errors import ExtensionError
 from sphinx.util.nodes import nested_parse_with_titles
 
 
@@ -29,12 +31,6 @@ _inline_code_block_re = re.compile(r"(?<!`)`([^`]+?)`")
 _example_inline_code_block_re = re.compile(r"(?<=^Example: )(.+)$", re.MULTILINE)
 
 
-def get_parser(module_name, attr):
-    module = __import__(module_name, globals(), locals(), [attr])
-    parser = getattr(module, attr)
-    return parser if not callable(parser) else parser()
-
-
 def indent(value, length=4):
     space = " " * length
     return "\n".join(space + line for line in value.splitlines())
@@ -49,6 +45,23 @@ class ArgparseDirective(Directive):
 
     _headlines = ["^", "~"]
 
+    _DEFAULT_MODULE = "streamlink_cli._parser"
+    _DEFAULT_ATTR = "get_parser"
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._available_options = []
+
+    @staticmethod
+    def get_parser(module: str, attr: str) -> argparse.ArgumentParser:
+        try:
+            mod = import_module(module)
+            obj = getattr(mod, attr)
+        except Exception as err:
+            raise ExtensionError("Invalid ext_argparse module or attr value") from err
+
+        return obj() if callable(obj) else obj
+
     def process_help(self, helptext):
         # Dedent the help to make sure we are always dealing with
         # non-indented text.
@@ -156,11 +169,10 @@ class ArgparseDirective(Directive):
                 yield from self.generate_parser_rst(parser, group, depth + 1)
 
     def run(self):
-        module = self.options.get("module")
-        attr = self.options.get("attr")
-        parser = get_parser(module, attr)
+        module = self.options.get("module", self._DEFAULT_MODULE)
+        attr = self.options.get("attr", self._DEFAULT_ATTR)
+        parser = self.get_parser(module, attr)
 
-        self._available_options = []
         for action in parser._actions:
             # positional parameters have an empty option_strings list
             self._available_options += action.option_strings or [action.dest]
diff --git a/script/build-shell-completions.sh b/script/build-shell-completions.sh
index 7dfd1ded..1ca53cd7 100755
--- a/script/build-shell-completions.sh
+++ b/script/build-shell-completions.sh
@@ -23,7 +23,7 @@ for shell in "${!COMPLETIONS[@]}"; do
   python -m shtab \
     "--shell=${shell}" \
     --error-unimportable \
-    streamlink_cli.main.parser_helper \
+    streamlink_cli._parser.get_parser \
     > "${dist}"
   echo "Completions for ${shell} written to ${dist}"
 done
diff --git a/src/streamlink_cli/_parser.py b/src/streamlink_cli/_parser.py
new file mode 100644
index 00000000..8b3efea1
--- /dev/null
+++ b/src/streamlink_cli/_parser.py
@@ -0,0 +1,16 @@
+"""
+Utility module for importing Streamlink's argparse.ArgumentParser instance
+when building the documentation, man page or command-line shell completions.
+"""
+
+from streamlink.session import Streamlink
+from streamlink_cli.argparser import build_parser
+from streamlink_cli.main import setup_plugin_args
+
+
+def get_parser():
+    session = Streamlink(plugins_builtin=True)
+    parser = build_parser()
+    setup_plugin_args(session, parser)
+
+    return parser
diff --git a/src/streamlink_cli/main.py b/src/streamlink_cli/main.py
index e485a55a..fc2a94ed 100644
--- a/src/streamlink_cli/main.py
+++ b/src/streamlink_cli/main.py
@@ -952,10 +952,3 @@ def main():
         )
 
     sys.exit(error_code)
-
-
-def parser_helper():
-    session = Streamlink(plugins_builtin=True)
-    parser = build_parser()
-    setup_plugin_args(session, parser)
-    return parser