Mypy

Author: AA-Turner

sphinxarg/ext.py

@@ -28,6 +28,8 @@
 from sphinxarg.utils import command_pos_args, target_to_anchor_id
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from docutils.nodes import Element
     from sphinx.addnodes import pending_xref
     from sphinx.application import Sphinx
@@ -152,7 +154,7 @@ class ArgParseDirective(SphinxDirective):
         'idxgroups': unchanged,
     }
     domain: Domain | None = None
-    idxgroups: list[str] | None = None
+    idxgroups: Sequence[str] = ()
 
     def _construct_manpage_specific_structure(self, parser_info):
         """
@@ -728,8 +730,10 @@ class SphinxArgParseDomain(Domain):
     name = 'commands'
     label = 'commands-label'
 
-    roles = {'command': XRefRole()}
-    indices = {}
+    roles = {
+        'command': XRefRole(),
+    }
+    indices = []
     initial_data: dict[str, list | dict] = {
         'commands': [],
         'commands-by-group': defaultdict(list),
@@ -773,7 +777,7 @@ def resolve_xref(
             logger.warning(msg)
             return None
 
-    def add_command(self, result: dict, anchor: str, groups: list[str] = None):
+    def add_command(self, result: dict, anchor: str, groups: Sequence[str] = ()):
         """Add an argparse command to the domain."""
         full_command = command_pos_args(result)
         desc = 'No description.'
@@ -786,7 +790,7 @@ def add_command(self, result: dict, anchor: str, groups: list[str] = None):
         # A separate list is kept to avoid the edge case that a command is used
         # once as part of a group (with idxgroups) and another time without the
         # option.
-        for group in groups or []:
+        for group in groups:
             self.data['commands-by-group'][group].append(idx_entry)
 
 

test/conftest.py

@@ -1,6 +1,5 @@
 """Test HTML output the same way that Sphinx does in test_build_html.py."""
 
-from itertools import chain, cycle
 from pathlib import Path
 
 import pytest
@@ -67,7 +66,3 @@ def parse(fname):
 
     yield parse
     etree_cache.clear()
-
-
-def flat_dict(d):
-    return chain.from_iterable([zip(cycle([fname]), values) for fname, values in d.items()])

test/test_commands_by_group_index.py

@@ -4,49 +4,71 @@
 import pytest
 
 from sphinxarg.ext import CommandsByGroupIndex
-
-from .conftest import check_xpath, flat_dict
+from test.utils.xpath import check_xpath
 
 
 @pytest.mark.parametrize(
     ('fname', 'expect'),
-    flat_dict({
-        'index.html': [
+    [
+        (
+            'index.html',
             (".//div[@role='navigation']//a[@class='reference internal']", 'Sample'),
+        ),
+        (
+            'index.html',
             (".//div[@role='navigation']//a[@class='reference internal']", 'Command A'),
+        ),
+        (
+            'index.html',
             (".//div[@role='navigation']//a[@class='reference internal']", 'Command B'),
+        ),
+        (
+            'index.html',
             (
                 ".//div[@role='navigation']//a[@class='reference internal']",
                 'Commands by Group',
             ),
-        ],
-        'commands-by-group.html': [
-            ('.//h1', 'Commands by Group'),
-            ('.//tr/td[2]/strong', 'ham in a cone'),
+        ),
+        ('commands-by-group.html', ('.//h1', 'Commands by Group')),
+        ('commands-by-group.html', ('.//tr/td[2]/strong', 'ham in a cone')),
+        (
+            'commands-by-group.html',
             (
                 ".//tr[td[2]/strong/text()='ham in a cone']/following-sibling::tr[1]/td[2]/a/code",  # NoQA: E501
                 'sample-directive-opts',
             ),
+        ),
+        (
+            'commands-by-group.html',
             (
                 ".//tr[td[2]/strong/text()='ham in a cone']/following-sibling::tr[2]/td[2]/a/code",  # NoQA: E501
                 'sample-directive-opts B',
             ),
-            ('.//tr/td[2]/strong', 'spam'),
+        ),
+        ('commands-by-group.html', ('.//tr/td[2]/strong', 'spam')),
+        (
+            'commands-by-group.html',
             (
                 ".//tr[td[2]/strong/text()='spam on a stick']/following-sibling::tr[1]/td[2]/a/code",  # NoQA: E501
                 'sample-directive-opts',
             ),
+        ),
+        (
+            'commands-by-group.html',
             (
                 ".//tr[td[2]/strong/text()='spam on a stick']/following-sibling::tr[2]/td[2]/a/code",  # NoQA: E501
                 'sample-directive-opts A',
             ),
+        ),
+        (
+            'commands-by-group.html',
             (
                 './/tr/td[2]/em',
                 '(other)',
                 False,
-            ),  # Other does not have idxgroups set at all and is not present.
-        ],
-    }),
+            ),
+        ),  # Other does not have idxgroups set at all and is not present.
+    ],
 )
 @pytest.mark.sphinx('html', testroot='command-by-group-index')
 def test_commands_by_group_index_html(app, cached_etree_parse, fname, expect):
@@ -56,18 +78,17 @@ def test_commands_by_group_index_html(app, cached_etree_parse, fname, expect):
 
 @pytest.mark.parametrize(
     ('fname', 'expect'),
-    flat_dict({
-        'index.html': [
+    [
+        (
+            'index.html',
             (
                 ".//div[@role='navigation']//a[@class='reference internal']",
                 'Commands grouped by SomeName',
             ),
-        ],
-        'commands-groupedby-somename.html': [
-            ('.//h1', 'Commands grouped by SomeName'),
-            ('.//h1', 'Commands by Group', False),
-        ],
-    }),
+        ),
+        ('commands-groupedby-somename.html', ('.//h1', 'Commands grouped by SomeName')),
+        ('commands-groupedby-somename.html', ('.//h1', 'Commands by Group', False)),
+    ],
 )
 @pytest.mark.sphinx(
     'html',

test/test_commands_index.py

@@ -1,29 +1,26 @@
 import pytest
 
-from .conftest import check_xpath, flat_dict
+from test.utils.xpath import check_xpath
 
 
 @pytest.mark.parametrize(
     ('fname', 'expect'),
-    flat_dict({
-        'subcommand-a.html': [
-            ('.//h1', 'Sample', False),
-            ('.//h1', 'Command A'),
-        ],
-        'subcommand-b.html': [
-            ('.//h1', 'Sample', False),
-            ('.//h1', 'Command B'),
-        ],
-        'commands-index.html': [
-            ('.//h1', 'Commands Index'),
-            ('.//tr/td[2]/a/code', 'sample-directive-opts'),
-            ('.//tr/td[3]/em', 'Support SphinxArgParse HTML testing'),
+    [
+        ('subcommand-a.html', ('.//h1', 'Sample', False)),
+        ('subcommand-a.html', ('.//h1', 'Command A')),
+        ('subcommand-b.html', ('.//h1', 'Sample', False)),
+        ('subcommand-b.html', ('.//h1', 'Command B')),
+        ('commands-index.html', ('.//h1', 'Commands Index')),
+        ('commands-index.html', ('.//tr/td[2]/a/code', 'sample-directive-opts')),
+        ('commands-index.html', ('.//tr/td[3]/em', 'Support SphinxArgParse HTML testing')),
+        (
+            'commands-index.html',
             (
                 ".//tr[td[2]/a/code/text()='sample-directive-opts']/td[3]/em",
                 'Support SphinxArgParse HTML testing',
             ),
-        ],
-    }),
+        ),
+    ],
 )
 @pytest.mark.sphinx('html', testroot='command-index')
 def test_commands_index_html(app, cached_etree_parse, fname, expect):

test/test_conf_options_html.py

@@ -2,19 +2,17 @@
 
 import pytest
 
-from .conftest import check_xpath, flat_dict
+from test.utils.xpath import check_xpath
 
 
 @pytest.mark.parametrize(
     ('fname', 'expect'),
-    flat_dict({
-        'index.html': [
-            ('.//h1', 'Sample'),
-            ('.//h2', 'Sub-commands'),
-            ('.//h3', 'sample-directive-opts A'),  # By default, just "A".
-            ('.//h3', 'sample-directive-opts B'),
-        ],
-    }),
+    [
+        ('index.html', ('.//h1', 'Sample')),
+        ('index.html', ('.//h2', 'Sub-commands')),
+        ('index.html', ('.//h3', 'sample-directive-opts A')),  # By default, just "A".
+        ('index.html', ('.//h3', 'sample-directive-opts B')),
+    ],
 )
 @pytest.mark.sphinx(
     'html',

test/test_default_html.py

@@ -1,52 +1,11 @@
 """Test the HTML builder and check output against XPath."""
 
 import posixpath
-import re
 
 import pytest
-from sphinx.ext.intersphinx import INVENTORY_FILENAME
 from sphinx.util.inventory import Inventory, InventoryFile
 
-
-def check_xpath(etree, fname, path, check, be_found=True):
-    nodes = list(etree.xpath(path))
-    if check is None:
-        assert nodes == [], f'found any nodes matching xpath {path!r} in file {fname}'
-        return
-    else:
-        assert nodes != [], f'did not find any node matching xpath {path!r} in file {fname}'
-    if callable(check):
-        check(nodes)
-    elif not check:
-        # only check for node presence
-        pass
-    else:
-
-        def get_text(node):
-            if node.text is not None:
-                # the node has only one text
-                return node.text
-            else:
-                # the node has tags and text; gather texts just under the node
-                return ''.join(n.tail or '' for n in node)
-
-        rex = re.compile(check)
-        if be_found:
-            if any(rex.search(get_text(node)) for node in nodes):
-                return
-            msg = (
-                f'{check!r} not found in any node matching path {path} in {fname}: '
-                f'{[node.text for node in nodes]!r}'
-            )
-        else:
-            if all(not rex.search(get_text(node)) for node in nodes):
-                return
-            msg = (
-                f'Found {check!r} in a node matching path {path} in {fname}: '
-                f'{[node.text for node in nodes]!r}'
-            )
-
-        raise AssertionError(msg)
+from test.utils.xpath import check_xpath
 
 
 @pytest.mark.parametrize(
@@ -134,7 +93,7 @@ def test_index_is_optional(app, cached_etree_parse):
 @pytest.mark.sphinx('html', testroot='default-html')
 def test_object_inventory(app, cached_etree_parse):
     app.build()
-    inventory_file = app.outdir / INVENTORY_FILENAME
+    inventory_file = app.outdir / 'objects.inv'
     assert inventory_file.exists() is True
 
     with inventory_file.open('rb') as f:

test/utils/__init__.py

@@ -0,0 +1,42 @@
+import re
+
+
+def check_xpath(etree, fname, path, check, be_found=True):
+    nodes = list(etree.xpath(path))
+    if check is None:
+        assert nodes == [], f'found any nodes matching xpath {path!r} in file {fname}'
+        return
+    else:
+        assert nodes != [], f'did not find any node matching xpath {path!r} in file {fname}'
+    if callable(check):
+        check(nodes)
+    elif not check:
+        # only check for node presence
+        pass
+    else:
+
+        def get_text(node):
+            if node.text is not None:
+                # the node has only one text
+                return node.text
+            else:
+                # the node has tags and text; gather texts just under the node
+                return ''.join(n.tail or '' for n in node)
+
+        rex = re.compile(check)
+        if be_found:
+            if any(rex.search(get_text(node)) for node in nodes):
+                return
+            msg = (
+                f'{check!r} not found in any node matching path {path} in {fname}: '
+                f'{[node.text for node in nodes]!r}'
+            )
+        else:
+            if all(not rex.search(get_text(node)) for node in nodes):
+                return
+            msg = (
+                f'Found {check!r} in a node matching path {path} in {fname}: '
+                f'{[node.text for node in nodes]!r}'
+            )
+
+        raise AssertionError(msg)