Aller au contenu

Les événements dans Forge Stats

Ce document décrit l'objet StatsEvent et la validation des noms d'événements.

Le fichier de code correspondant est forge_mvc_stats/events.py.

1. À quoi sert ce module ?

Un événement statistique est une chose mesurable : une vue de page, un clic, une soumission de formulaire.
Ce module définit le contrat d'un événement : son nom, son libellé, sa catégorie et ses métadonnées, ainsi que la normalisation et la validation du nom.

Il ne stocke rien et ne trace rien : il pose seulement la structure.

2. L'objet StatsEvent

@dataclass(frozen=True)
class StatsEvent:
    name: str                     # snake_case, obligatoire
    label: str = ""               # retombe sur name si vide
    category: str = "general"     # retombe sur "general" si vide
    metadata: dict[str, Any] = field(default_factory=dict)

Il est immuable (frozen=True).
Le constructeur valide et normalise name ; metadata doit être un dictionnaire (None devient {}).

3. Créer et valider

from forge_mvc_stats import make_event, validate_event

e = make_event("page_view", label="Vue de page", category="traffic",
               metadata={"path": "/contact"})
validate_event(e)   # retourne e
Fonction Comportement
make_event(name, ...) crée un StatsEvent validé
validate_event(event) vérifie que event est un StatsEvent ; retourne l'événement ou lève
normalize_event_name(value) minuscule, espaces et tirets vers _ ; lève si caractères interdits
validate_event_name(value) normalise puis vérifie le format [a-z][a-z0-9_]*

4. Les noms d'événements

Les noms sont de simples chaînes snake_case définies par l'application.
Forge ne fournit pas de liste prédéfinie, conformément au principe 1 (le framework n'est pas l'application).

Noms courants à utiliser directement : "page_view", "contact_click", "form_submit", "download_click", "external_link_click", "media_view".

5. Les erreurs

StatsEventError est levée pour un nom invalide ou une métadonnée non valide.

6. Contextes d'utilisation

  • Déclaration : make_event(...) au moment de mesurer quelque chose.
  • Tracking : passez l'événement à track_event (voir tracking).

7. Voir aussi