pylegend 0.7.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

pylegend/core/language/shared/pct_helpers.py

@@ -0,0 +1,56 @@
+# Copyright 2025 Goldman Sachs
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from datetime import datetime, date
+from pylegend._typing import (
+    PyLegendSequence,
+    PyLegendUnion,
+)
+from pylegend.core.language import (
+    convert_literal_to_literal_expression,
+    PyLegendBooleanLiteralExpression,
+    PyLegendStringLiteralExpression,
+    PyLegendIntegerLiteralExpression,
+    PyLegendFloatLiteralExpression,
+    PyLegendStrictDateLiteralExpression,
+    PyLegendDateTimeLiteralExpression,
+    PyLegendFloat,
+    PyLegendDateTime,
+    PyLegendStrictDate,
+    PyLegendString,
+    PyLegendInteger,
+    PyLegendBoolean,
+    PyLegendPrimitive
+)
+
+__all__: PyLegendSequence[str] = [
+    "c",
+]
+
+
+def c(constant: PyLegendUnion[int, float, bool, str, datetime, date]) -> PyLegendPrimitive:
+    expr = convert_literal_to_literal_expression(constant)
+    if isinstance(expr, PyLegendBooleanLiteralExpression):
+        return PyLegendBoolean(expr)
+    if isinstance(expr, PyLegendStringLiteralExpression):
+        return PyLegendString(expr)
+    if isinstance(expr, PyLegendIntegerLiteralExpression):
+        return PyLegendInteger(expr)
+    if isinstance(expr, PyLegendFloatLiteralExpression):
+        return PyLegendFloat(expr)
+    if isinstance(expr, PyLegendDateTimeLiteralExpression):
+        return PyLegendDateTime(expr)
+    if isinstance(expr, PyLegendStrictDateLiteralExpression):
+        return PyLegendStrictDate(expr)
+    raise RuntimeError(f"Unsupported constant type: {type(constant)}")

pylegend/core/language/shared/primitives/integer.py

@@ -33,9 +33,11 @@ from pylegend.core.language.shared.operations.integer_operation_expressions impo
     PyLegendIntegerSubtractExpression,
     PyLegendIntegerMultiplyExpression,
     PyLegendIntegerModuloExpression,
+    PyLegendIntegerCharExpression
 )
 if TYPE_CHECKING:
     from pylegend.core.language.shared.primitives import PyLegendFloat
+    from pylegend.core.language.shared.primitives.string import PyLegendString
 
 __all__: PyLegendSequence[str] = [
     "PyLegendInteger"
@@ -52,6 +54,10 @@ class PyLegendInteger(PyLegendNumber):
         self.__value_copy = value
         super().__init__(value)
 
+    def char(self) -> "PyLegendString":
+        from pylegend.core.language.shared.primitives.string import PyLegendString
+        return PyLegendString(PyLegendIntegerCharExpression(self.__value_copy))
+
     def to_sql_expression(
             self,
             frame_name_to_base_query_map: PyLegendDict[str, QuerySpecification],

pylegend/core/language/shared/primitives/primitive.py

@@ -32,11 +32,13 @@ from pylegend.core.language.shared.operations.primitive_operation_expressions im
     PyLegendPrimitiveNotEqualsExpression,
     PyLegendIsEmptyExpression,
     PyLegendIsNotEmptyExpression,
+    PyLegendPrimitiveToStringExpression
 )
 from pylegend.core.tds.tds_frame import FrameToSqlConfig
 from pylegend.core.tds.tds_frame import FrameToPureConfig
 if TYPE_CHECKING:
     from pylegend.core.language.shared.primitives.boolean import PyLegendBoolean
+    from pylegend.core.language.shared.primitives.string import PyLegendString
 
 __all__: PyLegendSequence[str] = [
     "PyLegendPrimitive",
@@ -100,6 +102,10 @@ class PyLegendPrimitive(metaclass=ABCMeta):
     def is_not_null(self) -> "PyLegendBoolean":
         return self.is_not_empty()
 
+    def to_string(self) -> "PyLegendString":
+        from pylegend.core.language.shared.primitives.string import PyLegendString
+        return PyLegendString(PyLegendPrimitiveToStringExpression(self.value()))
+
     @staticmethod
     def __validate_param_to_be_primitive(
             param: "PyLegendUnion[int, float, bool, str, date, datetime, PyLegendPrimitive]",

pylegend/core/language/shared/primitives/string.py

@@ -16,11 +16,14 @@ from pylegend._typing import (
     PyLegendSequence,
     PyLegendDict,
     PyLegendUnion,
+    PyLegendOptional
 )
+from pylegend.core.language.shared.literal_expressions import PyLegendIntegerLiteralExpression
 from pylegend.core.language.shared.primitives.primitive import PyLegendPrimitive
 from pylegend.core.language.shared.primitives.integer import PyLegendInteger
 from pylegend.core.language.shared.primitives.float import PyLegendFloat
 from pylegend.core.language.shared.primitives.boolean import PyLegendBoolean
+from pylegend.core.language.shared.primitives.datetime import PyLegendDateTime
 from pylegend.core.language.shared.expression import PyLegendExpressionStringReturn
 from pylegend.core.language.shared.literal_expressions import PyLegendStringLiteralExpression
 from pylegend.core.sql.metamodel import (
@@ -47,9 +50,26 @@ from pylegend.core.language.shared.operations.string_operation_expressions impor
     PyLegendStringLessThanEqualExpression,
     PyLegendStringGreaterThanExpression,
     PyLegendStringGreaterThanEqualExpression,
+    PyLegendStringParseBooleanExpression,
+    PyLegendStringParseDateTimeExpression,
+    PyLegendStringAsciiExpression,
+    PyLegendStringDecodeBase64Expression,
+    PyLegendStringEncodeBase64Expression,
+    PyLegendStringReverseExpression,
+    PyLegendStringToLowerFirstCharacterExpression,
+    PyLegendStringToUpperFirstCharacterExpression,
+    PyLegendStringLeftExpression,
+    PyLegendStringRightExpression,
+    PyLegendStringSubStringExpression,
+    PyLegendStringReplaceExpression,
+    PyLegendStringLpadExpression,
+    PyLegendStringRpadExpression,
+    PyLegendStringSplitPartExpression,
+    PyLegendStringFullMatchExpression,
+    PyLegendStringRepeatStringExpression,
+    PyLegendStringMatchExpression
 )
 
-
 __all__: PyLegendSequence[str] = [
     "PyLegendString"
 ]
@@ -120,6 +140,108 @@ class PyLegendString(PyLegendPrimitive):
     def parse_float(self) -> "PyLegendFloat":
         return PyLegendFloat(PyLegendStringParseFloatExpression(self.__value))
 
+    def parse_boolean(self) -> "PyLegendBoolean":
+        return PyLegendBoolean(PyLegendStringParseBooleanExpression(self.__value))
+
+    def parse_datetime(self) -> "PyLegendDateTime":
+        return PyLegendDateTime(PyLegendStringParseDateTimeExpression(self.__value))
+
+    def ascii(self) -> "PyLegendInteger":
+        return PyLegendInteger(PyLegendStringAsciiExpression(self.__value))
+
+    def b64decode(self) -> "PyLegendString":
+        return PyLegendString(PyLegendStringDecodeBase64Expression(self.__value))
+
+    def b64encode(self) -> "PyLegendString":
+        return PyLegendString(PyLegendStringEncodeBase64Expression(self.__value))
+
+    def reverse(self) -> "PyLegendString":
+        return PyLegendString(PyLegendStringReverseExpression(self.__value))
+
+    def to_lower_first_character(self) -> "PyLegendString":
+        return PyLegendString(PyLegendStringToLowerFirstCharacterExpression(self.__value))
+
+    def to_upper_first_character(self) -> "PyLegendString":
+        return PyLegendString(PyLegendStringToUpperFirstCharacterExpression(self.__value))
+
+    def left(self, count: PyLegendUnion[int, "PyLegendInteger"]) -> "PyLegendString":
+        PyLegendString.__validate_param_to_be_int_or_int_expr(count, "left parameter")
+        count_op = PyLegendIntegerLiteralExpression(count) if isinstance(count, int) else count.value()
+        return PyLegendString(PyLegendStringLeftExpression(self.__value, count_op))
+
+    def right(self, count: PyLegendUnion[int, "PyLegendInteger"]) -> "PyLegendString":
+        PyLegendString.__validate_param_to_be_int_or_int_expr(count, "right parameter")
+        count_op = PyLegendIntegerLiteralExpression(count) if isinstance(count, int) else count.value()
+        return PyLegendString(PyLegendStringRightExpression(self.__value, count_op))
+
+    def substring(
+            self,
+            start: PyLegendUnion[int, "PyLegendInteger"],
+            end: PyLegendOptional[PyLegendUnion[int, "PyLegendInteger"]] = None) -> "PyLegendString":
+        PyLegendString.__validate_param_to_be_int_or_int_expr(start, "substring start parameter")
+        start_op = PyLegendIntegerLiteralExpression(start) if isinstance(start, int) else start.value()
+        if end is None:
+            return PyLegendString(PyLegendStringSubStringExpression([self.__value, start_op]))
+        PyLegendString.__validate_param_to_be_int_or_int_expr(end, "substring end parameter")
+        end_op = PyLegendIntegerLiteralExpression(end) if isinstance(end, int) else end.value()
+        return PyLegendString(PyLegendStringSubStringExpression([self.__value, start_op, end_op]))
+
+    def replace(
+            self,
+            to_replace: PyLegendUnion[str, "PyLegendString"],
+            replacement: PyLegendUnion[str, "PyLegendString"]) -> "PyLegendString":
+        PyLegendString.__validate_param_to_be_str_or_str_expr(to_replace, "replace to_replace parameter")
+        to_replace_op = PyLegendStringLiteralExpression(to_replace) if isinstance(to_replace,
+                                                                                  str) else to_replace.__value
+        PyLegendString.__validate_param_to_be_str_or_str_expr(replacement, "replace replacement parameter")
+        replacement_op = PyLegendStringLiteralExpression(replacement) if isinstance(replacement,
+                                                                                    str) else replacement.__value
+        return PyLegendString(PyLegendStringReplaceExpression([self.__value, to_replace_op, replacement_op]))
+
+    def rjust(
+            self,
+            length: PyLegendUnion[int, "PyLegendInteger"],
+            fill_char: PyLegendUnion[str, "PyLegendString"] = ' ') -> "PyLegendString":
+        PyLegendString.__validate_param_to_be_int_or_int_expr(length, "rjust length parameter")
+        length_op = PyLegendIntegerLiteralExpression(length) if isinstance(length, int) else length.value()
+        fill_char_op = PyLegendStringLiteralExpression(fill_char) if isinstance(fill_char, str) else fill_char.__value
+        return PyLegendString(PyLegendStringLpadExpression([self.__value, length_op, fill_char_op]))
+
+    def ljust(
+            self,
+            length: PyLegendUnion[int, "PyLegendInteger"],
+            fill_char: PyLegendUnion[str, "PyLegendString"] = ' ') -> "PyLegendString":
+        PyLegendString.__validate_param_to_be_int_or_int_expr(length, "ljust length parameter")
+        length_op = PyLegendIntegerLiteralExpression(length) if isinstance(length, int) else length.value()
+        fill_char_op = PyLegendStringLiteralExpression(fill_char) if isinstance(fill_char, str) else fill_char.__value
+        return PyLegendString(PyLegendStringRpadExpression([self.__value, length_op, fill_char_op]))
+
+    def split_part(
+            self,
+            sep: PyLegendUnion[str, "PyLegendString"],
+            part: PyLegendUnion[int, "PyLegendInteger"]) -> "PyLegendString | None":
+        PyLegendString.__validate_param_to_be_str_or_str_expr(sep, "split_part sep parameter")
+        sep_op = PyLegendStringLiteralExpression(sep) if isinstance(sep, str) else sep.value()
+        PyLegendString.__validate_param_to_be_int_or_int_expr(part, "split_part part parameter")
+        part_op = PyLegendIntegerLiteralExpression(part) if isinstance(part, int) else part.value()
+        return PyLegendString(PyLegendStringSplitPartExpression([self.__value, sep_op, part_op]))
+
+    def full_match(self, pattern: PyLegendUnion[str, "PyLegendString"]) -> PyLegendBoolean:
+        PyLegendString.__validate_param_to_be_str_or_str_expr(pattern, "full_match parameter")
+        pattern_op = PyLegendStringLiteralExpression(pattern) if isinstance(pattern, str) else pattern.__value
+        return PyLegendBoolean(PyLegendStringFullMatchExpression(self.__value, pattern_op))
+
+    def match(self, pattern: PyLegendUnion[str, "PyLegendString"]) -> PyLegendBoolean:
+        PyLegendString.__validate_param_to_be_str_or_str_expr(pattern, "match parameter")  # pragma: no cover
+        pattern_op = PyLegendStringLiteralExpression(pattern) if isinstance(
+            pattern, str) else pattern.__value  # pragma: no cover
+        return PyLegendBoolean(PyLegendStringMatchExpression(self.__value, pattern_op))  # pragma: no cover
+
+    def repeat_string(self, times: PyLegendUnion[int, "PyLegendInteger"]) -> "PyLegendString":
+        PyLegendString.__validate_param_to_be_int_or_int_expr(times, "repeatString parameter")
+        times_op = PyLegendIntegerLiteralExpression(times) if isinstance(times, int) else times.value()
+        return PyLegendString(PyLegendStringRepeatStringExpression(self.__value, times_op))
+
     def __add__(self, other: PyLegendUnion[str, "PyLegendString"]) -> "PyLegendString":
         PyLegendString.__validate_param_to_be_str_or_str_expr(other, "String plus (+) parameter")
         other_op = PyLegendStringLiteralExpression(other) if isinstance(other, str) else other.__value
@@ -174,3 +296,9 @@ class PyLegendString(PyLegendPrimitive):
         if not isinstance(param, str):
             raise TypeError(desc + " should be a str."
                                    " Got value " + str(param) + " of type: " + str(type(param)))
+
+    @staticmethod
+    def __validate_param_to_be_int_or_int_expr(param: PyLegendUnion[int, "PyLegendInteger"], desc: str) -> None:
+        if not isinstance(param, (int, PyLegendInteger)):
+            raise TypeError(desc + " should be a int or a int expression (PyLegendInteger)."
+                                   " Got value " + str(param) + " of type: " + str(type(param)))

pylegend/core/sql/metamodel.py

@@ -148,7 +148,9 @@ class ComparisonOperator(Enum):
     LESS_THAN = 3,
     LESS_THAN_OR_EQUAL = 4,
     GREATER_THAN = 5,
-    GREATER_THAN_OR_EQUAL = 6
+    GREATER_THAN_OR_EQUAL = 6,
+    REGEX_MATCH = 7,
+    LIKE = 8
 
 
 class CurrentTimeType(Enum):

pylegend/core/sql/metamodel_extension.py

@@ -81,6 +81,7 @@ __all__: PyLegendSequence[str] = [
     "EpochExpression",
     "WindowExpression",
     "ConstantExpression",
+    "StringSubStringExpression"
 ]
 
 
@@ -745,3 +746,20 @@ class ConstantExpression(Expression):
     ) -> None:
         super().__init__(_type="constantExpression")
         self.name = name
+
+
+class StringSubStringExpression(Expression):
+    value: "Expression"
+    start: "Expression"
+    end: PyLegendOptional["Expression"]
+
+    def __init__(
+            self,
+            value: "Expression",
+            start: "Expression",
+            end: PyLegendOptional["Expression"] = None
+    ) -> None:
+        super().__init__(_type="stringSubStringExpression")
+        self.value = value
+        self.start = start
+        self.end = end

pylegend/core/tds/pandas_api/frames/functions/aggregate_function.py

@@ -0,0 +1,316 @@
+# Copyright 2025 Goldman Sachs
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numpy as np
+import collections.abc
+from pylegend._typing import (
+    PyLegendCallable,
+    PyLegendSequence,
+    PyLegendTuple,
+    PyLegendUnion,
+    PyLegendList,
+    PyLegendMapping,
+)
+from pylegend.core.language.pandas_api.pandas_api_aggregate_specification import (
+    PyLegendAggFunc,
+    PyLegendAggInput
+)
+from pylegend.core.language.pandas_api.pandas_api_tds_row import PandasApiTdsRow
+from pylegend.core.language.shared.helpers import escape_column_name, generate_pure_lambda
+from pylegend.core.language.shared.literal_expressions import convert_literal_to_literal_expression
+from pylegend.core.language.shared.primitive_collection import PyLegendPrimitiveCollection, create_primitive_collection
+from pylegend.core.language.shared.primitives.primitive import PyLegendPrimitive, PyLegendPrimitiveOrPythonPrimitive
+from pylegend.core.sql.metamodel import QuerySpecification, SelectItem, SingleColumn
+from pylegend.core.tds.pandas_api.frames.pandas_api_applied_function_tds_frame import PandasApiAppliedFunction
+from pylegend.core.tds.pandas_api.frames.pandas_api_base_tds_frame import PandasApiBaseTdsFrame
+from pylegend.core.tds.sql_query_helpers import copy_query, create_sub_query
+from pylegend.core.tds.tds_column import TdsColumn
+from pylegend.core.tds.tds_frame import FrameToPureConfig, FrameToSqlConfig
+
+
+class AggregateFunction(PandasApiAppliedFunction):
+    __base_frame: PandasApiBaseTdsFrame
+    __func: PyLegendAggInput
+    __axis: PyLegendUnion[int, str]
+    __args: PyLegendSequence[PyLegendPrimitiveOrPythonPrimitive]
+    __kwargs: PyLegendMapping[str, PyLegendPrimitiveOrPythonPrimitive]
+
+    @classmethod
+    def name(cls) -> str:
+        return "aggregate"  # pragma: no cover
+
+    def __init__(
+            self,
+            base_frame: PandasApiBaseTdsFrame,
+            func: PyLegendAggInput,
+            axis: PyLegendUnion[int, str],
+            *args: PyLegendPrimitiveOrPythonPrimitive,
+            **kwargs: PyLegendPrimitiveOrPythonPrimitive
+    ) -> None:
+        self.__base_frame = base_frame
+        self.__func = func
+        self.__axis = axis
+        self.__args = args
+        self.__kwargs = kwargs
+
+    def to_sql(self, config: FrameToSqlConfig) -> QuerySpecification:
+        db_extension = config.sql_to_string_generator().get_db_extension()
+        base_query: QuerySpecification = self.__base_frame.to_sql_query_object(config)
+
+        should_create_sub_query = (
+            len(base_query.groupBy) > 0 or
+            base_query.select.distinct or
+            base_query.offset is not None or
+            base_query.limit is not None
+        )
+
+        new_query: QuerySpecification
+        if should_create_sub_query:
+            new_query = create_sub_query(base_query, config, "root")
+        else:
+            new_query = copy_query(base_query)
+
+        new_select_items: PyLegendList[SelectItem] = []
+
+        for agg in self.__aggregates_list:
+            agg_sql_expr = agg[2].to_sql_expression({"r": new_query}, config)
+            new_select_items.append(
+                SingleColumn(alias=db_extension.quote_identifier(agg[0]), expression=agg_sql_expr)
+            )
+
+        new_query.select.selectItems = new_select_items
+        return new_query
+
+    def to_pure(self, config: FrameToPureConfig) -> str:
+        agg_strings = []
+        for agg in self.__aggregates_list:
+            map_expr_string = (agg[1].to_pure_expression(config) if isinstance(agg[1], PyLegendPrimitive)
+                               else convert_literal_to_literal_expression(agg[1]).to_pure_expression(config))
+            agg_expr_string = agg[2].to_pure_expression(config).replace(map_expr_string, "$c")
+            agg_strings.append(f"{escape_column_name(agg[0])}:{generate_pure_lambda('r', map_expr_string)}:"
+                               f"{generate_pure_lambda('c', agg_expr_string)}")
+
+        return (f"{self.__base_frame.to_pure(config)}{config.separator(1)}"
+                f"->aggregate({config.separator(2)}"
+                f"~[{', '.join(agg_strings)}]{config.separator(1)}"
+                f")")
+
+    def base_frame(self) -> PandasApiBaseTdsFrame:
+        return self.__base_frame
+
+    def tds_frame_parameters(self) -> PyLegendList["PandasApiBaseTdsFrame"]:
+        return []
+
+    def calculate_columns(self) -> PyLegendSequence["TdsColumn"]:
+        return [c.copy() for c in self.__base_frame.columns()]
+
+    def validate(self) -> bool:
+        if self.__axis not in [0, "index"]:
+            raise NotImplementedError(
+                f"The 'axis' parameter of the aggregate function must be 0 or 'index', but got: {self.__axis}"
+            )
+
+        if len(self.__args) > 0 or len(self.__kwargs) > 0:
+            raise NotImplementedError(
+                "AggregateFunction currently does not support additional positional "
+                "or keyword arguments. Please remove extra *args/**kwargs."
+            )
+
+        self.__aggregates_list: PyLegendList[
+            PyLegendTuple[str, PyLegendPrimitiveOrPythonPrimitive, PyLegendPrimitive]
+        ] = []
+
+        normalized_func: dict[str, PyLegendAggFunc] = self.__normalize_input_func_to_standard_dict(self.__func)
+        tds_row = PandasApiTdsRow.from_tds_frame("r", self.__base_frame)
+
+        for column_name, aggregate_function in normalized_func.items():
+            mapper_function: PyLegendCallable[[PandasApiTdsRow], PyLegendPrimitiveOrPythonPrimitive] = eval(
+                f'lambda r: r["{column_name}"]')
+            map_result: PyLegendPrimitiveOrPythonPrimitive = mapper_function(tds_row)
+            collection: PyLegendPrimitiveCollection = create_primitive_collection(map_result)
+
+            normalized_aggregate_function = self.__normalize_agg_func_to_lambda_function(aggregate_function)
+            agg_result: PyLegendPrimitive = normalized_aggregate_function(collection)
+
+            self.__aggregates_list.append((column_name, map_result, agg_result))
+
+        return True
+
+    def __normalize_input_func_to_standard_dict(
+            self,
+            func_input: PyLegendAggInput
+    ) -> dict[str, PyLegendAggFunc]:
+
+        column_names = [col.get_name() for col in self.calculate_columns()]
+
+        if isinstance(func_input, collections.abc.Mapping):
+            normalized: dict[str, PyLegendAggFunc] = {}
+
+            for key, value in func_input.items():
+                if not isinstance(key, str):
+                    raise TypeError(
+                        f"Invalid `func` argument for the aggregate function.\n"
+                        f"When a dictionary is provided, all keys must be strings.\n"
+                        f"But got key: {key!r} (type: {type(key).__name__})\n"
+                    )
+                if key not in column_names:
+                    raise ValueError(
+                        f"Invalid `func` argument for the aggregate function.\n"
+                        f"When a dictionary is provided, all keys must be column names.\n"
+                        f"Available columns are: {sorted(column_names)}\n"
+                        f"But got key: {key!r} (type: {type(key).__name__})\n"
+                    )
+
+                if isinstance(value, collections.abc.Sequence) and not isinstance(value, str):
+                    if len(value) != 1:
+                        raise ValueError(
+                            f"Invalid `func` argument for the aggregate function.\n"
+                            f"When providing a list of functions for a specific column, "
+                            f"the list must contain exactly one element (single aggregation only).\n"
+                            f"Column: {key!r}\n"
+                            f"List Length: {len(value)}\n"
+                            f"Value: {value!r}\n"
+                        )
+
+                    single_func = value[0]
+
+                    if not (callable(single_func) or isinstance(single_func, str) or isinstance(single_func, np.ufunc)):
+                        raise TypeError(
+                            f"Invalid `func` argument for the aggregate function.\n"
+                            f"The single element in the list for key {key!r} must be a callable, str, or np.ufunc.\n"
+                            f"But got element: {single_func!r} (type: {type(single_func).__name__})\n"
+                        )
+
+                    normalized[key] = single_func
+
+                else:
+                    if not (callable(value) or isinstance(value, str) or isinstance(value, np.ufunc)):
+                        raise TypeError(
+                            f"Invalid `func` argument for the aggregate function.\n"
+                            f"When a dictionary is provided, the value must be a callable, str, or np.ufunc "
+                            f"(or a list containing exactly one of these).\n"
+                            f"But got value for key {key!r}: {value!r} (type: {type(value).__name__})\n"
+                        )
+                    normalized[key] = value
+
+            return normalized
+
+        elif isinstance(func_input, collections.abc.Sequence) and not isinstance(func_input, str):
+
+            if len(func_input) != 1:
+                raise ValueError(
+                    f"Invalid `func` argument for the aggregate function.\n"
+                    f"When providing a list as the func argument, it must contain exactly one element "
+                    f"(which will be applied to all columns).\n"
+                    f"Multiple functions are not supported.\n"
+                    f"List Length: {len(func_input)}\n"
+                    f"Input: {func_input!r}\n"
+                )
+
+            single_func = func_input[0]
+
+            if not (callable(single_func) or isinstance(single_func, str) or isinstance(single_func, np.ufunc)):
+                raise TypeError(
+                    f"Invalid `func` argument for the aggregate function.\n"
+                    f"The single element in the top-level list must be a callable, str, or np.ufunc.\n"
+                    f"But got element: {single_func!r} (type: {type(single_func).__name__})\n"
+                )
+
+            return {col: single_func for col in column_names}
+
+        elif callable(func_input) or isinstance(func_input, str) or isinstance(func_input, np.ufunc):
+            return {col: func_input for col in column_names}
+
+        else:
+            raise TypeError(
+                "Invalid `func` argument for aggregate function. "
+                "Expected a callable, str, np.ufunc, a list containing exactly one of these, "
+                "or a mapping[str -> callable/str/ufunc/a list containing exactly one of these]. "
+                f"But got: {func_input!r} (type: {type(func_input).__name__})"
+            )
+
+    def __normalize_agg_func_to_lambda_function(
+            self,
+            func: PyLegendAggFunc
+    ) -> PyLegendCallable[[PyLegendPrimitiveCollection], PyLegendPrimitive]:
+
+        PYTHON_FUNCTION_TO_LEGEND_FUNCTION_MAPPING: PyLegendMapping[str, PyLegendList[str]] = {
+            "average":         ["mean", "average", "nanmean"],
+            "sum":             ["sum", "nansum"],
+            "min":             ["min", "amin", "minimum", "nanmin"],
+            "max":             ["max", "amax", "maximum", "nanmax"],
+            "std_dev_sample":  ["std", "std_dev", "nanstd"],
+            "variance_sample": ["var", "variance", "nanvar"],
+            "median":          ["median", "nanmedian"],
+            "count":           ["count", "size", "len", "length"],
+        }
+
+        FLATTENED_FUNCTION_MAPPING: dict[str, str] = {}
+        for target_method, source_list in PYTHON_FUNCTION_TO_LEGEND_FUNCTION_MAPPING.items():
+            for alias in source_list:
+                FLATTENED_FUNCTION_MAPPING[alias] = target_method
+
+        lambda_source: str
+        final_lambda: PyLegendCallable[[PyLegendPrimitiveCollection], PyLegendPrimitive]
+
+        if isinstance(func, str):
+            func_lower = func.lower()
+            if func_lower in FLATTENED_FUNCTION_MAPPING:
+                internal_method_name = FLATTENED_FUNCTION_MAPPING[func_lower]
+            else:
+                raise NotImplementedError(
+                    f"Invalid `func` argument for the aggregate function.\n"
+                    f"The string {func!r} does not correspond to any supported aggregation.\n"
+                    f"Available string functions are: {sorted(FLATTENED_FUNCTION_MAPPING.keys())}"
+                )  # pragma: no cover
+            lambda_source = self._generate_lambda_source(internal_method_name)
+            final_lambda = eval(lambda_source)
+            return final_lambda
+
+        elif isinstance(func, np.ufunc):
+            func_name = func.__name__
+            if func_name in FLATTENED_FUNCTION_MAPPING:
+                internal_method_name = FLATTENED_FUNCTION_MAPPING[func_name]
+            else:
+                raise NotImplementedError(
+                    f"Invalid `func` argument for the aggregate function.\n"
+                    f"The NumPy function {func_name!r} is not supported.\n"
+                    f"Supported aggregate functions are: {sorted(FLATTENED_FUNCTION_MAPPING.keys())}"
+                )  # pragma: no cover
+            lambda_source = self._generate_lambda_source(internal_method_name)
+            final_lambda = eval(lambda_source)
+            return final_lambda
+
+        else:
+            func_name = getattr(func, "__name__", "").lower()
+            if func_name in FLATTENED_FUNCTION_MAPPING and func_name != "<lambda>":
+                internal_method_name = FLATTENED_FUNCTION_MAPPING[func_name]
+                lambda_source = self._generate_lambda_source(internal_method_name)
+                final_lambda = eval(lambda_source)
+                return final_lambda
+            else:
+                def validation_wrapper(x: PyLegendPrimitiveCollection) -> PyLegendPrimitive:
+                    result = func(x)
+                    if not isinstance(result, PyLegendPrimitive):
+                        raise TypeError(
+                            f"Custom aggregation function must return a PyLegendPrimitive (Expression).\n"
+                            f"But got type: {type(result).__name__}\n"
+                            f"Value: {result!r}"
+                        )  # pragma: no cover
+                    return result
+
+                return validation_wrapper
+
+    def _generate_lambda_source(self, internal_method_name: str) -> str:
+        return f"lambda x: x.{internal_method_name}()"