Repository: python/cpython
Pull request: gh-94220: Align fnmatch docs with the implementation and amend markup
- Align the argument spec for fnmatch functions with the actual
  implementation.
- Update Sphinx markup to recent recommandations.
- Add link to 'iterable' glossary entry.


<!-- gh-issue-number: gh-94220 -->
* Issue: gh-94220
<!-- /gh-issue-number -->


<!-- readthedocs-preview cpython-previews start -->
----
📚 Documentation preview 📚: https://cpython-previews--114152.org.readthedocs.build/

<!-- readthedocs-preview cpython-previews end -->

Problem statement:
fnmatch module parameters names are not correct
**Documentation**

fnmatch module parameters names are not correct

```python
>>> import fnmatch
>>> fnmatch.fnmatch(filename='file.txt', pattern='*.txt')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: fnmatch() got an unexpected keyword argument 'filename'
```

<!-- gh-linked-prs -->
### Linked PRs
* gh-114152
* gh-114155
* gh-114156
<!-- /gh-linked-prs -->

Hints from issue discussion:
According to [docs](https://docs.python.org/3/library/fnmatch.html), fnmatch doesn't accept keyword arguments
In the docs the parameters are `filename` and `pattern` while in the code `name` and `pat` is being used.

Commit message: Merge branch 'main' into fix-fnmatch-docs

Patch to review:
diff --git a/Doc/library/fnmatch.rst b/Doc/library/fnmatch.rst
index aed8991d44772f..f92bcccdc35a23 100644
--- a/Doc/library/fnmatch.rst
+++ b/Doc/library/fnmatch.rst
@@ -50,10 +50,10 @@ Also note that :func:`functools.lru_cache` with the *maxsize* of 32768 is used t
 cache the compiled regex patterns in the following functions: :func:`fnmatch`,
 :func:`fnmatchcase`, :func:`.filter`.
 
-.. function:: fnmatch(filename, pattern)
+.. function:: fnmatch(name, pat)
 
-   Test whether the *filename* string matches the *pattern* string, returning
-   :const:`True` or :const:`False`.  Both parameters are case-normalized
+   Test whether the filename string *name* matches the pattern string *pat*,
+   returning ``True`` or ``False``.  Both parameters are case-normalized
    using :func:`os.path.normcase`. :func:`fnmatchcase` can be used to perform a
    case-sensitive comparison, regardless of whether that's standard for the
    operating system.
@@ -69,22 +69,24 @@ cache the compiled regex patterns in the following functions: :func:`fnmatch`,
               print(file)
 
 
-.. function:: fnmatchcase(filename, pattern)
+.. function:: fnmatchcase(name, pat)
 
-   Test whether *filename* matches *pattern*, returning :const:`True` or
-   :const:`False`; the comparison is case-sensitive and does not apply
-   :func:`os.path.normcase`.
+   Test whether filename *name* matches pattern *pat*,
+   returning ``True`` or ``False``;
+   the comparison is case-sensitive and does not apply :func:`os.path.normcase`.
 
 
-.. function:: filter(names, pattern)
+.. function:: filter(names, pat)
 
-   Construct a list from those elements of the iterable *names* that match *pattern*. It is the same as
-   ``[n for n in names if fnmatch(n, pattern)]``, but implemented more efficiently.
+   Construct a list from those elements of the :term:`iterable` *names*
+   that match pattern *pat*.
+   It is the same as ``[n for n in names if fnmatch(n, pat)]``,
+   but implemented more efficiently.
 
 
-.. function:: translate(pattern)
+.. function:: translate(pat)
 
-   Return the shell-style *pattern* converted to a regular expression for
+   Return the shell-style pattern *pat* converted to a regular expression for
    using with :func:`re.match`.
 
    Example:


Code review comments:
diff_hunk: @@ -69,22 +69,24 @@ cache the compiled regex patterns in the following functions: :func:`fnmatch`,
               print(file)
 
 
-.. function:: fnmatchcase(filename, pattern)
+.. function:: fnmatchcase(name, pat)
 
-   Test whether *filename* matches *pattern*, returning :const:`True` or
-   :const:`False`; the comparison is case-sensitive and does not apply
-   :func:`os.path.normcase`.
+   Test whether filename *name* matches pattern *pat*,
path: Doc/library/fnmatch.rst
text: @user1:
Taken the same wording from `fnmatch` above -- `fnmatchcase` doesn't take PathLike objects, so noting it's a string explicitly I think is useful.
```suggestion
   Test whether the filename string *name* matches the pattern string *pat*,
```

@author:
Good catch!