# (new) glob documentation could be improved

**URL:** <https://discuss.python.org/t/new-glob-documentation-could-be-improved/19054>\
**Category:** Documentation\
**Created:** [September 13, 2022, 5:23pm UTC](https://discuss.python.org/t/new-glob-documentation-could-be-improved/19054 "2022-09-13T17:23:06Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![mwichmann](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/mwichmann/32/1364_2.png) [@mwichmann](https://discuss.python.org/u/mwichmann)\
**Post date:** [September 13, 2022, 5:23pm UTC](https://discuss.python.org/t/new-glob-documentation-could-be-improved/19054/1 "2022-09-13T17:23:07Z")

</div>

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…

---

<div class="post-metadata">

**Author:** ![guido](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/guido/32/21_2.png) [@guido](https://discuss.python.org/u/guido)\
**Post date:** [September 13, 2022, 6:37pm UTC](https://discuss.python.org/t/new-glob-documentation-could-be-improved/19054/2 "2022-09-13T18:37:59Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![eryksun](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/eryksun/32/697_2.png) [@eryksun](https://discuss.python.org/u/eryksun)\
**Post date:** [September 13, 2022, 6:56pm UTC](https://discuss.python.org/t/new-glob-documentation-could-be-improved/19054/3 "2022-09-13T18:56:10Z")

</div>

To me, the following is more direct and correct:

```nohighlight
   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:

```auto
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:

```auto
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)

```

---

<div class="post-metadata">

**Author:** ![guido](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/guido/32/21_2.png) [@guido](https://discuss.python.org/u/guido)\
**Post date:** [September 13, 2022, 8:24pm UTC](https://discuss.python.org/t/new-glob-documentation-could-be-improved/19054/4 "2022-09-13T20:24:54Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![mwichmann](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/mwichmann/32/1364_2.png) [@mwichmann](https://discuss.python.org/u/mwichmann)\
**Post date:** [September 13, 2022, 11:10pm UTC](https://discuss.python.org/t/new-glob-documentation-could-be-improved/19054/5 "2022-09-13T23:10:40Z")

</div>

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”.