Fix help sections for CLI options

changelog/13221.doc.rst

@@ -0,0 +1 @@
+Improved grouping of CLI options in the ``--help`` output.

src/_pytest/capture.py

@@ -48,15 +48,15 @@
 
 def pytest_addoption(parser: Parser) -> None:
     group = parser.getgroup("general")
-    group._addoption(
+    group.addoption(
         "--capture",
         action="store",
         default="fd",
         metavar="method",
         choices=["fd", "sys", "no", "tee-sys"],
         help="Per-test capturing method: one of fd|sys|no|tee-sys",
     )
-    group._addoption(
+    group._addoption(  # private to use reserved lower-case short option
         "-s",
         action="store_const",
         const="no",

src/_pytest/debugging.py

@@ -40,21 +40,21 @@ def _validate_usepdb_cls(value: str) -> tuple[str, str]:
 
 def pytest_addoption(parser: Parser) -> None:
     group = parser.getgroup("general")
-    group._addoption(
+    group.addoption(
         "--pdb",
         dest="usepdb",
         action="store_true",
         help="Start the interactive Python debugger on errors or KeyboardInterrupt",
     )
-    group._addoption(
+    group.addoption(
         "--pdbcls",
         dest="usepdb_cls",
         metavar="modulename:classname",
         type=_validate_usepdb_cls,
         help="Specify a custom interactive Python debugger for use with --pdb."
         "For example: --pdbcls=IPython.terminal.debugger:TerminalPdb",
     )
-    group._addoption(
+    group.addoption(
         "--trace",
         dest="trace",
         action="store_true",

src/_pytest/helpconfig.py

@@ -55,14 +55,14 @@ def pytest_addoption(parser: Parser) -> None:
         help="Display pytest version and information about plugins. "
         "When given twice, also display information about plugins.",
     )
-    group._addoption(
+    group._addoption(  # private to use reserved lower-case short option
         "-h",
         "--help",
         action=HelpAction,
         dest="help",
         help="Show help message and configuration info",
     )
-    group._addoption(
+    group._addoption(  # private to use reserved lower-case short option
         "-p",
         action="append",
         dest="plugins",
@@ -90,7 +90,7 @@ def pytest_addoption(parser: Parser) -> None:
         "This file is opened with 'w' and truncated as a result, care advised. "
         "Default: pytestdebug.log.",
     )
-    group._addoption(
+    group._addoption(  # private to use reserved lower-case short option
         "-o",
         "--override-ini",
         dest="override_ini",

src/_pytest/main.py

@@ -54,59 +54,16 @@
 
 
 def pytest_addoption(parser: Parser) -> None:
-    parser.addini(
-        "norecursedirs",
-        "Directory patterns to avoid for recursion",
-        type="args",
-        default=[
-            "*.egg",
-            ".*",
-            "_darcs",
-            "build",
-            "CVS",
-            "dist",
-            "node_modules",
-            "venv",
-            "{arch}",
-        ],
-    )
-    parser.addini(
-        "testpaths",
-        "Directories to search for tests when no files or directories are given on the "
-        "command line",
-        type="args",
-        default=[],
-    )
-    parser.addini(
-        "collect_imported_tests",
-        "Whether to collect tests in imported modules outside `testpaths`",
-        type="bool",
-        default=True,
-    )
     group = parser.getgroup("general", "Running and selection options")
-    group._addoption(
+    group._addoption(  # private to use reserved lower-case short option
         "-x",
         "--exitfirst",
         action="store_const",
         dest="maxfail",
         const=1,
         help="Exit instantly on first error or failed test",
     )
-    group = parser.getgroup("pytest-warnings")
     group.addoption(
-        "-W",
-        "--pythonwarnings",
-        action="append",
-        help="Set which warnings to report, see -W option of Python itself",
-    )
-    parser.addini(
-        "filterwarnings",
-        type="linelist",
-        help="Each line specifies a pattern for "
-        "warnings.filterwarnings. "
-        "Processed after -W/--pythonwarnings.",
-    )
-    group._addoption(
         "--maxfail",
         metavar="num",
         action="store",
@@ -115,46 +72,37 @@ def pytest_addoption(parser: Parser) -> None:
         default=0,
         help="Exit after first num failures or errors",
     )
-    group._addoption(
+    group.addoption(
         "--strict-config",
         action="store_true",
         help="Any warnings encountered while parsing the `pytest` section of the "
         "configuration file raise errors",
     )
-    group._addoption(
+    group.addoption(
         "--strict-markers",
         action="store_true",
         help="Markers not registered in the `markers` section of the configuration "
         "file raise errors",
     )
-    group._addoption(
+    group.addoption(
         "--strict",
         action="store_true",
         help="(Deprecated) alias to --strict-markers",
     )
-    group._addoption(
-        "-c",
-        "--config-file",
-        metavar="FILE",
-        type=str,
-        dest="inifilename",
-        help="Load configuration from `FILE` instead of trying to locate one of the "
-        "implicit configuration files.",
-    )
-    group._addoption(
-        "--continue-on-collection-errors",
-        action="store_true",
-        default=False,
-        dest="continue_on_collection_errors",
-        help="Force test execution even if collection errors occur",
+
+    group = parser.getgroup("pytest-warnings")
+    group.addoption(
+        "-W",
+        "--pythonwarnings",
+        action="append",
+        help="Set which warnings to report, see -W option of Python itself",
     )
-    group._addoption(
-        "--rootdir",
-        action="store",
-        dest="rootdir",
-        help="Define root directory for tests. Can be relative path: 'root_dir', './root_dir', "
-        "'root_dir/another_dir/'; absolute path: '/home/user/root_dir'; path with variables: "
-        "'$HOME/root_dir'.",
+    parser.addini(
+        "filterwarnings",
+        type="linelist",
+        help="Each line specifies a pattern for "
+        "warnings.filterwarnings. "
+        "Processed after -W/--pythonwarnings.",
     )
 
     group = parser.getgroup("collect", "collection")
@@ -218,6 +166,13 @@ def pytest_addoption(parser: Parser) -> None:
         default=False,
         help="Don't ignore tests in a local virtualenv directory",
     )
+    group.addoption(
+        "--continue-on-collection-errors",
+        action="store_true",
+        default=False,
+        dest="continue_on_collection_errors",
+        help="Force test execution even if collection errors occur",
+    )
     group.addoption(
         "--import-mode",
         default="prepend",
@@ -226,6 +181,35 @@ def pytest_addoption(parser: Parser) -> None:
         help="Prepend/append to sys.path when importing test modules and conftest "
         "files. Default: prepend.",
     )
+    parser.addini(
+        "norecursedirs",
+        "Directory patterns to avoid for recursion",
+        type="args",
+        default=[
+            "*.egg",
+            ".*",
+            "_darcs",
+            "build",
+            "CVS",
+            "dist",
+            "node_modules",
+            "venv",
+            "{arch}",
+        ],
+    )
+    parser.addini(
+        "testpaths",
+        "Directories to search for tests when no files or directories are given on the "
+        "command line",
+        type="args",
+        default=[],
+    )
+    parser.addini(
+        "collect_imported_tests",
+        "Whether to collect tests in imported modules outside `testpaths`",
+        type="bool",
+        default=True,
+    )
     parser.addini(
         "consider_namespace_packages",
         type="bool",
@@ -234,6 +218,23 @@ def pytest_addoption(parser: Parser) -> None:
     )
 
     group = parser.getgroup("debugconfig", "test session debugging and configuration")
+    group._addoption(  # private to use reserved lower-case short option
+        "-c",
+        "--config-file",
+        metavar="FILE",
+        type=str,
+        dest="inifilename",
+        help="Load configuration from `FILE` instead of trying to locate one of the "
+        "implicit configuration files.",
+    )
+    group.addoption(
+        "--rootdir",
+        action="store",
+        dest="rootdir",
+        help="Define root directory for tests. Can be relative path: 'root_dir', './root_dir', "
+        "'root_dir/another_dir/'; absolute path: '/home/user/root_dir'; path with variables: "
+        "'$HOME/root_dir'.",
+    )
     group.addoption(
         "--basetemp",
         dest="basetemp",

src/_pytest/mark/__init__.py

@@ -79,7 +79,7 @@ def test_eval(test_input, expected):
 
 def pytest_addoption(parser: Parser) -> None:
     group = parser.getgroup("general")
-    group._addoption(
+    group._addoption(  # private to use reserved lower-case short option
         "-k",
         action="store",
         dest="keyword",
@@ -99,7 +99,7 @@ def pytest_addoption(parser: Parser) -> None:
         "The matching is case-insensitive.",
     )
 
-    group._addoption(
+    group._addoption(  # private to use reserved lower-case short option
         "-m",
         action="store",
         dest="markexpr",

src/_pytest/pastebin.py

@@ -20,7 +20,7 @@
 
 def pytest_addoption(parser: Parser) -> None:
     group = parser.getgroup("terminal reporting")
-    group._addoption(
+    group.addoption(
         "--pastebin",
         metavar="mode",
         action="store",