Build a Better Process
Build a Better Process
/ factorpad.com / tech / python / reference / python-os-path.html
An ad-free and cookie-free website.
Beginner
This Python reference offers programmers a quick way to learn Python and also serves as a source for reminders.
While the version documented here is Python 3.5.3, most of this is suitable for other versions of Python 3. Check your version for details.
Outline
The os.path module comes with 30 functions and works with two data types, strings or bytes. However, strings are most common and will be most of the focus here.
The functionality of os.path is mostly for finding with absolute and relative paths in the filesystem, but can also be used to find the time when files were created, modified and accessed. Also, Booleans help with program logic and the size of files can be accessed as well. So the module has many use cases.
Because Linux/macOS and Windows differ in path naming conventions some differences may occur and will be shown here. Case sensitivity is another topic to consider carefully when reviewing the examples here.
by os.path/usr/lib/python3.5/posixpath.pyimport os.pathos.path.join()Here we assume the most basic import scenario without aliasing. See our reference document on importing modules for more.
Assignment operations are not required for os.path as it comes with no methods, only functions. Valid data types include the string or bytes data type. A few functions require integers and tuples.
This section is offered as a review for beginners, skip to the functions if you understand string assignment in Python.
Below is syntax for creating a string object with assignment, followed by examples.
| Syntax | Priority |
|---|---|
x = str(object='')Assignment to a string using the formal approach with the built-in string function. If left blank, the default object='' will create an empty string object. |
High |
x = 'string'Assignment to a string using the shortcut, normally enclosed in single quote (') or double quote (") symbols. |
High |
Here we demonstrate how to create a valid string object created in the
context of filesystem paths. We labeled it
x and show how to create a string
using the long form and short form.
Note that in both examples either a single quote (') or double quote (") is required.
The Python os.path functions can
be called from Python scripts or the Python Interpreter.
In most cases, the parameter for each
os.path function requires one single
or multiple path strings as described above. Bytes can also be
supplied, but we will not cover that here.
Also, as a takeaway try to focus on the 6 noted as
High in the Priority
column. These are the most commonly searched for functions of the 30
in total.
The 30 functions in the os.path module are segmented into 4 groups.
True or
False responses.Strings are typically used to navigate the filesystem programmatically or report pathname specifications.
| Syntax | Priority |
|---|---|
os.path.abspath(path)Returns the full absolute path from the root. The path string is required and only one can be passed. |
High |
os.path.basename(path)Returns the basename or the last section in the path supplied without a directory notation (/) or (\\). The path string is required and only one can be passed. |
Mid |
os.path.commonpath(paths)Used to compare paths for multiple provided in a sequence (list or tuple typically). Returns the longest common subpath of the two or more paths supplied. The paths sequence is a required paramater and it cannot mix relative and absolute paths. |
Mid |
os.path.commonprefix(list)Used to compare paths for multiple provided in a list, however a tuple can be supplied as well. Returns the longest common subpath of the two or more paths supplied in the list working from left to right, so a functional directory name may not be returned. The list of paths is a required paramater and as long as a sequence is provided, whether it has one or two values, at a minimum an empty string ('') will be returned. It cannot mix relative and absolute paths. |
Low |
os.path.dirname(path)Returns the directory name in the path supplied as a string. So if a filename is supplied, the directory will be returned. The path is required and only one can be passed. |
High |
os.path.expanduser(path)For paths that begin with the ~
symbol signifying the user's home directory this function returns
the user's home directory or the originally supplied
path if the expansion fails or the string does
not begin with a ~.The path is a required string and only one can be passed. |
Mid |
os.path.expandvars(path)Returns the argument when environment variables are provided. The path is a required string and only one can be passed. |
Mid |
os.path.join(path, *paths)Used to construct paths from strings provided. The path is a required string and only one can be passed. The *paths parameter takes one or many path strings. |
High |
os.path.normcase(path)Used to normalize paths primarily for Windows filesystems due to their case-insensitive nature. On Windows the string is changed to lowercase and single forward slashes (/) are changed to two backward slashes (\\). On Linux it returns path unchanged. The path is a required string and only one can be passed. |
Mid |
os.path.normpath(path)Used to normalize paths by removing redundant separators, which may make symbolic links not function properly. On Windows it changes single forward slashes (/) to two backward slashes (\\). The path is a required string and only one can be passed. |
Mid |
os.path.realpath(path)Returns the canonical, or direct path, to the specified filename thereby eliminating any symbolic links, if any. The path is a required string and only one can be passed. |
Low |
os.path.relpath(path, start=os.curdir)Returns the relative path directions to go from the current directory to that specified in path. No actual directory lookup is being performed to confirm the existence of directories, instead this is calculated. The path is a required string. The start=os.curdir parameter is optional and defaults to the current directory, which can be overridden to a different directory. Also see the os.curdir function. |
Mid |
os.path.split(path)Splits the path into a (head, tail) tuple where head refers to the last pathname component containing a slash (/) on Linux or double back slash (\\) on Windows, with slashes stripped. The tail is the remaining part. It will never have a slash (/) or double back slash (\\). If the path ends with a slash (/) or double backslash (\\) the tail will be returned as an empty string. The path parameter is not required and will return two empty strings ('') for head and tail if not supplied. |
Mid |
os.path.splitdrive(path)Splits the path into a (drive, tail) tuple where drive refers to the mountpoint, so mostly on Windows and will include the colon symbol. The tail is the remaining part, it will often have the slash (/) or double backslash (\\). If the path doesn't have a drive letter, the head will be returned as an empty string. If the path uses UNC conventions ('//host/computer/dir') the head would result would be ('//host/computer', '/dir'). The path is a required string and only one can be supplied. |
Low |
os.path.splittext(path)Splits the path into a (root, ext) tuple where root refers to the first part of a filename and ext refers to the extension. Filenames with a leading period (.) will be ignored and the results will go in the root, the ext will be an empty string (''). The path is a required string and only one can be supplied. |
Mid |
Boolean responses are typically used to add logic to programs relating to filesystem paths.
| Syntax | Priority |
|---|---|
os.path.exists(path)Returns True if the
path exists, and
False if a directory is not
accessible (broken symbolic links, directory permissions,
non-existent paths).The path is a required string and only one can be passed. |
High |
os.path.lexists(path)Returns True if the
path exists, even if a symbolic link is
broken.The path is a required paramater, passed as a string and only one can be passed. |
Mid |
os.path.isabs(path)Returns True if
path is an absolute pathname.The path is a required string and only one can be passed. |
Mid |
os.path.isfile(path)Returns True if
path is an existing file.The path is a required paramater, passed as a string and only one can be passed. |
High |
os.path.isdir(path)Returns True if
path is an existing directory. This includes
regular and symbolic links.The path is a required paramater, passed as a string and only one can be passed. |
High |
os.path.islink(path)Returns True if
path is a symbolically linked directory.The path is a required paramater, passed as a string and only one can be passed. |
Mid |
os.path.ismount(path)Returns True if
path is a mount point. This may be a different
mount point in Linux or drive letter on Windows.The path is a required paramater, passed as a string and only one can be passed. |
Mid |
os.path.samefile(path1, path2)Returns True if
path1 and path2 point to the
same file or directory.The path1 and path2 parameters are required, both passed as a string. |
Low |
os.path.sameopenfile(fp1, fp2)Returns True if file descriptors
for fp1 and fp2 refer to the
same file. A file descriptor is a number that uniquely identifies
an open file on the computer.The fp1 and fp2 parameters are required, both passed as an integer. |
Low |
os.path.samestat(stat1, stat2)Returns True if the stat tuples
stat1 and stat2 refer to the
same file. These are often looked up using
os.fstat(), os.lstat() or
os.stat(). See example below.The stat1 and stat2 parameters are required, both passed as a tuple. See the os.stat function for more information. |
Low |
os.path.supports_unicode_filenamesReturns True if Unicode strings
can be supplied in filenames. This is the only function that does not require an argument. |
Low |
Timestamps are used to report access, modify and create times for files and directories.
| Syntax | Priority |
|---|---|
os.path.getatime(path)Returns the time since the directory supplied as path was last accessed. Time is given in seconds since the epoch time. See the time module for details. The path is a required paramater, passed as a string and only one can be passed. |
Low |
os.path.getmtime(path)Returns the time since the file supplied as path was last modified. Time is given in seconds since the epoch time. See the time module for details. The path is a required string and only one can be passed. |
Mid |
os.path.getctime(path)Returns the time since the file supplied as path had its metadata changed (Linux) or created (Windows). Time is given in seconds since the epoch time. See the time module for details. The path is a required paramater, passed as a string and only one can be passed. |
Mid |
There is one function that returns file sizes.
| Syntax | Priority |
|---|---|
os.path.getsize(path)Returns the size of the path file in bytes. The path is a required paramater, passed as a string and only one can be passed. |
Mid |
To calculate the aggregate size of all files in a directory it is common to use a loop.
For the examples below, to illustrate the difference between Linux/macOS and Windows, assume the following directory structure.
NOTE: Since macOS is similar to Linux with respect to directories using the forward slash symbol (/), that is where macOS is grouped in these examples. Where macOS and Linux differ is in case-insensitive versus case-insensitive file and pathnames. Please make this adjustment on your end.
Function examples are organized in the same fashion as the syntax was introduced above, so the 30 functions are segmented the same way.
True or
False responses.
Starting with the os.path.abspath()
function let's say we're in the base of the working directory. The dot
(.) specifies the current directory.
To illustrate the
os.path.basename function let's
specify the full path to the style.css
file and it returns only that filename part.
We can supply a list of paths to
os.path.commonpath() to see the
longest subpath in common with both files or directories.
In the example below we use the
os.path.commonpath() function which
matches common paths left to right. A working path may not result.
The os.path.dirname() function
returns the directory name of the specified path.
With the os.path.expanduser() function
you can expand the home directory symbol.
With the os.path.expandvars()
function you can access system environment variables and build paths
from there.
The os.path.join() function is used
to join or concatenate multiple paths specified as strings.
The os.path.normcase() function
helps to normalize paths for Windows in particular. Note how
directories were changed and all text lowercased on the Windows
example.
Use the os.path.normpath() function to
change all slashes to the Linux standard. This is primarily for
Windows, notice how on Linux Python returns the string unchanged.
The os.path.realpath() function will
return the canonical path, thereby eliminating symbolic links. In this
example all of our links are canonical.
The os.path.relpath() function
calculates the relative path specification that would take you to the
first path supplied from the second.
The os.path.split() function
splits the path into a directory part and file part returning a tuple.
The os.path.splitdrive() function
splits the path into a drive part and remaining part returning a tuple.
This is primarily used on Windows and using UNC conventions.
With the os.path.splitext() function
you can split a file path into a root part and and extension part.
Note that there is one 't' in splitext.
Boolean responses are typically used to add logic to programs relating to filesystem paths.
Use the os.path.exists() function
to report if a path exists. Note the difference in case sensitivity
between Linux and case insensitivity in Windows. In this case most
macOS systems behave more like the Windows operating system.
Use the os.path.lexists() function
to report if a path exists. In this example assume the directory path
was a symbolic link.
The os.path.isabs() function is used
to report whether a path name is an absolute path.
The os.path.isfile() function is used
to see if a regular file exists. Note the difference in case sensitivity
between Linux and case insensitivity in Windows, and in this case
macOS.
The os.path.isdir() function tests
whether the path points to a directory. Note the difference in case
sensitivity between Linux/macOS and case insensitivity in Windows.
Also, the final forward slash (/) or backward slashes (\\) need not
be included.
With the os.path.islink() function you
can test whether the path is symbolically linked. Here we don't have
symbolic links.
The os.path.ismount() function tests
whether the path is a mount point.
The os.path.samefile() function tests
whether the files specified are the same. Note the difference in case
sensitivity between Linux and case insensitivity in Windows. Again on
macOS, it case sensitivity is more like Windows.
The os.path.sameopenfile() function
tests whether the files specified by file descriptor are the same open
file. Arguments passed must be a file descriptor
integer. A use case may be to test whether a file like bot.py in our
example was open multiple times. Here we will use dummy integer
values as the rest is beyond our scope here.
The os.path.samestat() function
tests whether the files specified return the same stat which is a tuple
providing detailed information about files. These are often looked up
using os.fstat(), os.lstat() or
os.stat().
The os.path.supports_unicode_filenames
takes no arguments and reports whether the operating system supports
Unicode filenames.
These 3 functions return elapsed time since epoch as a float. To translate this to a readable format, the datatime module offers a solution.
Use the os.path.getatime() function
to return the time the path was last accessed in seconds since epoch.
The os.path.getmtime() function will
return the time the path was last modified in seconds since epoch.
The os.path.getctime() function is
used to return the time the path was created in seconds since epoch.
See the time and datetime modules
for additional processing of time.
The os.path.getsize() function
returns the size of a specified file in a directory and through a loop
can return a total.
That's a lot to take in during one sitting, which is why this is a reference document and will be here when you need it.
Keep in mind, there are no methods in the os.path module and most inputs are strings, so the examples below provide two examples of methods for strings. This can also be found in a separate discussion of strings in Python.
The method syntax examples below assume that the string object has
been named x.
| Syntax | Priority |
|---|---|
x.lower()A common use case with HTML strings, especially in search contexts, is to transform all uppercase characters to lowercase using this string method. |
Mid |
x.replace(old, new[, count])The old and new parameters are required and are supplied as strings (' ', " ", ''' ''', or """ """). The optional parameter count will make that number of replacements, from start to finish. |
Mid |
These methods, while not part of the os.path module are mentioned here so beginners can gain a better understanding of string objects in Python, and as a background for our next example.
At long last, in our final example we tie it all together. We create an instance of a path string object with text that was capitalized and provided in a messy format. Our objective is to see if it is a valid address on the system and finally, the size of the file.
Yay! We made it to the finish line. Now you've seen all 30 functions in the os.path module.
To accomplish this, we used the
lower() method for string objects
first to transform it to lowercase. Second we used the
replace() method to change pipes (|)
to forward slashes (/). Next, we tested to see if the filename exists
using the os.path.exists() function.
Finally, we printed out the size using the
os.path.getsize() function.
Thank you for stiking with it, as you can see the os.path offers a lot of useful functionality, but can be tedious.
To access local help on the Python os.path module type
help('os.path') at the Python
Interpreter. Output for Python 3.5.3 looks like this.
It includes an important message about file locations across Linux macOS and Windows computers because differences exist in case sensitivity and directory forward slashes (/) and backward slashes (\\).
In the end, the os.path module offers 30 convenient functions to handle the filesystem using Python. It and other modules in the os and io modules are important components of The Python Standard Libary for everyone to learn.
Keep a bookmark pointed here for reminders because there isn't a lot of public information on the os.path module at this level of detail. I hope it was a helpful exploration.
Subscribe to our growing YouTube Channel, a companion to this free online educational website. Hop on the no-spam email list for reminders.
/ factorpad.com / tech / python / reference / python-os-path.html
A newly-updated free resource. Connect and refer a friend today.