US State Name Validator

Build a utility that validates and normalizes US state names entered by users.

Requirements

Create a Python module that accepts user-provided state names and validates them against official US state names. The module should handle various input formats and return normalized state information.

Core Functionality

The module should provide a validate_state_name function that:

• Accepts a string representing a potential US state name
• Returns a dictionary with state information if valid
• Returns None if the input is not a valid US state name
• Handles case-insensitive matching (e.g., "california", "CALIFORNIA", "California" should all work)

The returned dictionary should include:

• name: The official full state name
• abbreviation: The two-letter postal abbreviation
• is_valid: Boolean indicating the state was found (always True when a dict is returned)

Test Cases

• When given "Maryland", returns {"name": "Maryland", "abbreviation": "MD", "is_valid": True} @test
• When given "california", returns {"name": "California", "abbreviation": "CA", "is_valid": True} @test
• When given "TEXAS", returns {"name": "Texas", "abbreviation": "TX", "is_valid": True} @test
• When given "NotAState", returns None @test
• When given an empty string, returns None @test

Implementation

@generates

API

def validate_state_name(name: str) -> dict | None:
    """
    Validates a US state name and returns normalized state information.

    Args:
        name: A string representing a potential US state name

    Returns:
        A dictionary with keys 'name', 'abbreviation', and 'is_valid' if valid,
        None if the input is not a valid state name
    """
    pass

Dependencies { .dependencies }

us { .dependency }

Provides US state metadata and lookup functionality.

@satisfied-by