kymflow_core.repository

Repository helpers for discovering and loading kymograph files.

This layer isolates filesystem traversal so GUI/CLI code can rely on a single API to fetch KymFile instances or lightweight metadata dictionaries.

Classes

FolderScanResult dataclass

Result of scanning a folder for kymograph files.

Attributes:

Name	Type	Description
folder	Path	Path to the scanned folder.
files	List[KymFile]	List of KymFile instances found in the folder.

Source code in src/kymflow_core/repository.py

@dataclass
class FolderScanResult:
    """Result of scanning a folder for kymograph files.

    Attributes:
        folder: Path to the scanned folder.
        files: List of KymFile instances found in the folder.
    """

    folder: Path
    files: List[KymFile]

Functions

metadata_table(folder)

Get metadata dictionaries for all TIFF files in a folder.

Lightweight alternative to scan_folder() that returns metadata dictionaries instead of KymFile objects. Useful for quickly populating tables without the overhead of instantiating full KymFile objects.

Parameters:

Name	Type	Description	Default
folder	str | Path	Directory path to scan for TIFF files.	required

Returns:

Type	Description
Sequence[dict]	Sequence of metadata dictionaries, one per TIFF file found.

Source code in src/kymflow_core/repository.py

def metadata_table(folder: str | Path) -> Sequence[dict]:
    """Get metadata dictionaries for all TIFF files in a folder.

    Lightweight alternative to scan_folder() that returns metadata dictionaries
    instead of KymFile objects. Useful for quickly populating tables without
    the overhead of instantiating full KymFile objects.

    Args:
        folder: Directory path to scan for TIFF files.

    Returns:
        Sequence of metadata dictionaries, one per TIFF file found.
    """
    return collect_metadata(folder)

scan_folder(folder, *, load_images=False)

Scan a folder for kymograph TIFF files.

Creates KymFile objects for every .tif file found in the specified folder. The scan is non-recursive (only direct children of the folder are checked).

Parameters:

Name	Type	Description	Default
folder	str | Path	Directory path to scan for TIFF files.	required
load_images	bool	If True, TIFF image arrays are loaded immediately. If False, images are loaded lazily when accessed. Defaults to False for efficient metadata-only workflows.	False

Returns:

Type	Description
FolderScanResult	FolderScanResult containing the folder path and list of KymFile
FolderScanResult	instances found.

Source code in src/kymflow_core/repository.py

def scan_folder(folder: str | Path, *, load_images: bool = False) -> FolderScanResult:
    """Scan a folder for kymograph TIFF files.

    Creates KymFile objects for every .tif file found in the specified folder.
    The scan is non-recursive (only direct children of the folder are checked).

    Args:
        folder: Directory path to scan for TIFF files.
        load_images: If True, TIFF image arrays are loaded immediately.
            If False, images are loaded lazily when accessed. Defaults to False
            for efficient metadata-only workflows.

    Returns:
        FolderScanResult containing the folder path and list of KymFile
        instances found.
    """
    base = Path(folder)
    tif_paths = sorted(path for path in base.glob("*.tif") if path.is_file())
    files = [KymFile(path, load_image=load_images) for path in tif_paths]
    return FolderScanResult(folder=base, files=files)