Skip to content

Styling Context

Central configuration for fonts, colors, and styling options with proper bundled font management.

FontConfig dataclass

Configuration for fonts used in plots.

Source code in pyretailscience/plots/styles/styling_context.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
@dataclass
class FontConfig:
    """Configuration for fonts used in plots."""

    title_font: str = "poppins_semi_bold"
    title_size: float = 20
    label_font: str = "poppins_regular"
    label_size: float = 12
    tick_font: str = "poppins_regular"
    tick_size: float = 10
    source_font: str = "poppins_light_italic"
    source_size: float = 10
    data_label_font: str = "poppins_regular"
    data_label_size: float = 8

StylingContext

Central styling context for fonts and styling options.

Source code in pyretailscience/plots/styles/styling_context.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
class StylingContext:
    """Central styling context for fonts and styling options."""

    def __init__(self) -> None:
        """Initialize the styling context with default fonts and cache."""
        self.fonts = FontConfig()
        self._font_cache: dict[str, fm.FontProperties] = {}

        # Built-in font registry - maps names to bundled font files
        self._builtin_fonts = {
            "poppins_bold": f"{ASSETS_PATH}/fonts/Poppins-Bold.ttf",
            "poppins_semi_bold": f"{ASSETS_PATH}/fonts/Poppins-SemiBold.ttf",
            "poppins_regular": f"{ASSETS_PATH}/fonts/Poppins-Regular.ttf",
            "poppins_medium": f"{ASSETS_PATH}/fonts/Poppins-Medium.ttf",
            "poppins_light_italic": f"{ASSETS_PATH}/fonts/Poppins-LightItalic.ttf",
        }

    def get_font_properties(self, font_name: str) -> fm.FontProperties:
        """Get matplotlib FontProperties with flexible font resolution.

        This method resolves fonts in the following priority order:
        1. Check cache for previously loaded font
        2. Try to load from bundled fonts if font_name matches a built-in font
        3. Try to load as a system font family name

        Args:
            font_name (str): The name of the font to load. Can be:
                - A built-in font name (e.g., 'poppins_regular')
                - A system font family name (e.g., 'Arial', 'Times New Roman')

        Returns:
            fm.FontProperties: A matplotlib FontProperties object that can be used
                for text rendering.
        """
        if font_name in self._font_cache:
            return self._font_cache[font_name]

        # Try to load built-in bundled fonts first
        if font_name in self._builtin_fonts:
            font_props = fm.FontProperties(fname=self._builtin_fonts[font_name])
            self._font_cache[font_name] = font_props
            return font_props

        # Try to load as system font family
        font_props = fm.FontProperties(family=font_name)
        self._font_cache[font_name] = font_props
        return font_props

__init__()

Initialize the styling context with default fonts and cache.

Source code in pyretailscience/plots/styles/styling_context.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
def __init__(self) -> None:
    """Initialize the styling context with default fonts and cache."""
    self.fonts = FontConfig()
    self._font_cache: dict[str, fm.FontProperties] = {}

    # Built-in font registry - maps names to bundled font files
    self._builtin_fonts = {
        "poppins_bold": f"{ASSETS_PATH}/fonts/Poppins-Bold.ttf",
        "poppins_semi_bold": f"{ASSETS_PATH}/fonts/Poppins-SemiBold.ttf",
        "poppins_regular": f"{ASSETS_PATH}/fonts/Poppins-Regular.ttf",
        "poppins_medium": f"{ASSETS_PATH}/fonts/Poppins-Medium.ttf",
        "poppins_light_italic": f"{ASSETS_PATH}/fonts/Poppins-LightItalic.ttf",
    }

get_font_properties(font_name)

Get matplotlib FontProperties with flexible font resolution.

This method resolves fonts in the following priority order: 1. Check cache for previously loaded font 2. Try to load from bundled fonts if font_name matches a built-in font 3. Try to load as a system font family name

Parameters:

Name Type Description Default
font_name str

The name of the font to load. Can be: - A built-in font name (e.g., 'poppins_regular') - A system font family name (e.g., 'Arial', 'Times New Roman')

 required

Returns:

Type Description
FontProperties

fm.FontProperties: A matplotlib FontProperties object that can be used for text rendering.
Source code in pyretailscience/plots/styles/styling_context.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def get_font_properties(self, font_name: str) -> fm.FontProperties:
    """Get matplotlib FontProperties with flexible font resolution.

    This method resolves fonts in the following priority order:
    1. Check cache for previously loaded font
    2. Try to load from bundled fonts if font_name matches a built-in font
    3. Try to load as a system font family name

    Args:
        font_name (str): The name of the font to load. Can be:
            - A built-in font name (e.g., 'poppins_regular')
            - A system font family name (e.g., 'Arial', 'Times New Roman')

    Returns:
        fm.FontProperties: A matplotlib FontProperties object that can be used
            for text rendering.
    """
    if font_name in self._font_cache:
        return self._font_cache[font_name]

    # Try to load built-in bundled fonts first
    if font_name in self._builtin_fonts:
        font_props = fm.FontProperties(fname=self._builtin_fonts[font_name])
        self._font_cache[font_name] = font_props
        return font_props

    # Try to load as system font family
    font_props = fm.FontProperties(family=font_name)
    self._font_cache[font_name] = font_props
    return font_props

get_styling_context()

Get the global styling context instance.

Source code in pyretailscience/plots/styles/styling_context.py 
80
81
82
def get_styling_context() -> StylingContext:
    """Get the global styling context instance."""
    return _styling_context