New in version 3.4.
Source code: Lib/pathlib.py
This module offers classes representing filesystem paths with semantics appropriate for different operating systems. Path classes are divided between pure paths, which provide purely computational operations without I/O, and concrete paths, which inherit from pure paths but also provide I/O operations.
If you’ve never used this module before or just aren’t sure which class is right for your task, Path is most likely what you need. It instantiates a concrete path for the platform the code is running on.
Pure paths are useful in some special cases; for example:
See also
PEP 428: The pathlib module – object-oriented filesystem paths.
See also
For low-level path manipulation on strings, you can also use the os.path module.
Importing the main class:
Listing subdirectories:
Listing Python source files in this directory tree:
Navigating inside a directory tree:
Querying path properties:
Opening a file:
Pure path objects provide path-handling operations which don’t actually access a filesystem. There are three ways to access these classes, which we also call flavours:
A generic class that represents the system’s path flavour (instantiating it creates either a PurePosixPath or a PureWindowsPath):
Each element of pathsegments can be either a string representing a path segment, an object implementing the os.PathLike interface which returns a string, or another path object:
When pathsegments is empty, the current directory is assumed:
When several absolute paths are given, the last is taken as an anchor (mimicking os.path.join()’s behaviour):
However, in a Windows path, changing the local root doesn’t discard the previous drive setting:
Spurious slashes and single dots are collapsed, but double dots ('..') are not, since this would change the meaning of a path in the face of symbolic links:
(a naïve approach would make PurePosixPath('foo/../bar') equivalent to PurePosixPath('bar'), which is wrong if foo is a symbolic link to another directory)
Pure path objects implement the os.PathLike interface, allowing them to be used anywhere the interface is accepted.
Changed in version 3.6: Added support for the os.PathLike interface.
A subclass of PurePath, this path flavour represents non-Windows filesystem paths:
pathsegments is specified similarly to PurePath.
A subclass of PurePath, this path flavour represents Windows filesystem paths:
pathsegments is specified similarly to PurePath.
Regardless of the system you’re running on, you can instantiate all of these classes, since they don’t provide any operation that does system calls.
Paths are immutable and hashable. Paths of a same flavour are comparable and orderable. These properties respect the flavour’s case-folding semantics:
Paths of a different flavour compare unequal and cannot be ordered:
The slash operator helps create child paths, similarly to os.path.join():
A path object can be used anywhere an object implementing os.PathLike is accepted:
The string representation of a path is the raw filesystem path itself (in native form, e.g. with backslashes under Windows), which you can pass to any function taking a file path as a string:
Similarly, calling bytes on a path gives the raw filesystem path as a bytes object, as encoded by os.fsencode():
Note
Calling bytes is only recommended under Unix. Under Windows, the unicode form is the canonical representation of filesystem paths.
To access the individual “parts” (components) of a path, use the following property:
A tuple giving access to the path’s various components:
(note how the drive and local root are regrouped in a single part)
Pure paths provide the following methods and properties:
A string representing the drive letter or name, if any:
UNC shares are also considered drives:
A string representing the (local or global) root, if any:
UNC shares always have a root:
The concatenation of the drive and root:
An immutable sequence providing access to the logical ancestors of the path:
The logical parent of the path:
You cannot go past an anchor, or empty path:
Note
This is a purely lexical operation, hence the following behaviour:
If you want to walk an arbitrary filesystem path upwards, it is recommended to first call Path.resolve() so as to resolve symlinks and eliminate “..” components.
A string representing the final path component, excluding the drive and root, if any:
UNC drive names are not considered:
The file extension of the final component, if any:
A list of the path’s file extensions:
The final path component, without its suffix:
Return a string representation of the path with forward slashes (/):
Represent the path as a file URI. ValueError is raised if the path isn’t absolute.
Return whether the path is absolute or not. A path is considered absolute if it has both a root and (if the flavour allows) a drive:
Return whether or not this path is relative to the other path.
New in version 3.9.
With PureWindowsPath, return True if the path is considered reserved under Windows, False otherwise. With PurePosixPath, False is always returned.
File system calls on reserved paths can fail mysteriously or have unintended effects.
Calling this method is equivalent to combining the path with each of the other arguments in turn:
Match this path against the provided glob-style pattern. Return True if matching is successful, False otherwise.
If pattern is relative, the path can be either relative or absolute, and matching is done from the right:
If pattern is absolute, the path must be absolute, and the whole path must match:
As with other methods, case-sensitivity follows platform defaults:
Compute a version of this path relative to the path represented by other. If it’s impossible, ValueError is raised:
NOTE: This function is part of PurePath and works with strings. It does not check or access the underlying file structure.
Return a new path with the name changed. If the original path doesn’t have a name, ValueError is raised:
Return a new path with the stem changed. If the original path doesn’t have a name, ValueError is raised:
New in version 3.9.
Return a new path with the suffix changed. If the original path doesn’t have a suffix, the new suffix is appended instead. If the suffix is an empty string, the original suffix is removed:
Concrete paths are subclasses of the pure path classes. In addition to operations provided by the latter, they also provide methods to do system calls on path objects. There are three ways to instantiate concrete paths:
A subclass of PurePath, this class represents concrete paths of the system’s path flavour (instantiating it creates either a PosixPath or a WindowsPath):
pathsegments is specified similarly to PurePath.
A subclass of Path and PurePosixPath, this class represents concrete non-Windows filesystem paths:
pathsegments is specified similarly to PurePath.
A subclass of Path and PureWindowsPath, this class represents concrete Windows filesystem paths:
pathsegments is specified similarly to PurePath.
You can only instantiate the class flavour that corresponds to your system (allowing system calls on non-compatible path flavours could lead to bugs or failures in your application):
Concrete paths provide the following methods in addition to pure paths methods. Many of these methods can raise an OSError if a system call fails (for example because the path doesn’t exist).
Changed in version 3.8: exists(), is_dir(), is_file(), is_mount(), is_symlink(), is_block_device(), is_char_device(), is_fifo(), is_socket() now return False instead of raising an exception for paths that contain characters unrepresentable at the OS level.
Return a new path object representing the current directory (as returned by os.getcwd()):
Return a new path object representing the user’s home directory (as returned by os.path.expanduser() with ~ construct):
New in version 3.5.
Return a os.stat_result object containing information about this path, like os.stat(). The result is looked up at each call to this method.
Change the file mode and permissions, like os.chmod():
Whether the path points to an existing file or directory:
Note
If the path points to a symlink, exists() returns whether the symlink points to an existing file or directory.
Return a new path with expanded ~ and ~user constructs, as returned by os.path.expanduser():
New in version 3.5.
Glob the given relative pattern in the directory represented by this path, yielding all matching files (of any kind):
The “**” pattern means “this directory and all subdirectories, recursively”. In other words, it enables recursive globbing:
Note
Using the “**” pattern in large directory trees may consume an inordinate amount of time.
Raises an auditing event pathlib.Path.glob with arguments self, pattern.
Return the name of the group owning the file. KeyError is raised if the file’s gid isn’t found in the system database.
Return True if the path points to a directory (or a symbolic link pointing to a directory), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.
Return True if the path points to a regular file (or a symbolic link pointing to a regular file), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.
Return True if the path is a mount point: a point in a file system where a different file system has been mounted. On POSIX, the function checks whether path’s parent, path/.., is on a different device than path, or whether path/.. and path point to the same i-node on the same device — this should detect mount points for all Unix and POSIX variants. Not implemented on Windows.
New in version 3.7.
Return True if the path points to a symbolic link, False otherwise.
False is also returned if the path doesn’t exist; other errors (such as permission errors) are propagated.
Return True if the path points to a Unix socket (or a symbolic link pointing to a Unix socket), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.
Return True if the path points to a FIFO (or a symbolic link pointing to a FIFO), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.
Return True if the path points to a block device (or a symbolic link pointing to a block device), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.
Return True if the path points to a character device (or a symbolic link pointing to a character device), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.
When the path points to a directory, yield path objects of the directory contents:
The children are yielded in arbitrary order, and the special entries '.' and '..' are not included. If a file is removed from or added to the directory after creating the iterator, whether an path object for that file be included is unspecified.
Like Path.chmod() but, if the path points to a symbolic link, the symbolic link’s mode is changed rather than its target’s.
Like Path.stat() but, if the path points to a symbolic link, return the symbolic link’s information rather than its target’s.
Create a new directory at this given path. If mode is given, it is combined with the process’ umask value to determine the file mode and access flags. If the path already exists, FileExistsError is raised.
If parents is true, any missing parents of this path are created as needed; they are created with the default permissions without taking mode into account (mimicking the POSIX mkdir -p command).
If parents is false (the default), a missing parent raises FileNotFoundError.
If exist_ok is false (the default), FileExistsError is raised if the target directory already exists.
If exist_ok is true, FileExistsError exceptions will be ignored (same behavior as the POSIX mkdir -p command), but only if the last path component is not an existing non-directory file.
Changed in version 3.5: The exist_ok parameter was added.
Open the file pointed to by the path, like the built-in open() function does:
Return the name of the user owning the file. KeyError is raised if the file’s uid isn’t found in the system database.
Return the binary contents of the pointed-to file as a bytes object:
New in version 3.5.
Return the decoded contents of the pointed-to file as a string:
The file is opened and then closed. The optional parameters have the same meaning as in open().
New in version 3.5.
Return the path to which the symbolic link points (as returned by os.readlink()):
New in version 3.9.
Rename this file or directory to the given target, and return a new Path instance pointing to target. On Unix, if target exists and is a file, it will be replaced silently if the user has permission. target can be either a string or another path object:
The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, not the directory of the Path object.
Changed in version 3.8: Added return value, return the new Path instance.
Rename this file or directory to the given target, and return a new Path instance pointing to target. If target points to an existing file or directory, it will be unconditionally replaced.
The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, not the directory of the Path object.
Changed in version 3.8: Added return value, return the new Path instance.
Make the path absolute, resolving any symlinks. A new path object is returned:
“..” components are also eliminated (this is the only method to do so):
If the path doesn’t exist and strict is True, FileNotFoundError is raised. If strict is False, the path is resolved as far as possible and any remainder is appended without checking whether it exists. If an infinite loop is encountered along the resolution path, RuntimeError is raised.
New in version 3.6: The strict argument (pre-3.6 behavior is strict).
This is like calling Path.glob() with “**/” added in front of the given relative pattern:
Raises an auditing event pathlib.Path.rglob with arguments self, pattern.
Remove this directory. The directory must be empty.
Return whether this path points to the same file as other_path, which can be either a Path object, or a string. The semantics are similar to os.path.samefile() and os.path.samestat().
An OSError can be raised if either file cannot be accessed for some reason.
New in version 3.5.
Make this path a symbolic link to target. Under Windows, target_is_directory must be true (default False) if the link’s target is a directory. Under POSIX, target_is_directory’s value is ignored.
Note
The order of arguments (link, target) is the reverse of os.symlink()’s.
Make target a hard link to this path.
Warning
This function does not make this path a hard link to target, despite the implication of the function and argument names. The argument order (target, link) is the reverse of Path.symlink_to(), but matches that of os.link().
New in version 3.8.
Create a file at this given path. If mode is given, it is combined with the process’ umask value to determine the file mode and access flags. If the file already exists, the function succeeds if exist_ok is true (and its modification time is updated to the current time), otherwise FileExistsError is raised.
Remove this file or symbolic link. If the path points to a directory, use Path.rmdir() instead.
If missing_ok is false (the default), FileNotFoundError is raised if the path does not exist.
If missing_ok is true, FileNotFoundError exceptions will be ignored (same behavior as the POSIX rm -f command).
Changed in version 3.8: The missing_ok parameter was added.
Open the file pointed to in bytes mode, write data to it, and close the file:
An existing file of the same name is overwritten.
New in version 3.5.
Open the file pointed to in text mode, write data to it, and close the file:
An existing file of the same name is overwritten. The optional parameters have the same meaning as in open().
New in version 3.5.
Below is a table mapping various os functions to their corresponding PurePath/Path equivalent.
Note
Although os.path.relpath() and PurePath.relative_to() have some overlapping use-cases, their semantics differ enough to warrant not considering them equivalent.
os and os.path
pathlib
os.path.abspath()
Path.resolve()
os.chmod()
Path.chmod()
os.mkdir()
Path.mkdir()
os.makedirs()
Path.mkdir()
os.rename()
Path.rename()
os.replace()
Path.replace()
os.rmdir()
Path.rmdir()
os.remove(), os.unlink()
Path.unlink()
os.getcwd()
Path.cwd()
os.path.exists()
Path.exists()
os.path.expanduser()
Path.expanduser() and Path.home()
os.listdir()
Path.iterdir()
os.path.isdir()
Path.is_dir()
os.path.isfile()
Path.is_file()
os.path.islink()
Path.is_symlink()
os.link()
Path.link_to()
os.symlink()
Path.symlink_to()
os.readlink()
Path.readlink()
os.stat()
Path.stat(), Path.owner(), Path.group()
os.path.isabs()
PurePath.is_absolute()
os.path.join()
PurePath.joinpath()
os.path.basename()
PurePath.name
os.path.dirname()
PurePath.parent
os.path.samefile()
Path.samefile()
os.path.splitext()
PurePath.suffix


A subclass of PurePath, this class represents concrete paths of the system’s path flavour (instantiating it creates either a PosixPath or a WindowsPath):
pathsegments is specified similarly to PurePath.


Change the file mode and permissions, like os.chmod():


Return a new path object representing the current directory (as returned by os.getcwd()):


Whether the path points to an existing file or directory:
Note
If the path points to a symlink, exists() returns whether the symlink points to an existing file or directory.


Return a new path with expanded ~ and ~user constructs, as returned by os.path.expanduser():
New in version 3.5.


Glob the given relative pattern in the directory represented by this path, yielding all matching files (of any kind):
The “**” pattern means “this directory and all subdirectories, recursively”. In other words, it enables recursive globbing:
Note
Using the “**” pattern in large directory trees may consume an inordinate amount of time.
Raises an auditing event pathlib.Path.glob with arguments self, pattern.


Return the name of the group owning the file. KeyError is raised if the file’s gid isn’t found in the system database.


Return a new path object representing the user’s home directory (as returned by os.path.expanduser() with ~ construct):
New in version 3.5.


Return True if the path points to a block device (or a symbolic link pointing to a block device), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.


Return True if the path points to a character device (or a symbolic link pointing to a character device), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.


Return True if the path points to a directory (or a symbolic link pointing to a directory), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.


Return True if the path points to a FIFO (or a symbolic link pointing to a FIFO), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.


Return True if the path points to a regular file (or a symbolic link pointing to a regular file), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.


Return True if the path is a mount point: a point in a file system where a different file system has been mounted. On POSIX, the function checks whether path’s parent, path/.., is on a different device than path, or whether path/.. and path point to the same i-node on the same device — this should detect mount points for all Unix and POSIX variants. Not implemented on Windows.
New in version 3.7.


Return True if the path points to a Unix socket (or a symbolic link pointing to a Unix socket), False if it points to another kind of file.
False is also returned if the path doesn’t exist or is a broken symlink; other errors (such as permission errors) are propagated.


Return True if the path points to a symbolic link, False otherwise.
False is also returned if the path doesn’t exist; other errors (such as permission errors) are propagated.


When the path points to a directory, yield path objects of the directory contents:
The children are yielded in arbitrary order, and the special entries '.' and '..' are not included. If a file is removed from or added to the directory after creating the iterator, whether an path object for that file be included is unspecified.


Like Path.chmod() but, if the path points to a symbolic link, the symbolic link’s mode is changed rather than its target’s.


Make target a hard link to this path.
Warning
This function does not make this path a hard link to target, despite the implication of the function and argument names. The argument order (target, link) is the reverse of Path.symlink_to(), but matches that of os.link().
New in version 3.8.


Like Path.stat() but, if the path points to a symbolic link, return the symbolic link’s information rather than its target’s.


Create a new directory at this given path. If mode is given, it is combined with the process’ umask value to determine the file mode and access flags. If the path already exists, FileExistsError is raised.
If parents is true, any missing parents of this path are created as needed; they are created with the default permissions without taking mode into account (mimicking the POSIX mkdir -p command).
If parents is false (the default), a missing parent raises FileNotFoundError.
If exist_ok is false (the default), FileExistsError is raised if the target directory already exists.
If exist_ok is true, FileExistsError exceptions will be ignored (same behavior as the POSIX mkdir -p command), but only if the last path component is not an existing non-directory file.
Changed in version 3.5: The exist_ok parameter was added.


Open the file pointed to by the path, like the built-in open() function does:


Return the name of the user owning the file. KeyError is raised if the file’s uid isn’t found in the system database.


Return the path to which the symbolic link points (as returned by os.readlink()):
New in version 3.9.


Return the binary contents of the pointed-to file as a bytes object:
New in version 3.5.


Return the decoded contents of the pointed-to file as a string:
The file is opened and then closed. The optional parameters have the same meaning as in open().
New in version 3.5.


Rename this file or directory to the given target, and return a new Path instance pointing to target. On Unix, if target exists and is a file, it will be replaced silently if the user has permission. target can be either a string or another path object:
The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, not the directory of the Path object.
Changed in version 3.8: Added return value, return the new Path instance.


Rename this file or directory to the given target, and return a new Path instance pointing to target. If target points to an existing file or directory, it will be unconditionally replaced.
The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, not the directory of the Path object.
Changed in version 3.8: Added return value, return the new Path instance.


Make the path absolute, resolving any symlinks. A new path object is returned:
“..” components are also eliminated (this is the only method to do so):
If the path doesn’t exist and strict is True, FileNotFoundError is raised. If strict is False, the path is resolved as far as possible and any remainder is appended without checking whether it exists. If an infinite loop is encountered along the resolution path, RuntimeError is raised.
New in version 3.6: The strict argument (pre-3.6 behavior is strict).


This is like calling Path.glob() with “**/” added in front of the given relative pattern:
Raises an auditing event pathlib.Path.rglob with arguments self, pattern.


Remove this directory. The directory must be empty.


Return whether this path points to the same file as other_path, which can be either a Path object, or a string. The semantics are similar to os.path.samefile() and os.path.samestat().
An OSError can be raised if either file cannot be accessed for some reason.
New in version 3.5.


Return a os.stat_result object containing information about this path, like os.stat(). The result is looked up at each call to this method.


Make this path a symbolic link to target. Under Windows, target_is_directory must be true (default False) if the link’s target is a directory. Under POSIX, target_is_directory’s value is ignored.
Note
The order of arguments (link, target) is the reverse of os.symlink()’s.


Create a file at this given path. If mode is given, it is combined with the process’ umask value to determine the file mode and access flags. If the file already exists, the function succeeds if exist_ok is true (and its modification time is updated to the current time), otherwise FileExistsError is raised.


Remove this file or symbolic link. If the path points to a directory, use Path.rmdir() instead.
If missing_ok is false (the default), FileNotFoundError is raised if the path does not exist.
If missing_ok is true, FileNotFoundError exceptions will be ignored (same behavior as the POSIX rm -f command).
Changed in version 3.8: The missing_ok parameter was added.


Open the file pointed to in bytes mode, write data to it, and close the file:
An existing file of the same name is overwritten.
New in version 3.5.


Open the file pointed to in text mode, write data to it, and close the file:
An existing file of the same name is overwritten. The optional parameters have the same meaning as in open().
New in version 3.5.


A subclass of Path and PurePosixPath, this class represents concrete non-Windows filesystem paths:
pathsegments is specified similarly to PurePath.


A generic class that represents the system’s path flavour (instantiating it creates either a PurePosixPath or a PureWindowsPath):
Each element of pathsegments can be either a string representing a path segment, an object implementing the os.PathLike interface which returns a string, or another path object:
When pathsegments is empty, the current directory is assumed:
When several absolute paths are given, the last is taken as an anchor (mimicking os.path.join()’s behaviour):
However, in a Windows path, changing the local root doesn’t discard the previous drive setting:
Spurious slashes and single dots are collapsed, but double dots ('..') are not, since this would change the meaning of a path in the face of symbolic links:
(a naïve approach would make PurePosixPath('foo/../bar') equivalent to PurePosixPath('bar'), which is wrong if foo is a symbolic link to another directory)
Pure path objects implement the os.PathLike interface, allowing them to be used anywhere the interface is accepted.
Changed in version 3.6: Added support for the os.PathLike interface.


The concatenation of the drive and root:


Return a string representation of the path with forward slashes (/):


Represent the path as a file URI. ValueError is raised if the path isn’t absolute.


A string representing the drive letter or name, if any:
UNC shares are also considered drives:


Return whether the path is absolute or not. A path is considered absolute if it has both a root and (if the flavour allows) a drive:


Return whether or not this path is relative to the other path.
New in version 3.9.


With PureWindowsPath, return True if the path is considered reserved under Windows, False otherwise. With PurePosixPath, False is always returned.
File system calls on reserved paths can fail mysteriously or have unintended effects.


Calling this method is equivalent to combining the path with each of the other arguments in turn:


Match this path against the provided glob-style pattern. Return True if matching is successful, False otherwise.
If pattern is relative, the path can be either relative or absolute, and matching is done from the right:
If pattern is absolute, the path must be absolute, and the whole path must match:
As with other methods, case-sensitivity follows platform defaults:


A string representing the final path component, excluding the drive and root, if any:
UNC drive names are not considered:


The logical parent of the path:
You cannot go past an anchor, or empty path:
Note
This is a purely lexical operation, hence the following behaviour:
If you want to walk an arbitrary filesystem path upwards, it is recommended to first call Path.resolve() so as to resolve symlinks and eliminate “..” components.


An immutable sequence providing access to the logical ancestors of the path:


A tuple giving access to the path’s various components:
(note how the drive and local root are regrouped in a single part)


Compute a version of this path relative to the path represented by other. If it’s impossible, ValueError is raised:
NOTE: This function is part of PurePath and works with strings. It does not check or access the underlying file structure.


A string representing the (local or global) root, if any:
UNC shares always have a root:


The final path component, without its suffix:


The file extension of the final component, if any:


Return a new path with the name changed. If the original path doesn’t have a name, ValueError is raised:


Return a new path with the stem changed. If the original path doesn’t have a name, ValueError is raised:
New in version 3.9.


Return a new path with the suffix changed. If the original path doesn’t have a suffix, the new suffix is appended instead. If the suffix is an empty string, the original suffix is removed:


A subclass of PurePath, this path flavour represents non-Windows filesystem paths:
pathsegments is specified similarly to PurePath.


A subclass of PurePath, this path flavour represents Windows filesystem paths:
pathsegments is specified similarly to PurePath.


A subclass of Path and PureWindowsPath, this class represents concrete Windows filesystem paths:
pathsegments is specified similarly to PurePath.


Source code: Lib/pdb.py
The module pdb defines an interactive source code debugger for Python programs. It supports setting (conditional) breakpoints and single stepping at the source line level, inspection of stack frames, source code listing, and evaluation of arbitrary Python code in the context of any stack frame. It also supports post-mortem debugging and can be called under program control.
The debugger is extensible – it is actually defined as the class Pdb. This is currently undocumented but easily understood by reading the source. The extension interface uses the modules bdb and cmd.
The debugger’s prompt is (Pdb). Typical usage to run a program under control of the debugger is:
Changed in version 3.3: Tab-completion via the readline module is available for commands and command arguments, e.g. the current global and local names are offered as arguments of the p command.
pdb.py can also be invoked as a script to debug other scripts. For example:
When invoked as a script, pdb will automatically enter post-mortem debugging if the program being debugged exits abnormally. After post-mortem debugging (or after normal exit of the program), pdb will restart the program. Automatic restarting preserves pdb’s state (such as breakpoints) and in most cases is more useful than quitting the debugger upon program’s exit.
New in version 3.2: pdb.py now accepts a -c option that executes commands as if given in a .pdbrc file, see Debugger Commands.
New in version 3.7: pdb.py now accepts a -m option that execute modules similar to the way python3 -m does. As with a script, the debugger will pause execution just before the first line of the module.
The typical usage to break into the debugger from a running program is to insert
at the location you want to break into the debugger. You can then step through the code following this statement, and continue running without the debugger using the continue command.
New in version 3.7: The built-in breakpoint(), when called with defaults, can be used instead of import pdb; pdb.set_trace().
The typical usage to inspect a crashed program is:
The module defines the following functions; each enters the debugger in a slightly different way:
Execute the statement (given as a string or a code object) under debugger control. The debugger prompt appears before any code is executed; you can set breakpoints and type continue, or you can step through the statement using step or next (all these commands are explained below). The optional globals and locals arguments specify the environment in which the code is executed; by default the dictionary of the module __main__ is used. (See the explanation of the built-in exec() or eval() functions.)
Evaluate the expression (given as a string or a code object) under debugger control. When runeval() returns, it returns the value of the expression. Otherwise this function is similar to run().
Call the function (a function or method object, not a string) with the given arguments. When runcall() returns, it returns whatever the function call returned. The debugger prompt appears as soon as the function is entered.
Enter the debugger at the calling stack frame. This is useful to hard-code a breakpoint at a given point in a program, even if the code is not otherwise being debugged (e.g. when an assertion fails). If given, header is printed to the console just before debugging begins.
Changed in version 3.7: The keyword-only argument header.
Enter post-mortem debugging of the given traceback object. If no traceback is given, it uses the one of the exception that is currently being handled (an exception must be being handled if the default is to be used).
Enter post-mortem debugging of the traceback found in sys.last_traceback.
The run* functions and set_trace() are aliases for instantiating the Pdb class and calling the method of the same name. If you want to access further features, you have to do this yourself:
Pdb is the debugger class.
The completekey, stdin and stdout arguments are passed to the underlying cmd.Cmd class; see the description there.
The skip argument, if given, must be an iterable of glob-style module name patterns. The debugger will not step into frames that originate in a module that matches one of these patterns. 1
By default, Pdb sets a handler for the SIGINT signal (which is sent when the user presses Ctrl-C on the console) when you give a continue command. This allows you to break into the debugger again by pressing Ctrl-C. If you want Pdb not to touch the SIGINT handler, set nosigint to true.
The readrc argument defaults to true and controls whether Pdb will load .pdbrc files from the filesystem.
Example call to enable tracing with skip:
Raises an auditing event pdb.Pdb with no arguments.
New in version 3.1: The skip argument.
New in version 3.2: The nosigint argument. Previously, a SIGINT handler was never set by Pdb.
Changed in version 3.6: The readrc argument.
See the documentation for the functions explained above.
The commands recognized by the debugger are listed below. Most commands can be abbreviated to one or two letters as indicated; e.g. h(elp) means that either h or help can be used to enter the help command (but not he or hel, nor H or Help or HELP). Arguments to commands must be separated by whitespace (spaces or tabs). Optional arguments are enclosed in square brackets ([]) in the command syntax; the square brackets must not be typed. Alternatives in the command syntax are separated by a vertical bar (|).
Entering a blank line repeats the last command entered. Exception: if the last command was a list command, the next 11 lines are listed.
Commands that the debugger doesn’t recognize are assumed to be Python statements and are executed in the context of the program being debugged. Python statements can also be prefixed with an exclamation point (!). This is a powerful way to inspect the program being debugged; it is even possible to change a variable or call a function. When an exception occurs in such a statement, the exception name is printed but the debugger’s state is not changed.
The debugger supports aliases. Aliases can have parameters which allows one a certain level of adaptability to the context under examination.
Multiple commands may be entered on a single line, separated by ;;. (A single ; is not used as it is the separator for multiple commands in a line that is passed to the Python parser.) No intelligence is applied to separating the commands; the input is split at the first ;; pair, even if it is in the middle of a quoted string.
If a file .pdbrc exists in the user’s home directory or in the current directory, it is read in and executed as if it had been typed at the debugger prompt. This is particularly useful for aliases. If both files exist, the one in the home directory is read first and aliases defined there can be overridden by the local file.
Changed in version 3.2: .pdbrc can now contain commands that continue debugging, such as continue or next. Previously, these commands had no effect.
Without argument, print the list of available commands. With a command as argument, print help about that command. help pdb displays the full documentation (the docstring of the pdb module). Since the command argument must be an identifier, help exec must be entered to get help on the ! command.
Print a stack trace, with the most recent frame at the bottom. An arrow indicates the current frame, which determines the context of most commands.
Move the current frame count (default one) levels down in the stack trace (to a newer frame).
Move the current frame count (default one) levels up in the stack trace (to an older frame).
With a lineno argument, set a break there in the current file. With a function argument, set a break at the first executable statement within that function. The line number may be prefixed with a filename and a colon, to specify a breakpoint in another file (probably one that hasn’t been loaded yet). The file is searched on sys.path. Note that each breakpoint is assigned a number to which all the other breakpoint commands refer.
If a second argument is present, it is an expression which must evaluate to true before the breakpoint is honored.
Without argument, list all breaks, including for each breakpoint, the number of times that breakpoint has been hit, the current ignore count, and the associated condition if any.
Temporary breakpoint, which is removed automatically when it is first hit. The arguments are the same as for break.
With a filename:lineno argument, clear all the breakpoints at this line. With a space separated list of breakpoint numbers, clear those breakpoints. Without argument, clear all breaks (but first ask confirmation).
Disable the breakpoints given as a space separated list of breakpoint numbers. Disabling a breakpoint means it cannot cause the program to stop execution, but unlike clearing a breakpoint, it remains in the list of breakpoints and can be (re-)enabled.
Enable the breakpoints specified.
Set the ignore count for the given breakpoint number. If count is omitted, the ignore count is set to 0. A breakpoint becomes active when the ignore count is zero. When non-zero, the count is decremented each time the breakpoint is reached and the breakpoint is not disabled and any associated condition evaluates to true.
Set a new condition for the breakpoint, an expression which must evaluate to true before the breakpoint is honored. If condition is absent, any existing condition is removed; i.e., the breakpoint is made unconditional.
Specify a list of commands for breakpoint number bpnumber. The commands themselves appear on the following lines. Type a line containing just end to terminate the commands. An example:
To remove all commands from a breakpoint, type commands and follow it immediately with end; that is, give no commands.
With no bpnumber argument, commands refers to the last breakpoint set.
You can use breakpoint commands to start your program up again. Simply use the continue command, or step, or any other command that resumes execution.
Specifying any command resuming execution (currently continue, step, next, return, jump, quit and their abbreviations) terminates the command list (as if that command was immediately followed by end). This is because any time you resume execution (even with a simple next or step), you may encounter another breakpoint—which could have its own command list, leading to ambiguities about which list to execute.
If you use the ‘silent’ command in the command list, the usual message about stopping at a breakpoint is not printed. This may be desirable for breakpoints that are to print a specific message and then continue. If none of the other commands print anything, you see no sign that the breakpoint was reached.
Execute the current line, stop at the first possible occasion (either in a function that is called or on the next line in the current function).
Continue execution until the next line in the current function is reached or it returns. (The difference between next and step is that step stops inside a called function, while next executes called functions at (nearly) full speed, only stopping at the next line in the current function.)
Without argument, continue execution until the line with a number greater than the current one is reached.
With a line number, continue execution until a line with a number greater or equal to that is reached. In both cases, also stop when the current frame returns.
Changed in version 3.2: Allow giving an explicit line number.
Continue execution until the current function returns.
Continue execution, only stop when a breakpoint is encountered.
Set the next line that will be executed. Only available in the bottom-most frame. This lets you jump back and execute code again, or jump forward to skip code that you don’t want to run.
It should be noted that not all jumps are allowed – for instance it is not possible to jump into the middle of a for loop or out of a finally clause.
List source code for the current file. Without arguments, list 11 lines around the current line or continue the previous listing. With . as argument, list 11 lines around the current line. With one argument, list 11 lines around at that line. With two arguments, list the given range; if the second argument is less than the first, it is interpreted as a count.
The current line in the current frame is indicated by ->. If an exception is being debugged, the line where the exception was originally raised or propagated is indicated by >>, if it differs from the current line.
New in version 3.2: The >> marker.
List all source code for the current function or frame. Interesting lines are marked as for list.
New in version 3.2.
Print the argument list of the current function.
Evaluate the expression in the current context and print its value.
Note
print() can also be used, but is not a debugger command — this executes the Python print() function.
Like the p command, except the value of the expression is pretty-printed using the pprint module.
Print the type of the expression.
Try to get source code for the given object and display it.
New in version 3.2.
Display the value of the expression if it changed, each time execution stops in the current frame.
Without expression, list all display expressions for the current frame.
New in version 3.2.
Do not display the expression any more in the current frame. Without expression, clear all display expressions for the current frame.
New in version 3.2.
Start an interactive interpreter (using the code module) whose global namespace contains all the (global and local) names found in the current scope.
New in version 3.2.
Create an alias called name that executes command. The command must not be enclosed in quotes. Replaceable parameters can be indicated by %1, %2, and so on, while %* is replaced by all the parameters. If no command is given, the current alias for name is shown. If no arguments are given, all aliases are listed.
Aliases may be nested and can contain anything that can be legally typed at the pdb prompt. Note that internal pdb commands can be overridden by aliases. Such a command is then hidden until the alias is removed. Aliasing is recursively applied to the first word of the command line; all other words in the line are left alone.
As an example, here are two useful aliases (especially when placed in the .pdbrc file):
Delete the specified alias.
Execute the (one-line) statement in the context of the current stack frame. The exclamation point can be omitted unless the first word of the statement resembles a debugger command. To set a global variable, you can prefix the assignment command with a global statement on the same line, e.g.:
Restart the debugged Python program. If an argument is supplied, it is split with shlex and the result is used as the new sys.argv. History, breakpoints, actions and debugger options are preserved. restart is an alias for run.
Quit from the debugger. The program being executed is aborted.
Enter a recursive debugger that steps through the code argument (which is an arbitrary expression or statement to be executed in the current environment).
Print the return value for the last return of a function.
Whether a frame is considered to originate in a certain module is determined by the __name__ in the frame globals.


Pdb is the debugger class.
The completekey, stdin and stdout arguments are passed to the underlying cmd.Cmd class; see the description there.
The skip argument, if given, must be an iterable of glob-style module name patterns. The debugger will not step into frames that originate in a module that matches one of these patterns. 1
By default, Pdb sets a handler for the SIGINT signal (which is sent when the user presses Ctrl-C on the console) when you give a continue command. This allows you to break into the debugger again by pressing Ctrl-C. If you want Pdb not to touch the SIGINT handler, set nosigint to true.
The readrc argument defaults to true and controls whether Pdb will load .pdbrc files from the filesystem.
Example call to enable tracing with skip:
Raises an auditing event pdb.Pdb with no arguments.
New in version 3.1: The skip argument.
New in version 3.2: The nosigint argument. Previously, a SIGINT handler was never set by Pdb.
Changed in version 3.6: The readrc argument.
See the documentation for the functions explained above.


See the documentation for the functions explained above.


Enter post-mortem debugging of the traceback found in sys.last_traceback.


Enter post-mortem debugging of the given traceback object. If no traceback is given, it uses the one of the exception that is currently being handled (an exception must be being handled if the default is to be used).


Execute the statement (given as a string or a code object) under debugger control. The debugger prompt appears before any code is executed; you can set breakpoints and type continue, or you can step through the statement using step or next (all these commands are explained below). The optional globals and locals arguments specify the environment in which the code is executed; by default the dictionary of the module __main__ is used. (See the explanation of the built-in exec() or eval() functions.)


Call the function (a function or method object, not a string) with the given arguments. When runcall() returns, it returns whatever the function call returned. The debugger prompt appears as soon as the function is entered.


Evaluate the expression (given as a string or a code object) under debugger control. When runeval() returns, it returns the value of the expression. Otherwise this function is similar to run().


Enter the debugger at the calling stack frame. This is useful to hard-code a breakpoint at a given point in a program, even if the code is not otherwise being debugged (e.g. when an assertion fails). If given, header is printed to the console just before debugging begins.
Changed in version 3.7: The keyword-only argument header.


Base class for warnings about features which are obsolete and expected to be deprecated in the future, but are not deprecated at the moment.
This class is rarely used as emitting a warning about a possible upcoming deprecation is unusual, and DeprecationWarning is preferred for already active deprecations.
Ignored by the default warning filters. Enabling the Python Development Mode shows this warning.


Raised when trying to run an operation without the adequate access rights - for example filesystem permissions. Corresponds to errno EACCES and EPERM.


Source code: Lib/pickle.py
The pickle module implements binary protocols for serializing and de-serializing a Python object structure. “Pickling” is the process whereby a Python object hierarchy is converted into a byte stream, and “unpickling” is the inverse operation, whereby a byte stream (from a binary file or bytes-like object) is converted back into an object hierarchy. Pickling (and unpickling) is alternatively known as “serialization”, “marshalling,” 1 or “flattening”; however, to avoid confusion, the terms used here are “pickling” and “unpickling”.
Warning
The pickle module is not secure. Only unpickle data you trust.
It is possible to construct malicious pickle data which will execute arbitrary code during unpickling. Never unpickle data that could have come from an untrusted source, or that could have been tampered with.
Consider signing data with hmac if you need to ensure that it has not been tampered with.
Safer serialization formats such as json may be more appropriate if you are processing untrusted data. See Comparison with json.
Python has a more primitive serialization module called marshal, but in general pickle should always be the preferred way to serialize Python objects. marshal exists primarily to support Python’s .pyc files.
The pickle module differs from marshal in several significant ways:
The pickle module keeps track of the objects it has already serialized, so that later references to the same object won’t be serialized again. marshal doesn’t do this.
This has implications both for recursive objects and object sharing. Recursive objects are objects that contain references to themselves. These are not handled by marshal, and in fact, attempting to marshal recursive objects will crash your Python interpreter. Object sharing happens when there are multiple references to the same object in different places in the object hierarchy being serialized. pickle stores such objects only once, and ensures that all other references point to the master copy. Shared objects remain shared, which can be very important for mutable objects.
There are fundamental differences between the pickle protocols and JSON (JavaScript Object Notation):
See also
The json module: a standard library module allowing JSON serialization and deserialization.
The data format used by pickle is Python-specific. This has the advantage that there are no restrictions imposed by external standards such as JSON or XDR (which can’t represent pointer sharing); however it means that non-Python programs may not be able to reconstruct pickled Python objects.
By default, the pickle data format uses a relatively compact binary representation. If you need optimal size characteristics, you can efficiently compress pickled data.
The module pickletools contains tools for analyzing data streams generated by pickle. pickletools source code has extensive comments about opcodes used by pickle protocols.
There are currently 6 different protocols which can be used for pickling. The higher the protocol used, the more recent the version of Python needed to read the pickle produced.
Note
Serialization is a more primitive notion than persistence; although pickle reads and writes file objects, it does not handle the issue of naming persistent objects, nor the (even more complicated) issue of concurrent access to persistent objects. The pickle module can transform a complex object into a byte stream and it can transform the byte stream into an object with the same internal structure. Perhaps the most obvious thing to do with these byte streams is to write them onto a file, but it is also conceivable to send them across a network or store them in a database. The shelve module provides a simple interface to pickle and unpickle objects on DBM-style database files.
To serialize an object hierarchy, you simply call the dumps() function. Similarly, to de-serialize a data stream, you call the loads() function. However, if you want more control over serialization and de-serialization, you can create a Pickler or an Unpickler object, respectively.
The pickle module provides the following constants:
An integer, the highest protocol version available. This value can be passed as a protocol value to functions dump() and dumps() as well as the Pickler constructor.
An integer, the default protocol version used for pickling. May be less than HIGHEST_PROTOCOL. Currently the default protocol is 4, first introduced in Python 3.4 and incompatible with previous versions.
Changed in version 3.0: The default protocol is 3.
Changed in version 3.8: The default protocol is 4.
The pickle module provides the following functions to make the pickling process more convenient:
Write the pickled representation of the object obj to the open file object file. This is equivalent to Pickler(file, protocol).dump(obj).
Arguments file, protocol, fix_imports and buffer_callback have the same meaning as in the Pickler constructor.
Changed in version 3.8: The buffer_callback argument was added.
Return the pickled representation of the object obj as a bytes object, instead of writing it to a file.
Arguments protocol, fix_imports and buffer_callback have the same meaning as in the Pickler constructor.
Changed in version 3.8: The buffer_callback argument was added.
Read the pickled representation of an object from the open file object file and return the reconstituted object hierarchy specified therein. This is equivalent to Unpickler(file).load().
The protocol version of the pickle is detected automatically, so no protocol argument is needed. Bytes past the pickled representation of the object are ignored.
Arguments file, fix_imports, encoding, errors, strict and buffers have the same meaning as in the Unpickler constructor.
Changed in version 3.8: The buffers argument was added.
Return the reconstituted object hierarchy of the pickled representation data of an object. data must be a bytes-like object.
The protocol version of the pickle is detected automatically, so no protocol argument is needed. Bytes past the pickled representation of the object are ignored.
Arguments file, fix_imports, encoding, errors, strict and buffers have the same meaning as in the Unpickler constructor.
Changed in version 3.8: The buffers argument was added.
The pickle module defines three exceptions:
Common base class for the other pickling exceptions. It inherits Exception.
Error raised when an unpicklable object is encountered by Pickler. It inherits PickleError.
Refer to What can be pickled and unpickled? to learn what kinds of objects can be pickled.
Error raised when there is a problem unpickling an object, such as a data corruption or a security violation. It inherits PickleError.
Note that other exceptions may also be raised during unpickling, including (but not necessarily limited to) AttributeError, EOFError, ImportError, and IndexError.
The pickle module exports three classes, Pickler, Unpickler and PickleBuffer:
This takes a binary file for writing a pickle data stream.
The optional protocol argument, an integer, tells the pickler to use the given protocol; supported protocols are 0 to HIGHEST_PROTOCOL. If not specified, the default is DEFAULT_PROTOCOL. If a negative number is specified, HIGHEST_PROTOCOL is selected.
The file argument must have a write() method that accepts a single bytes argument. It can thus be an on-disk file opened for binary writing, an io.BytesIO instance, or any other custom object that meets this interface.
If fix_imports is true and protocol is less than 3, pickle will try to map the new Python 3 names to the old module names used in Python 2, so that the pickle data stream is readable with Python 2.
If buffer_callback is None (the default), buffer views are serialized into file as part of the pickle stream.
If buffer_callback is not None, then it can be called any number of times with a buffer view. If the callback returns a false value (such as None), the given buffer is out-of-band; otherwise the buffer is serialized in-band, i.e. inside the pickle stream.
It is an error if buffer_callback is not None and protocol is None or smaller than 5.
Changed in version 3.8: The buffer_callback argument was added.
Write the pickled representation of obj to the open file object given in the constructor.
Do nothing by default. This exists so a subclass can override it.
If persistent_id() returns None, obj is pickled as usual. Any other value causes Pickler to emit the returned value as a persistent ID for obj. The meaning of this persistent ID should be defined by Unpickler.persistent_load(). Note that the value returned by persistent_id() cannot itself have a persistent ID.
See Persistence of External Objects for details and examples of uses.
A pickler object’s dispatch table is a registry of reduction functions of the kind which can be declared using copyreg.pickle(). It is a mapping whose keys are classes and whose values are reduction functions. A reduction function takes a single argument of the associated class and should conform to the same interface as a __reduce__() method.
By default, a pickler object will not have a dispatch_table attribute, and it will instead use the global dispatch table managed by the copyreg module. However, to customize the pickling for a specific pickler object one can set the dispatch_table attribute to a dict-like object. Alternatively, if a subclass of Pickler has a dispatch_table attribute then this will be used as the default dispatch table for instances of that class.
See Dispatch Tables for usage examples.
New in version 3.3.
Special reducer that can be defined in Pickler subclasses. This method has priority over any reducer in the dispatch_table. It should conform to the same interface as a __reduce__() method, and can optionally return NotImplemented to fallback on dispatch_table-registered reducers to pickle obj.
For a detailed example, see Custom Reduction for Types, Functions, and Other Objects.
New in version 3.8.
Deprecated. Enable fast mode if set to a true value. The fast mode disables the usage of memo, therefore speeding the pickling process by not generating superfluous PUT opcodes. It should not be used with self-referential objects, doing otherwise will cause Pickler to recurse infinitely.
Use pickletools.optimize() if you need more compact pickles.
This takes a binary file for reading a pickle data stream.
The protocol version of the pickle is detected automatically, so no protocol argument is needed.
The argument file must have three methods, a read() method that takes an integer argument, a readinto() method that takes a buffer argument and a readline() method that requires no arguments, as in the io.BufferedIOBase interface. Thus file can be an on-disk file opened for binary reading, an io.BytesIO object, or any other custom object that meets this interface.
The optional arguments fix_imports, encoding and errors are used to control compatibility support for pickle stream generated by Python 2. If fix_imports is true, pickle will try to map the old Python 2 names to the new names used in Python 3. The encoding and errors tell pickle how to decode 8-bit string instances pickled by Python 2; these default to ‘ASCII’ and ‘strict’, respectively. The encoding can be ‘bytes’ to read these 8-bit string instances as bytes objects. Using encoding='latin1' is required for unpickling NumPy arrays and instances of datetime, date and time pickled by Python 2.
If buffers is None (the default), then all data necessary for deserialization must be contained in the pickle stream. This means that the buffer_callback argument was None when a Pickler was instantiated (or when dump() or dumps() was called).
If buffers is not None, it should be an iterable of buffer-enabled objects that is consumed each time the pickle stream references an out-of-band buffer view. Such buffers have been given in order to the buffer_callback of a Pickler object.
Changed in version 3.8: The buffers argument was added.
Read the pickled representation of an object from the open file object given in the constructor, and return the reconstituted object hierarchy specified therein. Bytes past the pickled representation of the object are ignored.
Raise an UnpicklingError by default.
If defined, persistent_load() should return the object specified by the persistent ID pid. If an invalid persistent ID is encountered, an UnpicklingError should be raised.
See Persistence of External Objects for details and examples of uses.
Import module if necessary and return the object called name from it, where the module and name arguments are str objects. Note, unlike its name suggests, find_class() is also used for finding functions.
Subclasses may override this to gain control over what type of objects and how they can be loaded, potentially reducing security risks. Refer to Restricting Globals for details.
Raises an auditing event pickle.find_class with arguments module, name.
A wrapper for a buffer representing picklable data. buffer must be a buffer-providing object, such as a bytes-like object or a N-dimensional array.
PickleBuffer is itself a buffer provider, therefore it is possible to pass it to other APIs expecting a buffer-providing object, such as memoryview.
PickleBuffer objects can only be serialized using pickle protocol 5 or higher. They are eligible for out-of-band serialization.
New in version 3.8.
Return a memoryview of the memory area underlying this buffer. The returned object is a one-dimensional, C-contiguous memoryview with format B (unsigned bytes). BufferError is raised if the buffer is neither C- nor Fortran-contiguous.
Release the underlying buffer exposed by the PickleBuffer object.
The following types can be pickled:
Attempts to pickle unpicklable objects will raise the PicklingError exception; when this happens, an unspecified number of bytes may have already been written to the underlying file. Trying to pickle a highly recursive data structure may exceed the maximum recursion depth, a RecursionError will be raised in this case. You can carefully raise this limit with sys.setrecursionlimit().
Note that functions (built-in and user-defined) are pickled by “fully qualified” name reference, not by value. 2 This means that only the function name is pickled, along with the name of the module the function is defined in. Neither the function’s code, nor any of its function attributes are pickled. Thus the defining module must be importable in the unpickling environment, and the module must contain the named object, otherwise an exception will be raised. 3
Similarly, classes are pickled by named reference, so the same restrictions in the unpickling environment apply. Note that none of the class’s code or data is pickled, so in the following example the class attribute attr is not restored in the unpickling environment:
These restrictions are why picklable functions and classes must be defined in the top level of a module.
Similarly, when class instances are pickled, their class’s code and data are not pickled along with them. Only the instance data are pickled. This is done on purpose, so you can fix bugs in a class or add methods to the class and still load objects that were created with an earlier version of the class. If you plan to have long-lived objects that will see many versions of a class, it may be worthwhile to put a version number in the objects so that suitable conversions can be made by the class’s __setstate__() method.
In this section, we describe the general mechanisms available to you to define, customize, and control how class instances are pickled and unpickled.
In most cases, no additional code is needed to make instances picklable. By default, pickle will retrieve the class and the attributes of an instance via introspection. When a class instance is unpickled, its __init__() method is usually not invoked. The default behaviour first creates an uninitialized instance and then restores the saved attributes. The following code shows an implementation of this behaviour:
Classes can alter the default behaviour by providing one or several special methods:
In protocols 2 and newer, classes that implements the __getnewargs_ex__() method can dictate the values passed to the __new__() method upon unpickling. The method must return a pair (args, kwargs) where args is a tuple of positional arguments and kwargs a dictionary of named arguments for constructing the object. Those will be passed to the __new__() method upon unpickling.
You should implement this method if the __new__() method of your class requires keyword-only arguments. Otherwise, it is recommended for compatibility to implement __getnewargs__().
Changed in version 3.6: __getnewargs_ex__() is now used in protocols 2 and 3.
This method serves a similar purpose as __getnewargs_ex__(), but supports only positional arguments. It must return a tuple of arguments args which will be passed to the __new__() method upon unpickling.
__getnewargs__() will not be called if __getnewargs_ex__() is defined.
Changed in version 3.6: Before Python 3.6, __getnewargs__() was called instead of __getnewargs_ex__() in protocols 2 and 3.
Classes can further influence how their instances are pickled; if the class defines the method __getstate__(), it is called and the returned object is pickled as the contents for the instance, instead of the contents of the instance’s dictionary. If the __getstate__() method is absent, the instance’s __dict__ is pickled as usual.
Upon unpickling, if the class defines __setstate__(), it is called with the unpickled state. In that case, there is no requirement for the state object to be a dictionary. Otherwise, the pickled state must be a dictionary and its items are assigned to the new instance’s dictionary.
Note
If __getstate__() returns a false value, the __setstate__() method will not be called upon unpickling.
Refer to the section Handling Stateful Objects for more information about how to use the methods __getstate__() and __setstate__().
Note
At unpickling time, some methods like __getattr__(), __getattribute__(), or __setattr__() may be called upon the instance. In case those methods rely on some internal invariant being true, the type should implement __new__() to establish such an invariant, as __init__() is not called when unpickling an instance.
As we shall see, pickle does not use directly the methods described above. In fact, these methods are part of the copy protocol which implements the __reduce__() special method. The copy protocol provides a unified interface for retrieving the data necessary for pickling and copying objects. 4
Although powerful, implementing __reduce__() directly in your classes is error prone. For this reason, class designers should use the high-level interface (i.e., __getnewargs_ex__(), __getstate__() and __setstate__()) whenever possible. We will show, however, cases where using __reduce__() is the only option or leads to more efficient pickling or both.
The interface is currently defined as follows. The __reduce__() method takes no argument and shall return either a string or preferably a tuple (the returned object is often referred to as the “reduce value”).
If a string is returned, the string should be interpreted as the name of a global variable. It should be the object’s local name relative to its module; the pickle module searches the module namespace to determine the object’s module. This behaviour is typically useful for singletons.
When a tuple is returned, it must be between two and six items long. Optional items can either be omitted, or None can be provided as their value. The semantics of each item are in order:
Optionally, a callable with a (obj, state) signature. This callable allows the user to programmatically control the state-updating behavior of a specific object, instead of using obj’s static __setstate__() method. If not None, this callable will have priority over obj’s __setstate__().
New in version 3.8: The optional sixth tuple item, (obj, state), was added.
Alternatively, a __reduce_ex__() method may be defined. The only difference is this method should take a single integer argument, the protocol version. When defined, pickle will prefer it over the __reduce__() method. In addition, __reduce__() automatically becomes a synonym for the extended version. The main use for this method is to provide backwards-compatible reduce values for older Python releases.
For the benefit of object persistence, the pickle module supports the notion of a reference to an object outside the pickled data stream. Such objects are referenced by a persistent ID, which should be either a string of alphanumeric characters (for protocol 0) 5 or just an arbitrary object (for any newer protocol).
The resolution of such persistent IDs is not defined by the pickle module; it will delegate this resolution to the user-defined methods on the pickler and unpickler, persistent_id() and persistent_load() respectively.
To pickle objects that have an external persistent ID, the pickler must have a custom persistent_id() method that takes an object as an argument and returns either None or the persistent ID for that object. When None is returned, the pickler simply pickles the object as normal. When a persistent ID string is returned, the pickler will pickle that object, along with a marker so that the unpickler will recognize it as a persistent ID.
To unpickle external objects, the unpickler must have a custom persistent_load() method that takes a persistent ID object and returns the referenced object.
Here is a comprehensive example presenting how persistent ID can be used to pickle external objects by reference.
If one wants to customize pickling of some classes without disturbing any other code which depends on pickling, then one can create a pickler with a private dispatch table.
The global dispatch table managed by the copyreg module is available as copyreg.dispatch_table. Therefore, one may choose to use a modified copy of copyreg.dispatch_table as a private dispatch table.
For example
creates an instance of pickle.Pickler with a private dispatch table which handles the SomeClass class specially. Alternatively, the code
does the same, but all instances of MyPickler will by default share the same dispatch table. The equivalent code using the copyreg module is
Here’s an example that shows how to modify pickling behavior for a class. The TextReader class opens a text file, and returns the line number and line contents each time its readline() method is called. If a TextReader instance is pickled, all attributes except the file object member are saved. When the instance is unpickled, the file is reopened, and reading resumes from the last location. The __setstate__() and __getstate__() methods are used to implement this behavior.
A sample usage might be something like this:
New in version 3.8.
Sometimes, dispatch_table may not be flexible enough. In particular we may want to customize pickling based on another criterion than the object’s type, or we may want to customize the pickling of functions and classes.
For those cases, it is possible to subclass from the Pickler class and implement a reducer_override() method. This method can return an arbitrary reduction tuple (see __reduce__()). It can alternatively return NotImplemented to fallback to the traditional behavior.
If both the dispatch_table and reducer_override() are defined, then reducer_override() method takes priority.
Note
For performance reasons, reducer_override() may not be called for the following objects: None, True, False, and exact instances of int, float, bytes, str, dict, set, frozenset, list and tuple.
Here is a simple example where we allow pickling and reconstructing a given class:
New in version 3.8.
In some contexts, the pickle module is used to transfer massive amounts of data. Therefore, it can be important to minimize the number of memory copies, to preserve performance and resource consumption. However, normal operation of the pickle module, as it transforms a graph-like structure of objects into a sequential stream of bytes, intrinsically involves copying data to and from the pickle stream.
This constraint can be eschewed if both the provider (the implementation of the object types to be transferred) and the consumer (the implementation of the communications system) support the out-of-band transfer facilities provided by pickle protocol 5 and higher.
The large data objects to be pickled must implement a __reduce_ex__() method specialized for protocol 5 and higher, which returns a PickleBuffer instance (instead of e.g. a bytes object) for any large data.
A PickleBuffer object signals that the underlying buffer is eligible for out-of-band data transfer. Those objects remain compatible with normal usage of the pickle module. However, consumers can also opt-in to tell pickle that they will handle those buffers by themselves.
A communications system can enable custom handling of the PickleBuffer objects generated when serializing an object graph.
On the sending side, it needs to pass a buffer_callback argument to Pickler (or to the dump() or dumps() function), which will be called with each PickleBuffer generated while pickling the object graph. Buffers accumulated by the buffer_callback will not see their data copied into the pickle stream, only a cheap marker will be inserted.
On the receiving side, it needs to pass a buffers argument to Unpickler (or to the load() or loads() function), which is an iterable of the buffers which were passed to buffer_callback. That iterable should produce buffers in the same order as they were passed to buffer_callback. Those buffers will provide the data expected by the reconstructors of the objects whose pickling produced the original PickleBuffer objects.
Between the sending side and the receiving side, the communications system is free to implement its own transfer mechanism for out-of-band buffers. Potential optimizations include the use of shared memory or datatype-dependent compression.
Here is a trivial example where we implement a bytearray subclass able to participate in out-of-band buffer pickling:
The reconstructor (the _reconstruct class method) returns the buffer’s providing object if it has the right type. This is an easy way to simulate zero-copy behaviour on this toy example.
On the consumer side, we can pickle those objects the usual way, which when unserialized will give us a copy of the original object:
But if we pass a buffer_callback and then give back the accumulated buffers when unserializing, we are able to get back the original object:
This example is limited by the fact that bytearray allocates its own memory: you cannot create a bytearray instance that is backed by another object’s memory. However, third-party datatypes such as NumPy arrays do not have this limitation, and allow use of zero-copy pickling (or making as few copies as possible) when transferring between distinct processes or systems.
See also
PEP 574 – Pickle protocol 5 with out-of-band data
By default, unpickling will import any class or function that it finds in the pickle data. For many applications, this behaviour is unacceptable as it permits the unpickler to import and invoke arbitrary code. Just consider what this hand-crafted pickle data stream does when loaded:
In this example, the unpickler imports the os.system() function and then apply the string argument “echo hello world”. Although this example is inoffensive, it is not difficult to imagine one that could damage your system.
For this reason, you may want to control what gets unpickled by customizing Unpickler.find_class(). Unlike its name suggests, Unpickler.find_class() is called whenever a global (i.e., a class or a function) is requested. Thus it is possible to either completely forbid globals or restrict them to a safe subset.
Here is an example of an unpickler allowing only few safe classes from the builtins module to be loaded:
A sample usage of our unpickler working has intended:
As our examples shows, you have to be careful with what you allow to be unpickled. Therefore if security is a concern, you may want to consider alternatives such as the marshalling API in xmlrpc.client or third-party solutions.
Recent versions of the pickle protocol (from protocol 2 and upwards) feature efficient binary encodings for several common features and built-in types. Also, the pickle module has a transparent optimizer written in C.
For the simplest code, use the dump() and load() functions.
The following example reads the resulting pickled data.
See also
Pickle interface constructor registration for extension types.
Tools for working with and analyzing pickled data.
Indexed databases of objects; uses pickle.
Shallow and deep object copying.
High-performance serialization of built-in types.
Don’t confuse this with the marshal module
This is why lambda functions cannot be pickled: all lambda functions share the same name: <lambda>.
The exception raised will likely be an ImportError or an AttributeError but it could be something else.
The copy module uses this protocol for shallow and deep copying operations.
The limitation on alphanumeric characters is due to the fact the persistent IDs, in protocol 0, are delimited by the newline character. Therefore if any kind of newline characters occurs in persistent IDs, the resulting pickle will become unreadable.


An integer, the default protocol version used for pickling. May be less than HIGHEST_PROTOCOL. Currently the default protocol is 4, first introduced in Python 3.4 and incompatible with previous versions.
Changed in version 3.0: The default protocol is 3.
Changed in version 3.8: The default protocol is 4.


Write the pickled representation of the object obj to the open file object file. This is equivalent to Pickler(file, protocol).dump(obj).
Arguments file, protocol, fix_imports and buffer_callback have the same meaning as in the Pickler constructor.
Changed in version 3.8: The buffer_callback argument was added.


Return the pickled representation of the object obj as a bytes object, instead of writing it to a file.
Arguments protocol, fix_imports and buffer_callback have the same meaning as in the Pickler constructor.
Changed in version 3.8: The buffer_callback argument was added.


An integer, the highest protocol version available. This value can be passed as a protocol value to functions dump() and dumps() as well as the Pickler constructor.


Read the pickled representation of an object from the open file object file and return the reconstituted object hierarchy specified therein. This is equivalent to Unpickler(file).load().
The protocol version of the pickle is detected automatically, so no protocol argument is needed. Bytes past the pickled representation of the object are ignored.
Arguments file, fix_imports, encoding, errors, strict and buffers have the same meaning as in the Unpickler constructor.
Changed in version 3.8: The buffers argument was added.


Return the reconstituted object hierarchy of the pickled representation data of an object. data must be a bytes-like object.
The protocol version of the pickle is detected automatically, so no protocol argument is needed. Bytes past the pickled representation of the object are ignored.
Arguments file, fix_imports, encoding, errors, strict and buffers have the same meaning as in the Unpickler constructor.
Changed in version 3.8: The buffers argument was added.


A wrapper for a buffer representing picklable data. buffer must be a buffer-providing object, such as a bytes-like object or a N-dimensional array.
PickleBuffer is itself a buffer provider, therefore it is possible to pass it to other APIs expecting a buffer-providing object, such as memoryview.
PickleBuffer objects can only be serialized using pickle protocol 5 or higher. They are eligible for out-of-band serialization.
New in version 3.8.
Return a memoryview of the memory area underlying this buffer. The returned object is a one-dimensional, C-contiguous memoryview with format B (unsigned bytes). BufferError is raised if the buffer is neither C- nor Fortran-contiguous.
Release the underlying buffer exposed by the PickleBuffer object.


Return a memoryview of the memory area underlying this buffer. The returned object is a one-dimensional, C-contiguous memoryview with format B (unsigned bytes). BufferError is raised if the buffer is neither C- nor Fortran-contiguous.


Release the underlying buffer exposed by the PickleBuffer object.


Common base class for the other pickling exceptions. It inherits Exception.


This takes a binary file for writing a pickle data stream.
The optional protocol argument, an integer, tells the pickler to use the given protocol; supported protocols are 0 to HIGHEST_PROTOCOL. If not specified, the default is DEFAULT_PROTOCOL. If a negative number is specified, HIGHEST_PROTOCOL is selected.
The file argument must have a write() method that accepts a single bytes argument. It can thus be an on-disk file opened for binary writing, an io.BytesIO instance, or any other custom object that meets this interface.
If fix_imports is true and protocol is less than 3, pickle will try to map the new Python 3 names to the old module names used in Python 2, so that the pickle data stream is readable with Python 2.
If buffer_callback is None (the default), buffer views are serialized into file as part of the pickle stream.
If buffer_callback is not None, then it can be called any number of times with a buffer view. If the callback returns a false value (such as None), the given buffer is out-of-band; otherwise the buffer is serialized in-band, i.e. inside the pickle stream.
It is an error if buffer_callback is not None and protocol is None or smaller than 5.
Changed in version 3.8: The buffer_callback argument was added.
Write the pickled representation of obj to the open file object given in the constructor.
Do nothing by default. This exists so a subclass can override it.
If persistent_id() returns None, obj is pickled as usual. Any other value causes Pickler to emit the returned value as a persistent ID for obj. The meaning of this persistent ID should be defined by Unpickler.persistent_load(). Note that the value returned by persistent_id() cannot itself have a persistent ID.
See Persistence of External Objects for details and examples of uses.
A pickler object’s dispatch table is a registry of reduction functions of the kind which can be declared using copyreg.pickle(). It is a mapping whose keys are classes and whose values are reduction functions. A reduction function takes a single argument of the associated class and should conform to the same interface as a __reduce__() method.
By default, a pickler object will not have a dispatch_table attribute, and it will instead use the global dispatch table managed by the copyreg module. However, to customize the pickling for a specific pickler object one can set the dispatch_table attribute to a dict-like object. Alternatively, if a subclass of Pickler has a dispatch_table attribute then this will be used as the default dispatch table for instances of that class.
See Dispatch Tables for usage examples.
New in version 3.3.
Special reducer that can be defined in Pickler subclasses. This method has priority over any reducer in the dispatch_table. It should conform to the same interface as a __reduce__() method, and can optionally return NotImplemented to fallback on dispatch_table-registered reducers to pickle obj.
For a detailed example, see Custom Reduction for Types, Functions, and Other Objects.
New in version 3.8.
Deprecated. Enable fast mode if set to a true value. The fast mode disables the usage of memo, therefore speeding the pickling process by not generating superfluous PUT opcodes. It should not be used with self-referential objects, doing otherwise will cause Pickler to recurse infinitely.
Use pickletools.optimize() if you need more compact pickles.


A pickler object’s dispatch table is a registry of reduction functions of the kind which can be declared using copyreg.pickle(). It is a mapping whose keys are classes and whose values are reduction functions. A reduction function takes a single argument of the associated class and should conform to the same interface as a __reduce__() method.
By default, a pickler object will not have a dispatch_table attribute, and it will instead use the global dispatch table managed by the copyreg module. However, to customize the pickling for a specific pickler object one can set the dispatch_table attribute to a dict-like object. Alternatively, if a subclass of Pickler has a dispatch_table attribute then this will be used as the default dispatch table for instances of that class.
See Dispatch Tables for usage examples.
New in version 3.3.


Write the pickled representation of obj to the open file object given in the constructor.


Deprecated. Enable fast mode if set to a true value. The fast mode disables the usage of memo, therefore speeding the pickling process by not generating superfluous PUT opcodes. It should not be used with self-referential objects, doing otherwise will cause Pickler to recurse infinitely.
Use pickletools.optimize() if you need more compact pickles.


Do nothing by default. This exists so a subclass can override it.
If persistent_id() returns None, obj is pickled as usual. Any other value causes Pickler to emit the returned value as a persistent ID for obj. The meaning of this persistent ID should be defined by Unpickler.persistent_load(). Note that the value returned by persistent_id() cannot itself have a persistent ID.
See Persistence of External Objects for details and examples of uses.


Special reducer that can be defined in Pickler subclasses. This method has priority over any reducer in the dispatch_table. It should conform to the same interface as a __reduce__() method, and can optionally return NotImplemented to fallback on dispatch_table-registered reducers to pickle obj.
For a detailed example, see Custom Reduction for Types, Functions, and Other Objects.
New in version 3.8.


Error raised when an unpicklable object is encountered by Pickler. It inherits PickleError.
Refer to What can be pickled and unpickled? to learn what kinds of objects can be pickled.


This takes a binary file for reading a pickle data stream.
The protocol version of the pickle is detected automatically, so no protocol argument is needed.
The argument file must have three methods, a read() method that takes an integer argument, a readinto() method that takes a buffer argument and a readline() method that requires no arguments, as in the io.BufferedIOBase interface. Thus file can be an on-disk file opened for binary reading, an io.BytesIO object, or any other custom object that meets this interface.
The optional arguments fix_imports, encoding and errors are used to control compatibility support for pickle stream generated by Python 2. If fix_imports is true, pickle will try to map the old Python 2 names to the new names used in Python 3. The encoding and errors tell pickle how to decode 8-bit string instances pickled by Python 2; these default to ‘ASCII’ and ‘strict’, respectively. The encoding can be ‘bytes’ to read these 8-bit string instances as bytes objects. Using encoding='latin1' is required for unpickling NumPy arrays and instances of datetime, date and time pickled by Python 2.
If buffers is None (the default), then all data necessary for deserialization must be contained in the pickle stream. This means that the buffer_callback argument was None when a Pickler was instantiated (or when dump() or dumps() was called).
If buffers is not None, it should be an iterable of buffer-enabled objects that is consumed each time the pickle stream references an out-of-band buffer view. Such buffers have been given in order to the buffer_callback of a Pickler object.
Changed in version 3.8: The buffers argument was added.
Read the pickled representation of an object from the open file object given in the constructor, and return the reconstituted object hierarchy specified therein. Bytes past the pickled representation of the object are ignored.
Raise an UnpicklingError by default.
If defined, persistent_load() should return the object specified by the persistent ID pid. If an invalid persistent ID is encountered, an UnpicklingError should be raised.
See Persistence of External Objects for details and examples of uses.
Import module if necessary and return the object called name from it, where the module and name arguments are str objects. Note, unlike its name suggests, find_class() is also used for finding functions.
Subclasses may override this to gain control over what type of objects and how they can be loaded, potentially reducing security risks. Refer to Restricting Globals for details.
Raises an auditing event pickle.find_class with arguments module, name.


Import module if necessary and return the object called name from it, where the module and name arguments are str objects. Note, unlike its name suggests, find_class() is also used for finding functions.
Subclasses may override this to gain control over what type of objects and how they can be loaded, potentially reducing security risks. Refer to Restricting Globals for details.
Raises an auditing event pickle.find_class with arguments module, name.


Read the pickled representation of an object from the open file object given in the constructor, and return the reconstituted object hierarchy specified therein. Bytes past the pickled representation of the object are ignored.


Raise an UnpicklingError by default.
If defined, persistent_load() should return the object specified by the persistent ID pid. If an invalid persistent ID is encountered, an UnpicklingError should be raised.
See Persistence of External Objects for details and examples of uses.


Error raised when there is a problem unpickling an object, such as a data corruption or a security violation. It inherits PickleError.
Note that other exceptions may also be raised during unpickling, including (but not necessarily limited to) AttributeError, EOFError, ImportError, and IndexError.


Source code: Lib/pickletools.py
This module contains various constants relating to the intimate details of the pickle module, some lengthy comments about the implementation, and a few useful functions for analyzing pickled data. The contents of this module are useful for Python core developers who are working on the pickle; ordinary users of the pickle module probably won’t find the pickletools module relevant.
New in version 3.2.
When invoked from the command line, python -m pickletools will disassemble the contents of one or more pickle files. Note that if you want to see the Python object stored in the pickle rather than the details of pickle format, you may want to use -m pickle instead. However, when the pickle file that you want to examine comes from an untrusted source, -m pickletools is a safer option because it does not execute pickle bytecode.
For example, with a tuple (1, 2) pickled in file x.pickle:
Annotate each line with a short opcode description.
Name of a file where the output should be written.
The number of blanks by which to indent a new MARK level.
When multiple objects are disassembled, preserve memo between disassemblies.
When more than one pickle file are specified, print given preamble before each disassembly.
Outputs a symbolic disassembly of the pickle to the file-like object out, defaulting to sys.stdout. pickle can be a string or a file-like object. memo can be a Python dictionary that will be used as the pickle’s memo; it can be used to perform disassemblies across multiple pickles created by the same pickler. Successive levels, indicated by MARK opcodes in the stream, are indented by indentlevel spaces. If a nonzero value is given to annotate, each opcode in the output is annotated with a short description. The value of annotate is used as a hint for the column where annotation should start.
New in version 3.2: The annotate argument.
Provides an iterator over all of the opcodes in a pickle, returning a sequence of (opcode, arg, pos) triples. opcode is an instance of an OpcodeInfo class; arg is the decoded value, as a Python object, of the opcode’s argument; pos is the position at which this opcode is located. pickle can be a string or a file-like object.
Returns a new equivalent pickle string after eliminating unused PUT opcodes. The optimized pickle is shorter, takes less transmission time, requires less storage space, and unpickles more efficiently.


Outputs a symbolic disassembly of the pickle to the file-like object out, defaulting to sys.stdout. pickle can be a string or a file-like object. memo can be a Python dictionary that will be used as the pickle’s memo; it can be used to perform disassemblies across multiple pickles created by the same pickler. Successive levels, indicated by MARK opcodes in the stream, are indented by indentlevel spaces. If a nonzero value is given to annotate, each opcode in the output is annotated with a short description. The value of annotate is used as a hint for the column where annotation should start.
New in version 3.2: The annotate argument.


Provides an iterator over all of the opcodes in a pickle, returning a sequence of (opcode, arg, pos) triples. opcode is an instance of an OpcodeInfo class; arg is the decoded value, as a Python object, of the opcode’s argument; pos is the position at which this opcode is located. pickle can be a string or a file-like object.


Returns a new equivalent pickle string after eliminating unused PUT opcodes. The optimized pickle is shorter, takes less transmission time, requires less storage space, and unpickles more efficiently.


Source code: Lib/pipes.py
The pipes module defines a class to abstract the concept of a pipeline — a sequence of converters from one file to another.
Because the module uses /bin/sh command lines, a POSIX or compatible shell for os.system() and os.popen() is required.
The pipes module defines the following class:
An abstraction of a pipeline.
Example:
Template objects following methods:
Restore a pipeline template to its initial state.
Return a new, equivalent, pipeline template.
If flag is true, turn debugging on. Otherwise, turn debugging off. When debugging is on, commands to be executed are printed, and the shell is given set -x command to be more verbose.
Append a new action at the end. The cmd variable must be a valid bourne shell command. The kind variable consists of two letters.
The first letter can be either of '-' (which means the command reads its standard input), 'f' (which means the commands reads a given file on the command line) or '.' (which means the commands reads no input, and hence must be first.)
Similarly, the second letter can be either of '-' (which means the command writes to standard output), 'f' (which means the command writes a file on the command line) or '.' (which means the command does not write anything, and hence must be last.)
Add a new action at the beginning. See append() for explanations of the arguments.
Return a file-like object, open to file, but read from or written to by the pipeline. Note that only one of 'r', 'w' may be given.
Copy infile to outfile through the pipe.


Append a new action at the end. The cmd variable must be a valid bourne shell command. The kind variable consists of two letters.
The first letter can be either of '-' (which means the command reads its standard input), 'f' (which means the commands reads a given file on the command line) or '.' (which means the commands reads no input, and hence must be first.)
Similarly, the second letter can be either of '-' (which means the command writes to standard output), 'f' (which means the command writes a file on the command line) or '.' (which means the command does not write anything, and hence must be last.)


Return a new, equivalent, pipeline template.


Copy infile to outfile through the pipe.


If flag is true, turn debugging on. Otherwise, turn debugging off. When debugging is on, commands to be executed are printed, and the shell is given set -x command to be more verbose.


Return a file-like object, open to file, but read from or written to by the pipeline. Note that only one of 'r', 'w' may be given.


Add a new action at the beginning. See append() for explanations of the arguments.


Restore a pipeline template to its initial state.