pyxx.files.TextFile¶

class pyxx.files.TextFile(path: str | Path | None = None, comment_chars: Tuple[str, ...] | str | None = None)¶

Bases: File

Base class for processing text files

This class can be used to represent text files (that is, files with a series of ASCII-based characters as content, that can be open and read with an editor such as Notepad). It provides the capability to read/write text files and perform processing operations such as removing commented lines.

Attributes

`comment_chars`	A tuple of all characters considered to denote comments
`contents`	A reference to a list containing the (potentially modified) file content of each line of the file
`line_ending`	The character(s) used to denote the end of lines in the text file
`raw_contents`	A copy of the raw file content
`trailing_newline`	Whether the original file had a newline at the end of the file

Methods

`__init__`([path, comment_chars])	Define a text file
`clean_contents`([remove_comments, ...])	Clean `contents` in-place
`overwrite`([prologue, epilogue, line_ending])	Write data in `contents` to the file specified by `path`
`parse`()	Parses the data in `contents` and stores it in class attributes
`read`([path, parse])	Read file from disk
`set_contents`(contents, trailing_newline[, ...])	Add data to the `contents` list
`update_contents`()	Updates the `contents` list based on object attributes
`write`(output_file[, write_mode, ...])	Write file to disk

Inherited Attributes

`hashes`	A copy of the dictionary containing any file hashes previously computed for the file specified by the `path` attribute
`path`	Path describing the location of the file on the disk

Inherited Methods

`clear_file_hashes`()	Clears any stored file hashes
`compute_file_hashes`([hash_functions, store])	Computes hashes of the file specified by the `path` attribute
`has_changed`()	Returns whether the file specified by the `path` attribute has changed since the last time file hashes were computed
`set_read_metadata`([path])	Configures metadata related to file to be read from disk
`store_file_hashes`([hash_functions])	Computes and stores hashes of the file specified by the `path` attribute
`track_new_file`(path[, hash_functions])	Shortcut for simultaneously modifying the `path` attribute and storing file hashes

__init__(path: str | Path | None = None, comment_chars: Tuple[str, ...] | str | None = None) → None¶

Define a text file

Creates an object that represents and can be used to process a text file.

Parameters:

path (str or pathlib.Path, optional) – Location of the text file in the file system (default is None)
comment_chars (tuple or str, optional) – Character(s) considered to represent comments in the text file (default is None, which considers no characters to denote comments in the file)

Notes

Passing an empty string ('') or empty tuple (()) as the comment_chars argument is equivalent to passing None (or not providing this argument) – in all these cases, the file will be considered to have no characters denoting comments.

property comment_chars: Tuple[str, ...] | None¶: A tuple of all characters considered to denote comments

property contents: List[str]¶

A reference to a list containing the (potentially modified) file content of each line of the file

Warning

This attribute returns the list by reference. This means that if you set a variable equal to this reference, then editing this variable will edit the contents attribute (e.g., if you set my_content = MyTextFile.contents, then editing my_content will change the content stored in MyTextFile).

Notes

If trying to set the contents attribute, do not try to set this attribute directly (i.e., don’t use code similar to MyTextFile.contents = ['line1', 'line2', 'line3']). Instead, use the set_contents() method, as it offers greater control over whether the contents are passed by reference or value.

property line_ending: str | Tuple[str, ...]¶

The character(s) used to denote the end of lines in the text file

This property only applies to files that were read using the read() method. After reading a file, this property stores the line ending(s) used in the file. Lines in text files can be terminated with '\n' (LF), '\r\n' (CRLF), '\r', or a combination of these characters (potentially with different line endings on different lines).

After reading a file, this property stores either a string containing the line endings on every line of the file, or a tuple containing all line endings encountered throughout the file.

property raw_contents: List[str] | None¶

A copy of the raw file content

If the file was read using the read() method, this attribute stores the original, unaltered contents of each line of the input file, and it returns a copy of this list of lines. If the file was not read with the read() method, this attribute stores a value of None.

property trailing_newline: bool¶: Whether the original file had a newline at the end of the file

clean_contents(remove_comments: bool = False, skip_full_line_comments: bool = False, strip: bool = False, concat_lines: bool = False, remove_blank_lines: bool = False) → None¶

Clean contents in-place

Cleans contents (removing comments, blank lines, etc.) based on user-defined rules. Modifications are made in-place (i.e., the resulting content is stored in contents).

Parameters:

remove_comments (bool, optional) – Whether to remove comments from file (default is True)
skip_full_line_comments (bool, optional) – Whether to skip removing comments where the comment is the only text on a line. Only applies if remove_comments is True (default is False)
strip (bool, optional) – Whether to strip leading and trailing whitespace from each line (default is True)
concat_lines (bool, optional) – Whether to concatenate lines ending with a backslash with the following line (default is True)
remove_blank_lines (bool, optional) – Whether to remove lines that contain no content after other cleaning operations have completed (default is True)

overwrite(prologue: str = '', epilogue: str | None = None, line_ending: str = '\n') → None¶

Write data in contents to the file specified by path

Writes the lines of content in the contents attribute to the (previously-defined) file specified by the path attribute, suppressing warnings before overwriting the file. This is useful for cases when the file contents are manually populated and it is desired to “dump” them to a file. This method is also useful if a file’s contents need to be updated periodically based on the results of another process.

Parameters:

prologue (str, optional) – Content written at beginning of file (default is '')
epilogue (str, optional) – Content written at end of file (default is to use the value of the line_ending argument if trailing_newline is True and '' otherwise)
line_ending (str, optional) – String written at the end of each line when writing file content (default is '\n')

parse() → None¶

Parses the data in contents and stores it in class attributes

This method by default does nothing. However, it is intended that subclasses of TextFile should override this method and define file-specific behavior in this method for extracting data from the file and storing it in custom object attributes.

For example, if defining a CSV-parser, the parse() method might parse data from the file and store it as a NumPy array.

clear_file_hashes() → None¶: Clears any stored file hashes

compute_file_hashes(hash_functions: tuple | str = ('md5', 'sha256'), store: bool = False) → Dict[str, str]¶

Computes hashes of the file specified by the path attribute

Computes and returns the hashes of the file specified by the path attribute, with the option to populate the hashes dictionary with their values.

Parameters:

hash_functions (tuple or str, optional) – Tuple of strings (or individual string) specifying which hash(es) to compute. Any hash functions supported by hashlib can be used. Default is ('md5', 'sha256')
store (bool, optional) – Whether to store the computed hashes in the hashes dictionary (default is False)

Returns:

A dictionary containing the file hashes specified by hash_functions

Return type:

dict