Search code examples
pythonlistdir

Why is the listdir() function part of os module and not os.path?

os.path module seems to be the default module for all path related functions. Yet, the listdir() function is part of the os module and not os.path module, even though it accepts a path as its input. Why has this design decision been made ?

Solution

  • I personally find the division between os and os.path to be a little inconsistent. According to the documentation, os.path should just be an alias to a module that works with paths for a particular platform (i.e., on OS X, Linux, and BSD you'll get posixpath, on Windows or ancient Macs you'll get something else).

    >>> import os
>>> help(os)
Help on module os:

NAME
    os - OS routines for Mac, NT, or Posix depending on what system we're on.
...
>>> help(os.path)
Help on module posixpath:

NAME
    posixpath - Common operations on Posix pathnames.

    The listdir function doesn't operate on the path itself, instead it operates on the directory identified by the path. Most of the functions in os.path operate on the actual path and not on the filesystem.

    This means that many functions in os.path are string manipulation functions, and most functions in os are IO functions / syscalls.

    Examples:

    • os.path.join, os.path.dirname, os.path.splitext, are just string manipulation functions.

    • os.listdir, os.getcwd, os.remove, os.stat are all syscalls, and actually touch the filesystem.

    Counterexamples:

    • os.path has exists, getmtime, islink, and others which are basically wrappers around os.stat, and touch the filesystem. I consider them miscategorized, but others may disagree.

    Fun fact of the day: You won't find the modules in the top level of the library documentation, but you can actually import the version of os.path for any platform without having to actually run on that platform. This is documented in the documentation for os.path,

    However, you can also import and use the individual modules if you want to manipulate a path that is always in one of the different formats. They all have the same interface:

    • posixpath for UNIX-style paths
    • ntpath for Windows paths
    • macpath for old-style MacOS paths
    • os2emxpath for OS/2 EMX paths

    You can't do the same thing with os, it wouldn't make any sense.