Source code for pylegend.core.language.shared.primitives.strictdate

# Copyright 2023 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
from pylegend._typing import (
    PyLegendSequence,
    PyLegendDict,
    PyLegendUnion,
)
from pylegend.core.language.shared.primitives.date import PyLegendDate
from pylegend.core.language.shared.expression import (
    PyLegendExpressionStrictDateReturn,
)
from pylegend.core.language.shared.literal_expressions import (
    PyLegendStrictDateLiteralExpression,
    PyLegendIntegerLiteralExpression,
    PyLegendStringLiteralExpression
)
from pylegend.core.sql.metamodel import (
    Expression,
    QuerySpecification
)
from pylegend.core.tds.pandas_api.frames.helpers.series_helper import grammar_method
from pylegend.core.tds.tds_frame import FrameToSqlConfig
from pylegend.core.language.shared.operations.date_operation_expressions import PyLegendDateTimeBucketExpression
from pylegend.core.language.shared.primitives.integer import PyLegendInteger

__all__: PyLegendSequence[str] = [
    "PyLegendStrictDate"
]

"""
Strict-date expression type in the PyLegend expression language.

``PyLegendStrictDate`` represents a date-only value (no time component)
within a PyLegend query.  It inherits every calendar-extraction,
comparison, shifting, and differencing method from
:class:`~pylegend.core.language.shared.primitives.date.PyLegendDate` and
adds ``time_bucket`` for grouping dates into fixed-width buckets.

Instances are produced when a column whose Legend type is ``StrictDate``
is accessed on a TDS frame, or by calling :meth:`date_part` on a
``PyLegendDate`` / ``PyLegendDateTime`` expression.
"""


class PyLegendStrictDate(PyLegendDate):
    __value: PyLegendExpressionStrictDateReturn

    def __init__(
            self,
            value: PyLegendExpressionStrictDateReturn
    ) -> None:
        super().__init__(value)
        self.__value = value

    def to_sql_expression(
            self,
            frame_name_to_base_query_map: PyLegendDict[str, QuerySpecification],
            config: FrameToSqlConfig
    ) -> Expression:
        return self.__value.to_sql_expression(frame_name_to_base_query_map, config)

    def value(self) -> PyLegendExpressionStrictDateReturn:
        return self.__value



    @grammar_method
    def time_bucket(
            self,
            quantity: PyLegendUnion[int, "PyLegendInteger"],
            duration_unit: str) -> "PyLegendDate":
        """
        Group the date into fixed-width buckets.

        Returns the start of the bucket that each date falls into.
        Useful for time-series aggregation at a coarser granularity.

        Parameters
        ----------
        quantity : int or PyLegendInteger
            The width of each bucket expressed in *duration_unit*.
        duration_unit : str
            One of ``'YEARS'``, ``'MONTHS'``, ``'WEEKS'``, ``'DAYS'``
            (case-insensitive).

        Returns
        -------
        PyLegendDate
            The bucket-start date.

        Raises
        ------
        TypeError
            If *quantity* is not an ``int`` or ``PyLegendInteger``.
        ValueError
            If *duration_unit* is not one of the supported units.

        Examples
        --------
        .. ipython:: python

            import pylegend
            frame = pylegend.samples.pandas_api.northwind_orders_frame()

            frame["bucket"] = frame["Shipped Date"].date_part().time_bucket(3, "MONTHS")
            frame[["Shipped Date", "bucket"]].head(3).to_pandas()

        """
        self.validate_param_to_be_int_or_int_expr(quantity, "time bucket quantity parameter")
        quantity_op = PyLegendIntegerLiteralExpression(quantity) if isinstance(quantity, int) else quantity.value()
        self.validate_strict_date_duration_unit_param(duration_unit)
        duration_unit_op = PyLegendStringLiteralExpression(duration_unit.upper())
        return PyLegendDate(PyLegendDateTimeBucketExpression([
            self.__value,
            quantity_op,
            duration_unit_op,
            PyLegendStringLiteralExpression("STRICTDATE")]))


    @staticmethod
    def __convert_to_strictdate_expr(
            val: PyLegendUnion[date, "PyLegendStrictDate"]
    ) -> PyLegendExpressionStrictDateReturn:
        if isinstance(val, date):
            return PyLegendStrictDateLiteralExpression(val)
        return val.__value

    @staticmethod
    def validate_param_to_be_strictdate(
            param: PyLegendUnion[date, "PyLegendStrictDate"],
            desc: str
    ) -> None:
        if not isinstance(param, (date, PyLegendStrictDate)):
            raise TypeError(desc + " should be a datetime.date or a StrictDate expression (PyLegendStrictDate)."
                                   " Got value " + str(param) + " of type: " + str(type(param)))

    @staticmethod
    def validate_strict_date_duration_unit_param(duration_unit: str) -> None:
        if duration_unit.lower() not in ('years', 'months', 'weeks', 'days'):
            raise ValueError(
                f"Unknown duration unit - {duration_unit}. Supported values are - YEARS, MONTHS, WEEKS, DAYS"
            )