morphic.shared¶

Constants, utilities, and helpers shared across all morphic modules.

Constants¶

Shared constants for morphic – extension sets, exclusion lists, defaults.

Merges constants from both the converter and dupfinder modules so that every part of the project works with a single canonical set of supported file types.

Utilities¶

Shared utility helpers used across morphic modules.

morphic.shared.utils.normalise_ext(ext)[source]¶

Lowercase and unify aliases (.jpeg -> .jpg, .tiff -> .tif).

Parameters:: ext (str)
Return type:: str

morphic.shared.utils.is_image(path)[source]¶

Return True if the file extension is an image type.

Parameters:: path (str)
Return type:: bool

morphic.shared.utils.is_video(path)[source]¶

Return True if the file extension is a video type.

Parameters:: path (str)
Return type:: bool

morphic.shared.utils.format_file_size(size_bytes)[source]¶

Format file size in human-readable format.

Parameters:: size_bytes (int)
Return type:: str

morphic.shared.utils.format_duration(seconds)[source]¶

Format duration in human-readable format.

Parameters:: seconds (float)
Return type:: str

morphic.shared.utils.is_excluded_path(file_path, excluded_folders=frozenset({'$recycle', '$recycle.bin', '.cache', '.ds_store', '.fseventsd', '.git', '.hg', '.spotlight-v100', '.svn', '.thumb', '.thumbnails', '.trash', '.trashes', '.venv', '@eadir', '__pycache__', 'appdata', 'lost+found', 'node_modules', 'recycled', 'recycler', 'system volume information', 'thumbs', 'trash', 'venv', 'windows'}))[source]¶

Check if a file path contains any excluded folder.

Parameters:

file_path (str)
excluded_folders (frozenset[str])

Return type:

bool

morphic.shared.utils.find_files_by_extension(folder, extensions, excluded_folders=frozenset({'$recycle', '$recycle.bin', '.cache', '.ds_store', '.fseventsd', '.git', '.hg', '.spotlight-v100', '.svn', '.thumb', '.thumbnails', '.trash', '.trashes', '.venv', '@eadir', '__pycache__', 'appdata', 'lost+found', 'node_modules', 'recycled', 'recycler', 'system volume information', 'thumbs', 'trash', 'venv', 'windows'}))[source]¶

Find all files with given extensions in folder recursively.

Parameters:

folder (str) – Root folder to search.
extensions (set[str]) – File extensions to match (with dot, e.g. ".jpg").
excluded_folders (set[str]) – Folder names to exclude.

Returns:

Sorted list of absolute file paths.

Return type:

list[str]

morphic.shared.utils.suppress_stderr()[source]¶

Suppress stderr output at the file-descriptor level.

Silences low-level library warnings (e.g. ffmpeg/OpenCV codec messages) that cannot be caught by Python’s logging framework.

Return type:: Generator[None, None, None]

File Browser¶

Native OS file/folder dialog support.

Attempts to open a native folder picker on Linux, macOS, and Windows. Falls back gracefully when no GUI toolkit is available (e.g. headless server).

morphic.shared.file_browser.open_native_folder_dialog(initial_dir=None)[source]¶

Open the native OS folder picker dialog.

Returns the selected folder path, or None if cancelled / unavailable.

Tries, in order:

tkinter filedialog.askdirectory()
zenity — GNOME / GTK-based Linux
kdialog — KDE Linux
osascript — macOS
powershell — Windows

Parameters:: initial_dir (str | None)
Return type:: str | None

Thumbnails¶

Thumbnail generation shared by converter and dupfinder frontends.

Generates JPEG thumbnails for images (Pillow) and videos (ffmpeg subprocess).

morphic.shared.thumbnails.generate_image_thumbnail(file_path, size=300)[source]¶

Create a JPEG thumbnail for an image file.

Parameters:

file_path (str) – Absolute path to the image.
size (int) – Maximum width/height in pixels.

Returns:

JPEG image bytes (seeked to 0).

Return type:

io.BytesIO

morphic.shared.thumbnails.generate_video_thumbnail(file_path, size=300)[source]¶

Extract a single frame from a video and return it as a JPEG thumbnail.

Uses ffmpeg piped to stdout. Returns None on failure.

Parameters:

file_path (str) – Absolute path to the video.
size (int) – Maximum width/height in pixels.

Returns:

JPEG image bytes (seeked to 0), or None.

Return type:

io.BytesIO | None