Skip to content

Commit

Permalink
test/doc: add more tests of star behavior, and document it.
Browse files Browse the repository at this point in the history
  • Loading branch information
nedbat committed Aug 30, 2023
1 parent df8d143 commit c2fa035
Show file tree
Hide file tree
Showing 3 changed files with 62 additions and 6 deletions.
11 changes: 9 additions & 2 deletions CHANGES.rst
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,15 @@ development at the same time, such as 4.5.x and 5.0.
Unreleased
----------

Nothing yet.
- The semantics of stars in file patterns has been clarified in the docs. A
leading or trailing star matches any number of path components, like a double
star would. This is different than the behavior of a star in the middle of a
pattern. This discrepancy was `identified by Sviatoslav Sydorenko
<starbad_>`_, who `provided patient detailed diagnosis <pull 1650_>`_ and
graciously agreed to a pragmatic resolution.

.. _starbad: https://github.com/nedbat/coveragepy/issues/1407#issuecomment-1631085209
.. _pull 1650: https://github.com/nedbat/coveragepy/pull/1650

.. scriv-start-here
Expand All @@ -32,7 +39,7 @@ Version 7.3.0 — 2023-08-12

- Added a :meth:`.Coverage.collect` context manager to start and stop coverage
data collection.

- Dropped support for Python 3.7.

- Fix: in unusual circumstances, SQLite cannot be set to asynchronous mode.
Expand Down
40 changes: 37 additions & 3 deletions doc/source.rst
Original file line number Diff line number Diff line change
Expand Up @@ -181,12 +181,46 @@ File patterns
File path patterns are used for include and omit, and for combining path
remapping. They follow common shell syntax:

- ``*`` matches any number of file name characters, not including the directory
separator.

- ``?`` matches a single file name character.

- ``*`` matches any number of file name characters, not including the directory
separator. As a special case, if a pattern starts with ``*/``, it is treated
as ``**/``, and if a pattern ends with ``/*``, it is treated as ``/**``.

- ``**`` matches any number of nested directory names, including none.

- Both ``/`` and ``\`` will match either a slash or a backslash, to make
cross-platform matching easier.

- A pattern with no directory separators matches the file name in any
subdirectory.

Some examples:

.. list-table::
:widths: 20 20 20
:header-rows: 1

* - Pattern
- Matches
- Doesn't Match
* - a*.py
- | anything.py
| sub1/sub2/another.py
- | cat.py
* - sub/\*/\*.py
- | sub/a/main.py
| sub/b/another.py
- | sub/foo.py
| sub/m1/m2/foo.py
* - sub/\*\*/\*.py
- | sub/something.py
| sub/a/main.py
| sub/b/another.py
| sub/m1/m2/foo.py
- | sub1/anything.py
| sub1/more/code/main.py
* - \*/sub/\*
- | some/where/sub/more/something.py
| sub/hello.py
- | sub1/anything.py
17 changes: 16 additions & 1 deletion tests/test_files.py
Original file line number Diff line number Diff line change
Expand Up @@ -235,9 +235,24 @@ def globs_to_regex_params(
),
globs_to_regex_params(
["*/foo"], case_insensitive=False, partial=True,
matches=["abc/foo/hi.py", "foo/hi.py"],
matches=["abc/foo/hi.py", "foo/hi.py", "abc/def/foo/hi.py"],
nomatches=["abc/xfoo/hi.py"],
),
globs_to_regex_params(
["*c/foo"], case_insensitive=False, partial=True,
matches=["abc/foo/hi.py"],
nomatches=["abc/xfoo/hi.py", "foo/hi.py", "def/abc/foo/hi.py"],
),
globs_to_regex_params(
["foo/x*"], case_insensitive=False, partial=True,
matches=["foo/x", "foo/xhi.py", "foo/x/hi.py"],
nomatches=[],
),
globs_to_regex_params(
["foo/x*"], case_insensitive=False, partial=False,
matches=["foo/x", "foo/xhi.py"],
nomatches=["foo/x/hi.py"],
),
globs_to_regex_params(
["**/foo"],
matches=["foo", "hello/foo", "hi/there/foo"],
Expand Down

0 comments on commit c2fa035

Please sign in to comment.