pic_scanner.helpers.filesystem package

Submodules

pic_scanner.helpers.filesystem.classes module

classes.py

This module provides a class for managing a collection of files and a class for managing a single file. The FileCollection class takes a list of file paths and creates a class representing a collection of files with properties for total size and number of files and a dictionary of extensions with properties for total size and number of files. The File class is a placeholder for future development. It is not currently used in the application. It is intended to be used for managing individual files in the future.

Classes:

File:

A placeholder class for managing individual files.

FileCollection:

A class for managing a collection of files.

Methods:

get_total_size_in_lowest_unit:: Get the total size of the collection in the lowest unit.
get_total_extension_size_in_lowest_unit:: Get the total size of a specific extension in the lowest unit.
remove_file:: Remove a file from the collection.
reprocess_files:: Reprocess the files in the collection.

NeedsReprocessingTag:

A descriptor class for managing the needs_reprocessing attribute of the FileCollection class.

Functions:

get_lowest_unit_size:: Get the lowest unit size for a given size.

Since:

1.0

class pic_scanner.helpers.filesystem.classes.File(path)

Bases: object

Parameters:: path (str | Path)

__init__(path)

Parameters:: path (str | Path)

class pic_scanner.helpers.filesystem.classes.FileCollection(paths=None)

Bases: object

A class for managing a collection of files.

Properties:

paths (list):: A list of file paths.
total_size (int):: The total size of the collection, in bytes.
total_files (int):: The total number of files in the collection.
extensions (dict):: A dictionary of extensions with properties for total size and number of files.
needs_reprocessing (bool):: A flag indicating whether the collection needs reprocessing.

Parameters:: paths (list)

get_total_size_in_lowest_unit()

Get the total size of the collection in the lowest unit.

Return type:: tuple[int | float, str]

get_total_extension_size_in_lowest_unit()

Get the total size of a specific extension in the lowest unit.

Parameters:

extension (str)
return_as_string (bool)

Return type:

tuple[int | float, str]

remove_file()

Remove a file from the collection.

Parameters:: path (Path | str)

reprocess_files(): Reprocess the files in the collection.

Examples

>>> collection = FileCollection(paths=['/path/to/file1', '/path/to/file2'])
>>> collection.total_size
123456  # Total size of the collection, in bytes.

__init__(paths=None)

Initialize the FileCollection with a list of file paths.

FileCollection is a class for managing a collection of files. It takes a list of file paths and creates a class representing a collection of files with properties for total size and number of files and a dictionary of extensions with properties for total size and number of files.

Parameters:: paths (list) – A list of file paths.
Returns:: None

_process_files()

Process the files in the collection.

This method processes the files in the collection. It calculates the total size of the collection, the total number of files, and the total size of each extension in the collection. It populates the total_size, total_files, and extensions attributes of the class.

Returns:: None

extensions: dict

get_total_extension_size_in_lowest_unit(extension, return_as_string=False)

Get the total size of a specific extension in the lowest unit with a size greater than or equal to 1.

Parameters:

extension (str) – The extension to get the size of.
return_as_string (bool) – A flag indicating whether to return the size as a string. If True, the size will be returned as a string with the unit. If False, the size will be returned as a tuple with the size and the unit.

Returns:

The total size of the extension and the unit.

Return type:

tuple[Union[int, float], str]

Raises:

ValueError – If the extension is not found in the collection.

get_total_size_in_lowest_unit()

Get the total size of the collection in the lowest unit with a size greater than or equal to 1.

This method calculates the total size of the collection in the lowest unit with a size greater than or equal to 1. It returns the size and the unit as a tuple. The unit is a string representing the unit of the size.

Returns:: The total size of the collection and the unit.
Return type:: tuple[Union[int, float], str]

property needs_reprocessing: bool

Returns whether the collection needs reprocessing.

This property returns a boolean value indicating whether the collection needs reprocessing. If the collection has been modified since the last processing, this property will return True. If the collection has not been modified, it will return False. The property is read-only.

Returns:: True if the collection needs reprocessing, False otherwise.
Return type:: bool

paths: list

remove_file(path, **kwargs)

Remove a file from the collection.

This method removes a file from the collection. It takes a file path as an argument and removes the file from the collection. It then reprocesses the files in the collection to update the total size, total number of files, and total size of each extension.

Note

This method does not delete the file from the file system. It only removes the file from the collection, and only if the file is in the collection. If the file is not in the collection, this method will raise a KeyError. After removing the file, the collection will be reprocessed to update the total size, total number of files, and total size of each extension.

Parameters:

path (Union[Path, str]) – The file path to remove.
**kwargs – Additional keyword arguments.

Raises:

KeyError – If the file is not in the collection.

Returns:

None

reprocess_files()

Reprocess the files in the collection.

This method reprocesses the files in the collection. It recalculates the total size of the collection, the total number of files, and the total size of each extension in the collection. It populates the total_size, total_files, and extensions attributes of the class. This method is used to update the collection after files have been added or removed.

Note

This method should be called after files have been added or removed from the collection. It will only reprocess the files if the needs_reprocessing attribute is set to True. After reprocessing, the needs_reprocessing attribute will be set to False.

Returns:: None

total_files: int = 0

total_size: int = 0

class pic_scanner.helpers.filesystem.classes.NeedsReprocessingTag(value=False)

Bases: object

Parameters:: value (bool)

__init__(value=False)

Parameters:: value (bool)

pic_scanner.helpers.filesystem.classes.get_lowest_unit_size(size)

Get the lowest unit size for a given size.

Parameters:: size (int) – The size to convert.
Returns:: The converted size and the unit.
Return type:: tuple[Union[int, float], str]

Examples

>>> get_lowest_unit_size(1024)
(1.0, 'KB')
>>> get_lowest_unit_size(1024 * 1024)
(1.0, 'MB')
>>> get_lowest_unit_size(1024 * 1024 * 1024)
(1.0, 'GB')
>>> get_lowest_unit_size(1024 * 1024 * 1024 * 1024)
(1.0, 'TB')
>>> get_lowest_unit_size(1024 * 1024 * 1024 * 1024 * 1024)
(1.0, 'PB')
>>> get_lowest_unit_size(1024 * 1024 * 1024 * 1024 * 1024 * 1024)
(1.0, 'EB')
>>> get_lowest_unit_size(1024 * 1024 * 1024 * 1024 * 1024 * 1024 * 1024)
(1.0, 'ZB')
>>> get_lowest_unit_size(1024 * 1024 * 1024 * 1024 * 1024 * 1024 * 1024 * 1024)
(1.0, 'YB')

pic_scanner.helpers.filesystem.units module

pic_scanner.helpers.filesystem.units.UNIT_MAP = {'B': Unit(unit_name='bytes', unit_abbrev='B', base_multiplier=1, pluralize='bytes'), 'EB': Unit(unit_name='exabytes', unit_abbrev='EB', base_multiplier=1152921504606846976, pluralize='exabytes'), 'GB': Unit(unit_name='gigabytes', unit_abbrev='GB', base_multiplier=1073741824, pluralize='gigabytes'), 'KB': Unit(unit_name='kilobytes', unit_abbrev='KB', base_multiplier=1024, pluralize='kilobytes'), 'MB': Unit(unit_name='megabytes', unit_abbrev='MB', base_multiplier=1048576, pluralize='megabytes'), 'PB': Unit(unit_name='petabytes', unit_abbrev='PB', base_multiplier=1125899906842624, pluralize='petabytes'), 'TB': Unit(unit_name='terabytes', unit_abbrev='TB', base_multiplier=1099511627776, pluralize='terabytes'), 'YB': Unit(unit_name='yottabytes', unit_abbrev='YB', base_multiplier=1208925819614629174706176, pluralize='yottabytes'), 'ZB': Unit(unit_name='zetabytes', unit_abbrev='ZB', base_multiplier=1180591620717411303424, pluralize='zetabytes')}: A dictionary mapping storage units to their respective data classes.

Module contents

__init__.py

The filesystem module provides functions for working with the filesystem.

This module provides functions for checking if a path is valid, checking if a directory is valid, checking if a file is valid, provisioning a path, provisioning a list of paths, gathering files in a directory, and getting the abbreviation for a storage unit.

Functions:

check_path:: Check if a path is valid.
check_directory:: Check if a directory is valid.
check_file:: Check if a file is valid.
provision_path:: Provision a path.
provision_paths:: Provision a list of paths.
gather_files_in_dir:: Gather all files in a directory.
get_storage_unit_abbreviation:: Get the abbreviation for a storage unit.

Since:

1.0

pic_scanner.helpers.filesystem.check_directory(path, **kwargs)

Check if a directory is valid.

This function checks if a directory is valid. If the path is a string, it will be converted to a Path object. If the path is not expanded, it will be expanded. If the path is not resolved, it will be resolved. If the path is not converted to a string, it will be converted to a string. If the path is not provisioned, it will be provisioned.

Note

Provisioning a path involves converting it to a Path object, expanding it, and resolving it.

Parameters:

path (Union[str, Path]) – The directory to check.
**kwargs – Additional keyword arguments.

Returns:

A flag indicating whether the directory is valid.

Return type:

bool

pic_scanner.helpers.filesystem.check_file(path, **kwargs)

Check if a file is valid.

Parameters:: path (Union[str, Path]) – The file to check.
Returns:: A flag indicating whether the file is valid.
Return type:: bool

pic_scanner.helpers.filesystem.check_path(path, do_not_expand=False, do_not_resolve=False, do_not_convert=False, do_not_provision=False)

Check if a path is valid.

This function checks if a path is valid. If the path is a string, it will be converted to a Path object. If the path is not expanded, it will be expanded. If the path is not resolved, it will be resolved. If the path is not converted to a string, it will be converted to a string. If the path is not provisioned, it will be provisioned.

Note

Provisioning a path involves converting it to a Path object, expanding it, and resolving it.

Parameters:

path (Union[str, Path]) – The path to check.
do_not_expand (bool) – A flag indicating whether to expand the path.
do_not_resolve (bool) – A flag indicating whether to resolve the path.
do_not_convert (bool) – A flag indicating whether to convert the path to a string.
do_not_provision (bool) – A flag indicating whether to provision the path.

Returns:

A flag indicating whether the path is valid.

Return type:

bool

pic_scanner.helpers.filesystem.provision_path(path, do_not_expand=False, do_not_resolve=False, do_not_convert=False)

Provision a path.

Parameters:

path (str) – The path to provision.
do_not_convert (bool) – A flag indicating whether to convert the path to a string.
do_not_expand (bool) – A flag indicating whether to expand the path.
do_not_resolve (bool) – A flag indicating whether to resolve the path.

Returns:

The provisioned path.

Return type:

Path