Time Standards¶

Offline lookups against the bundled USA Swimming motivational standards (the 2025–2028 cuts), shipped as JSON inside the package — no setup or network access. USA Swimming revises the cuts every four years, so refreshing them is just a matter of upgrading tunas.

TimeStandard is an ordered IntEnum from slowest to fastest — B < BB < A < AA < AAA < AAAA — so a qualifies_for(...) result can be compared directly (std >= TimeStandard.AA). Each member has a .display() name.

Lookups take an event, an age, and a sex, bucketing the age into single-year groups (10 & under, 11-12, 13-14, 15-16, 17-18). Standards exist for MALE/FEMALE only — passing Sex.MIXED raises ValueError. An event/age/sex with no defined cut returns None (or an empty list).

qualifies_for — the single fastest standard a time meets, or None.
all_qualified — every standard met, ordered slowest first.
standard_time — the cutoff Time for one standard, or None.

If the bundled data is missing or malformed, lookups raise StandardsError.

standards ¶

USA Swimming motivational time standards (B through AAAA) bundled offline.

TimeStandard ¶

Bases: IntEnum

USA Swimming motivational standards ordered slowest (B) to fastest (AAAA).

display ¶

display() -> str

Human-readable standard name (e.g., "AAAA").

Source code in src/tunas/standards.py

def display(self) -> str:
    """Human-readable standard name (e.g., "AAAA")."""
    return self.name

qualifies_for ¶

qualifies_for(
    time: Time, event: Event, age: int, sex: Sex
) -> TimeStandard | None

Determine the fastest USA Swimming motivational standard achieved for the given event, age, and sex.

Uses a youngest-first lookup for the swimmer's age group (10 & Under, 11-12, 13-14, 15-16, 17-18).

Parameters:

Name	Type	Description	Default
`time`	`Time`	The swimmer's time.	required
`event`	`Event`	The event.	required
`age`	`int`	The swimmer's age in years.	required
`sex`	`Sex`	The swimmer's sex (must be MALE or FEMALE).	required

Returns:

Type	Description
`TimeStandard \| None`	The fastest achieved `TimeStandard` (from slowest B to fastest AAAA), or `None`
`TimeStandard \| None`	if the time does not qualify for any motivational standard.

Raises:

Type	Description
`ValueError`	If `sex` is `Sex.MIXED`.

Source code in src/tunas/standards.py

def qualifies_for(time: Time, event: Event, age: int, sex: Sex) -> TimeStandard | None:
    """Determine the fastest USA Swimming motivational standard achieved for the given event,
    age, and sex.

    Uses a youngest-first lookup for the swimmer's age group (10 & Under, 11-12, 13-14, 15-16,
    17-18).

    Args:
        time: The swimmer's time.
        event: The event.
        age: The swimmer's age in years.
        sex: The swimmer's sex (must be MALE or FEMALE).

    Returns:
        The fastest achieved `TimeStandard` (from slowest B to fastest AAAA), or `None`
        if the time does not qualify for any motivational standard.

    Raises:
        ValueError: If `sex` is `Sex.MIXED`.
    """
    _check_sex(sex)
    best: TimeStandard | None = None
    for standard in TimeStandard:
        cutoff = _cutoff(standard, event, age, sex)
        if cutoff is not None and time.centiseconds <= cutoff:
            best = standard
    return best

all_qualified ¶

all_qualified(
    time: Time, event: Event, age: int, sex: Sex
) -> list[TimeStandard]

Retrieve all USA Swimming motivational standards qualified for by the given time.

Parameters:

Name	Type	Description	Default
`time`	`Time`	The swimmer's time.	required
`event`	`Event`	The event.	required
`age`	`int`	The swimmer's age in years.	required
`sex`	`Sex`	The swimmer's sex (must be MALE or FEMALE).	required

Returns:

Type	Description
`list[TimeStandard]`	A list of all qualified `TimeStandard` values, ordered from slowest (B) to fastest (AAAA).

Raises:

Type	Description
`ValueError`	If `sex` is `Sex.MIXED`.

Source code in src/tunas/standards.py

def all_qualified(time: Time, event: Event, age: int, sex: Sex) -> list[TimeStandard]:
    """Retrieve all USA Swimming motivational standards qualified for by the given time.

    Args:
        time: The swimmer's time.
        event: The event.
        age: The swimmer's age in years.
        sex: The swimmer's sex (must be MALE or FEMALE).

    Returns:
        A list of all qualified `TimeStandard` values, ordered from slowest (B) to fastest (AAAA).

    Raises:
        ValueError: If `sex` is `Sex.MIXED`.
    """
    _check_sex(sex)
    return [
        standard
        for standard in TimeStandard
        if (cutoff := _cutoff(standard, event, age, sex)) is not None
        and time.centiseconds <= cutoff
    ]

standard_time ¶

standard_time(
    standard: TimeStandard, event: Event, age: int, sex: Sex
) -> Time | None

Get the cutoff time required to achieve a specific motivational standard.

Parameters:

Name	Type	Description	Default
`standard`	`TimeStandard`	The target motivational standard.	required
`event`	`Event`	The event.	required
`age`	`int`	The swimmer's age in years.	required
`sex`	`Sex`	The swimmer's sex (must be MALE or FEMALE).	required

Returns:

Type	Description
`Time \| None`	The cutoff `Time` required to achieve the standard, or `None` if the standard
`Time \| None`	is undefined for the event/age/sex combination.

Raises:

Type	Description
`ValueError`	If `sex` is `Sex.MIXED`.

Source code in src/tunas/standards.py

def standard_time(standard: TimeStandard, event: Event, age: int, sex: Sex) -> Time | None:
    """Get the cutoff time required to achieve a specific motivational standard.

    Args:
        standard: The target motivational standard.
        event: The event.
        age: The swimmer's age in years.
        sex: The swimmer's sex (must be MALE or FEMALE).

    Returns:
        The cutoff `Time` required to achieve the standard, or `None` if the standard
        is undefined for the event/age/sex combination.

    Raises:
        ValueError: If `sex` is `Sex.MIXED`.
    """
    _check_sex(sex)
    cutoff = _cutoff(standard, event, age, sex)
    return Time(cutoff) if cutoff is not None else None