api_24sea.datasignals.schemas
=============================

.. py:module:: api_24sea.datasignals.schemas

.. autoapi-nested-parse::

   Data signals types.



Classes
-------

.. autoapisummary::

   api_24sea.datasignals.schemas.BaseDataSignalSchema
   api_24sea.datasignals.schemas.GetOldestTimestampSchema
   api_24sea.datasignals.schemas.GetData
   api_24sea.datasignals.schemas.GetStats
   api_24sea.datasignals.schemas.GetAvailability


Functions
---------

.. autoapisummary::

   api_24sea.datasignals.schemas.build_query_str
   api_24sea.datasignals.schemas.get_selected_metrics
   api_24sea.datasignals.schemas.get_selected_locations


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

.. py:class:: BaseDataSignalSchema(**data)



   Shared base schema for data signals requests.
   Includes common fields and validation logic for timestamp, sites, locations,
   metrics, and headers. Inherit from this class to create specific schemas for
   data retrieval and stats retrieval.


   .. py:method:: validate_timestamp(v: Union[datetime.datetime, str]) -> str

      Validate and format timestamp input.



   .. py:method:: validate_sites_locations(v)

      Validate and format sites and locations input.



   .. py:method:: validate_metrics(v)

      Validate and format metrics input.



   .. py:method:: validate_headers(v)

      Validate and format headers input.



   .. py:method:: validate_method(v: str) -> str

      Validate and normalize request method input.



   .. py:property:: query_str
      :type: str


      Build a query string based on self.



   .. py:method:: get_selected_metrics(df: Optional[pandas.DataFrame], log: bool = True) -> pandas.DataFrame

      Calculate the selected metrics DataFrame based on a df (metrics
      overview) and the query object.



   .. py:method:: group_metrics(df: Optional[pandas.DataFrame]) -> pandas.core.groupby.DataFrameGroupBy

      Group metrics by site and location.



   .. py:method:: group_metrics_by_site(df: Optional[pandas.DataFrame]) -> pandas.core.groupby.DataFrameGroupBy

      Group metrics by site while keeping per-site locations.



.. py:class:: GetOldestTimestampSchema(/, **data: Any)



   Schema for oldest timestamp requests.


   .. py:method:: validate_locations(v) -> Optional[str]

      Normalize locations to a comma-separated lower-case string.



   .. py:method:: validate_site(v)

      Normalize site to a lower-case string.



   .. py:method:: validate_method(v: str) -> str

      Validate and normalize request method input.



   .. py:method:: get_selected_locations(df: Optional[pandas.DataFrame]) -> pandas.DataFrame

      Get the selected locations DataFrame based on the query object.



.. py:class:: GetData(**data)



   A pydantic schema for the data signals (data retrieval).
   Includes all common fields plus 'outer_join_on_timestamp' for join behavior.


.. py:class:: GetStats(**data)



   A pydantic schema for the data signals (stats retrieval).
   Inherits all common fields from the base schema.


.. py:class:: GetAvailability(**data)



   A pydantic schema for the data signals (availability retrieval).
   Inherits all common fields from the base schema.


.. py:function:: build_query_str(query: BaseDataSignalSchema) -> str

   Build a query string based on the provided BaseDataSignalSchema instance.

   Parameters
   ----------
   query : BaseDataSignalSchema
       The query object containing the filtering criteria.

   Returns
   -------
   str
       The constructed query string.


.. py:function:: get_selected_metrics(query: BaseDataSignalSchema, metrics_overview: pandas.DataFrame, log: bool = True) -> pandas.DataFrame

   Calculate the selected metrics DataFrame based on the metrics_overview,
   and the query object.

   Parameters
   ----------
   metrics_overview : pd.DataFrame
       The metrics overview DataFrame.
   query_str : str
       The query string to filter metrics.
   log : bool, optional
       Whether to log the selected metrics, by default True.

   Returns
   -------
   pd.DataFrame
       The filtered and sorted metrics DataFrame.


.. py:function:: get_selected_locations(query: GetOldestTimestampSchema, metrics_overview: pandas.DataFrame, log: bool = True) -> pandas.DataFrame

   Calculate the selected locations DataFrame based on the metrics_overview,
   and the query object.

   Parameters
   ----------
   query: GetOldestTimestampSchema
       Timestamp schema query class instance.
   metrics_overview : pd.DataFrame
       The metrics overview DataFrame.
   log : bool, optional
       Whether to log the selected locations, by default True.

   Returns
   -------
   pd.DataFrame
       The filtered and sorted locations DataFrame.