Skip to content

api

PathSummary

Represents a summary of a path, including the path itself, the number of files, and the total size. The summary represents a sequence of files when the index_set value is non-empty. If the summary is a nested accumulation of paths, child paths are in the dictionary 'children'.

If a path represents a directory, it ends with a directory separator.

children = children instance-attribute

The children of this path, if the summary is nested

file_count instance-attribute

The number of files

index_set = index_set or set() instance-attribute

The set of indexes if the path is a printf pattern or an empty set otherwise

path = path instance-attribute

Either the path, or a printf pattern if index_set is non-empty

total_size = total_size instance-attribute

The total size of all files, if sizes are provided

is_dir()

Returns True if the path is a directory (indicated by a trailing '/')

summary(*, include_totals=True, relative_to=None)

Returns the path summary, including file count and size totals by default.

summary_totals()

Returns the totals of the summary, like 'sequence indexes 1-3, 3 files, 30 MB' if the path represents a sequence or '1 file' if the path represents a file and there is no size information available.

human_readable_file_size(size_in_bytes)

Convert a size in bytes to something human readable. For example 1000 bytes will be converted to 1 KB. Sizes close enough to a postfix threshold will be rounded up to the next threshold. For example 999999 bytes would be output as 1.0 MB and NOT 999.99 KB (or as a consequence of Python's round function 1000.0 KB).

This function is for display purposes only.

summarize_path_list(path_list, *, path_format=None, total_size_by_path=None, max_entries=10, include_totals=True)

Creates a string summary of the files in the list provided, grouping numbered filenames by their sequence pattern, and nesting summaries of the directory into the specified maximum number of entries.

By default, paths are for the current operating system. If path_format is provided, you can override that to PathFormat.WINDOWS or PathFormat.POSIX as necessary.

If total_size_by_path is provided, it must provide a total size for every path in path_list.

>>> print(summarize_path_list(["frame_1.png", "frame_3.png", "frame_20.png", "readme.txt"]))
frame_%d.png (3 files, sequence 1,3,20)
readme.txt (1 file)

summarize_paths_by_nested_directory(path_list, *, path_format=None, total_size_by_path=None)

Summarizes the provided paths by sequence, and then nests them into common parent paths. The returned summaries do not contain a common parent, for example if they are different relative paths, or absolute paths for different drives on Windows

By default, paths are for the current operating system. If path_format is provided, you can override that to PathFormat.WINDOWS or PathFormat.POSIX as necessary.

summarize_paths_by_sequence(path_list, *, path_format=None, total_size_by_path=None)

Identifies numbered sequences of files/directories within a list of paths. Returns a sorted list of PathSummary objects. If total_size_by_path is provided, it must provide a total size for every path in path_list.

group_sequence_paths(["frame_1.png", "frame_3.png", "frame_20.png", "readme.txt"]) {PathSummary("frame_%d.png", index_set={1, 3, 20}), PathSummary("readme.txt")}

group_sequence_paths(["frame_01.png", "frame_1.png", "frame_30.png", "frame_09.png"]) {PathSummary("frame_%02d.png", index_set={1, 9, 20}), PathSummary("frame_1.png")}