This issue is also tripping me up. I have a project where I'd like to exclude certain third-party directories, but using match_dir means that pydocstyle no longer searches recursively for files.

So a practical example: in my config file, I have:

[pydocstyle]
match_dir = (\.|foo|tests)
match = .*\.py

This will match files in the top-level folder, foo/a.py, and tests/test_a.py. It will not match foo/bar/b.py nor tests/bar/test_b.py.

I have also tried: (\.|foo.*|tests.*), (\.|foo/.*|tests/.*), and (\.|foo/bar|tests/bar), all with the same result.

it seems that match and match_dir just check the pattern over the dir and file name .. not the full absolute or relative path ... is there a reason for that?

maybe I don't understand well the reasons .. but my first guess is that would be easier to apply the a match pattern using as parameter the full relative path (the absolute path could have an undesirable result).

probably related to this method https://github.com/PyCQA/pydocstyle/blob/master/src/pydocstyle/config.py#L124

For backward compatibility reasons there would probably need to be a match_path option that, by default, matched everything.

The only thing I could get to work was excluding directories by following the example here. I also could not figure out how to use a positive filter.

[pydocstyle]
match = (?!test_).*\.py
match_dir = ^(?!(venv|ci_tests|some_sub_dir)).*

Has there been any developments with matching directories using --match-dir? I would like to exclude all directories except for the directories mentioned in --match-dir.

Currently, I am trying to pass --match-dir as an argument to pydocstyle when using it as a pre-commit hook, however, it seems to not exclude directories and instead includes all directories.

An example of my .pre-commit-config.yaml file:

repos:
  ...
  - repo: https://github.com/pycqa/pydocstyle
    rev: 5.1.1
    hooks:
      - id: pydocstyle
        args:
          - --match-dir='^(src).*'

Solution

Pre-commit can restrict the files that are passed to pydocstyle using the files key, for example:

repos:
- repo: https://github.com/pycqa/pydocstyle
  rev: 5.1.1
  hooks:
  - id: pydocstyle
    files: ^src/

More information can be found here.