pathutils

sleap.io.pathutils

Utilities for working with file paths.

Functions:

Name	Description
filenames_prefix_change	Finds missing files by changing the initial part of paths.
find_changed_subpath	Finds the smallest initial section of path that was changed.
list_file_missing	Given a list of filenames, returns list of whether file exists.

filenames_prefix_change(filenames, old_prefix, new_prefix, missing=None, confirm_callback=None, is_sequence=None, original_filenames=None)

Finds missing files by changing the initial part of paths.

Parameters:

Name	Type	Description	Default
filenames		The list of filenames, needn't all be missing. For image sequences, this contains display paths (first frame).	required
old_prefix		Initial part of path to replace.	required
new_prefix		Initial part with which to replace it.	required
missing	bool	List of which files are known to be missing; if not given, then we'll check each file.	None
confirm_callback	Optional[Callable]	If given, then we'll call this before applying change to confirm that user wants to apply the change.	None
is_sequence	Optional[List[bool]]	List indicating which entries are image sequences. For sequences, ALL frames must exist at the new location.	None
original_filenames	Optional[List]	For image sequences, the full list of frame paths. Used for frame verification when auto-applying prefix changes.	None

Returns:

Type	Description
	None; filenames (and missing, if given) have new data.

Source code in sleap/io/pathutils.py

def filenames_prefix_change(
    filenames,
    old_prefix,
    new_prefix,
    missing: bool = None,
    confirm_callback: Optional[Callable] = None,
    is_sequence: Optional[List[bool]] = None,
    original_filenames: Optional[List] = None,
):
    """
    Finds missing files by changing the initial part of paths.

    Args:
        filenames: The list of filenames, needn't all be missing.
            For image sequences, this contains display paths (first frame).
        old_prefix: Initial part of path to replace.
        new_prefix: Initial part with which to replace it.
        missing: List of which files are known to be missing; if not given,
            then we'll check each file.
        confirm_callback: If given, then we'll call this before applying
            change to confirm that user wants to apply the change.
        is_sequence: List indicating which entries are image sequences.
            For sequences, ALL frames must exist at the new location.
        original_filenames: For image sequences, the full list of frame paths.
            Used for frame verification when auto-applying prefix changes.

    Returns:
        None; `filenames` (and `missing`, if given) have new data.
    """
    from pathlib import Path

    if not filenames or not old_prefix or not new_prefix:
        return

    # Initialize sequence tracking if not provided
    if is_sequence is None:
        is_sequence = [False] * len(filenames)
    if original_filenames is None:
        original_filenames = filenames

    # Ask for confirmation if there's a confirmation callback given
    need_to_ask = True if callable(confirm_callback) else False

    # Try changing every filename unless we're given list of which are missing
    check = missing if missing else [True] * len(filenames)

    # Just to be on the safe side, make sure this list covers all filenames
    if len(check) < len(filenames):
        check.extend([True] * (len(filenames) - len(check)))

    for i, filename in enumerate(filenames):
        if check[i]:
            if filename.startswith(old_prefix):
                try_filename = filename.replace(old_prefix, new_prefix)
                try_filename = fix_path_separator(try_filename)

                # For image sequences, check if first frame exists at new location
                if is_sequence[i]:
                    frames = original_filenames[i]
                    if not isinstance(frames, list):
                        frames = [frames]

                    # Check if first frame exists with the prefix change
                    if frames:
                        first_frame = str(frames[0])
                        if first_frame.startswith(old_prefix):
                            try_frame = first_frame.replace(old_prefix, new_prefix)
                            try_frame = fix_path_separator(try_frame)
                            if not Path(try_frame).exists():
                                continue  # Skip - first frame not found
                else:
                    # Regular video - just check if file exists
                    if not Path(try_filename).exists():
                        continue

                # Check if user would like to apply change to all paths
                # with the same initial segment.
                if need_to_ask and not confirm_callback():
                    return

                # We're still here, so we can go ahead and replace
                need_to_ask = False
                filenames[i] = try_filename
                check[i] = False

                # Save prefix change in config file so that it can be used
                # automatically in the future
                save_path_prefix_replacement(old_prefix, new_prefix)

find_changed_subpath(old_path, new_path)

Finds the smallest initial section of path that was changed.

Parameters:

Name	Type	Description	Default
old_path	str	Old path	required
new_path	str	New path	required

Returns:

Type	Description
Tuple[str, str]	(initial part of old path), (corresponding replacement in new path)

Source code in sleap/io/pathutils.py

def find_changed_subpath(old_path: str, new_path: str) -> Tuple[str, str]:
    """Finds the smallest initial section of path that was changed.

    Args:
        old_path: Old path
        new_path: New path

    Returns:
        (initial part of old path), (corresponding replacement in new path)
    """
    seps = ("/", "\\")

    # Find overlap at end of paths
    old_common = ""
    new_char_idx = -1
    for old_char_idx in range(len(old_path) - 1, 0, -1):
        old_char = old_path[old_char_idx]
        new_char = new_path[new_char_idx]
        if old_char == new_char or old_char in seps and new_char in seps:
            old_common = old_char + old_common
            new_char_idx -= 1
        else:
            break

    # Get the initial part of the old path which was replaced, and the
    # initial part of the new path which replaced it.
    old_initial = old_path[: old_char_idx + 1]
    new_inital = new_path[: new_char_idx + 1] if new_char_idx < -1 else new_path

    return (old_initial, new_inital)

list_file_missing(filenames)

Given a list of filenames, returns list of whether file exists.

Source code in sleap/io/pathutils.py

def list_file_missing(filenames):
    """Given a list of filenames, returns list of whether file exists."""
    return [not os.path.exists(filename) for filename in filenames]