pytest icon indicating copy to clipboard operation
pytest copied to clipboard

docs: fix misleading docstring about default vs skip=True in getoption

Open midoriao opened this issue 1 month ago • 2 comments

This PR clarifies the pytest.Config.getoption docstring to make the exceptional behavior of default with skip=True explicit.

Also adds a small test verifying that behavior.

Stituation before this change

The previous docstring implied:

  • The default parameter is ignored when the option is declared.

But actual behavior is:

  • The default is not ignored even if the option is declared, when skip=True and the option has None value.

This can be reproduced by the following test case (already existing in testing/test_config.py):

def test_config_getoption_declared_option_name(self, pytester: Pytester) -> None:
	pytester.makeconftest(
		"""
		def pytest_addoption(parser):
			parser.addoption("--hello", "-X", dest="hello")
	"""
	)
	config_novalue = pytester.parseconfig()
	assert config_novalue.getoption("hello", default=1, skip=True) == 1

Rationale

The getoption() behavior involves multiple conditions (whether the option is declared or not, None or not, default, skip), which previously made the docstring easy to misinterpret. This PR avoids multiple "note that ..." caveats and keeps each parameter’s description self-contained and readable.

  • The docstring now describes the skip=True special case in plain language.
  • The misleading reference to the pytest_addoption hook was removed, since this method’s behavior is independent of how the option was added.
  • The emphasis markup of **declared** was removed.
    • It was intended to hint that an option might be declared but still have a None value (context: #12886). The new wording states this condition explicitly.
  • Clarify the case when default=None and skip=True.

Notes

No behavior change; documentation and test addition only. Related historical issue: #10558

midoriao avatar Nov 05 '25 08:11 midoriao