test: make Constants attribute docstring doctests actually run#195
Merged
Conversation
Constants class attributes document their default with a bare string literal after the assignment (e.g. patronymic_name_order = False / """..."""), Sphinx's attribute-docstring convention. That string is never a real __doc__, so doctest.DocTestFinder (and pytest's --doctest-modules) never discovers the .. doctest:: examples inside it -- they can silently go stale, which already happened once for middle_name_as_last. Add tests/test_config_attribute_docstrings.py, which parses the source with ast to recover those literals (the same info Sphinx's static analysis reads) and runs any doctest examples through doctest.DocTestParser/DocTestRunner, so pytest -q now exercises them. Discovery also caught a second dormant docstring (empty_attribute_default) with its own bugs: a missing space after >>> and an expectation of literal None output where the REPL prints nothing for None.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Constantsclass attributes (e.g.patronymic_name_order,middle_name_as_last) document their behavior with a bare string literal placed right after the assignment — Sphinx's attribute-docstring convention. That string never becomes a real__doc__, sodoctest.DocTestFinder(and pytest's--doctest-modules, enabled viaaddopts) never discovers the.. doctest::examples inside it. This let a stale example slip through CI once already (middle_name_as_last, Weak Arabic Name handling #133).tests/test_config_attribute_docstrings.py, which parsesnameparser/config/__init__.pywithastto recover those literals (the same source-level info Sphinx's autodoc reads) and runs any.. doctest::examples found throughdoctest.DocTestParser/DocTestRunner, sopytest -qnow actually exercises them — no separate copy of the example text to keep in sync.empty_attribute_default) with two real bugs: a missing space after>>>and an expectation of literalNoneoutput where the REPL actually prints nothing for aNoneresult. Both fixed.Test plan
pytest -q— full suite passes (1046 passed, 4 skipped, 22 xfailed)ruff check/mypyon touched files — cleanmiddle_name_as_last's expected doctest output, confirmedpytest -qfailed with a clear diff, then reverted and confirmed green again🤖 Generated with Claude Code