pic_scanner.helpers.filesystem.classes

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

Classes

`NeedsReprocessingTag`
`File`
`FileCollection`	A class for managing a collection of files.

Functions

`check_file`(→ bool)	Check if a file is valid.
`provision_paths`(→ list)	Provision a list of paths.
`provision_path`(→ pathlib.Path)	Provision a path.
`get_lowest_unit_size`(→ tuple[Union[int, float], str])	Get the lowest unit size for a given size.

Module Contents

pic_scanner.helpers.filesystem.classes.check_file(path: str | pathlib.Path, **kwargs) → bool

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.classes.provision_paths(path_list: list) → list

Provision a list of paths.

This function takes a list of paths and provisions them.

Note

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

Parameters:: path_list (list) – The list of paths to provision.
Returns:: The provisioned list of paths.
Return type:: list

pic_scanner.helpers.filesystem.classes.provision_path(path: str | pathlib.Path, do_not_expand: bool = False, do_not_resolve: bool = False, do_not_convert: bool = False) → pathlib.Path

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

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

Parameters:: value (bool)

pic_scanner.helpers.filesystem.classes.get_lowest_unit_size(size: int) → tuple[int | float, str]

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')

class pic_scanner.helpers.filesystem.classes.File(path: str | pathlib.Path)

Parameters:: path (Union[str, pathlib.Path])

class pic_scanner.helpers.filesystem.classes.FileCollection(paths: List[str] = None)

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[str])

get_total_size_in_lowest_unit()

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

Return type:: tuple[Union[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[Union[int, float], str]

remove_file()

Remove a file from the collection.

Parameters:: path (Union[pathlib.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.

paths: list

total_size: int

total_files: int

extensions: dict

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

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

get_total_size_in_lowest_unit() → tuple[int | float, str]

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]

get_total_extension_size_in_lowest_unit(extension: str, return_as_string: bool = False) → tuple[int | float, str]

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.

remove_file(path: pathlib.Path | str, **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