Decorators
===============================

.. py:module:: gridstatus.decorators


Module Contents
---------------

Classes Summary
~~~~~~~~~~~~~~~

.. autoapisummary::

   gridstatus.decorators.DayBeginOffset
   gridstatus.decorators.FiveMinOffset
   gridstatus.decorators.HourBeginOffset
   gridstatus.decorators.MonthBeginOffset
   gridstatus.decorators.support_date_range
   gridstatus.decorators.YearBeginOffset




Functions
~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   gridstatus.decorators.date_range_maker
   gridstatus.decorators.pjm_update_dates



Attributes Summary
~~~~~~~~~~~~~~~~~~~

.. autoapisummary::

   gridstatus.decorators.P
   gridstatus.decorators.T


Contents
~~~~~~~~~~~~~~~~~~~
.. py:function:: date_range_maker(start: pandas.Timestamp, end: pandas.Timestamp, freq: str | pandas.DateOffset, inclusive: str = 'neither') -> List[pandas.Timestamp]

   Generate a date range based on start and end dates and a frequency.


.. py:class:: DayBeginOffset




   **Methods**

   .. autoapisummary::
      :nosignatures:

      gridstatus.decorators.DayBeginOffset.__ladd__
      gridstatus.decorators.DayBeginOffset.__radd__

   .. py:method:: __ladd__(other: pandas.Timestamp) -> pandas.Timestamp

   .. py:method:: __radd__(other: pandas.Timestamp) -> pandas.Timestamp


.. py:class:: FiveMinOffset




   **Methods**

   .. autoapisummary::
      :nosignatures:

      gridstatus.decorators.FiveMinOffset.__ladd__
      gridstatus.decorators.FiveMinOffset.__radd__

   .. py:method:: __ladd__(other: pandas.Timestamp) -> pandas.Timestamp

   .. py:method:: __radd__(other: pandas.Timestamp) -> pandas.Timestamp


.. py:class:: HourBeginOffset




   **Methods**

   .. autoapisummary::
      :nosignatures:

      gridstatus.decorators.HourBeginOffset.__ladd__
      gridstatus.decorators.HourBeginOffset.__radd__

   .. py:method:: __ladd__(other: pandas.Timestamp) -> pandas.Timestamp

   .. py:method:: __radd__(other: pandas.Timestamp) -> pandas.Timestamp


.. py:class:: MonthBeginOffset




   **Methods**

   .. autoapisummary::
      :nosignatures:

      gridstatus.decorators.MonthBeginOffset.__ladd__
      gridstatus.decorators.MonthBeginOffset.__radd__

   .. py:method:: __ladd__(other: pandas.Timestamp) -> pandas.Timestamp

   .. py:method:: __radd__(other: pandas.Timestamp) -> pandas.Timestamp


.. py:data:: P

.. py:function:: pjm_update_dates(dates: List[pandas.Timestamp | None], args_dict: Dict[str, Any]) -> List[pandas.Timestamp | None]

   PJM has a weird API. This method updates the date range list to account
   for the following restrictions:

    - date ranges cannot span year boundaries
    - date ranges cannot span archive / standard boundaries
    - date range is inclusive of start and end dates


.. py:class:: support_date_range(frequency: str | Callable[[Dict[str, Any]], str] | None, update_dates: Callable[[List[pandas.Timestamp | None], Dict[str, Any]], List[pandas.Timestamp | None]] | None = None, return_raw: bool = False)

   Decorator that enables automatic date range splitting and iteration.

   This decorator automatically splits large date ranges into smaller chunks based on
   the specified frequency, calls the decorated function for each chunk, and combines
   the results.

   :param frequency: Maximum frequency for splitting date ranges. Common values are
                     "DAY_START" (split by day), "HOUR_START" (split by hour),
                     "5_MIN" (split by 5 minute intervals), "MONTH_START" (split by month),
                     "YEAR_START" (split by year), or None (no splitting, pass date range as-is).
   :param update_dates: Optional callback to customize date range splitting logic.
   :param return_raw: If True, return list of results instead of concatenating.

   The decorated functions also accept these keyword arguments:

       - **error** (str): Error handling mode. Default is "ignore" which prints
         errors and continues. Use "raise" to raise errors immediately.
       - **start**: Alternative parameter name for 'date' (automatically converted).

   Example::

       @support_date_range(frequency="DAY_START")
       def get_data(self, date, end=None, verbose=False):
           # Function is called once per day in the range
           return fetch_data_for_date(date)

       # Usage:
       df = iso.get_data(date="2024-01-01", end="2024-01-10", error="raise")
       # Calls get_data for each day and concatenates results



   **Attributes**

   .. list-table::
      :widths: 15 85
      :header-rows: 0

      * - **frequency**
        - None
      * - **return_raw**
        - False
      * - **update_dates**
        - None


   **Methods**

   .. autoapisummary::
      :nosignatures:

      gridstatus.decorators.support_date_range.__call__

   .. py:method:: __call__(f: Callable[P, T]) -> Callable[P, T]


.. py:data:: T

.. py:class:: YearBeginOffset




   **Methods**

   .. autoapisummary::
      :nosignatures:

      gridstatus.decorators.YearBeginOffset.__ladd__
      gridstatus.decorators.YearBeginOffset.__radd__

   .. py:method:: __ladd__(other: pandas.Timestamp) -> pandas.Timestamp

   .. py:method:: __radd__(other: pandas.Timestamp) -> pandas.Timestamp