Skip to content

track_status

Utilities for classifying track statuses and editability.

normalize_track_status 

normalize_track_status(status)

Normalize track status strings for consistent comparisons.

Performs runtime type validation to ensure defensive programming, even if incorrect types are passed at runtime.

Handles AppleScript raw enum constants like «constant ****kSub» by extracting the 4-character code and mapping to standard status strings.

Parameters:

Name Type Description Default
status object

Track status (expected str or None, but validated at runtime)

 required

Returns:

Type Description
str

Normalized lowercase status string, or empty string for None

Raises:

Type Description
TypeError

If status is not a string or None
Source code in src/core/models/track_status.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def normalize_track_status(status: object) -> str:
    """Normalize track status strings for consistent comparisons.

    Performs runtime type validation to ensure defensive programming,
    even if incorrect types are passed at runtime.

    Handles AppleScript raw enum constants like «constant ****kSub» by
    extracting the 4-character code and mapping to standard status strings.

    Args:
        status: Track status (expected str or None, but validated at runtime)

    Returns:
        Normalized lowercase status string, or empty string for None

    Raises:
        TypeError: If status is not a string or None

    """
    if status is None:
        return ""
    if not isinstance(status, str):
        type_name = type(status).__name__
        msg = f"Expected status to be str or None, got {type_name}"
        logger.warning("normalize_track_status: %s", msg)
        raise TypeError(msg)

    normalized = status.strip().lower()

    # Handle AppleScript raw enum constants like «constant ****kSub»
    if "«constant" in normalized or "constant" in normalized:
        if normalized_status := _extract_status_from_applescript_constant(normalized):
            return normalized_status
        # If we can't parse it, log warning but continue
        logger.warning("Could not parse AppleScript constant: %s", status)

    return normalized

is_prerelease_status 

is_prerelease_status(status)

Check if the status marks the track as read-only prerelease.

Source code in src/core/models/track_status.py 
100
101
102
def is_prerelease_status(status: object) -> bool:
    """Check if the status marks the track as read-only prerelease."""
    return normalize_track_status(status) in READ_ONLY_STATUSES

is_available_status 

is_available_status(status)

Determine if the track status allows standard processing.

Source code in src/core/models/track_status.py 
105
106
107
108
def is_available_status(status: object) -> bool:
    """Determine if the track status allows standard processing."""
    normalized = normalize_track_status(status)
    return normalized in AVAILABLE_STATUSES

can_edit_metadata 

can_edit_metadata(status)

Return True when the track metadata can be edited.

Source code in src/core/models/track_status.py 
111
112
113
def can_edit_metadata(status: object) -> bool:
    """Return True when the track metadata can be edited."""
    return not is_prerelease_status(status)

filter_available_tracks 

filter_available_tracks(tracks)

Filter tracks that are available for processing based on status.

Source code in src/core/models/track_status.py 
116
117
118
def filter_available_tracks(tracks: Iterable[TrackDict]) -> list[TrackDict]:
    """Filter tracks that are available for processing based on status."""
    return [track for track in tracks if is_available_status(track.track_status)]