`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

Comece com zipfile.Path e os pontos de entrada glob() e rglob(), incluindo o caminho de implementação mostrado como zipfile/_path/init.py. Revise os exemplos relatados de padrão vazio e '*', depois inspecione o PR vinculado gh-144460 e a discussão. Considera-se concluído quando o comportamento documentado, o prefixo de caminhos, os resultados de diretórios, os arquivos ocultos e as considerações de segurança estiverem definidos e cobertos.