plox.tools.files

Assorted utilities for dealing with anything related to local file system.

If it is a generic method for dealing with something locally on disk, about a file, or about something related to a file, it is a good bet that it is a function that belongs in this module.

from plox.tools import files

Attributes

FilePath

Represent one of many formats for a local file on disk.

Functions

bin_file_contents(path)

Read and return a local binary file path's contents as a byte array.

delete_folder_and_contents(pth)

Recursively deletes a given folder path.

ensure_dir(path)

Ensure the local directory structure exists for a given path.

existing_filepath(file_path)

Check whether a given path is an existent file.

file_contents(path)

Read and return a local file path's contents as a string.

file_contents_from_envar(key)

Fetch and envars's local file path's contents as a string.

file_lines(filename[, skip_filtration, patterns])

Return the contents of a given filepath as its individual lines.

format_bytes(number_bytes[, metric, precision])

Format bytes to human readable, using binary (1024) or metric (1000) representation.

list_files(directory_path[, sort])

Return a list of files (str) in a directory.

walkdir(dirpattern[, recursive, ignore_pattern])

Walk a local directory, and yield a set of found files.

Module Contents

plox.tools.files.FilePath

Represent one of many formats for a local file on disk.

plox.tools.files.bin_file_contents(path)

Read and return a local binary file path’s contents as a byte array.

Parameters:

path (FilePath) – Path on local disk to file.

Returns:

Contents of binary file.

Return type:

bytearray

plox.tools.files.delete_folder_and_contents(pth)

Recursively deletes a given folder path.

Parameters:

pth (pathlib.Path) – The path to local disk to entirely remove.

plox.tools.files.ensure_dir(path)

Ensure the local directory structure exists for a given path.

If the path does not exist as a directory, it is made.

Parameters:

path (str) – The path at to check is a valid directory path.

plox.tools.files.existing_filepath(file_path)

Check whether a given path is an existent file.

If not, raises and ArgumentTypeError, as the intended purpose of this helper utility is a type for an argparse argument.

Parameters:

file_path (str) – The path to the file to check exists.

Raises:

argparse.ArgumentTypeError – If the given file_path does not exist.

Returns:

Passed in file_path

Return type:

str

plox.tools.files.file_contents(path)

Read and return a local file path’s contents as a string.

Parameters:

path (FilePath) – Path on local disk to file.

Returns:

Contents of file

Return type:

str

plox.tools.files.file_contents_from_envar(key)

Fetch and envars’s local file path’s contents as a string.

Parameters:

key (str) – Name of environment variable whose value represents the file path to read.

Returns:

Contents of the value of the environment’s key at local disk path.

Return type:

str

plox.tools.files.file_lines(filename, skip_filtration=True, patterns=None)

Return the contents of a given filepath as its individual lines.

By default, will not include any filtration of the file’s contents. If desired, can set skip_filtration to True and specify the list of patterns to exclude (on a per-line re.match basis) via the patterns argument.

Parameters:

  • filename (FilePath) – The path on disk of the file whose lines of content will be parsed and returned.

  • skip_filtration (bool) – Whether the results should ignore any filtration. Default true.

  • patterns (Optional[list[re.Pattern[str]]]) – A list of regex patterns which if skip_filtration is false will be ignored if matching a given line.

Returns:

The set of lines that the file consists of after potentially filtering.

Return type:

list[str]

plox.tools.files.format_bytes(number_bytes, metric=False, precision=1)

Format bytes to human readable, using binary (1024) or metric (1000) representation.

Inspired by: https://stackoverflow.com/a/63839503

Example

>>> format_bytes(1024)
'1.0 KiB'
>>> format_bytes(1000)
'1000.0 B'
>>> format_bytes(1000, metric=True)
'1.0 kB'
>>> format_bytes(1024, metric=True, precision=3)
'1.024 kB'
>>> format_bytes(1_234_567_898_765_432, metric=True, precision=3)
'1.235 PB'
Parameters:

  • number_bytes (Union[int, float]) – The number of bytes to convert to a human readable labeled quantity.

  • metric (bool) – Whether or not the metric system is used; Default is False - results in using binary.

  • precision (int) – Number of digits/precision. Must be between 1-3.

Returns:

The human friendly sized representation of the bytes.

Return type:

str

plox.tools.files.list_files(directory_path, sort=False)

Return a list of files (str) in a directory.

Parameters:

  • directory_path (str) – The path to the local directory on disk.

  • sort (bool) – Whether or not the results should be alphabetically sorted. Default False.

Return type:

list[str]

plox.tools.files.walkdir(dirpattern, recursive=True, ignore_pattern=None)

Walk a local directory, and yield a set of found files.

Parameters:

  • dirpattern (str) – The pattern to walk through. Example, ** or /some/path/**.

  • recursive (bool) – Whether or not to recursively list sub-items.

  • ignore_pattern (Optional[list[str]]) – A list of wildcard like patterns that, if provided, any file matching will _not_ be returned.

Return type:

collections.abc.Generator[str, None, None]