(new) glob documentation could be improved

I asked a question on scons-dev about the new (for 3.11) include_hidden flag (for glob and iglob) - the docstring doesn’t quite match the docs in the rst file, with the latter saying “If include_hidden is true, “**” pattern will match hidden directories”. Besides the minor grammatical hiccup, it appears the effect of the flag is not limited to just the “**” pattern.

And then @eryksun pointed out that the simplistic term “hidden directories” is not very descriptiive:

Shouldn’t this explain what a “hidden directory” is? For example, a Windows user may think this means a directory with FILE_ATTRIBUTE_HIDDEN set, but that’s not what’s meant here. Also, I think it should note that enabling include_hidden negates the earlier claim that “files beginning with a dot (.) can only be matched by patterns that also start with a dot”. For example, glob.glob(‘*’, include_hidden=True) includes all of the conventionally hidden directories and hidden files in the current directory.

So I’d like to suggest we come up with a better description here - I’m thinkin about it, but open to wiser heads with better ideas…

Are you willing to create an issue for this and possibly submit a PR to close the issue?

To me, the following is more direct and correct:

   If *include_hidden* is true, patterns that do not begin with a dot (``.``)
   may also match names that begin with a dot.

Also, in “Lib/glob.y”, the following implementation of _glob1() looks wrong to me:

def _glob1(dirname, pattern, dir_fd, dironly, include_hidden=False):
    names = _listdir(dirname, dir_fd, dironly)
    if include_hidden or not _ishidden(pattern):
        names = (x for x in names if include_hidden or not _ishidden(x))
    return fnmatch.filter(names, pattern)

If include_hidden is true, the above needlessly makes a shallow copy of names. I think it should instead be implemented as follows:

def _glob1(dirname, pattern, dir_fd, dironly, include_hidden=False):
    names = _listdir(dirname, dir_fd, dironly)
    if not include_hidden and not _ishidden(pattern):
        names = (x for x in names if not _ishidden(x))
    return fnmatch.filter(names, pattern)

Can you just file an issue for that (and a PR if possible)?

Hmm, I’m not sure if I completely like this bit either:

If recursive is true, the pattern “**” will match any files and zero or more directories, subdirectories and symbolic links to directories. If the pattern is followed by an os.sep or os.altsep then files will not match.

That’s true, but I’d be happier with the term “by itself” somewhere in there, or some other such wording. **/ matches no files in the current directory or subdirectories, as it says, but the (at least in my experience more common) style of pattern like **/*.py does match files, both in the top directory and in any recursed directories, yet the ** was “followed by an os.sep”.