Skip to content

KPI Builder Base Class

KPIBuilder

Bases: ABC, Generic[KPIDefinitionType]

Abstract base class for all KPI builders.

Provides common functionality for fluent builder patterns used in KPI definition creation. All builders support optional name prefixes and suffixes for customizing KPI names.

Subclasses must implement: - build(): Generate list of KPI definitions from builder configuration

Common pattern:

>>> builder = SomeKPIBuilder()
>>> definitions = (
...     builder
...     .some_config_method(...)
...     .with_name_prefix("Custom: ")
...     .with_name_suffix(" (v2)")
...     .with_extra_attributes(my_category='my_cat_1', my_group='my_grp_1')
...     .build()
... )
Source code in submodules/mesqual/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
102
103
104
class KPIBuilder(ABC, Generic[KPIDefinitionType]):
    """
    Abstract base class for all KPI builders.

    Provides common functionality for fluent builder patterns used in KPI definition creation.
    All builders support optional name prefixes and suffixes for customizing KPI names.

    Subclasses must implement:
    - build(): Generate list of KPI definitions from builder configuration

    Common pattern:

        >>> builder = SomeKPIBuilder()
        >>> definitions = (
        ...     builder
        ...     .some_config_method(...)
        ...     .with_name_prefix("Custom: ")
        ...     .with_name_suffix(" (v2)")
        ...     .with_extra_attributes(my_category='my_cat_1', my_group='my_grp_1')
        ...     .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".

        Kwargs:
            kwargs: 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 submodules/mesqual/mesqual/kpis/builders/base.py 
32
33
34
35
36
37
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 submodules/mesqual/mesqual/kpis/builders/base.py 
39
40
41
42
43
44
45
46
47
48
49
50
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 submodules/mesqual/mesqual/kpis/builders/base.py 
52
53
54
55
56
57
58
59
60
61
62
63
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 submodules/mesqual/mesqual/kpis/builders/base.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
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".

Kwargs

kwargs: Custom key-value attributes.

Returns:

Type Description
KPIBuilder

Self for method chaining
Source code in submodules/mesqual/mesqual/kpis/builders/base.py 
81
82
83
84
85
86
87
88
89
90
91
92
93
94
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".

    Kwargs:
        kwargs: 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 submodules/mesqual/mesqual/kpis/builders/base.py 
 96
 97
 98
 99
100
101
102
103
104
@abstractmethod
def build(self) -> list[KPIDefinitionType]:
    """
    Generate all KPI definitions from builder configuration.

    Returns:
        List of KPI definition instances
    """
    pass