pytest-dev / pytest-dev/pytest

[doctest] Allow filtering which py files are considered for --doctest-modules

Open
#11,716 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

plugin: doctests type: proposal
Dominant language
Python
Stars
14.5k
Forks
3.4k
Avg merge
2d 9h
Merged PRs (30d)
35

Description

When doctestmodules is True, we unconditionally attempt to doctest all files, except for a few explicitly denylisted file names:

    if file_path.suffix == ".py":
        if config.option.doctestmodules and not any(
            (_is_setup_py(file_path), _is_main_py(file_path))
        ):
            mod: DoctestModule = DoctestModule.from_parent(parent, path=file_path)
            return mod

In some situations, such as happened in https://github.com/pytest-dev/pytest/issues/1881, it would be useful to limit the set of files to be doctested; e.g., a fairly common desire is to only doctest files in src/, and not bother trying to doctest test files. In my situation, I have a repository that has a number of scripts that do not have __name__ == '__main__' guards, and doctest immediately chokes on them.

The fix is relatively simple, subject to bikeshedding how exactly the option should be spelled. I would propose we name the new option --doctest-modules-glob, and have it work equivalently to --doctest-glob but generating DoctestModule instead of DoctestTextFile. I can submit the PR, if someone agrees to help shepherd it. Thanks!

(This is technically a dupe of https://github.com/pytest-dev/pytest/issues/1881 but I am submitting a fresh issue because there's a lot of irrelevant noise in the original issue.)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The relevant entry point is the --doctest-modules collection branch shown in the issue; compare its file matching with --doctest-glob. Add coverage for selecting module files while excluding nonmatching files, and verify that the existing setup.py and main.py exclusions still hold.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
testing
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.