Utilities

🔖 Git version utility

The version_info.py file provides get_version() to access Git version information of the codebase. imported wherever version information is needed within the application. Its design ensures robust and consistent version reporting across different environments and deployment scenarios.

It attempts to retrieve the latest Git tag, formats the version string to include commit distance and hash when not on a tag, and gracefully falls back to a default value ("dev") if Git is unavailable or an error occurs. This ensures that the application always has a meaningful version identifier, useful for debugging, deployment, and user information.

API get_version

version_info

Functions:

Name	Description
get_version	Get the application version string for the current environment.

get_version()

Get the application version string for the current environment.

This function prefers a pre-baked version from the environment and falls back to querying Git metadata when available.

Parameters:

Name	Type	Description	Default
APP_VERSION		Optional environment variable containing a pre-baked version string.	required

Returns:

Type	Description
str	The resolved version string, or "dev" when no version information can
str	be determined.

Source code in src/utils/version_info.py

def get_version() -> str:
    """Get the application version string for the current environment.

    This function prefers a pre-baked version from the environment and falls
    back to querying Git metadata when available.

    Args:
        APP_VERSION: Optional environment variable containing a pre-baked
            version string.

    Returns:
        The resolved version string, or "dev" when no version information can
        be determined.
    """
    if baked_version := os.getenv("APP_VERSION"):
        return baked_version

    # Local development fallback
    try:
        if result := subprocess.check_output(
            ["git", "describe", "--tags", "--abbrev=8", "--always"],
            stderr=subprocess.DEVNULL,
            text=True,
            timeout=5,
        ).strip():
            version = _parse_and_format_version(result)
            os.environ["APP_VERSION"] = version
            return version
    except Exception as e:
        logger.warning(f"Git version detection failed: {e}")

    return "dev"

🖼️ Cover image compositor

This file cover_compositor.py defines a CoverCompositor utility that generates a composite “collage” image from a set of album cover images. It:

• Takes a directory of cover images and a list of cover filenames (with possible duplicates).
• Builds a square grid (N×N) of cover tiles sized 400×400 pixels each.
• Uses cover frequency (duplicates) to influence which covers are repeated when filling the grid.
• Performs basic image processing (center square crop, slight contrast boost).
• Outputs the final composite as a base64-encoded JPEG data URL (data:image/jpeg;base64,...), suitable for embedding directly in HTML or APIs without separate image hosting.

API CoverCompositor

CoverCompositor(covers_dir, logger=None)

Creates composite cover artwork from individual cover images.

Provides utilities to arrange multiple covers into a grid and export the result as an embeddable image.

Initializes the compositor with a covers directory and optional logger.

Stores paths and logging configuration so composite images can be built and diagnostics recorded.

Parameters:

Name	Type	Description	Default
covers_dir	Path	Filesystem path where individual cover images are stored.	required
logger	Logger	Optional logger instance used for warnings and diagnostic messages.	None

Methods:

Name	Description
generate_grid_composite	Generates a composite cover image from multiple individual cover files.

Source code in src/utils/cover_compositor.py

def __init__(self, covers_dir: Path, logger: Logger=None):
    """Initializes the compositor with a covers directory and optional logger.

    Stores paths and logging configuration so composite images can be built and diagnostics recorded.

    Args:
        covers_dir: Filesystem path where individual cover images are stored.
        logger: Optional logger instance used for warnings and diagnostic messages.
    """
    self.covers_dir = covers_dir
    self._logger = logger

generate_grid_composite(cover_paths)

Generates a composite cover image from multiple individual cover files.

Builds a square grid of cover tiles and returns the result as a base64-encoded JPEG data URL.

Parameters:

Name	Type	Description	Default
cover_paths	list[str]	List of cover filenames (may contain duplicates for weighting).	required

Returns:

Name	Type	Description
str	str	A data URL string containing the base64-encoded JPEG composite image.

Raises:

Type	Description
ValueError	If no cover paths are provided or no images can be loaded.

Source code in src/utils/cover_compositor.py

def generate_grid_composite(self, cover_paths: list[str]) -> str:
    """Generates a composite cover image from multiple individual cover files.

    Builds a square grid of cover tiles and returns the result as a base64-encoded JPEG data URL.

    Args:
        cover_paths: List of cover filenames (may contain duplicates for weighting).

    Returns:
        str: A data URL string containing the base64-encoded JPEG composite image.

    Raises:
        ValueError: If no cover paths are provided or no images can be loaded.
    """
    if not cover_paths:
        raise ValueError("No covers provided")

    fill_covers, grid_size = self._build_fill_covers(cover_paths)
    tiles = self._load_tiles(fill_covers)

    if not tiles:
        raise ValueError("No images could be loaded")

    composite = self._compose_grid(tiles, grid_size)
    return self._encode_image_to_data_url(composite)