State Capital Time Zone Analyzer

Build a Python utility that analyzes and reports time zone information for US state capitals.

Specification

Create a module that provides functionality to analyze time zone information for state capitals. The module should help users understand which time zones state capitals are located in and provide grouping capabilities.

Your implementation must provide the following capabilities:

Get Capital Time Zone

Return the time zone identifier for a given state's capital city. The function should accept a state abbreviation and return the capital's time zone as a string. If the state cannot be found or has no capital time zone information, return None.

• Input: "CA" returns "America/Los_Angeles" @test
• Input: "NY" returns "America/New_York" @test
• Input: "TX" returns "America/Chicago" @test
• Input: "XX" (invalid state) returns None @test

Group Capitals by Time Zone

Return a dictionary grouping capital cities by their time zone. The dictionary should map time zone identifiers to lists of capital city names. Only include states that have both a capital city and capital time zone defined.

• Returns a dictionary with time zone keys @test
• "America/New_York" key contains multiple capitals including "Albany" and "Annapolis" @test
• "America/Phoenix" key contains ["Phoenix"] @test

Count Capitals per Time Zone

Return the number of state capitals in each time zone as a dictionary. Map time zone identifiers to integer counts. Only count states with defined capital and capital time zone information.

• Returns a dictionary mapping time zones to counts @test
• "America/New_York" has the largest count of capitals (at least 10) @test

Implementation

@generates

API

def get_capital_timezone(state_abbr: str) -> Optional[str]:
    """
    Get the time zone for a state's capital city.

    Args:
        state_abbr: Two-letter state abbreviation (e.g., "CA", "NY")

    Returns:
        Time zone identifier (e.g., "America/Los_Angeles") or None if not found
    """

def group_capitals_by_timezone() -> Dict[str, List[str]]:
    """
    Group capital cities by their time zones.

    Returns:
        Dictionary mapping time zone identifiers to lists of capital city names
        Only includes states with both capital and capital_tz defined
    """

def count_capitals_per_timezone() -> Dict[str, int]:
    """
    Count how many state capitals are in each time zone.

    Returns:
        Dictionary mapping time zone identifiers to counts of capitals
        Only counts states with both capital and capital_tz defined
    """

Dependencies { .dependencies }

us { .dependency }

Provides US state and territory metadata including capital cities and time zone information.

@satisfied-by