Typing strict, Protocols et dataclasses

Le contrat : mypy --strict

Le projet compile avec mypy --strict : toute fonction est typée, tout Any qui fuit fait échouer la CI. Ce choix transforme Python en langage à contrats — les signatures deviennent la documentation, et le refactoring redevient sûr.

async def match_line(line: StructuredLine, catalog: CatalogProvider) -> MatchResult: ...

Protocol : l'interface sans héritage

La règle du projet : composition > héritage, jamais d'ABC. L'outil : typing.Protocol — le structural typing (duck typing vérifié statiquement) :

from typing import Protocol

class CatalogProvider(Protocol):
    async def search(self, query: str, limit: int) -> list[Variant]: ...
    async def get_by_sku(self, sku: str) -> Variant | None: ...

# AUCUNE classe n'hérite de CatalogProvider. Toute classe qui a
# ces méthodes EST un CatalogProvider aux yeux de mypy :
class LocalCatalogProvider:                    # pas de « (CatalogProvider) » !
    async def search(self, query: str, limit: int) -> list[Variant]: ...

Avantage décisif dans un modular monolith : engine déclare le Protocol chez lui (ou dans shared), catalog fournit une implémentation sans dépendre du consommateur — zéro couplage d'import, la frontière du module 0 tient toute seule.

dataclass(frozen=True, slots=True) : la donnée immuable

Les objets-valeurs du projet sont des dataclasses gelées :

from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class MatchResult:
    variant_id: str
    score: float
    method: str      # "exact" | "hybrid" | "deep"

• frozen=True : immuable → partageable entre tâches async sans effroi ;
• slots=True : pas de __dict__ → moins de mémoire, et les fautes de frappe d'attributs explosent au lieu de créer un champ silencieux (le « fail loud » du projet).