Package plumbum.fs

File system utilities

Atomic file operations

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

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

Example:

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

Added in version 1.3.

classmethod open(filename)

Shortcut for AtomicCounterFile(AtomicFile(filename))

Return type:

Self

reset(value=None)

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

Return type:

None

next()

Read and increment the counter, returning its previous value

Return type:

int

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

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

Note

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

Added in version 1.3.

reopen()

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

Return type:

None

locked(blocking=True)

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

Parameters:

blocking (bool) – 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)

Return type:

Generator[None, None, None]

delete()

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

Return type:

None

read_atomic()

Atomically read the entire file

Return type:

bytes

read_shared()

Read the file without holding the lock

Return type:

bytes

write_atomic(data)

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".

Return type:

None

class plumbum.fs.atomic.PidFile(filename)

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.

Added in version 1.3.

acquire()

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

Return type:

None

release()

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

Return type:

None

exception plumbum.fs.atomic.PidFileTaken(msg, pid)

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.mounts.MountEntry(dev, point, fstype, options)

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

plumbum.fs.mounts.mount_table()

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

Return type:

list[MountEntry]

plumbum.fs.mounts.mounted(fs)

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

Return type:

bool