File management routines

DevNullFilelikeObject

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

class satella.files.DevNullFilelikeObject(binary=False)

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

Parameters:

binary (bool) – is this a binary file

close()

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

Return type:

None

flush()
Raises:

ValueError – when this object has been closed

Return type:

None

read(byte_count=None)
Raises:
  • ValueError – this object has been closed

  • io.UnsupportedOperation – since reading from this is forbidden

Parameters:

byte_count (Optional[int]) –

Return type:

Union[str, bytes]

seek(v)

Seek to a particular file offset

Parameters:

v (int) –

Return type:

int

seekable()

Is this file seekable?

Return type:

bool

tell()

Return the current file offset

Returns:

the current file offset

Return type:

int

truncate(_DevNullFilelikeObject__size=None)

Truncate file to __size starting bytes

Parameters:

_DevNullFilelikeObject__size (Optional[int]) –

Return type:

int

writable()

Is this object writable

Return type:

bool

write(y)

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

Parameters:

y (Union[str, bytes]) –

Return type:

int

jump_to_directory

safe_listdir

satella.os.safe_listdir(directory)

Return elements of directory.

Returns nothing (an empty iterator) if directory does not exist, or is not a directory.

Parameters:

directory (str) – path to the element to examine.

Return type:

Iterator[str]

read_lines

satella.files.read_lines(path, delete_empty_lines=True, encoding='utf-8')

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 (str) – path of file to read

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

  • encoding (str) – encoding to read the file with

Returns:

each line as a separate entry

Return type:

List[str]

read_re_sub_and_write

satella.files.read_re_sub_and_write(path, pattern, repl)

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

Note that this is not thread or multiprocess safe.

Parameters:
  • path (str) – path of file to treat

  • pattern (Union[compile, str]) – regexp compiled pattern or a string, a pattern to match the file contents

  • repl (Callable[[Any], str]) – string or a callable(re.Match)->str to replace the contents

Return type:

None

find_files

satella.files.find_files(path, wildcard='(.*)', prefix_with=None, scan_subdirectories=True, apply_wildcard_to_entire_path=False, prefix_with_path=True)

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 (str) – path to look into.

  • wildcard (str) – a regular expression to match

  • prefix_with (Optional[str]) – an optional path component to prefix before the filename with os.path.join

  • scan_subdirectories (bool) – whether to scan subdirectories

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

  • prefix_with_path (bool) – whether to add path to the resulting path

Returns:

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

Return type:

Iterator[str]

split

read_in_file

satella.files.read_in_file(path, encoding=None, default=<class 'satella.files._NOTSET'>)

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

Parameters:
  • path (str) – path of file to read

  • encoding (Optional[str]) – optional encoding. If default, this will be returned as bytes

  • default (Optional[Union[bytes, str]]) – 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

Return type:

Union[bytes, str]

write_to_file

satella.files.write_to_file(path, data, encoding=None)

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

Parameters:
  • path (str) – Path to put the file under

  • data (Union[bytes, str]) – Data to write. Must be bytes if no encoding is given, str otherwise

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

Return type:

None

write_out_file_if_different

satella.files.write_out_file_if_different(path, data, encoding=None)

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 (str) – Path to put the file under

  • data (Union[bytes, str]) – Data to write. Must be bytes if no encoding is given, str otherwise

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

Returns:

if write has happened

Return type:

bool

AutoflushFile

class satella.files.AutoflushFile(file, mode, *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'
Parameters:
  • file (str) – path to the file

  • mode (str) – mode to open the file with. Allowed values are w, wb, w+, a+, wb+, ab+, a, ab. w+ and wb+ will truncate the file. Effective mode will be chosen by the class whatever just makes sense.

Raises:

ValueError – invalid mode chosen

close()

Closes the file.

Return type:

None

read(*args, **kwargs)

Read a file, returning the read-in data

Returns:

data readed

Return type:

Union[str, bytes]

readall()

Read all contents into the file

Return type:

Union[str, bytes]

seek(offset, whence=0)

Seek to a provided position within the file

Parameters:
  • offset (int) – offset to seek file

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

Returns:

current pointer

Return type:

int

truncate(_size=None)

Truncate file to __size starting bytes

Parameters:

_size (Optional[int]) –

Return type:

int

write(*args, **kwargs)

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

Returns:

amount of bytes written

Return type:

int