Common Path Patterns

What is the difference between PurePath and Path?

One interesting problem you will encounter if you write cross-platform code is dealing with the peculiarities of each platform. The file system differences between POSIX (which you should interpret to mean platforms other than Windows in this instance) and Microsoft Windows are sometimes vast chasms and other times more or less the same. But as a package author you must reconcile them, somehow, and offer a unified interface.

To that end, the pathlib module introduces two distinct types of classes you can instantiate directly if you want to keep your code platform-agnostic.

1. PurePath, for inspecting and manipulating abstract paths and filenames only. There are no I/O capabilities here, and no way to query the underlying file system. But if you need to construct or parse Windows paths on Linux, or vice versa, the PurePath class is indispensable.

2. Path, which inherits from PurePath, but adds file system and I/O support.

Interestingly, however, the two aforementioned classes are not the class instances you end up with if you create them. To ensure your code works everywhere the pathlib module checks where the code is running and instantiates either: PosixPath (or PurePosixPath) for non-Windows platforms; or WindowsPath (or PureWindowsPath) for Windows.

Because of the distinction between Pure and regular Path objects, you cannot instantiate a WindowsPath on Linux as Linux does not understand Windows-specific file system I/O (or the other way around) and it would result in errors or – worse – code that seems to work OK but silently fails or misbehaves. So if you want to manipulate platform-specific paths and filenames you must use the PurePath-derived versions. For all other use-cases you want Path.

Constructing and Altering Paths

>>> Path('/tmp') / 'hello.txt'
PosixPath('/tmp/hello.txt')

>>> '/tmp' / Path('hello') / 'bar.txt'
PosixPath('/tmp/hello/bar.txt')

>>> '/tmp' / 'hello' / Path('world.txt')
TypeError: unsupported operand type(s) for /: 'str' and 'str'

>>> '/tmp' / ('hello' / Path('world.txt'))
PosixPath('/tmp/hello/world.txt')

>>> Path('/home/inspiredpython').joinpath('documents', 'hello.txt')
PosixPath('/home/inspiredpython/documents/hello.txt')

>>> Path('/home').joinpath('/tmp', 'myfile.txt')
PosixPath('/tmp/myfile.txt')

>>> Path('/home/inspiredpython/test.py').with_name('hello.txt')
PosixPath('/home/inspiredpython/hello.txt')

>>> Path('/home/inspiredpython/test.py').with_suffix('.txt')
PosixPath('/home/inspiredpython/test.txt')

Listing or Iterating over Directories

A common activity is to walk through every file or directory given a starting Path.

>>> list(Path('/home/inspiredpython/'))
[PosixPath('.bashrc'), ...]

>>> list(Path('/usr/share/dict/').rglob('*english'))
[PosixPath('/usr/share/dict/british-english'),
 PosixPath('/usr/share/dict/american-english')]

Reading and Writing to Files

The traditional way to open() a file for reading is:

with open("/tmp/hello.txt") as f:
    text = f.read()

But you can do this with a Path object also. Most of the same arguments you pass to open also work with Path.open():

with Path("/tmp/hello.txt").open("r", encoding="iso-8859-1") as f:
    text = f.read()

However, if you only need the contents of the file, and if you do not need the still-open file object after the fact, you can simplify the code even further:

text = Path("/tmp/hello.txt").read_text()

Replacing read with write and you can write data:

text = "Hello, World!"
Path("/tmp/hello.txt").write_text(text)

And you can do the same but with binary with Path.write_bytes() and Path.read_bytes() if you have a bytes object:

import os

binary = os.urandom(32)
Path("/tmp/hello.bin").write_bytes(binary)

Extracting and Splitting a Path

Operating on parts of a filename or filepath is common, and unlike the traditional functions found in os.path, Path is designed to be user friendly, consistent and as unambiguous as possible from the start.

>>> Path('inspiredpython.txt').suffix
'.txt'

>>> Path('archive.tar.gz').suffixes
['.tar', '.gz']

>>> Path('README').suffixes
[]

>>> Path('README.md').stem
'README'

>>> Path('.bashrc').stem
'.bashrc'

>>> Path('/opt/hello.txt').name
'hello.txt'

>>> Path('/var/log/dmesg').parts
('/', 'var', 'log', 'dmesg')

>>> Path('/home/inspiredpython/README.md').parent
PosixPath('/home/inspiredpython')

>>> tuple(Path('/home/inspiredpython/README.md').parents)
(PosixPath('/home/inspiredpython'), PosixPath('/home'), PosixPath('/'))

>>> Path(r'C:\Users\inspiredpython\Document\inspired.py').drive
'C:'

>>> p.root
'/'

>>> p.drive
''

Quick Shortcuts

If you quickly need a Path object set to one of several common defaults, you can use these class methods exposed on the Path class.

You can get the cwd (current working directory) using the Path.cwd() classmethod:

>>> Path.cwd()
PosixPath('/tmp/some-directory/')

You can also get the home directory on Linux or Windows.

>>> Path.home()
PosixPath('/home/inspiredpython/')

The Builder Pattern

One tantalizing feature of Path – as I explained above – is that it consolidates many disparate functions into a standardized class that you can instantiate and query. One useful side-effect of that is what is known as the Builder Pattern.

The Builder Pattern is a common Object-Oriented Programming pattern. The Path class implements a version of that. The basic idea is that when you instantiate a Path class you are given an object that, in turn, can create more Path objects based on the values already present in the object.

Consider this example:

>>> Path('/home/inspired/Documents/python.txt')
PosixPath('/home/inspired/Documents/python.txt')

Observe that creating a Path object in turn gives you another Path. That is the capstone of the builder pattern. Most methods or properties present on a Path object will, in turn, give you a new Path with the change you asked for applied to it.

It’s possible to chain these methods and properties to build new Path constructs:

>>> Path('/home/inspired/Documents/python.txt').parent.parent.joinpath('files').joinpath('python.rst')
PosixPath('/home/inspired/files/python.rst')

That’s a powerful feature and a useful way of constructing or altering paths in a programmatic, linear way. You can of course store parts of that chain in a function (or variable) and use them as a mini-factory:

def switch_to_files(p):
    return p.parent.parent.joinpath('files')

>>> p = Path('/home/inspired/Documents/python.txt')
>>> switch_to_files(p)
PosixPath('/home/inspired/files')
>>> switch_to_files(p) / 'hello-world.txt'
PosixPath('/home/inspired/files/hello-world.txt')

Summary

The Path class makes it easy to interact with files and paths

By consolidating the most common file and path operations into a single class you won’t have to poke around in the os module.

Transparent cross-platform file and path support

You can use Path to transparently handle both Linux and Windows paths without worry. If you must generate paths for a particular platform you can instantiate PurePosixPath and PureWindowsPath but you lose the ability to interact with the actual file system.

Reading to, and writing from, files is also supported

If your needs are simple you can use the built-in file reader and writer in Path. It also supports binary. You can also open a file directly via the Path interface if you need access to the underlying file object.

The builder pattern is a powerful way of constructing paths

Instead of string concatenation and awkwardly nesting function calls to os and friends you can trivially construct and alter paths and filenames with a unified interface.