iripau.shutil module

Generic and stand-alone shell utilities.

class iripau.shutil.FileLock(file_name, timeout=None)

Bases: object

Provides a file‐based lock to ensure that only one thread or process can access a shared resource at a time.

The lock is implemented by creating a lock file at the specified path. Acquisition blocks until the lock file can be exclusively created without contention. Supports optional timeout and context‐manager protocol.

Parameters:

• file_name (str) – Filesystem path to the lock file.

• timeout (float) – Maximum time in seconds to wait for the lock.

lock_path

Filesystem path to the lock file.

Type:

str

timeout

Maximum time in seconds to wait for the lock.

Type:

Optional[float]

acquired

Whether the file lock is acquired by this object.

Type:

boot

poll_time = 0.05

Time to wait between file creation tries.

Type:

float

acquire(timeout=None)

Block until the file lock is exclusively created.

Parameters:

timeout (float) – Override the maximum time in seconds to wait for the lock.

Raises:

TimeoutError – If timeout reached.

release()

Release a lock. If locked, remove the file previously created.

locked()

Whether the file lock is acquired.

iripau.shutil.create_file(file_name, content='')

Create a file with the specified content.

Parameters:

• file_name (str) – Path to the file to be created or overrode.

• content (bytes | str) – The file will be created with this data.

iripau.shutil.read_file(file_name, binary=False)

Return the content of a file.

Parameters:

• file_name (str) – Path to the file to read.

• binary (bool) – Whether the file content is binary.

Return type:

bytes | str

Returns:

The content of the file.

iripau.shutil.remove_file(file_name)

Delete a file. If the file does not exist, do nothing.

Parameters:

file_name (str) – Path to the file to delete.

iripau.shutil.remove_tree(root)

Delete a file or a directory. If root does not exist, do nothing.

Parameters:

root (str) – Path to the file or directory to delete.

iripau.shutil.file_created(file_name, content='')

A context-manager that creates a file with the desired content at enter and delete it at exit.

Parameters:

• file_name (str) – Path to the file to be created or overrode.

• content (bytes | str) – The file will be created with this data.

Yields:

str – The file_name.

Example

Create a file, send it to a remote host and delete it:

import subprocess


with file_created("/tmp/example.txt", "Some content") as file_name:
    # scp /tmp/example.txt host:/tmp/
    subprocess.run(["scp", file_name, "host:/tmp/"])

iripau.shutil.wait_for_file(file_obj, *args, **kwargs)

Block until there is new data to be read in file_obj.

Parameters:

• file_obj (IOBase) – A file opened to read.

• *args – Passed to functools.wait_for().

• **kwargs – Passed to functools.wait_for().

iripau.shutil.rotate(path, seq=0)

Rotate file or directory backups by renaming existing entries with incrementing suffixes. File extensions are preserved.

Parameters:

• path (str) – Path to the file or directory to rotate.

• seq (int) – Initial sequence index, normally left at 0.

Example

Rotate a log file and its backups so that a new log.txt can be created without overiding the previous log files:

# To cause the following effect:
# | Original files | Renamed files |
# | -------------- | ------------- |
# | log.txt        | log.1.txt     |
# | log.1.txt      | log.2.txt     |
# | log.2.txt      | log.3.txt     |

rotate("log.txt")