`zipfile`: `zipfile.Path`’s `glob()` and `rglob()` are not documented

Documentation

It seems documentation for zipfile.Path’s glob() and rglob() is missing (or maybe they're meant to be private but wrongly "exported"?!

Also, the behaviour of rglob() seems a bit unexpected:

Assume the following test zip file:

1/
1/a
1/b
1/c
1/1/
1/1/loop
1/2/
1/2/a
1/2/b
1/2/c
1/3/
2/
2/f
3/
3/g
.dir/
.dir/a/
.dir/a/1
.dir/.1
.dir/.d
.file

where pathnames ending in / are directories and loop is a symlink to ../../1.

With:

p = zipfile.Path("test.zip")

glob() does not allow an empty pattern:

i = p.glob("")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/usr/lib/python3.13/zipfile/_path/__init__.py", line 419, in glob
    raise ValueError(f"Unacceptable pattern: {pattern!r}")
ValueError: Unacceptable pattern: ''

But rglob() does:

>>> for i in  p.rglob(""):
...     print(i)
test.zip/1/
test.zip/1/1/
test.zip/1/2/
test.zip/1/3/
test.zip/2/
test.zip/3/
test.zip/.dir/
test.zip/.dir/a/

in which case it seems to list only directories.

If using * as pattern:

>>> for i in  p.rglob("*"):
...     print(i)
test.zip/1/a
test.zip/1/b
test.zip/1/c
test.zip/1/1/
test.zip/1/1/loop
test.zip/1/2/
test.zip/1/2/a
test.zip/1/2/b
test.zip/1/2/c
test.zip/1/3/
test.zip/2/f
test.zip/3/g
test.zip/.dir/a/
test.zip/.dir/a/1
test.zip/.dir/.1
test.zip/.dir/.d

the results are also a bit... unexpected...

• . files are included (which is at least not compatible with POSIX pattern matching notation on pathnames)
• some but not all directories are given, e.g. we have 1/1/ but not 1/, which we did get when the pattern is the empty string.
• documentation should also note, that the zip file name is for some reason prepended.

It's also not really clear whether these two functions are safe at all,... e.g. could they be used to break out of traversing the ZIP's contents with some tricky .. (cause at some point the docs warn about Path not doing any such sanitisations).

Cheers,
Chris.

Linked PRs

• gh-144460

Start with zipfile.Path and the glob() and rglob() entry points, including the implementation path shown as zipfile/_path/init.py. Review the reported empty-pattern and '*' examples, then inspect linked PR gh-144460 and the discussion. Done means the documented behavior, path prefixing, directory results, dot files, and safety considerations are settled and covered.