Python type narrowing with TypeGuard and isinstance

from typing import TypeGuard, Union, Any
from dataclasses import dataclass

# Basic isinstance narrowing — mypy/pyright understand this automatically
def process_value(value: str | int | None) -> str:
    if value is None:
        return ''
    if isinstance(value, int):
        return str(value)  # value is int here
    return value.upper()  # value is str here

# TypeGuard for custom type predicates
@dataclass
class ValidTrace:
    id: str
    title: str
    trust_score: float

def is_valid_trace(obj: Any) -> TypeGuard[ValidTrace]:
    return (
        isinstance(obj, dict) and
        isinstance(obj.get('id'), str) and
        isinstance(obj.get('title'), str) and
        isinstance(obj.get('trust_score'), float)
    )

def process_api_response(data: Any) -> ValidTrace | None:
    if is_valid_trace(data):
        return data  # Type is narrowed to ValidTrace here
    return None

# Narrowing with literal types
from typing import Literal

Status = Literal['pending', 'validated', 'rejected']

def is_status(value: str) -> TypeGuard[Status]:
    return value in ('pending', 'validated', 'rejected')

def handle_status(raw: str) -> None:
    if is_status(raw):
        handle_trace_status(raw)  # raw is Status here

# assert_never for exhaustive matching
from typing import Never

def handle_event(event: Literal['created', 'updated', 'deleted']) -> str:
    match event:
        case 'created': return 'New item'
        case 'updated': return 'Item changed'
        case 'deleted': return 'Item removed'
        case _ as unreachable:
            # Type checker errors if any case is missed
            assert_never(unreachable)

def assert_never(value: Never) -> Never:
    raise AssertionError(f'Unhandled case: {value}')