file_handler Module

File system operations for ttmp32gme.

Key Functions

make_new_album_dir(library_path, album_title, album_artist): Create album directory

remove_album(album_path): Delete album and contents

cleanup_filename(filename): Sanitize filename (remove special chars, replace spaces)

get_tiptoi_dir(): Detect TipToi mount point (searches common locations)

check_config_file(): Initialize config database (~/.ttmp32gme/config.sqlite)

get_default_library_path(): Get default library location (~/.ttmp32gme/library)

get_oid_cache(): Get OID image cache directory

open_browser(url): Open URL in system browser

Usage

from ttmp32gme.build.file_handler import make_new_album_dir, get_tiptoi_dir

# Create album
album_dir = make_new_album_dir("/path/to/library", "Album", "Artist")

# Detect TipToi
tiptoi = get_tiptoi_dir()
if tiptoi:
    print(f"Found at: {tiptoi}")

Build and file handling utilities for ttmp32gme.

ttmp32gme.build.file_handler.get_resource_path(relative_path)[source]

Get absolute path to resource, works for dev and PyInstaller.

This function provides consistent resource path resolution across both development and PyInstaller bundle environments. PyInstaller extracts bundled files to a temporary directory (sys._MEIPASS) at runtime, while development mode accesses files directly from the source tree.

HOW IT WORKS:

  1. Development mode (sys.frozen == False):

    • Base path: Path(__file__).parent.parent.parent

    • This resolves to: src/ttmp32gme/build/file_handler.py -> src/

    • Example: get_resource_path(“upload.html”) -> /path/to/src/upload.html

  2. PyInstaller mode (sys.frozen == True):

    • Base path: sys._MEIPASS (PyInstaller’s temporary extraction directory)

    • Files are in: _internal/ subdirectory of the bundle

    • Example: get_resource_path(“upload.html”) -> /tmp/_MEIPASS/upload.html

WHEN TO USE:

Use this function whenever you need to load any resource file that’s bundled with the application:

  • HTML files (upload.html, library.html, etc.)

  • Configuration files (config.sqlite)

  • Static assets (images, CSS, JS) - though Flask handles these automatically

  • Any other data files included in the PyInstaller spec

DO NOT USE for:

  • User data directories (use get_local_storage() instead)

  • Temporary files (use system temp directories)

  • Executables (use get_executable_path() instead)

ADDING NEW RESOURCES:

When adding a new resource file to the project:

  1. Add it to the PyInstaller spec file’s datas list:

    datas = [
    (str(source_path / "myfile.ext"), "destination_dir"),
]

  2. Load it in code using this function:

    my_file = get_resource_path("destination_dir/myfile.ext")
with open(my_file) as f:
    content = f.read()

  3. Test both modes:

    • Development: python -m ttmp32gme.ttmp32gme

    • PyInstaller: pyinstaller spec_file.spec && ./dist/ttmp32gme/ttmp32gme

Parameters:

relative_path (str) – Path relative to the application root directory. Examples: “upload.html”, “ttmp32gme/config.sqlite”

Return type:

Path

Returns:

Absolute Path object to the resource file.

Example

>>> # In development mode
>>> get_resource_path("upload.html")
PosixPath('/home/user/ttmp32gme/src/upload.html')

>>> # In PyInstaller bundle
>>> get_resource_path("upload.html")
PosixPath('/tmp/_MEIxxxxxx/upload.html')
ttmp32gme.build.file_handler.get_local_storage()[source]

Get the local storage directory for configuration and library.

Return type:

Path

Returns:

Path to local storage directory

ttmp32gme.build.file_handler.get_default_library_path()[source]

Get the default library path.

Return type:

Path

Returns:

Path to default library directory

ttmp32gme.build.file_handler.check_config_file()[source]

Check for and initialize config file if needed.

Return type:

Path

Returns:

Path to config file

ttmp32gme.build.file_handler.make_temp_album_dir(temp_name, library_path=None)[source]

Create a temporary album directory.

Parameters:

  • temp_name (int) – Numeric identifier for temp directory

  • library_path (Optional[Path]) – Optional library path, uses default if not provided

Return type:

Path

Returns:

Path to temporary album directory

ttmp32gme.build.file_handler.make_new_album_dir(album_title, library_path=None)[source]

Create a new album directory with unique name.

Parameters:

  • album_title (str) – Title for the album

  • library_path (Optional[Path]) – Optional library path, uses default if not provided

Return type:

Path

Returns:

Path to new album directory

ttmp32gme.build.file_handler.move_to_album(temp_dir, album_dir)[source]

Move files from temp directory to album directory.

Parameters:

  • temp_dir (Path) – Source temporary directory

  • album_dir (Path) – Destination album directory

Return type:

bool

Returns:

True if successful

ttmp32gme.build.file_handler.remove_temp_dir(temp_dir)[source]

Remove a temporary directory.

Parameters:

temp_dir (Path) – Temporary directory to remove

Return type:

bool

Returns:

True if successful

ttmp32gme.build.file_handler.clear_album(album_dir)[source]

Clear all files from an album directory.

Parameters:

album_dir (Path) – Album directory to clear

Return type:

bool

Returns:

True if successful

ttmp32gme.build.file_handler.remove_album(album_dir)[source]

Remove an album directory completely.

Parameters:

album_dir (Path) – Album directory to remove

Return type:

bool

Returns:

True if successful

ttmp32gme.build.file_handler.cleanup_filename(filename)[source]

Clean up filename by removing invalid characters.

Parameters:

filename (str) – Original filename

Return type:

str

Returns:

Cleaned filename

ttmp32gme.build.file_handler.get_executable_path(executable_name)[source]

Find executable in PATH or common locations.

Looks for bundled dependencies first (for PyInstaller builds), then checks PATH and common installation locations.

Parameters:

executable_name (str) – Name of executable to find

Return type:

Optional[str]

Returns:

Path to executable or None if not found

ttmp32gme.build.file_handler.get_tiptoi_dir()[source]

Find the TipToi device mount point.

Return type:

Optional[Path]

Returns:

Path to TipToi mount point or None if not found

ttmp32gme.build.file_handler.get_gmes_already_on_tiptoi()[source]

Get list of GME files already on TipToi device.

Return type:

List[str]

Returns:

List of GME filenames found on the TipToi device

ttmp32gme.build.file_handler.delete_gme_tiptoi(gme_filename)[source]

Delete a GME file from TipToi device.

Parameters:

gme_filename (str) – Name of GME file to delete

Return type:

bool

Returns:

True if successful

ttmp32gme.build.file_handler.copy_library(old_path, new_path)[source]

Move library to a new location.

Parameters:

  • old_path (Path) – Current library path

  • new_path (Path) – New library path

Return type:

bool

Returns:

True if successful

Raises:

AssertionError – If old path doesn’t exist or new path is not empty

ttmp32gme.build.file_handler.open_browser(host, port)[source]

Open the default web browser to the application URL.

Parameters:

  • host (str) – Server host

  • port (int) – Server port

Return type:

bool

Returns:

True if successful