pylegend 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

pylegend/core/tds/legendql_api/frames/functions/legendql_api_extend_function.py

@@ -0,0 +1,256 @@
+# 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 date, datetime
+from pylegend._typing import (
+    PyLegendList,
+    PyLegendSequence,
+    PyLegendCallable,
+    PyLegendUnion,
+    PyLegendTuple,
+)
+from pylegend.core.language.legendql_api.legendql_api_tds_row import LegendQLApiTdsRow
+from pylegend.core.sql.metamodel_extension import WindowExpression
+from pylegend.core.tds.legendql_api.frames.legendql_api_applied_function_tds_frame import LegendQLApiAppliedFunction
+from pylegend.core.tds.sql_query_helpers import copy_query, create_sub_query
+from pylegend.core.sql.metamodel import (
+    QuerySpecification,
+    SingleColumn,
+    Window,
+)
+from pylegend.core.tds.tds_column import TdsColumn
+from pylegend.core.tds.tds_frame import FrameToSqlConfig
+from pylegend.core.tds.tds_frame import FrameToPureConfig
+from pylegend.core.tds.legendql_api.frames.legendql_api_base_tds_frame import LegendQLApiBaseTdsFrame
+from pylegend.core.language import (
+    PyLegendPrimitive,
+    PyLegendPrimitiveOrPythonPrimitive,
+    convert_literal_to_literal_expression, PyLegendPrimitiveCollection, create_primitive_collection,
+)
+from pylegend.core.language.shared.helpers import generate_pure_lambda, escape_column_name
+from pylegend.core.tds.abstract.function_helpers import tds_column_for_primitive
+
+__all__: PyLegendSequence[str] = [
+    "LegendQLApiExtendFunction"
+]
+
+
+class LegendQLApiExtendFunction(LegendQLApiAppliedFunction):
+    __base_frame: LegendQLApiBaseTdsFrame
+    __new_column_expressions: PyLegendList[
+        PyLegendUnion[
+            PyLegendTuple[str, PyLegendPrimitiveOrPythonPrimitive],
+            PyLegendTuple[str, PyLegendPrimitiveOrPythonPrimitive, PyLegendPrimitive]
+        ]
+    ]
+
+    @classmethod
+    def name(cls) -> str:
+        return "extend"
+
+    def __init__(
+            self,
+            base_frame: LegendQLApiBaseTdsFrame,
+            extend_columns: PyLegendUnion[
+                PyLegendTuple[
+                    str,
+                    PyLegendCallable[[LegendQLApiTdsRow], PyLegendPrimitiveOrPythonPrimitive]
+                ],
+                PyLegendTuple[
+                    str,
+                    PyLegendCallable[[LegendQLApiTdsRow], PyLegendPrimitiveOrPythonPrimitive],
+                    PyLegendCallable[[PyLegendPrimitiveCollection], PyLegendPrimitive]
+                ],
+                PyLegendList[
+                    PyLegendUnion[
+                        PyLegendTuple[
+                            str,
+                            PyLegendCallable[[LegendQLApiTdsRow], PyLegendPrimitiveOrPythonPrimitive]
+                        ],
+                        PyLegendTuple[
+                            str,
+                            PyLegendCallable[[LegendQLApiTdsRow], PyLegendPrimitiveOrPythonPrimitive],
+                            PyLegendCallable[[PyLegendPrimitiveCollection], PyLegendPrimitive]
+                        ]
+                    ]
+                ]
+            ]
+    ) -> None:
+        self.__base_frame = base_frame
+        col_expressions: PyLegendList[
+            PyLegendUnion[
+                PyLegendTuple[str, PyLegendPrimitiveOrPythonPrimitive],
+                PyLegendTuple[str, PyLegendPrimitiveOrPythonPrimitive, PyLegendPrimitive]
+            ]
+        ] = []
+        tds_row = LegendQLApiTdsRow.from_tds_frame("r", self.__base_frame)
+        for (i, extend_column) in enumerate(extend_columns if isinstance(extend_columns, list) else [extend_columns]):
+            if isinstance(extend_column, tuple) and len(extend_column) in [2, 3]:
+                if not isinstance(extend_column[0], str):
+                    raise TypeError(
+                        "'extend' function extend_columns argument incompatible. "
+                        "First element in an extend tuple should be a string (new column name). "
+                        "E.g - ('new col', lambda r: r.c1 + 1). "
+                        f"Element at index {i} (0-indexed) is incompatible"
+                    )
+                if not isinstance(extend_column[1], type(lambda x: 0)) or (extend_column[1].__code__.co_argcount != 1):
+                    raise TypeError(
+                        "'extend' function extend_columns argument incompatible. "
+                        "Second element in an extend tuple should be a lambda function which takes one argument "
+                        "(LegendQLApiTdsRow) E.g - ('new col', lambda r: r.c1 + 1)."
+                        f"Element at index {i} (0-indexed) is incompatible"
+                    )
+                try:
+                    result = extend_column[1](tds_row)
+                except Exception as e:
+                    raise RuntimeError(
+                        "'extend' function extend_columns argument incompatible. "
+                        f"Error occurred while evaluating extend lambda at index {i} (0-indexed). Message: " + str(e)
+                    ) from e
+
+                if not isinstance(result, (int, float, bool, str, date, datetime, PyLegendPrimitive)):
+                    raise TypeError(
+                        "'extend' function extend_columns argument incompatible. "
+                        f"Extend lambda at index {i} (0-indexed) returns non-primitive - {str(type(result))}"
+                    )
+                if len(extend_column) == 2:
+                    col_expressions.append((extend_column[0], result))
+                else:
+                    if (not isinstance(extend_column[2], type(lambda x: 0)) or
+                            (extend_column[2].__code__.co_argcount != 1)):
+                        raise TypeError(
+                            "'extend' function extend_columns argument incompatible. "
+                            "Third element in an extend tuple should be a lambda function which takes one argument "
+                            "(collection) E.g - ('new col', lambda r: r.c1, lambda c: c.sum()). "
+                            f"Element at index {i} (0-indexed) is incompatible"
+                        )
+                    collection = create_primitive_collection(result)
+                    try:
+                        agg_result = extend_column[2](collection)
+                    except Exception as e:
+                        raise RuntimeError(
+                            "'extend' function extend_columns argument incompatible. "
+                            f"Error occurred while evaluating aggregation lambda at index {i} (0-indexed). "
+                            "Message: " + str(e)
+                        ) from e
+                    if not isinstance(agg_result, PyLegendPrimitive):
+                        raise TypeError(
+                            "'extend' function extend_columns argument incompatible. "
+                            f"Aggregation lambda at index {i} (0-indexed) "
+                            f"returns non-primitive - {str(type(agg_result))}"
+                        )
+                    col_expressions.append((extend_column[0], result, agg_result))
+            else:
+                raise TypeError(
+                    "'extend' function extend_columns argument should be a list of tuples with two/three elements - "
+                    "first element being a string (new column name), second element being a lambda "
+                    "function which takes one argument (LegendQLApiTdsRow) and third element being an optional "
+                    "aggregation lambda function which takes one argument "
+                    "E.g - [('new col1', lambda r: r.c1 + 1), ('new col2', lambda r: r.c2, lambda c: c.sum())]. "
+                    f"Element at index {i} (0-indexed) is incompatible"
+                )
+        self.__new_column_expressions = col_expressions
+
+    def to_sql(self, config: FrameToSqlConfig) -> QuerySpecification:
+        base_query = self.__base_frame.to_sql_query_object(config)
+        should_create_sub_query = len(base_query.groupBy) > 0
+        db_extension = config.sql_to_string_generator().get_db_extension()
+
+        new_query = (
+            create_sub_query(base_query, config, "root") if should_create_sub_query else
+            copy_query(base_query)
+        )
+
+        for c in self.__new_column_expressions:
+            if len(c) == 2:
+                if isinstance(c[1], (bool, int, float, str, date, datetime)):
+                    col_sql_expr = convert_literal_to_literal_expression(c[1]).to_sql_expression(
+                        {"r": new_query},
+                        config
+                    )
+                else:
+                    col_sql_expr = c[1].to_sql_expression({"r": new_query}, config)
+
+                new_query.select.selectItems.append(
+                    SingleColumn(alias=db_extension.quote_identifier(c[0]), expression=col_sql_expr)
+                )
+            else:
+                agg_sql_expr = c[2].to_sql_expression({"r": new_query}, config)
+                window_expr = WindowExpression(
+                    nested=agg_sql_expr,
+                    window=Window(windowRef=None, partitions=[], orderBy=[], windowFrame=None)
+                )
+                new_query.select.selectItems.append(
+                    SingleColumn(alias=db_extension.quote_identifier(c[0]), expression=window_expr)
+                )
+        return new_query
+
+    def to_pure(self, config: FrameToPureConfig) -> str:
+        def render_single_column_expression(
+                c: PyLegendUnion[
+                    PyLegendTuple[str, PyLegendPrimitiveOrPythonPrimitive],
+                    PyLegendTuple[str, PyLegendPrimitiveOrPythonPrimitive, PyLegendPrimitive]
+                ]
+        ) -> str:
+            escaped_col_name = escape_column_name(c[0])
+            expr_str = (c[1].to_pure_expression(config) if isinstance(c[1], PyLegendPrimitive) else
+                        convert_literal_to_literal_expression(c[1]).to_pure_expression(config))
+            if len(c) == 2:
+                return f"{escaped_col_name}:{generate_pure_lambda('r', expr_str)}"
+            else:
+                agg_expr_str = c[2].to_pure_expression(config).replace(expr_str, "$c")
+                return (f"{escaped_col_name}:"
+                        f"{generate_pure_lambda('r', expr_str)}:"
+                        f"{generate_pure_lambda('c', agg_expr_str)}")
+
+        if all([len(t) == 2 for t in self.__new_column_expressions]) or all(
+                [len(t) == 3 for t in self.__new_column_expressions]):
+            if len(self.__new_column_expressions) == 1:
+                extend_str = f"->extend(~{render_single_column_expression(self.__new_column_expressions[0])})"
+            else:
+                extend_str = (f"->extend(~[{config.separator(2)}" +
+                              ("," + config.separator(2, True)).join(
+                                  [render_single_column_expression(x) for x in self.__new_column_expressions]
+                              ) +
+                              f"{config.separator(1)}])")
+            return f"{self.__base_frame.to_pure(config)}{config.separator(1)}" + extend_str
+        else:
+            extend_str = self.__base_frame.to_pure(config)
+            for c in self.__new_column_expressions:
+                extend_str += f"{config.separator(1)}->extend(~{render_single_column_expression(c)})"
+            return extend_str
+
+    def base_frame(self) -> LegendQLApiBaseTdsFrame:
+        return self.__base_frame
+
+    def tds_frame_parameters(self) -> PyLegendList["LegendQLApiBaseTdsFrame"]:
+        return []
+
+    def calculate_columns(self) -> PyLegendSequence["TdsColumn"]:
+        new_columns = [c.copy() for c in self.__base_frame.columns()]
+        for c in self.__new_column_expressions:
+            new_columns.append(tds_column_for_primitive(c[0], c[1] if len(c) == 2 else c[2]))
+        return new_columns
+
+    def validate(self) -> bool:
+        col_names = [x[0] for x in self.__new_column_expressions]
+
+        if len(col_names) != len(set(col_names)):
+            raise ValueError(f"Extend column names list has duplicates: {col_names}")
+
+        for c in col_names:
+            if c in [c.get_name() for c in self.__base_frame.columns()]:
+                raise ValueError(f"Extend column name - '{c}' already exists in base frame")
+
+        return True

pylegend/core/tds/legendql_api/frames/functions/legendql_api_filter_function.py

@@ -0,0 +1,121 @@
+# 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 pylegend._typing import (
+    PyLegendList,
+    PyLegendSequence,
+    PyLegendCallable,
+    PyLegendUnion,
+)
+from pylegend.core.language.legendql_api.legendql_api_tds_row import LegendQLApiTdsRow
+from pylegend.core.tds.legendql_api.frames.legendql_api_applied_function_tds_frame import LegendQLApiAppliedFunction
+from pylegend.core.tds.sql_query_helpers import copy_query, create_sub_query
+from pylegend.core.sql.metamodel import (
+    QuerySpecification,
+    LogicalBinaryType,
+    LogicalBinaryExpression,
+)
+from pylegend.core.tds.tds_column import TdsColumn
+from pylegend.core.tds.tds_frame import FrameToSqlConfig
+from pylegend.core.tds.tds_frame import FrameToPureConfig
+from pylegend.core.tds.legendql_api.frames.legendql_api_base_tds_frame import LegendQLApiBaseTdsFrame
+from pylegend.core.language import (
+    PyLegendBoolean,
+    PyLegendBooleanLiteralExpression,
+    PyLegendPrimitive,
+    convert_literal_to_literal_expression,
+)
+from pylegend.core.language.shared.helpers import generate_pure_lambda
+
+__all__: PyLegendSequence[str] = [
+    "LegendQLApiFilterFunction"
+]
+
+
+class LegendQLApiFilterFunction(LegendQLApiAppliedFunction):
+    __base_frame: LegendQLApiBaseTdsFrame
+    __filter_function: PyLegendCallable[[LegendQLApiTdsRow], PyLegendUnion[bool, PyLegendBoolean]]
+
+    @classmethod
+    def name(cls) -> str:
+        return "filter"
+
+    def __init__(
+            self,
+            base_frame: LegendQLApiBaseTdsFrame,
+            filter_function: PyLegendCallable[[LegendQLApiTdsRow], PyLegendUnion[bool, PyLegendBoolean]]
+    ) -> None:
+        self.__base_frame = base_frame
+        self.__filter_function = filter_function
+
+    def to_sql(self, config: FrameToSqlConfig) -> QuerySpecification:
+        base_query = self.__base_frame.to_sql_query_object(config)
+        should_create_sub_query = (len(base_query.groupBy) > 0) or \
+                                  (base_query.offset is not None) or (base_query.limit is not None)
+        new_query = (
+            create_sub_query(base_query, config, "root") if should_create_sub_query else
+            copy_query(base_query)
+        )
+
+        tds_row = LegendQLApiTdsRow.from_tds_frame("frame", self.__base_frame)
+        filter_expr = self.__filter_function(tds_row)
+        if isinstance(filter_expr, bool):
+            filter_expr = PyLegendBoolean(PyLegendBooleanLiteralExpression(filter_expr))
+        filter_sql_expr = filter_expr.to_sql_expression(
+            {"frame": new_query},
+            config
+        )
+
+        if new_query.where is None:
+            new_query.where = filter_sql_expr
+        else:
+            new_query.where = LogicalBinaryExpression(LogicalBinaryType.AND, new_query.where, filter_sql_expr)
+
+        return new_query
+
+    def to_pure(self, config: FrameToPureConfig) -> str:
+        tds_row = LegendQLApiTdsRow.from_tds_frame("r", self.__base_frame)
+        filter_expr = self.__filter_function(tds_row)
+        filter_expr_string = (filter_expr.to_pure_expression(config) if isinstance(filter_expr, PyLegendPrimitive) else
+                              convert_literal_to_literal_expression(filter_expr).to_pure_expression(config))
+        return (f"{self.__base_frame.to_pure(config)}{config.separator(1)}" +
+                f"->filter({generate_pure_lambda('r', filter_expr_string)})")
+
+    def base_frame(self) -> LegendQLApiBaseTdsFrame:
+        return self.__base_frame
+
+    def tds_frame_parameters(self) -> PyLegendList["LegendQLApiBaseTdsFrame"]:
+        return []
+
+    def calculate_columns(self) -> PyLegendSequence["TdsColumn"]:
+        return [c.copy() for c in self.__base_frame.columns()]
+
+    def validate(self) -> bool:
+        tds_row = LegendQLApiTdsRow.from_tds_frame("frame", self.__base_frame)
+
+        copy = self.__filter_function  # For MyPy
+        if not isinstance(copy, type(lambda x: 0)) or (copy.__code__.co_argcount != 1):
+            raise TypeError("Filter function should be a lambda which takes one argument (TDSRow)")
+
+        try:
+            result = self.__filter_function(tds_row)
+        except Exception as e:
+            raise RuntimeError(
+                "Filter function incompatible. Error occurred while evaluating. Message: " + str(e)
+            ) from e
+
+        if not isinstance(result, (bool, PyLegendBoolean)):
+            raise RuntimeError("Filter function incompatible. Returns non boolean - " + str(type(result)))
+
+        return True

pylegend/core/tds/legendql_api/frames/functions/legendql_api_function_helpers.py

@@ -0,0 +1,137 @@
+# 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 pylegend._typing import (
+    PyLegendList,
+    PyLegendSequence,
+    PyLegendCallable,
+    PyLegendUnion,
+)
+from pylegend.core.language import PyLegendColumnExpression
+from pylegend.core.language.legendql_api.legendql_api_custom_expressions import (
+    LegendQLApiPrimitive,
+    LegendQLApiSortInfo,
+    LegendQLApiSortDirection,
+)
+from pylegend.core.language.legendql_api.legendql_api_tds_row import LegendQLApiTdsRow
+from pylegend.core.tds.legendql_api.frames.legendql_api_base_tds_frame import LegendQLApiBaseTdsFrame
+
+
+__all__: PyLegendSequence[str] = [
+    "infer_columns_from_frame",
+    "infer_sorts_from_frame",
+]
+
+
+def infer_columns_from_frame(
+    base_frame: LegendQLApiBaseTdsFrame,
+    columns: PyLegendUnion[
+        str,
+        PyLegendList[str],
+        PyLegendCallable[
+            [LegendQLApiTdsRow],
+            PyLegendUnion[LegendQLApiPrimitive, PyLegendList[LegendQLApiPrimitive]]
+        ]
+    ],
+    context: str
+) -> PyLegendList[str]:
+    if isinstance(columns, str):
+        return [columns]
+    if isinstance(columns, list) and all([isinstance(c, str) for c in columns]):
+        return columns
+
+    if isinstance(columns, type(lambda x: 0)) and (columns.__code__.co_argcount == 1):
+        tds_row = LegendQLApiTdsRow.from_tds_frame("frame", base_frame)
+        try:
+            result = columns(tds_row)
+        except Exception as e:
+            raise RuntimeError(
+                f"{context} argument lambda incompatible. Error occurred while evaluating. Message: " + str(e)
+            ) from e
+
+        list_result = result if isinstance(result, list) else [result]
+
+        columns_list = []
+        for (i, r) in enumerate(list_result):
+            if isinstance(r, LegendQLApiPrimitive) and isinstance(r.value(), PyLegendColumnExpression):
+                col_expr: PyLegendColumnExpression = r.value()
+                columns_list.append(col_expr.get_column())
+            else:
+                raise TypeError(
+                    f"{context} argument lambda incompatible. Columns can be simple column expressions "
+                    f"(E.g - lambda r: [r.column1, r.column2, r['column with spaces']). "
+                    f"Element at index {i} (0-indexed) is incompatible"
+                )
+        return columns_list
+
+    raise TypeError(f"{context} argument can either be a list of strings (column names) or "
+                    f"a lambda function which takes one argument (LegendQLApiTdsRow)")
+
+
+def infer_sorts_from_frame(
+    base_frame: LegendQLApiBaseTdsFrame,
+    sort_infos: PyLegendUnion[
+        str,
+        PyLegendList[str],
+        PyLegendCallable[
+            [LegendQLApiTdsRow],
+            PyLegendUnion[
+                LegendQLApiPrimitive,
+                LegendQLApiSortInfo,
+                PyLegendList[PyLegendUnion[LegendQLApiPrimitive, LegendQLApiSortInfo]],
+            ]
+        ]
+    ],
+    context: str
+) -> PyLegendList[LegendQLApiSortInfo]:
+    tds_row = LegendQLApiTdsRow.from_tds_frame("frame", base_frame)
+    sort_info_list = []
+
+    if isinstance(sort_infos, str):
+        col_expr1: PyLegendColumnExpression = tds_row[sort_infos].value()  # type: ignore
+        sort_info_list.append(LegendQLApiSortInfo(col_expr1, LegendQLApiSortDirection.ASC))
+
+    elif isinstance(sort_infos, list) and all([isinstance(s, str) for s in sort_infos]):
+        for s in sort_infos:
+            col_expr2: PyLegendColumnExpression = tds_row[s].value()  # type: ignore
+            sort_info_list.append(LegendQLApiSortInfo(col_expr2, LegendQLApiSortDirection.ASC))
+
+    elif isinstance(sort_infos, type(lambda x: 0)) and (sort_infos.__code__.co_argcount == 1):
+        try:
+            result = sort_infos(tds_row)
+        except Exception as e:
+            raise RuntimeError(
+                f"{context} argument lambda incompatible. "
+                "Error occurred while evaluating. Message: " + str(e)
+            ) from e
+
+        list_result = result if isinstance(result, list) else [result]
+        for (i, r) in enumerate(list_result):
+            if isinstance(r, LegendQLApiPrimitive) and isinstance(r.value(), PyLegendColumnExpression):
+                col_expr3: PyLegendColumnExpression = r.value()
+                sort_info_list.append(LegendQLApiSortInfo(col_expr3, LegendQLApiSortDirection.ASC))
+            elif isinstance(r, LegendQLApiSortInfo):
+                sort_info_list.append(r)
+            else:
+                raise TypeError(
+                    f"{context} argument lambda incompatible. Columns can be simple column "
+                    f"expressions or sort infos. "
+                    f"(E.g - lambda r: [r.column1, r['column with spaces'].descending(), r.column3.ascending()). "
+                    f"Element at index {i} (0-indexed) is incompatible"
+                )
+    else:
+        raise TypeError(f"{context} argument can either be a list of strings (column names) or "
+                        "a lambda function which takes one argument (LegendQLApiTdsRow)")
+
+    return sort_info_list