Sortium Package

Submodules

class sortium.sorter.Sorter(file_types_dict: dict[str, list[str]] = {'Documents': ['.pdf', '.docx', '.txt'], 'Images': ['.jpg', '.jpeg', '.png', '.gif'], 'Music': ['.mp3', '.wav'], 'Others': [], 'Videos': ['.mp4', '.avi']}, file_utils: FileUtils = None)[source]

Bases: object

Sorter class to organize files in a directory by file type and modification date.

file_types_dict

A mapping of file category names (e.g., “Images”, “Documents”) to lists of associated file extensions (e.g., [“.jpg”, “.png”]). This dictionary is used to determine how files should be grouped during sorting. If not provided, the default mapping from DEFAULT_FILE_TYPES is used.

Type:

dict[str, list[str]]

Example

>>> file_types = {
...     "Images": [".jpg", ".jpeg", ".png", ".gif"],
...     "Documents": [".pdf", ".docx", ".txt"],
...     "Videos": [".mp4", ".avi"],
...     "Music": [".mp3", ".wav"],
...     "Others": []
... }
>>> sorter = Sorter(file_types)
>>> sorter.sort_by_type('/path/to/downloads')
>>> sorter.sort_by_date('/path/to/downloads', ['Images', 'Documents'])
sort_by_date(folder_path: str, folder_types: list[str]) → None[source]

Sorts files inside specified category folders into subfolders based on their last modified date.

Each file is moved into a subfolder named by the modification date in the format “DD-MMM-YYYY”.

Parameters:

  • folder_path (str) – Root directory path containing the category folders.

  • folder_types (list[str]) – List of category folder names to process (e.g., [‘Images’, ‘Documents’]).

Raises:

FileNotFoundError – If the root folder (folder_path) does not exist.

Notes

  • If a category folder in folder_types does not exist, it will be skipped with a printed message.

  • Errors during moving individual files are caught and printed but do not stop the process.

sort_by_type(folder_path: str, ignore_dir: list[str] = None) → None[source]

Sorts files in a directory into subdirectories by file type.

Parameters:

  • folder_path (str) – Path to the directory containing unsorted files.

  • ignore_dir (list[str]) – Names of subdirectories within folder_path that should be ignored during processing.

Raises:

FileNotFoundError – If the specified folder does not exist.

class sortium.file_utils.FileUtils[source]

Bases: object

FileUtils class for file utilities that provides various methods for working with files and directories and also are used in the Sorter class. A Custom FileUtils class can be provided to the Sorter class to satisfy the specific requirements.

find_unique_extensions(source_path: str, ignore_dir: list[str] | None = None) → Set[str][source]

Recursively finds all unique file extensions in a given directory and its subdirectories.

Parameters:

  • source_path (str) – Path to the root directory.

  • ignore_dir (list[str], optional) – List of directory names to ignore. Defaults to None.

Returns:

A set of unique file extensions found in the directory tree.

Return type:

Set[str]

Raises:

FileNotFoundError – If the source_path does not exist.

flatten_dir(folder_path: str, dest_folder_path: str, ignore_dir: list[str] | None = None, rm_subdir: bool = False) → None[source]

Moves all files from subdirectories of a given folder into a destination folder.

This is useful for flattening a directory structure by collecting all files from nested folders and moving them into one target folder.

Parameters:

  • folder_path (str) – Path to the root folder containing subdirectories with files.

  • dest_folder_path (str) – Path to the folder where all files should be moved.

  • ignore_dir (list[str]) – Names of subdirectories within folder_path that should be ignored during processing.

  • rm_subdir (bool) – If True, subdirectories will be removed after moving their contents. Default is False.

Raises:

FileNotFoundError – If the root folder (folder_path) does not exist.

Notes

  • Any errors encountered while moving files or removing subdirectories are caught and printed, but not raised.

  • Fails silently (with printed messages) on permission issuesmissing files, or non-empty directories during deletion.

get_file_modified_date(file_path: str) → datetime[source]

Returns the last modified datetime of a file.

Parameters:

file_path (str) – Full path to the file.

Returns:

Datetime object representing the last modification time.

Return type:

datetime

Raises:

FileNotFoundError – If the file does not exist.

get_subdirectories_names(folder_path: str, ignore_dir: list[str] = None) → list[str][source]

Returns a list of subdirectory names in a given folder, excluding any specified to be ignored.

Parameters:

  • folder_path (str) – Full path to the folder.

  • ignore_dir (list[str], optional) – List of subdirectory names to ignore. Defaults to [] if not provided.

Returns:

List of subdirectory names.

Return type:

list[str]

sortium.config.DEFAULT_FILE_TYPES: dict[str, list[str]] = {'Documents': ['.pdf', '.docx', '.txt'], 'Images': ['.jpg', '.jpeg', '.png', '.gif'], 'Music': ['.mp3', '.wav'], 'Others': [], 'Videos': ['.mp4', '.avi']}

Default file type categories and their associated file extensions.

This dictionary maps human-readable category names to lists of common file extensions that belong to each category. It is used by the Sorter class to determine how files should be categorized and organized during sorting.

Type:

dict[str, list[str]]

Example

>>> DEFAULT_FILE_TYPES["Images"]
['.jpg', '.jpeg', '.png', '.gif']
Categories:

  • “Images”: Common image file formats.

  • “Documents”: Text and document file formats.

  • “Videos”: Video file formats.

  • “Music”: Audio file formats.

  • “Others”: Files that do not match any of the above categories.