File management routines

DevNullFilelikeObject

A file-like object that will dispose of your content.

class satella.files.DevNullFilelikeObject(binary: bool = False)

A /dev/null filelike object. For multiple uses.

Parameters:

binary – is this a binary file

close() → None

Close this stream. Further write()s and flush()es will raise a ValueError. No-op if invoked multiple times

flush() → None

Raises:

ValueError – when this object has been closed

read(byte_count: int | None = None) → str | bytes

Raises:

• ValueError – this object has been closed

• io.UnsupportedOperation – since reading from this is forbidden

seek(v: int) → int

Seek to a particular file offset

seekable() → bool

Is this file seekable?

tell() → int

Return the current file offset

Returns:

the current file offset

truncate(_DevNullFilelikeObject__size: int | None = None) → int

Truncate file to __size starting bytes

writable() → bool

Is this object writable

write(y: str | bytes) → int

Discard any amount of bytes.

This will raise a RuntimeWarning warning upon writing invalid type.

Raises:

• ValueError – this object has been closed

• TypeError – eg. type set to binary and text provided to write

Returns:

length of written content

safe_listdir

read_lines

satella.files.read_lines(path: str, delete_empty_lines: bool = True, encoding: str = 'utf-8') → List[str]

Read lines from a particular file, removing end-of-line characters and optionally empty lines. Additionally whitespaces (and end-of-line characters) will be removed from both ends of each line.

Parameters:

• path – path of file to read

• delete_empty_lines – set to False if empty lines are not to be removed

• encoding – encoding to read the file with

Returns:

each line as a separate entry

read_re_sub_and_write

satella.files.read_re_sub_and_write(path: str, pattern: compile | str, repl: Callable[[Any], str]) → None

Read a text file, treat with re.sub and write the contents.

Note that this is not thread or multiprocess safe.

Parameters:

• path – path of file to treat

• pattern – regexp compiled pattern or a string, a pattern to match the file contents

• repl – string or a callable(re.Match)->str to replace the contents

find_files

satella.files.find_files(path: str, wildcard: str = '(.*)', prefix_with: str | None = None, scan_subdirectories: bool = True, apply_wildcard_to_entire_path: bool = False, prefix_with_path: bool = True) → Iterator[str]

Look at given path’s files and all subdirectories and return an iterator of file names (paths included) that conform to given wildcard.

Note that wildcard is only applied to the file name if apply_wildcard_to_entire_path is False, else the wildcard is applied to entire path (including the application of prefix_with!).

Files will be additionally prefixed with path, but only if prefix_with_path is True

Warning

Note that this will try to match only the start of the path. For a complete match remember to put a $ at the end of the string!

Parameters:

• path – path to look into.

• wildcard – a regular expression to match

• prefix_with – an optional path component to prefix before the filename with os.path.join

• scan_subdirectories – whether to scan subdirectories

• apply_wildcard_to_entire_path – whether to take the entire relative path into account when checking wildcard

• prefix_with_path – whether to add path to the resulting path

Returns:

paths with the files. They will be relative paths, relative to path

split

read_in_file

satella.files.read_in_file(path: str, encoding: str | None = None, default: bytes | str | None = <class 'satella.files._NOTSET'>) → bytes | str

Opens a file for reading, reads it in, converts to given encoding (or returns as bytes if not given), and closes it.

Parameters:

• path – path of file to read

• encoding – optional encoding. If default, this will be returned as bytes

• default – value to return when the file does not exist. Default (None) will raise a FileNotFoundError

Returns:

file content, either decoded as a str, or not as bytes

Raises:

FileNotFoundError – file did not exist and default was not set

write_to_file

satella.files.write_to_file(path: str, data: bytes | str, encoding: str | None = None) → None

Write provided content as a file, applying given encoding (or data is bytes, if none given)

Parameters:

• path – Path to put the file under

• data – Data to write. Must be bytes if no encoding is given, str otherwise

• encoding – Encoding. Default is None, which means no encoding (bytes will be written)

write_out_file_if_different

satella.files.write_out_file_if_different(path: str, data: bytes | str, encoding: str | None = None) → bool

Syntactic sugar for

>>> try:
>>>     if read_in_file(path, encoding) != data:
>>>         write_to_file(path, data, encoding)
>>>         return True
>>>     else:
>>>         return False
>>> except OSError:
>>>     write_to_file(path, data, encoding)
>>>     return True

Parameters:

• path – Path to put the file under

• data – Data to write. Must be bytes if no encoding is given, str otherwise

• encoding – Encoding. Default is None, which means no encoding (bytes will be written)

Returns:

if write has happened

AutoflushFile

class satella.files.AutoflushFile(file: str, mode: str, *con_args, **con_kwargs)

A file that is supposed to be closed after each write command issued.

The file will be open only when there’s an action to do on it called.

Best for appending so that other processes can read.

Use like:

>>> f = AutoflushFile('test.txt', 'rb+', encoding='utf-8')
>>> f.write('test')
>>> with open('test.txt', 'a+', encoding='utf-8') as fin:
>>>     assert fin.read() == 'test'

close() → None

Closes the file.

read(*args, **kwargs) → str | bytes

Read a file, returning the read-in data

Returns:

data readed

readall() → str | bytes

Read all contents into the file

seek(offset: int, whence: int = 0) → int

Seek to a provided position within the file

Parameters:

• offset – offset to seek file

• whence – how to count. Refer to documentation of file.seek()

Returns:

current pointer

truncate(_size: int | None = None) → int

Truncate file to __size starting bytes

write(*args, **kwargs) → int

Write a particular value to the file, close it afterwards.

Returns:

amount of bytes written