Issue #15176: Clarified behavior, documentation, and implementation

of os.listdir().

1 files changed, 8 insertions, 5 deletions

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index bc0d69d..0b6ab24 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1488,16 +1488,19 @@ features:
 .. function:: listdir(path='.')
 
    Return a list containing the names of the entries in the directory given by
-   *path* (default: ``'.'``).  The list is in arbitrary order.  It does not
-   include the special entries ``'.'`` and ``'..'`` even if they are present in
-   the directory.
+   *path*.  The list is in arbitrary order, and does not include the special
+   entries ``'.'`` and ``'..'`` even if they are present in the directory.
 
-   This function can be called with a bytes or string argument, and returns
-   filenames of the same datatype.
+   *path* may be either of type ``str`` or of type ``bytes``.  If *path*
+   is of type ``bytes``, the filenames returned will also be of type ``bytes``;
+   in all other circumstances, they will be of type ``str``.
 
    This function can also support :ref:`specifying a file descriptor
    <path_fd>`; the file descriptor must refer to a directory.
 
+   .. note::
+      To encode ``str`` filenames to ``bytes``, use :func:`~os.fsencode`.
+
    Availability: Unix, Windows.
 
    .. versionchanged:: 3.2