File management routines¶

DevNullFilelikeObject¶

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

class satella.files.DevNullFilelikeObject¶

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

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: Optional[int] = None)¶

Raises:	ValueError – this object has been closed io.UnsupportedOperation – since reading from this is forbidden

write(x: Union[str, bytes]) → int¶

Discard any amount of bytes

Raises:	ValueError – this object has been closed
Returns:	length of written content

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: Union[re.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: Optional[str] = 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: Optional[str] = None, default: Union[bytes, str, None] = <class 'satella.files._NOTSET'>) → Union[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: Union[bytes, str], encoding: Optional[str] = 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: Union[bytes, str], encoding: Optional[str] = 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