Skip to content

KPI Builder Base Class

KPIBuilder

Bases: ABC, Generic[KPIDefinitionType]

Base class of the KPI builders: methods that configure the builder and return it, then build().

All builders take a name prefix, a name suffix and extra attributes for the KPIs. A subclass implements build(), which returns the KPI definitions.

Examples:

>>> from mesqual.kpis import Aggregations, FlagAggKPIBuilder
>>> definitions = (
...     FlagAggKPIBuilder()
...     .for_flag('Country.Results.price')
...     .with_aggregation(Aggregations.Mean)
...     .with_name_prefix('Study: ')
...     .with_extra_attributes(category='prices')
...     .build()
... )
Source code in src/mesqual/kpis/builders/base.py
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 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
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
class KPIBuilder(ABC, Generic[KPIDefinitionType]):
    """
    Base class of the KPI builders: methods that configure the builder and return it, then `build()`.

    All builders take a name prefix, a name suffix and extra attributes for
    the KPIs. A subclass implements `build()`, which returns the KPI
    definitions.

    Examples:
        >>> from mesqual.kpis import Aggregations, FlagAggKPIBuilder
        >>> definitions = (
        ...     FlagAggKPIBuilder()
        ...     .for_flag('Country.Results.price')
        ...     .with_aggregation(Aggregations.Mean)
        ...     .with_name_prefix('Study: ')
        ...     .with_extra_attributes(category='prices')
        ...     .build()
        ... )
    """

    def __init__(self):
        """Initialize builder with common attributes."""
        self._name_prefix: str = ''
        self._name_suffix: str = ''
        self._extra_attributes: dict = dict()
        self._custom_name: str | None = None

    def with_name_prefix(self, prefix: str) -> KPIBuilder:
        """
        Set name prefix for generated KPIs.

        Args:
            prefix: Prefix string to prepend to KPI names

        Returns:
            Self for method chaining
        """
        self._name_prefix = prefix
        return self

    def with_name_suffix(self, suffix: str) -> KPIBuilder:
        """
        Set name suffix for generated KPIs.

        Args:
            suffix: Suffix string to append to KPI names

        Returns:
            Self for method chaining
        """
        self._name_suffix = suffix
        return self

    def with_custom_name(self, name: str) -> KPIBuilder:
        """
        Set custom name that completely overrides automatic name generation.

        When set, the KPI will use this exact name instead of generating one
        from flag, aggregation, object, etc.

        Args:
            name: Custom name for the KPI

        Returns:
            Self for method chaining
        """
        self._custom_name = name
        return self

    def with_extra_attributes(self, **kwargs) -> KPIBuilder:
        """
        Set additional extra (custom) attributes.

        When set, the KPI will contain these attributes under "kpi.attributes.extra_attributes".

        Args:
            **kwargs (Any): Custom key-value attributes.

        Returns:
            Self for method chaining
        """
        self._extra_attributes.update(**kwargs)
        return self

    @abstractmethod
    def build(self) -> list[KPIDefinitionType]:
        """
        Generate all KPI definitions from builder configuration.

        Returns:
            List of KPI definition instances
        """
        pass

__init__

__init__()

Initialize builder with common attributes.

Source code in src/mesqual/kpis/builders/base.py
29
30
31
32
33
34
def __init__(self):
    """Initialize builder with common attributes."""
    self._name_prefix: str = ''
    self._name_suffix: str = ''
    self._extra_attributes: dict = dict()
    self._custom_name: str | None = None

with_name_prefix

with_name_prefix(prefix: str) -> KPIBuilder

Set name prefix for generated KPIs.

Parameters:

Name Type Description Default
prefix str

Prefix string to prepend to KPI names

required

Returns:

Type Description
KPIBuilder

Self for method chaining

Source code in src/mesqual/kpis/builders/base.py
36
37
38
39
40
41
42
43
44
45
46
47
def with_name_prefix(self, prefix: str) -> KPIBuilder:
    """
    Set name prefix for generated KPIs.

    Args:
        prefix: Prefix string to prepend to KPI names

    Returns:
        Self for method chaining
    """
    self._name_prefix = prefix
    return self

with_name_suffix

with_name_suffix(suffix: str) -> KPIBuilder

Set name suffix for generated KPIs.

Parameters:

Name Type Description Default
suffix str

Suffix string to append to KPI names

required

Returns:

Type Description
KPIBuilder

Self for method chaining

Source code in src/mesqual/kpis/builders/base.py
49
50
51
52
53
54
55
56
57
58
59
60
def with_name_suffix(self, suffix: str) -> KPIBuilder:
    """
    Set name suffix for generated KPIs.

    Args:
        suffix: Suffix string to append to KPI names

    Returns:
        Self for method chaining
    """
    self._name_suffix = suffix
    return self

with_custom_name

with_custom_name(name: str) -> KPIBuilder

Set custom name that completely overrides automatic name generation.

When set, the KPI will use this exact name instead of generating one from flag, aggregation, object, etc.

Parameters:

Name Type Description Default
name str

Custom name for the KPI

required

Returns:

Type Description
KPIBuilder

Self for method chaining

Source code in src/mesqual/kpis/builders/base.py
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def with_custom_name(self, name: str) -> KPIBuilder:
    """
    Set custom name that completely overrides automatic name generation.

    When set, the KPI will use this exact name instead of generating one
    from flag, aggregation, object, etc.

    Args:
        name: Custom name for the KPI

    Returns:
        Self for method chaining
    """
    self._custom_name = name
    return self

with_extra_attributes

with_extra_attributes(**kwargs) -> KPIBuilder

Set additional extra (custom) attributes.

When set, the KPI will contain these attributes under "kpi.attributes.extra_attributes".

Parameters:

Name Type Description Default
**kwargs Any

Custom key-value attributes.

{}

Returns:

Type Description
KPIBuilder

Self for method chaining

Source code in src/mesqual/kpis/builders/base.py
78
79
80
81
82
83
84
85
86
87
88
89
90
91
def with_extra_attributes(self, **kwargs) -> KPIBuilder:
    """
    Set additional extra (custom) attributes.

    When set, the KPI will contain these attributes under "kpi.attributes.extra_attributes".

    Args:
        **kwargs (Any): Custom key-value attributes.

    Returns:
        Self for method chaining
    """
    self._extra_attributes.update(**kwargs)
    return self

build abstractmethod

build() -> list[KPIDefinitionType]

Generate all KPI definitions from builder configuration.

Returns:

Type Description
list[KPIDefinitionType]

List of KPI definition instances

Source code in src/mesqual/kpis/builders/base.py
 93
 94
 95
 96
 97
 98
 99
100
101
@abstractmethod
def build(self) -> list[KPIDefinitionType]:
    """
    Generate all KPI definitions from builder configuration.

    Returns:
        List of KPI definition instances
    """
    pass