from typing import (
    TypeVar, Generic, Protocol, overload, Literal, Final,
    TypeAlias, TypedDict, ParamSpec, Callable, runtime_checkable,
)

# Types de base et types composes modernes (Python 3.9+ : sans importer List/Dict)
def traiter(noms: list[str], scores: dict[str, int]) -> tuple[str, int]:
    meilleur = max(scores.items(), key=lambda item: item[1])
    return meilleur

# Union moderne avec | (Python 3.10+)
def afficher(valeur: int | str | None) -> str:
    return str(valeur) if valeur is not None else "N/A"

# --- Generics : classes/fonctions parametrees par un type ---
T = TypeVar("T")

class Pile(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

    def empiler(self, item: T) -> None:
        self._items.append(item)

    def depiler(self) -> T:
        return self._items.pop()

    def est_vide(self) -> bool:
        return len(self._items) == 0

pile_entiers: Pile[int] = Pile()
pile_entiers.empiler(1)
pile_entiers.empiler(2)
# pile_entiers.empiler("texte")    # erreur detectee par un type checker (pas a l'execution)

# Syntaxe generique moderne (Python 3.12+)
class Boite[T]:
    def __init__(self, contenu: T) -> None:
        self.contenu = contenu

def premier[T](items: list[T]) -> T:
    return items[0]

# TypeVar borne : restreint les types acceptes
NumericT = TypeVar("NumericT", int, float)

def doubler(valeur: NumericT) -> NumericT:
    return valeur * 2

# --- Protocol : duck typing structurel (pas besoin d'heriter explicitement) ---
@runtime_checkable
class Dessinable(Protocol):
    def dessiner(self) -> str: ...

class Cercle:
    def dessiner(self) -> str:
        return "O"

class Carre:
    def dessiner(self) -> str:
        return "[]"

def afficher_forme(forme: Dessinable) -> None:
    # Cercle et Carre ne "heritent" pas de Dessinable, mais respectent sa structure
    print(forme.dessiner())

afficher_forme(Cercle())
afficher_forme(Carre())
print(isinstance(Cercle(), Dessinable))    # True grace a @runtime_checkable

# --- overload : plusieurs signatures pour une meme fonction ---
@overload
def traiter_entree(valeur: int) -> str: ...
@overload
def traiter_entree(valeur: str) -> int: ...

def traiter_entree(valeur):
    # une SEULE implementation reelle ; @overload sert uniquement le type checker
    if isinstance(valeur, int):
        return str(valeur)
    return len(valeur)

# --- Literal, Final, TypedDict ---
Mode = Literal["lecture", "ecriture", "ajout"]

def ouvrir_mode(chemin: str, mode: Mode) -> None:
    ...

VERSION: Final = "1.0.0"     # signale au type checker que la valeur ne doit pas changer

class Utilisateur(TypedDict):
    nom: str
    age: int
    email: str | None

def creer_utilisateur() -> Utilisateur:
    return {"nom": "Alice", "age": 30, "email": None}

# TypeAlias : nommer un type complexe pour la lisibilite
JSON: TypeAlias = "dict[str, JSON] | list[JSON] | str | int | float | bool | None"

# ParamSpec : preserver la signature exacte d'une fonction a travers un decorateur type
P = ParamSpec("P")
def journaliser[**P, R](fonction: Callable[P, R]) -> Callable[P, R]:
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"Appel de {fonction.__name__}")
        return fonction(*args, **kwargs)
    return wrapper