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