tukan-python 0.1.0__py3-none-any.whl

tukan_python/query.py

@@ -0,0 +1,515 @@
+from collections import defaultdict
+from typing import Literal, Optional
+
+import pandas as pd
+
+from tukan_python.tukan import Tukan
+
+
+class Query:
+    """
+    Helper class for building and executing queries against the TukanMX API.
+
+    This class allows flexible construction of query payloads, including filters,
+    groupings, and aggregations. It supports saving, executing, and reconstructing
+    queries from names, IDs, or payloads.
+
+    Attributes:
+        Tukan (Tukan): Instance of the Tukan API client.
+        table_name (str): Name of the data table to query.
+        where (list[dict]): List of filter conditions.
+        group_by (list[dict]): List of group-by conditions.
+        aggregate (list[dict]): List of aggregate operations.
+        language (str): Language for the query results.
+    """
+
+    def __init__(
+        self,
+        table_name: str,
+        token: Optional[str] = None,
+        where: Optional[list[dict]] = None,
+        group_by: Optional[list[dict]] = None,
+        aggregate: Optional[list[dict]] = None,
+        language: str = "en",
+    ):
+        """
+        Initialize a new Query instance.
+
+        Args:
+            table_name (str): Name of the data table to query.
+            token (Optional[str]): API token for authentication.
+            where (Optional[list[dict]]): List of filter conditions.
+            group_by (Optional[list[dict]]): List of group-by conditions.
+            aggregate (Optional[list[dict]]): List of aggregate operations.
+            language (str): Language for the query results.
+        """
+        self.table_name = table_name
+        self.Tukan = Tukan(token)
+        self.__set_metadata__()
+        self.where = where if where is not None else []
+        self.group_by = group_by if group_by is not None else []
+        self.aggregate = aggregate if aggregate is not None else []
+        self.language = language
+
+    def __set_metadata__(self) -> dict:
+        """
+        Get the metadata for the table.
+
+        Returns:
+            dict: Table metadata.
+        """
+        meta = self.Tukan.get_table_metadata(self.table_name)
+        dt_to_refs = defaultdict(set)
+        for ref in meta["data_table_references"]:
+            dt_to_refs[ref["type"]].add(ref["id"])
+
+        self.dtypes_to_refs = dt_to_refs
+        self.all_indicators = meta["indicators"]
+
+    def get_table_name(self) -> str:
+        """
+        Get the name of the table for the query.
+
+        Returns:
+            str: The name of the table.
+        """
+        return self.table_name
+
+    def set_where(self, where: list[dict]) -> None:
+        """
+        Set the filter conditions for the query.
+
+        Args:
+            where (list[dict]): List of filter conditions.
+        """
+        self.where = where
+        return self
+
+    def get_where(self) -> list[dict]:
+        """
+        Get the filter conditions for the query.
+
+        Returns:
+            list[dict]: List of filter conditions.
+        """
+        return self.where
+
+    def add_filter(self, filter: dict) -> None:
+        """
+        Add a filter condition to the query.
+
+        Args:
+            filter (dict): Filter condition to add.
+        """
+        self.where.append(filter)
+        return self
+
+    def add_date_filter(
+        self, reference: str, date_from: str, date_to: Optional[str] = None
+    ) -> None:
+        """
+        Add a date filter to the query. Dates should be in ISO format (YYYY-MM-DD).
+
+        Args:
+            reference (str): Reference field for the date filter.
+            date_from (str): Start date for the filter.
+            date_to (Optional[str]): End date for the filter (optional).
+        """
+        dt_filter = {"reference": reference, "from": date_from}
+        if date_to is not None:
+            dt_filter["to"] = date_to
+        self.where.append(dt_filter)
+        return self
+
+    def add_numeric_filter(
+        self,
+        reference: str,
+        lte: Optional[float] = None,
+        eq: Optional[float] = None,
+        gte: Optional[float] = None,
+    ) -> None:
+        """
+        Add a numeric filter to the query.
+
+        Args:
+            reference (str): Reference field for the numeric filter.
+            lte (Optional[float]): Less-than-or-equal value.
+            eq (Optional[float]): Equal value.
+            gte (Optional[float]): Greater-than-or-equal value.
+        """
+        self.__validate_numeric_filter__(lte, eq, gte)
+        nm_filter = {"reference": reference, "lte": lte, "eq": eq, "gte": gte}
+        nm_filter = {k: v for k, v in nm_filter.items() if v is not None}
+        self.where.append(nm_filter)
+        return self
+
+    def __validate_numeric_filter__(
+        self,
+        lte: Optional[float] = None,
+        eq: Optional[float] = None,
+        gte: Optional[float] = None,
+    ) -> None:
+        """
+        Validate the numeric filter arguments.
+
+        Args:
+            lte (Optional[float]): Less-than-or-equal value.
+            eq (Optional[float]): Equal value.
+            gte (Optional[float]): Greater-than-or-equal value.
+
+        Raises:
+            ValueError: If the filter arguments are invalid.
+        """
+        if eq is None and lte is None and gte is None:
+            raise ValueError("At least one of eq, lte, or gte must be specified")
+        elif eq is not None and (lte is not None or gte is not None):
+            raise ValueError("The eq parameter cannot be used with lte or gte")
+
+    def add_standard_filter(self, reference: str, value: list[str]) -> None:
+        """
+        Add a standard (categorical) filter to the query.
+
+        Args:
+            reference (str): Reference field for the filter.
+            value (list[str]): List of values to filter by.
+        """
+        self.where.append({"reference": reference, "value": value})
+        return self
+
+    def set_group_by(self, group_by: list[dict]) -> None:
+        """
+        Set the group-by conditions for the query.
+
+        Args:
+            group_by (list[dict]): List of group-by conditions.
+        """
+        self.group_by = group_by
+        return self
+
+    def get_group_by(self) -> list[dict]:
+        """
+        Get the group-by conditions for the query.
+
+        Returns:
+            list[dict]: List of group-by conditions.
+        """
+        return self.group_by
+
+    def add_to_group_by(self, group_by: dict) -> None:
+        """
+        Add a group-by condition to the query.
+
+        Args:
+            group_by (dict): Group-by condition to add.
+        """
+        self.group_by.append(group_by)
+        return self
+
+    def add_non_date_reference_to_group_by(self, reference: str) -> None:
+        """
+        Add a non-date reference to the group-by conditions.
+
+        Args:
+            reference (str): Reference field to group by.
+        """
+        self.group_by.append({"reference": reference})
+        return self
+
+    def add_date_reference_to_group_by(
+        self,
+        reference: str,
+        level: Literal["yearly", "quarterly", "monthly", "as_is"] = "as_is",
+    ) -> None:
+        """
+        Add a date reference to the group-by conditions with a specified granularity.
+
+        Args:
+            reference (str): Reference field to group by.
+            level (Literal): Granularity level ('yearly', 'quarterly', 'monthly', 'as_is').
+        """
+        self.__validate_date_filter__(level)
+        dt_filter = {"reference": reference, "level": level}
+        self.group_by.append(dt_filter)
+        return self
+
+    def __validate_date_filter__(
+        self, level: Literal["yearly", "quarterly", "monthly", "as_is"]
+    ) -> None:
+        """
+        Validate the date filter granularity level.
+
+        Args:
+            level (Literal): Granularity level to validate.
+
+        Raises:
+            ValueError: If the level is invalid.
+        """
+        if level not in {"yearly", "quarterly", "monthly", "as_is"}:
+            raise ValueError(
+                "Invalid level. Must be 'yearly', 'quarterly', 'monthly', or 'as_is'"
+            )
+
+    def set_aggregate(self, aggregate: list[dict]) -> None:
+        """
+        Set the aggregate operations for the query.
+
+        Args:
+            aggregate (list[dict]): List of aggregate operations.
+        """
+        self.aggregate = aggregate
+        return self
+
+    def get_aggregate(self) -> list[dict]:
+        """
+        Get the aggregate operations for the query.
+
+        Returns:
+            list[dict]: List of aggregate operations.
+        """
+        return self.aggregate
+
+    def add_aggregate(self, indicator: str, operations: list[str]) -> None:
+        """
+        Add an aggregate operation for a specific indicator.
+
+        Args:
+            indicator (str): Indicator to aggregate.
+            operations (list[str]): List of operations (e.g., ['sum', 'avg', 'identity']).
+        """
+        self.__validate_aggregate__(operations)
+        self.aggregate.append({"indicator": indicator, "operations": operations})
+        return self
+
+    def __validate_aggregate__(self, operations: list[str]) -> None:
+        """
+        Validate the aggregate operations.
+
+        Args:
+            operations (list[str]): List of aggregate operations.
+
+        Raises:
+            ValueError: If operations are empty or invalid.
+        """
+        if len(operations) == 0:
+            raise ValueError("At least one operation must be specified")
+        elif {*operations} - {"sum", "avg", "identity"}:
+            raise ValueError("Invalid operation. Must be 'sum', 'avg', or 'identity'")
+
+    def set_language(self, language: str) -> None:
+        """
+        Set the language for the query results.
+
+        Args:
+            language (str): The language code (e.g., 'en', 'es').
+        """
+        self.language = language
+        return self
+
+    def get_language(self) -> str:
+        """
+        Get the language for the query results.
+
+        Returns:
+            str: The language code.
+        """
+        return self.language
+
+    def __get_select__(self) -> list[dict]:
+        """
+        Get the select clause for the query.
+
+        Returns:
+            list[dict]: List containing the table and indicators to select.
+        """
+        indicators = [x["indicator"] for x in self.aggregate]
+        return [{"table": self.table_name, "indicators": indicators}]
+
+    def __get_iterate__(self) -> list[dict]:
+        """
+        Get the iterate clause for the query.
+
+        Returns:
+            list[dict]: List containing group-by and aggregate operations.
+        """
+        return [{"group_by": self.group_by, "aggregate": self.aggregate}]
+
+    def __str__(self) -> str:
+        """
+        Return the string representation of the query payload.
+
+        Returns:
+            str: Stringified query payload.
+        """
+        payload_info = {
+            "table_name": self.table_name,
+            "language": self.language,
+            "where": self.where,
+            "group_by": self.group_by,
+            "aggregate": self.aggregate,
+        }
+        return str(payload_info)
+
+    def __request_payload__(self) -> dict:
+        """
+        Construct the full query payload as a dictionary.
+
+        Returns:
+            dict: The query payload.
+        """
+        return {
+            "select": self.__get_select__(),
+            "where": self.where,
+            "iterate": self.__get_iterate__(),
+            "language": self.language,
+        }
+
+    def set_aggregate_for_all_indicators(self, operations: list[str]) -> None:
+        """
+        Set the aggregate to identity for all indicators in the current table.
+        """
+        all_indicators = self.__all_indicators_refs_for_table__()
+        self.aggregate = [
+            {"indicator": indicator, "operations": operations}
+            for indicator in all_indicators
+        ]
+        return self
+
+    def set_groupby_for_all_columns(self) -> None:
+        """
+        Set group-by for all references (columns) in the current table.
+        """
+        references = self.__all_non_date_references__()
+        non_date_group_by = [{"reference": reference} for reference in references]
+        date_group_by = [
+            {"reference": reference, "level": "as_is"}
+            for reference in self.dtypes_to_refs["DT"]
+        ]
+        group_by = [*non_date_group_by, *date_group_by]
+        self.set_group_by(group_by)
+        return self
+
+    def __all_non_date_references__(self) -> list[str]:
+        """
+        Get all reference columns for the current table.
+
+        Returns:
+            list[str]: List of reference column names.
+        """
+        non_dt_ref_groups = [
+            values for key, values in self.dtypes_to_refs.items() if key != "DT"
+        ]
+        return [*set.union(*non_dt_ref_groups)]
+
+    def __all_indicators_refs_for_table__(self) -> list[str]:
+        """
+        Get all indicator references for the current table.
+
+        Returns:
+            list[str]: List of indicator reference names.
+        """
+        all_indicators = [indicator["ref"] for indicator in self.all_indicators]
+        return all_indicators
+
+    def save_query(self, name: str) -> str:
+        """
+        Save the current query to the server with the given name.
+
+        Args:
+            name (str): Name to save the query as.
+
+        Returns:
+            str: Server response.
+        """
+        BODY = {
+            "data_table": self.table_name,
+            "language": self.language,
+            "name": name,
+            "query": self.__request_payload__(),
+        }
+
+        response = self.Tukan.__execute_post_operation__(BODY, "visualizations/query/")
+
+        return response
+
+    def execute_query(
+        self, mode: Literal["vertical", "horizontal"] = "vertical"
+    ) -> dict:
+        """
+        Execute the query on the server and return the results.
+
+        Args:
+            mode (Literal): Output mode, 'vertical' or 'horizontal'.
+
+        Returns:
+            dict: Dictionary containing indicators and the result DataFrame.
+        """
+        payload = self.__request_payload__()
+        payload["mode"] = mode
+        response = self.Tukan.__execute_post_operation__(payload, "data/new_retrieve/")
+        df = pd.DataFrame(response["data"])
+        return {"indicators": response["indicators"], "df": df}
+
+
+def create_identity_query_for_table_with_date_filters(
+    table_name: str,
+    language: Literal["en", "es"],
+    from_date: str,
+    to_date: str,
+) -> dict:
+    """
+    Create an identity query for a table with date filters applied.
+
+    Args:
+        table_name (str): Name of the table.
+        language (Literal): Language for the query.
+        from_date (str): Start date for the filter.
+        to_date (str): End date for the filter.
+    """
+    query = create_identity_query_for_table(table_name, language)
+    for date_ref in query.dtypes_to_refs["DT"]:
+        query.add_date_filter(date_ref, from_date, to_date)
+    return query
+
+
+def create_identity_query_for_table(
+    table_name: str, language: Literal["en", "es"]
+) -> dict:
+    """
+    Create an identity query for a table (all indicators, all references, group by all columns).
+
+    Args:
+        table_name (str): Name of the table.
+        language (Literal): Language for the query.
+    """
+    query = Query(table_name)
+    query.set_aggregate_for_all_indicators(["identity"])
+    query.set_language(language)
+    query.set_groupby_for_all_columns()
+    return query
+
+
+def create_query_from_query_id_or_name(query_id_or_name: str) -> Query:
+    """
+    Create Query instance from a query ID or name on the server.
+
+    Args:
+        query_id_or_name (str): The query's ID or name.
+    """
+    query = Tukan().get_query_from_name_or_id(query_id_or_name)["query"]
+    query = create_query_from_payload(query)
+    return query
+
+
+def create_query_from_payload(payload: dict) -> Query:
+    """
+    Create Query instance from a query payload dictionary.
+
+    Args:
+        payload (dict): The query payload.
+    """
+    query = Query(payload["table_name"])
+    query.set_where(payload["where"])
+    query.set_group_by(payload["group_by"])
+    query.set_aggregate(payload["aggregate"])
+    query.set_language(payload["language"])
+    return query

tukan_python/tukan.py

@@ -0,0 +1,560 @@
+import os
+from collections import OrderedDict
+import json
+from functools import partial, update_wrapper
+from random import randint
+from time import sleep
+from typing import Callable, Optional
+
+import requests
+import pandas as pd
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class Tukan:
+    """
+    Handles authentication and requests to the TukanMX API.
+
+    This class provides methods for retrieving tables, indicators, and metadata,
+    as well as sending and receiving data via POST and GET operations. It also
+    provides utility methods for checking the existence of tables and indicators,
+    and for parsing hierarchical data structures.
+
+    Attributes:
+        token (str): API token for authentication.
+        env (str): Base URL for the TukanMX API.
+    """
+
+    def __init__(self, token: Optional[str] = None):
+        """
+        Initialize a new Tukan API client instance.
+
+        Args:
+            token (Optional[str]): API token for authentication. If not provided, will use the API_TUKAN environment variable.
+
+        Raises:
+            ValueError: If no token is provided and API_TUKAN is not set in the environment.
+        """
+        env_token = os.getenv("API_TUKAN")
+        if token is None and not env_token:
+            raise ValueError(
+                "Token not provided and not found in environment variables"
+            )
+        self.token = token or env_token
+        self.env = "https://client.tukanmx.com/"
+
+    def __execute_post_operation__(self, payload: dict, source: str):
+        """
+        Execute a POST request to the TukanMX API.
+
+        Args:
+            payload (dict): JSON payload to send in the POST request.
+            source (str): API endpoint to post to.
+
+        Returns:
+            dict: Parsed JSON response from the API.
+
+        Raises:
+            Exception: If the operation is not allowed (HTTP 403).
+        """
+        target_url = self.env + source
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"token {self.token}",
+        }
+        request_partial = wrapped_partial(
+            requests.request,
+            method="POST",
+            url=target_url,
+            json=payload,
+            headers=headers,
+            timeout=20,
+        )
+        response = self.__persistent_request__(request_partial)
+        if response.status_code < 300:
+            message = response.json()
+            return message
+        elif response.status_code == 403:
+            logger.info(f"{response.text}")
+            raise Exception("Operation not allowed on admin. Contact administrator!")
+        else:
+            message = response.text
+            return json.loads(message)
+
+    def __execute_get_operation__(self, source: str, query: dict):
+        """
+        Execute a GET request to the TukanMX API.
+
+        Args:
+            source (str): API endpoint to query.
+            query (dict): Query parameters for the GET request.
+
+        Returns:
+            dict: Parsed JSON response from the API.
+        """
+        target_url = self.env + source
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"token {self.token}",
+        }
+        response = requests.get(url=target_url, params=query, headers=headers)
+        if response.status_code < 300:
+            message = response.json()
+            return message
+        else:
+            message = response.text
+            return json.loads(message)
+
+    def __persistent_request__(self, request_partial: Callable):
+        """
+        Attempt a request persistently, retrying on failure.
+
+        Args:
+            request_partial (Callable): A partial function representing the request to execute.
+
+        Returns:
+            requests.Response: The successful response object.
+        """
+        attempts = 0
+        while attempts < 2:
+            try:
+                response = request_partial()
+                if response.status_code < 300:
+                    break
+            except Exception as e:
+                pass
+            attempts += 1
+            sleep(randint(3, 5))
+        return response
+
+    def all_tables(self, page: int = 1, page_size: int = 2_500) -> list[dict]:
+        """
+        Retrieve a list of all available data tables.
+
+        Args:
+            page (int): Page number for pagination.
+            page_size (int): Number of tables per page.
+
+        Returns:
+            list[dict]: List of table metadata dictionaries.
+        """
+        payload = {
+            "resource": "datatable",
+            "operation": "view",
+            "page": page,
+            "page_size": page_size,
+        }
+        response = self.__execute_post_operation__(payload, "data/")
+        return response["data"]
+
+    def get_table(self, table_name: str) -> dict:
+        """
+        Retrieve metadata for a specific data table by name or ID.
+
+        Args:
+            table_name (str): The name or ID of the data table.
+
+        Returns:
+            dict: Metadata dictionary for the table.
+        """
+        payload = {
+            "resource": "datatable",
+            "operation": "view",
+            "page": "1",
+            "page_size": "1",
+            "filter_by": {"id": table_name},
+        }
+        response = self.__execute_post_operation__(payload, "data/")
+        return response["data"][0]
+
+    def does_table_exist(self, table_name: str) -> bool:
+        """
+        Check if a data table exists by name or ID.
+
+        Args:
+            table_name (str): The name or ID of the data table.
+
+        Returns:
+            bool: True if the table exists, False otherwise.
+        """
+        try:
+            self.get_table(table_name)
+            return True
+        except IndexError:
+            return False
+
+    def get_table_metadata(self, table_name: str, language="en") -> dict:
+        """
+        Retrieve metadata for a specific table, including columns and references.
+
+        Args:
+            table_name (str): The name or ID of the data table.
+            language (str): Language for metadata (default is 'en').
+
+        Returns:
+            dict: Metadata dictionary for the table.
+        """
+        payload = {"data": {"id": table_name, "language": language}}
+        response = self.__execute_post_operation__(payload, "data/metadata/")
+        return response
+
+    def all_indicators(self, page: int = 1, page_size: int = 2_500) -> list[dict]:
+        """
+        Retrieve all indicators available in the database.
+
+        Args:
+            page (int): Page number for pagination (default is 1).
+            page_size (int): Number of indicators per page (default is 2,500).
+
+        Returns:
+            list[dict]: List of indicator metadata dictionaries.
+        """
+        payload = {
+            "resource": "indicator",
+            "operation": "view",
+            "page": page,
+            "page_size": page_size,
+        }
+        response = self.__execute_post_operation__(payload, "data/")
+        return response["data"]
+
+    def all_indicators_for_table(
+        self, table_name: str, page: int = 1, page_size: int = 2_500
+    ) -> list[dict]:
+        """
+        Retrieve all indicators for a specific table.
+
+        Args:
+            table_name (str): The name or ID of the data table.
+            page (int): Page number for pagination.
+            page_size (int): Number of indicators per page.
+
+        Returns:
+            list[dict]: List of indicator metadata dictionaries.
+        """
+        payload = {
+            "resource": "indicator",
+            "operation": "view",
+            "page": page,
+            "page_size": page_size,
+            "filter_by": {"data_table": table_name},
+        }
+        response = self.__execute_post_operation__(payload, "data/")
+        return response["data"]
+
+    def does_indicator_ref_exist(self, indicator_ref: str) -> bool:
+        """
+        Check if an indicator reference exists.
+
+        Args:
+            indicator_ref (str): The reference ID of the indicator.
+
+        Returns:
+            bool: True if the indicator exists, False otherwise.
+        """
+        try:
+            indicator_info = self.get_indicator_by_ref(indicator_ref, page_size=1)
+        except IndexError:
+            indicator_info = {}
+        return bool(indicator_info)
+
+    def get_indicator_by_ref(
+        self, indicator_ref: str, page: int = 1, page_size: int = 2_500
+    ) -> dict:
+        """
+        Retrieve indicator metadata by its reference ID.
+
+        Args:
+            indicator_ref (str): The reference ID of the indicator.
+            page (int): Page number for pagination.
+            page_size (int): Number of indicators per page.
+
+        Returns:
+            dict: Metadata dictionary for the indicator.
+        """
+        payload = {
+            "resource": "indicator",
+            "operation": "view",
+            "page": page,
+            "page_size": page_size,
+            "filter_by": {"ref": indicator_ref},
+        }
+        response = self.__execute_post_operation__(payload, "data/")
+        return response["data"][0]
+
+    def ask_leah(self, query: str, language: str = "en") -> list[dict]:
+        """
+        Query the Leah endpoint for table suggestions based on a natural language query.
+
+        Args:
+            query (str): The question or prompt for Leah.
+            language (str): Language for the query (default is 'en').
+
+        Returns:
+            dict: Parsed response with table metadata suggestions.
+        """
+        payload = {"query": query, "language": language}
+        response = self.__execute_post_operation__(payload, "leah/")
+        parsed_response = parse_leah(response)
+        return parsed_response
+
+    def get_tree_for_table(self, table_name: str) -> dict[str, pd.DataFrame]:
+        """
+        Retrieve hierarchical tree structures for a given table.
+
+        Args:
+            table_name (str): The name or ID of the data table.
+
+        Returns:
+            dict[str, dict[str, pd.DataFrame]]: Dictionary mapping table references to its reference values with hierarchical information.
+        """
+        payload = {
+            "operation": "view",
+            "resource": "tree",
+            "filter_by": {"data_table": table_name},
+        }
+        response = self.__execute_post_operation__(payload, "data/")
+        parsed_trees = parse_leah_trees(response["data"][0]["tree"])
+        return parsed_trees
+
+    def get_query_from_name_or_id(self, query_name_or_id: str) -> OrderedDict:
+        """
+        Retrieve a saved query by its name or ID and return its details in an OrderedDict.
+
+        Args:
+            query_name_or_id (str): Name or ID of the saved query.
+
+        Returns:
+            OrderedDict: Ordered dictionary containing keys 'id', 'name', 'author_name', 'created', and 'query'.
+        """
+        BODY = {
+            "page_size": "10_000",
+            "current": "1",
+            "order_by": "-updated",
+            "tags": "",
+            "search": query_name_or_id,
+            "api": "visualizations",
+            "resource": "queries",
+        }
+        response = self.__execute_get_operation__("visualizations/queries", BODY)
+        data = response["data"][0]
+        parsed_data = parse_query_data(data)
+        return parsed_data
+
+
+def wrapped_partial(func, *args, **kwargs) -> Callable:
+    """
+    Returns a partial function with updated wrapper metadata.
+
+    Args:
+        func (Callable): The function to partially apply.
+        *args: Positional arguments to pre-fill.
+        **kwargs: Keyword arguments to pre-fill.
+
+    Returns:
+        Callable: The partially applied function with updated metadata.
+    """
+    partial_func = partial(func, *args, **kwargs)
+    update_wrapper(partial_func, func)
+    return partial_func
+
+
+def parse_leah(response: dict) -> list[dict]:
+    """
+    Parses a Leah API response into a list of table metadata dictionaries.
+
+    Args:
+        response (dict): The Leah API response containing 'openai_completion' and 'optional_tables'.
+
+    Returns:
+        list[dict]: List of dictionaries with table 'id', 'description', and 'name'.
+    """
+    ans = []
+    all_tables = response["openai_completion"] + response["optional_tables"]
+    for element in all_tables:
+        table_metadata = element["metadata"]["data_table"]
+        ans.append(
+            {
+                "id": table_metadata["id"],
+                "description": table_metadata["description"],
+                "name": table_metadata["name"],
+            }
+        )
+    return ans
+
+
+def parse_leah_trees(response: dict) -> dict[str, pd.DataFrame]:
+    """
+    Parses Leah tree responses into a dictionary of DataFrames.
+
+    Args:
+        response (dict): Leah tree response mapping keys to tree JSON objects.
+
+    Returns:
+        dict[str, pd.DataFrame]: Dictionary mapping keys to DataFrames representing the tree structure.
+    """
+    ans = {}
+    for key, tree in response.items():
+        heritage_df = generate_heritage_col_df_from_json(tree)
+        ans[key] = heritage_df
+    return ans
+
+
+def generate_heritage_col_df_from_json(tree_json: dict) -> pd.DataFrame:
+    """
+    Generates a pandas DataFrame from a heritage tree JSON structure.
+
+    Args:
+        tree_json (dict): JSON object representing the heritage tree.
+
+    Returns:
+        pd.DataFrame: DataFrame containing the heritage columns merged with display data.
+    """
+    [ref_name] = tree_json.keys()
+    all_ref_lineages, display_map = lineages_of_refs_and_display_map_from_json(
+        tree_json
+    )
+    heritage_df = heritage_df_from_ref_lineages(all_ref_lineages, ref_name)
+    display_df = display_df_from_map(display_map, ref_name)
+    return pd.merge(heritage_df, display_df, on=ref_name)
+
+
+def lineages_of_refs_and_display_map_from_json(tree_json: dict) -> tuple[list, list]:
+    """
+    Extracts all reference lineages and display map from a tree JSON structure.
+
+    Args:
+        tree_json (dict): JSON object representing the tree structure.
+
+    Returns:
+        tuple[list, list]:
+            - List of all reference lineages (each as a list of reference IDs).
+            - Display map as a list of tuples (ref_id, data dict).
+    """
+    [(root_ref, root_ref_info)] = tree_json.items()
+    root_ref_node = [root_ref]
+    all_nodes = [root_ref_node]
+    display_map = [(root_ref, root_ref_info["data"])]
+    add_nodes_recursively(
+        root_ref_node, root_ref_info["children"], all_nodes, display_map
+    )
+    return all_nodes, display_map
+
+
+def add_nodes_recursively(
+    ancestry: list[str], sons: list, all_nodes: list, display_map: list
+):
+    """
+    Recursively traverses and collects nodes and display data from a tree structure.
+
+    Args:
+        ancestry (list[str]): The lineage of ancestor references leading to the current node.
+        sons (list): List of child nodes (as dicts).
+        all_nodes (list): Accumulator for all reference lineages.
+        display_map (list): Accumulator for display map tuples (ref_id, data dict).
+    """
+    for son in sons:
+        [(son_ref_id, son_ref_info)] = son.items()
+        sons_heritage = ancestry + [son_ref_id]
+        display_map.append((son_ref_id, son_ref_info["data"]))
+        all_nodes.append(sons_heritage)
+        grand_children = son_ref_info.get("children", [])
+        add_nodes_recursively(sons_heritage, grand_children, all_nodes, display_map)
+
+
+def heritage_df_from_ref_lineages(
+    all_ref_lineages: list, ref_name: str
+) -> pd.DataFrame:
+    """
+    Generates a DataFrame from a list of reference lineages.
+
+    Args:
+        all_ref_lineages (list): List of reference lineages (each as a list of reference IDs).
+        ref_name (str): Name of the reference column.
+
+    Returns:
+        pd.DataFrame: DataFrame with columns for each ancestor and the reference itself.
+    """
+    max_num_ancestors = len(max(all_ref_lineages, key=len)) - 1
+    col_names = ref_col_names(ref_name, max_num_ancestors)
+    col_names_to_refs = []
+    for lineage in all_ref_lineages:
+        lineage_with_all_levels = right_fill_ancestor_ref(lineage, max_num_ancestors)
+        col_names_to_refs.append(dict(zip(col_names, lineage_with_all_levels)))
+    return pd.DataFrame(col_names_to_refs)
+
+
+def ref_col_names(ref_name: str, max_num_ancestors: int) -> list:
+    """
+    Generates column names for ancestor references and the main reference.
+
+    Args:
+        ref_name (str): Name of the reference column.
+        max_num_ancestors (int): Maximum number of ancestor levels.
+
+    Returns:
+        list: List of column names for each ancestor and the reference.
+    """
+    ancestor_cols = [f"{ref_name}_p{n}" for n in range(max_num_ancestors)]
+    return ancestor_cols + [ref_name]
+
+
+def right_fill_ancestor_ref(lineage: list[str], max_num_ancestors: int) -> list[str]:
+    """
+    Fills the ancestor portion of a lineage to a fixed length with None values.
+
+    Args:
+        lineage (list[str]): List of reference IDs representing a lineage.
+        max_num_ancestors (int): The total number of ancestor columns required.
+
+    Returns:
+        list[str]: The lineage, right-filled with None for missing ancestors.
+    """
+    ancestors = lineage[:-1]
+    ancestors_fill = ancestors + ([None] * (max_num_ancestors - len(ancestors)))
+    return ancestors_fill + [lineage[-1]]
+
+
+def display_df_from_map(display_map: list, ref_name: str) -> pd.DataFrame:
+    """
+    Generates a pandas DataFrame from a display map.
+
+    Args:
+        display_map (list): List of tuples (ref_id, data dict) for each node in the tree.
+        ref_name (str): Name of the reference column.
+
+    Returns:
+        pd.DataFrame: DataFrame containing reference IDs and their associated display data.
+    """
+    data = [{ref_name: ref, **data} for ref, data in display_map]
+    return pd.DataFrame(data)
+
+
+def parse_query_data(data: dict) -> OrderedDict:
+    """
+    Parse a query data dictionary and return an OrderedDict with selected keys.
+
+    Args:
+        data (dict): Dictionary containing query data as returned by the API.
+
+    Returns:
+        OrderedDict: Ordered dictionary with keys 'id', 'name', 'author_name', 'created', and 'query'.
+    """
+    data["query"] = parse_query(data["query"])
+    ordered_keys = ["id", "name", "author_name", "created", "updated", "query"]
+    ordered_pairs = [(key, data[key]) for key in ordered_keys]
+    ordered_data = OrderedDict(ordered_pairs)
+    return ordered_data
+
+
+def parse_query(query: dict) -> dict:
+    parsed_query = {
+        "table_name": query["select"][0]["table"],
+        "where": query["where"],
+        "group_by": query["iterate"][0]["group_by"],
+        "aggregate": query["iterate"][0]["aggregate"],
+        "language": query["language"],
+    }
+    return parsed_query

tukan_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: tukan_python
+Version: 0.1.0
+Summary: A package to utilize the tukan API.
+Author-email: roberto <roberto@tukanmx.com>
+License: MIT License
+        
+        Copyright (c) 2021 TukanMx
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/TukanMx/tukan_python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: loguru==0.7.2
+Requires-Dist: numpy==1.26.1
+Requires-Dist: pandas==2.1.1
+Requires-Dist: pytest==7.4.2
+Requires-Dist: python-dotenv==1.0.0
+Requires-Dist: requests==2.31.0
+Requires-Dist: tqdm==4.66.1
+Dynamic: license-file
+
+# tukan_python
+
+A Python package to interact with the TukanMX API, retrieve table metadata, and build and execute queries with flexible filters, groupings, and aggregations.
+
+## Installation
+
+Once the package is published to PyPI, install it using:
+
+```bash
+pip install tukan_python
+```
+
+## Usage
+
+### Authentication
+
+You need an API token to use the TukanMX API. You can provide it directly to the `Tukan` or `Query` classes, or set it as an environment variable:
+
+```bash
+export API_TUKAN=your_api_token
+```
+
+### Main Classes
+
+#### Tukan
+Handles authentication and requests to the TukanMX API. Provides methods for retrieving tables, indicators, and metadata, as well as sending and receiving data.
+
+```python
+from tukan_python.tukan import Tukan
+
+tukan = Tukan(token="your_api_token")
+
+# Retrieve metadata for a table
+metadata = tukan.get_table_metadata("table_name")
+
+# Retrieve a list of tables
+all_tables = tukan.get_tables()
+
+# Retrieve a list of indicators
+indicators = tukan.get_indicators()
+```
+
+#### Query
+Helper class for building and executing queries against the TukanMX API. Supports filters, groupings, aggregations, and execution.
+
+```python
+from tukan_python.query import Query
+
+# Create a Query instance
+query = Query("table_name", token="your_api_token")
+
+# Add filters, groupings, or aggregations as needed
+query.set_where([{ "reference": "column", "eq": "value" }])
+query.set_group_by([{ "reference": "column" }])
+query.set_aggregate([{ "indicator": "indicator_name", "operation": "sum" }])
+
+# Execute the query
+result = query.execute_query()
+print(result["df"])  # result is a dict with 'indicators' and a pandas DataFrame
+```
+
+#### Utility Functions
+
+- `create_identity_query_for_table(table_name, language)`
+- `create_identity_query_for_table_with_date_filters(table_name, language, from_date, to_date)`
+- `create_query_from_query_id_or_name(query_id_or_name)`
+- `create_query_from_payload(payload)`
+
+These functions help build queries quickly from table names, IDs, or payloads.
+
+## License
+See the `LICENSE` file for license information.
+
+---
+
+For more details, see the code in `tukan_python/tukan.py` and `tukan_python/query.py`.

tukan_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+tukan_python/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tukan_python/query.py,sha256=QbpTFYPMvEfYdDJg0Yyk9HlaXWfL_FAVPqdVgn_WZgY,16212
+tukan_python/tukan.py,sha256=DqgQFgE_RN7vTQBQbLf-FBP7fkW047MweIqBsZQB3qY,18760
+tukan_python-0.1.0.dist-info/licenses/LICENSE,sha256=4-KXxjgpAywK6yAHKLHmKoSJ2KqqKzOZYTcey0B0xGY,1064
+tukan_python-0.1.0.dist-info/METADATA,sha256=omBgbBUHpyI-mG_q8C91ypRTn6Cm4DdKHpD_BHcJDow,4125
+tukan_python-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tukan_python-0.1.0.dist-info/top_level.txt,sha256=64Ewy3_aoQ0bzlFumNTozOHZ60jP-EGxgC-duqmPlnM,13
+tukan_python-0.1.0.dist-info/RECORD,,

tukan_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tukan_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 TukanMx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tukan_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tukan_python