Package plumbum.fs

File system utilities

Atomic file operations

class plumbum.fs.atomic.AtomicFile(filename, ignore_deletion=False)[source]

Atomic file operations implemented using file-system advisory locks (flock on POSIX, LockFile on Windows).


On Linux, the manpage says flock might have issues with NFS mounts. You should take this into account.

New in version 1.3.


Close and reopen the file; useful when the file was deleted from the file system by a different process

locked(*args, **kwds)[source]

A context manager that locks the file; this function is reentrant by the thread currently holding the lock.

Parameters:blocking – if True, the call will block until we can grab the file system lock. if False, the call may fail immediately with the underlying exception (IOError or WindowsError)

Atomically delete the file (holds the lock while doing it)


Atomically read the entire file


Read the file without holding the lock


Writes the given data atomically to the file. Note that it overwrites the entire file; write_atomic("foo") followed by write_atomic("bar") will result in only "bar".

class plumbum.fs.atomic.AtomicCounterFile(atomicfile, initial=0)[source]

An atomic counter based on AtomicFile. Each time you call next(), it will atomically read and increment the counter’s value, returning its previous value


acf ="/some/file")
print   # e.g., 7
print   # 8
print   # 9

New in version 1.3.

classmethod open(filename)[source]

Shortcut for AtomicCounterFile(AtomicFile(filename))


Reset the counter’s value to the one given. If None, it will default to the initial value provided to the constructor


Read and increment the counter, returning its previous value

exception plumbum.fs.atomic.PidFileTaken(msg, pid)[source]

This exception is raised when PidFile.acquire fails to lock the pid file. Note that it derives from SystemExit, so unless explicitly handled, it will terminate the process cleanly

class plumbum.fs.atomic.PidFile(filename)[source]

A PID file is a file that’s locked by some process from the moment it starts until it dies (the OS will clear the lock when the process exits). It is used to prevent two instances of the same process (normally a daemon) from running concurrently. The PID file holds its process’ PID, so you know who’s holding it.

New in version 1.3.


Attempt to acquire the PID file. If it’s already locked, raises PidFileTaken. You should normally acquire the file as early as possible when the program starts


Release the PID file (should only happen when the program terminates)

class plumbum.fs.mounts.MountEntry(dev, point, fstype, options)[source]

Represents a mount entry (device file, mount point and file system type)


returns the system’s current mount table (a list of MountEntry objects)


Indicates if a the given filesystem (device file or mount point) is currently mounted