Module utils

Fonctions utilitaires pour la charte graphique « Back to the Kitchen » : couleurs et thème Plotly.

Usage pratique : voir exemples code ci-dessous pour intégration dans vos graphiques.

utils.color_theme

Classe POO ColorTheme pour la charte graphique « Back to the Kitchen ».

Classe ColorTheme - Charte graphique Back to the Kitchen.

Ce module fournit une classe centralisée pour gérer toutes les couleurs de l’application Mangetamain Analytics avec une approche POO.

class mangetamain_analytics.utils.color_theme.ColorTheme[source]

Bases : object

Thème de couleurs “Back to the Kitchen” avec accesseurs typés.

Cette classe encapsule toutes les couleurs de la charte graphique dans une interface POO avec méthodes utilitaires.

Exemples

>>> # Accès direct aux couleurs
>>> bar_color = ColorTheme.ORANGE_PRIMARY
>>> text_color = ColorTheme.TEXT_PRIMARY

>>> # Conversion en RGBA
>>> rgba = ColorTheme.to_rgba(ColorTheme.ORANGE_PRIMARY, 0.5)
>>> # 'rgba(255, 140, 0, 0.5)'

>>> # Récupération thème Plotly
>>> theme = ColorTheme.get_plotly_theme()

BACKGROUND: str = '#1E1E1E'

SECONDARY_BACKGROUND: str = '#333333'

BACKGROUND_MAIN: str = '#1E1E1E'

BACKGROUND_SIDEBAR: str = '#000000'

BACKGROUND_FOOTER: str = '#1a1a1a'

BACKGROUND_CARD: str = '#333333'

TEXT: str = '#F0F0F0'

TEXT_PRIMARY: str = '#F0F0F0'

TEXT_SECONDARY: str = '#888888'

TEXT_WHITE: str = '#ffffff'

PRIMARY: str = '#FF8C00'

SECONDARY_ACCENT: str = '#FFD700'

ORANGE_PRIMARY: str = '#FF8C00'

ORANGE_SECONDARY: str = '#E24E1B'

ORANGE_LIGHT: str = '#FFA07A'

SUCCESS: str = '#28A745'

WARNING: str = '#FFC107'

ERROR: str = '#DC3545'

INFO: str = '#17A2B8'

CHART_COLORS: list[str] = ['#FF8C00', '#FFD700', '#E24E1B', '#1E90FF', '#00CED1', '#FFA07A', '#B0E0E6', '#DAA520']

STEELBLUE_PALETTE: list[str] = ['#4682b4', '#5a9bd5', '#3a6ba5']

classmethod gradient_orange() → str[source]: Dégradé orange (PRIMARY → ORANGE_SECONDARY).

classmethod gradient_dark() → str[source]: Dégradé fond sombre (SIDEBAR → MAIN).

ENV_PROD: dict[str, str] = {'bg': '#28A745', 'icon': '🟢', 'text': '#ffffff'}

ENV_PREPROD: dict[str, str] = {'bg': '#FFC107', 'icon': '🔍', 'text': '#333333'}

ENV_PROD_BG: str = '#28A745'

ENV_PROD_TEXT: str = '#ffffff'

ENV_PREPROD_BG: str = '#FFC107'

ENV_PREPROD_TEXT: str = '#333333'

BUTTON_PRIMARY_BG: str = '#FF8C00'

BUTTON_PRIMARY_TEXT: str = '#ffffff'

BUTTON_PRIMARY_HOVER: str = '#FFA07A'

BUTTON_SECONDARY_BG: str = 'transparent'

BUTTON_SECONDARY_BORDER: str = '#FF8C00'

BUTTON_SECONDARY_TEXT: str = '#FF8C00'

CARD_BORDER: str = '#333333'

CARD_SHADOW: str = '0 4px 6px rgba(0, 0, 0, 0.3)'

CARD_SHADOW_ORANGE: str = '0 4px 6px rgba(255, 140, 66, 0.3)'

INPUT_BORDER: str = '#444444'

INPUT_FOCUS_BORDER: str = '#FF8C00'

INPUT_BG: str = '#333333'

classmethod to_rgba(hex_color: str, alpha: float = 1.0) → str[source]

Convertit une couleur HEX en RGBA avec validation.

Paramètres:

hex_color – Couleur au format hex (#RRGGBB)
alpha – Transparence (0.0 à 1.0)

Renvoie:

Couleur au format rgba(r, g, b, a)

Lève:

ValueError – Si hex_color invalide ou alpha hors range

Exemples

>>> ColorTheme.to_rgba("#FF8C00", 0.5)
'rgba(255, 140, 0, 0.5)'

>>> ColorTheme.to_rgba(ColorTheme.ORANGE_PRIMARY, 0.8)
'rgba(255, 140, 0, 0.8)'

classmethod get_plotly_theme() → dict[source]

Retourne le thème Plotly complet.

Renvoie:: Dictionnaire de configuration Plotly avec fond, grilles, axes et palette de couleurs

Exemples

>>> theme = ColorTheme.get_plotly_theme()
>>> fig.update_layout(**theme['layout'])

classmethod get_seasonal_colors() → dict[str, str][source]

Retourne le mapping couleurs saisonnières.

Renvoie:: couleur_hex}
Type renvoyé:: Dictionnaire {saison

Exemples

>>> colors = ColorTheme.get_seasonal_colors()
>>> autumn_color = colors["Automne"]
>>> # '#FF8C00'

classmethod get_seasonal_color(season: str) → str[source]

Retourne la couleur pour une saison donnée.

Paramètres:: season – Nom de la saison (Printemps, Été, Automne, Hiver)
Renvoie:: Couleur hex de la saison, ou ORANGE_PRIMARY si saison inconnue

Exemples

>>> ColorTheme.get_seasonal_color("Automne")
'#FF8C00'

>>> ColorTheme.get_seasonal_color("Inconnu")
'#FF8C00'  # Fallback

Constantes Principales

Couleurs de base :

ORANGE_PRIMARY : Orange vif #FF8C00 (couleur principale)
ORANGE_SECONDARY : Rouge/Orange #E24E1B (accent secondaire)
SECONDARY_ACCENT : Jaune doré #FFD700
BACKGROUND_MAIN : Gris foncé #1E1E1E (zone principale)
BACKGROUND_SIDEBAR : Noir pur #000000 (sidebar)
BACKGROUND_CARD : Gris moyen #333333 (cards et widgets)
TEXT_PRIMARY : Gris clair #F0F0F0 (texte principal)
TEXT_SECONDARY : Gris moyen #888888 (texte secondaire)
TEXT_WHITE : Blanc pur #ffffff

Couleurs d’état :

SUCCESS : Vert #28A745 (succès, badge PROD)
WARNING : Jaune #FFC107 (warnings, badge PREPROD)
ERROR : Rouge #DC3545 (erreurs)
INFO : Cyan #17A2B8 (informations)

Palettes graphiques :

CHART_COLORS : Liste de 8 couleurs pour graphiques Plotly
STEELBLUE_PALETTE : Palette de 3 nuances de bleu

Palettes saisonnières :

get_seasonal_colors() : Mapping saison → couleur (Automne, Hiver, Printemps, Été)
get_seasonal_color(season) : Couleur individuelle pour une saison

Méthodes utilitaires :

to_rgba(hex_color, alpha) : Convertit HEX en RGBA avec validation
get_plotly_theme() : Retourne le thème Plotly personnalisé

Exemples d’Utilisation

Utiliser les couleurs principales :

from utils.color_theme import ColorTheme
import plotly.graph_objects as go

# Graphique avec couleur primaire
fig = go.Figure()
fig.add_trace(go.Bar(
    x=['A', 'B', 'C'],
    y=[10, 20, 30],
    marker_color=ColorTheme.ORANGE_PRIMARY
))

Utiliser la palette graphique :

from utils.color_theme import ColorTheme

# Pour graphiques multi-séries
fig = go.Figure()
for i, serie in enumerate(data_series):
    color = ColorTheme.CHART_COLORS[i % len(ColorTheme.CHART_COLORS)]
    fig.add_trace(go.Scatter(
        x=serie['x'],
        y=serie['y'],
        name=serie['name'],
        line=dict(color=color)
    ))

Utiliser les couleurs saisonnières :

from utils.color_theme import ColorTheme

# Couleur par saison (méthode 1)
season_color = ColorTheme.get_seasonal_colors()['Automne']  # #FF8C00

# Couleur par saison (méthode 2 - recommandée)
season_color = ColorTheme.get_seasonal_color('Automne')  # #FF8C00

Convertir en RGBA :

from utils.color_theme import ColorTheme

# Ajouter transparence
transparent_orange = ColorTheme.to_rgba(ColorTheme.ORANGE_PRIMARY, alpha=0.5)
# Retourne: 'rgba(255, 140, 0, 0.5)'

utils.chart_theme

Applique le thème unifié aux graphiques Plotly.

Thème graphique pour les visualisations Plotly.

Ce module fournit des fonctions pour appliquer automatiquement la charte graphique Back to the Kitchen aux graphiques Plotly.

mangetamain_analytics.utils.chart_theme.apply_chart_theme(fig: Any, title: str | None = None) → Any[source]

Applique le thème Back to the Kitchen à un graphique Plotly.

Paramètres:

fig – Figure Plotly à thématiser
title – Titre optionnel du graphique

Renvoie:

Figure Plotly avec le thème appliqué

mangetamain_analytics.utils.chart_theme.get_bar_color() → str[source]

Retourne la couleur principale pour les barres.

Renvoie:: Couleur hex pour les barres d’histogramme

mangetamain_analytics.utils.chart_theme.get_line_colors() → list[str][source]

Retourne la liste de couleurs pour les lignes multiples.

Renvoie:: Liste de couleurs hex

mangetamain_analytics.utils.chart_theme.get_scatter_color() → str[source]

Retourne la couleur pour les scatter plots.

Renvoie:: Couleur hex pour les points de scatter

mangetamain_analytics.utils.chart_theme.get_reference_line_color() → str[source]

Retourne la couleur pour les lignes de référence (régression, etc).

Renvoie:: Couleur hex pour les lignes de référence

mangetamain_analytics.utils.chart_theme.apply_subplot_theme(fig: Any, num_rows: int = 1, num_cols: int = 2) → Any[source]

Applique le thème à un graphique avec subplots.

Paramètres:

fig – Figure Plotly avec subplots
num_rows – Nombre de lignes de subplots
num_cols – Nombre de colonnes de subplots

Renvoie:

Figure Plotly avec le thème appliqué

Fonctions Principales

apply_chart_theme(fig, title) : Applique le thème à un graphique Plotly
apply_subplot_theme(fig, num_rows, num_cols) : Thème pour subplots multiples
get_bar_color() : Couleur principale pour barres d’histogramme
get_line_colors() : Liste de couleurs pour lignes multiples
get_scatter_color() : Couleur pour scatter plots
get_reference_line_color() : Couleur pour lignes de référence

Exemples d’Utilisation

Graphique simple avec thème :

from utils import chart_theme
import plotly.graph_objects as go

fig = go.Figure()
fig.add_trace(go.Scatter(x=[1, 2, 3], y=[4, 5, 6]))

# Appliquer le thème
chart_theme.apply_chart_theme(fig, title="Mon graphique")

# Afficher avec Streamlit
st.plotly_chart(fig, use_container_width=True)

Graphique avec subplots :

from utils import chart_theme
from plotly.subplots import make_subplots

# Créer layout 2x2
fig = make_subplots(
    rows=2, cols=2,
    subplot_titles=("Graphique 1", "Graphique 2", "Graphique 3", "Graphique 4")
)

# Ajouter traces
fig.add_trace(go.Scatter(x=[1, 2], y=[3, 4]), row=1, col=1)
fig.add_trace(go.Bar(x=[1, 2], y=[5, 6]), row=1, col=2)

# Appliquer thème pour subplots
chart_theme.apply_subplot_theme(fig, num_rows=2, num_cols=2)

Utiliser les couleurs prédéfinies :

from utils import chart_theme

# Couleur pour barres
bar_color = chart_theme.get_bar_color()  # ORANGE_PRIMARY

# Couleurs pour lignes multiples
line_colors = chart_theme.get_line_colors()
# Retourne: [ORANGE_PRIMARY, STEELBLUE, ORANGE_SECONDARY, ...]

# Couleur pour scatter
scatter_color = chart_theme.get_scatter_color()  # STEELBLUE

# Couleur ligne référence (moyenne, médiane)
ref_color = chart_theme.get_reference_line_color()  # SECONDARY_ACCENT

Graphique complet avec thème personnalisé :

from utils import chart_theme
from utils.color_theme import ColorTheme
import plotly.graph_objects as go

fig = go.Figure()

# Barres avec couleur personnalisée
fig.add_trace(go.Bar(
    x=['Lundi', 'Mardi', 'Mercredi'],
    y=[120, 95, 140],
    marker_color=chart_theme.get_bar_color(),
    name='Volume'
))

# Ligne de référence (moyenne)
fig.add_hline(
    y=118.3,
    line_dash="dash",
    line_color=chart_theme.get_reference_line_color(),
    annotation_text="Moyenne"
)

# Appliquer thème unifié
chart_theme.apply_chart_theme(
    fig,
    title="Volume par jour de semaine"
)

# Personnalisation supplémentaire
fig.update_layout(
    showlegend=True,
    height=500
)

st.plotly_chart(fig, use_container_width=True)

Thème Appliqué Automatiquement

Le thème configure automatiquement :

Background : Fond transparent, grille subtile grise
Texte : Couleur TEXT_PRIMARY (#F0F0F0)
Axes : Couleur grise, lignes de grille pointillées
Hover : Labels formatés avec séparateurs de milliers
Police : Arial 14px pour titres, 12px pour axes
Marges : Optimisées pour Streamlit (l=80, r=50, t=100, b=80)

Note : Utiliser use_container_width=True avec st.plotly_chart() pour responsive design.