Module utils

Utility functions for « Back to the Kitchen » visual identity: colors and Plotly theme.

Practical usage: see code examples below for integration into your charts.

utils.color_theme

ColorTheme OOP class for « Back to the Kitchen » visual identity.

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

Main Constants

Base colors:

ORANGE_PRIMARY: Bright orange #FF8C00 (primary color)
ORANGE_SECONDARY: Red/Orange #E24E1B (secondary accent)
SECONDARY_ACCENT: Golden yellow #FFD700
BACKGROUND_MAIN: Dark gray #1E1E1E (main area)
BACKGROUND_SIDEBAR: Pure black #000000 (sidebar)
BACKGROUND_CARD: Medium gray #333333 (cards and widgets)
TEXT_PRIMARY: Light gray #F0F0F0 (main text)
TEXT_SECONDARY: Medium gray #888888 (secondary text)
TEXT_WHITE: Pure white #ffffff

Status colors:

SUCCESS: Green #28A745 (success, PROD badge)
WARNING: Yellow #FFC107 (warnings, PREPROD badge)
ERROR: Red #DC3545 (errors)
INFO: Cyan #17A2B8 (information)

Chart palettes:

CHART_COLORS: List of 8 colors for Plotly charts
STEELBLUE_PALETTE: Palette of 3 shades of blue

Seasonal palettes:

get_seasonal_colors(): Mapping season → color (Autumn, Winter, Spring, Summer)
get_seasonal_color(season): Individual color for a season

Utility methods:

to_rgba(hex_color, alpha): Convert HEX to RGBA with validation
get_plotly_theme(): Return custom Plotly theme

Usage Examples

Using primary colors:

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

# Chart with primary color
fig = go.Figure()
fig.add_trace(go.Bar(
    x=['A', 'B', 'C'],
    y=[10, 20, 30],
    marker_color=ColorTheme.ORANGE_PRIMARY
))

Using chart palette:

from utils.color_theme import ColorTheme

# For multi-series charts
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)
    ))

Using seasonal colors:

from utils.color_theme import ColorTheme

# Color by season (method 1)
season_color = ColorTheme.get_seasonal_colors()['Autumn']  # #FF8C00

# Color by season (method 2 - recommended)
season_color = ColorTheme.get_seasonal_color('Autumn')  # #FF8C00

Convert to RGBA:

from utils.color_theme import ColorTheme

# Add transparency
transparent_orange = ColorTheme.to_rgba(ColorTheme.ORANGE_PRIMARY, alpha=0.5)
# Returns: 'rgba(255, 140, 0, 0.5)'

utils.chart_theme

Apply unified theme to Plotly charts.

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é

Main Functions

apply_chart_theme(fig, title): Apply theme to a Plotly chart
apply_subplot_theme(fig, num_rows, num_cols): Theme for multiple subplots
get_bar_color(): Primary color for histogram bars
get_line_colors(): List of colors for multiple lines
get_scatter_color(): Color for scatter plots
get_reference_line_color(): Color for reference lines

Usage Examples

Simple chart with theme:

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]))

# Apply theme
chart_theme.apply_chart_theme(fig, title="My Chart")

# Display with Streamlit
st.plotly_chart(fig, use_container_width=True)

Chart with subplots:

from utils import chart_theme
from plotly.subplots import make_subplots

# Create 2x2 layout
fig = make_subplots(
    rows=2, cols=2,
    subplot_titles=("Chart 1", "Chart 2", "Chart 3", "Chart 4")
)

# Add 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)

# Apply theme for subplots
chart_theme.apply_subplot_theme(fig, num_rows=2, num_cols=2)

Using predefined colors:

from utils import chart_theme

# Color for bars
bar_color = chart_theme.get_bar_color()  # ORANGE_PRIMARY

# Colors for multiple lines
line_colors = chart_theme.get_line_colors()
# Returns: [ORANGE_PRIMARY, STEELBLUE, ORANGE_SECONDARY, ...]

# Color for scatter
scatter_color = chart_theme.get_scatter_color()  # STEELBLUE

# Color for reference line (mean, median)
ref_color = chart_theme.get_reference_line_color()  # SECONDARY_ACCENT

Complete chart with custom theme:

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

fig = go.Figure()

# Bars with custom color
fig.add_trace(go.Bar(
    x=['Monday', 'Tuesday', 'Wednesday'],
    y=[120, 95, 140],
    marker_color=chart_theme.get_bar_color(),
    name='Volume'
))

# Reference line (mean)
fig.add_hline(
    y=118.3,
    line_dash="dash",
    line_color=chart_theme.get_reference_line_color(),
    annotation_text="Mean"
)

# Apply unified theme
chart_theme.apply_chart_theme(
    fig,
    title="Volume by day of week"
)

# Additional customization
fig.update_layout(
    showlegend=True,
    height=500
)

st.plotly_chart(fig, use_container_width=True)

Automatically Applied Theme

The theme automatically configures:

Background: Transparent background, subtle gray grid
Text: TEXT_PRIMARY color (#F0F0F0)
Axes: Gray color, dashed grid lines
Hover: Labels formatted with thousands separators
Font: Arial 14px for titles, 12px for axes
Margins: Optimized for Streamlit (l=80, r=50, t=100, b=80)

Note: Use use_container_width=True with st.plotly_chart() for responsive design.