tukan-python 0.2.1__py3-none-any.whl

tukan_python/__init__.py

@@ -0,0 +1,5 @@
+from .tukan import Tukan
+from .query import Query
+
+__version__ = "0.2.0"
+__all__ = ["Tukan", "Query", "__version__"]

tukan_python/query.py

@@ -0,0 +1,209 @@
+from typing import Literal, Optional
+
+import pandas as pd
+
+from tukan_python.tukan import Tukan
+
+
+class Query:
+
+    def __init__(
+        self,
+        token: Optional[str] = None,
+        table_name: Optional[str] = None,
+        where: Optional[list[dict]] = None,
+        group_by: Optional[list[dict]] = None,
+        aggregate: Optional[list[dict]] = None,
+        language: str = "en",
+        engine: Optional[Literal["air", "blizzard"]] = None,
+    ):
+        self.Tukan = Tukan(token)
+        self.table_name = table_name
+        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
+        self.engine = engine
+
+    def set_table_name(self, table_name: str) -> None:
+        self.table_name = table_name
+
+    def set_where(self, where: list[dict]) -> None:
+        self.where = where
+
+    def add_date_filter(
+        self, reference: str, date_from: str, date_to: Optional[str] = None
+    ) -> None:
+        dt_filter = {"reference": reference, "from": date_from}
+        if date_to is not None:
+            dt_filter["to"] = date_to
+        self.where.append(dt_filter)
+
+    def add_numeric_filter(
+        self,
+        reference: str,
+        lte: Optional[float] = None,
+        eq: Optional[float] = None,
+        gte: Optional[float] = None,
+    ) -> None:
+        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)
+
+    def validate_numeric_filter(
+        self,
+        lte: Optional[float] = None,
+        eq: Optional[float] = None,
+        gte: Optional[float] = None,
+    ) -> None:
+        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:
+        self.where.append({"reference": reference, "value": value})
+
+    def set_group_by(self, group_by: list[dict]) -> None:
+        self.group_by = group_by
+
+    def add_non_date_reference_to_group_by(self, reference: str) -> None:
+        self.group_by.append({"reference": reference})
+
+    def add_date_reference_to_group_by(
+        self, reference: str, level: Literal["yearly", "quarterly", "monthly", "as_is"]
+    ) -> None:
+        self.validate_date_filter(level)
+        dt_filter = {"reference": reference, "level": level}
+        self.group_by.append(dt_filter)
+
+    def validate_date_filter(
+        self, level: Literal["yearly", "quarterly", "monthly", "as_is"]
+    ) -> None:
+        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:
+        self.aggregate = aggregate
+
+    def add_aggregate(self, indicator: str, operations: list[str]) -> None:
+        self.validate_aggregate(operations)
+        self.aggregate.append({"indicator": indicator, "operations": operations})
+
+    def validate_aggregate(self, operations: list[str]) -> None:
+        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:
+        self.language = language
+
+    def set_engine(self, engine: Literal["air", "blizzard"]) -> None:
+        self.engine = engine
+
+    def get_select(self) -> list[dict]:
+        indicators = [x["indicator"] for x in self.aggregate]
+        return [{"table": self.table_name, "indicators": indicators}]
+
+    def get_iterate(self) -> list[dict]:
+        return [{"group_by": self.group_by, "aggregate": self.aggregate}]
+
+    def __str__(self) -> str:
+        return str(self.__request_payload__())
+
+    def __request_payload__(self) -> dict:
+        payload = {
+            "select": self.get_select(),
+            "where": self.where,
+            "iterate": self.get_iterate(),
+            "language": self.language,
+        }
+        if self.engine is not None:
+            payload["engine"] = self.engine
+        return payload
+
+    def create_identity_query_for_table(
+        self, table_name: str, language: Literal["en", "es"]
+    ) -> dict:
+        self.set_table_name(table_name)
+        self.set_identity_aggregate_for_indicators(table_name)
+        self.set_language(language)
+        self.set_groupby_for_all_columns(table_name)
+
+    def create_identity_query_for_table_with_date_filters(
+        self,
+        table_name: str,
+        language: Literal["en", "es"],
+        from_date: str,
+        to_date: str,
+    ) -> dict:
+        self.create_identity_query_for_table(table_name, language)
+        date_refs = self.all_dt_references_for_table(table_name)
+        for date_ref in date_refs:
+            self.add_date_filter(date_ref, from_date, to_date)
+
+    def all_dt_references_for_table(self, table_name: str) -> list[str]:
+        metadata = self.Tukan.get_table_metadata(table_name, language="en")
+        date_refs = metadata["data_table"]["date_ranges"].keys()
+        return [*date_refs]
+
+    def set_identity_aggregate_for_indicators(self, table_name: str) -> None:
+        all_indicators = self.all_indicators_for_table(table_name)
+        self.aggregate = [
+            {"indicator": indicator, "operations": ["identity"]}
+            for indicator in all_indicators
+        ]
+
+    def set_groupby_for_all_columns(self, table_name: str) -> None:
+        references = self.all_references_for_table(table_name)
+        group_by = [{"reference": reference} for reference in references]
+        self.set_group_by(group_by)
+
+    def all_references_for_table(self, table_name: str) -> list[str]:
+        return self.Tukan.get_table(table_name)["references"]
+
+    def all_indicators_for_table(self, table_name: str) -> list[str]:
+        all_indicators = self.Tukan.all_indicators_for_table(table_name)
+        all_indicators = [indicator["ref"] for indicator in all_indicators]
+        return all_indicators
+
+    def save_query(self, name: str) -> str:
+        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:
+        payload = self.__request_payload__()
+        payload["mode"] = mode
+        endpoint = "data/retrieve/" if self.engine == "blizzard" else "data/new_retrieve/"
+        response = self.Tukan.execute_post_operation(payload, endpoint)
+
+        if self.engine == "blizzard":
+            all_data = response["data"]
+            offset = len(all_data)
+            while response.get("has_more_data", False):
+                payload["offset"] = offset
+                response = self.Tukan.execute_post_operation(payload, endpoint)
+                all_data.extend(response["data"])
+                offset += len(response["data"])
+            df = pd.DataFrame(all_data)
+        else:
+            df = pd.DataFrame(response["data"])
+
+        result = {"df": df}
+        if "indicators" in response:
+            result["indicators"] = response["indicators"]
+        return result

tukan_python/tukan.py

@@ -0,0 +1,218 @@
+import logging
+import os
+import json
+from functools import partial, update_wrapper
+from io import StringIO
+from random import randint
+from time import sleep
+from typing import Callable, Optional
+
+import pandas as pd
+import requests
+from dotenv import load_dotenv
+
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+
+class Tukan:
+    def __init__(self, token: Optional[str] = None):
+        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):
+        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=90,
+        )
+        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 persistent_request(self, request_partial: Callable):
+        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]:
+        payload = {
+            "resource": "datatable",
+            "operation": "view",
+            "page": page,
+            "page_size": page_size,
+        }
+        response = self.execute_post_operation(payload, "data/")
+        # Filter out tables that should not be indexed (restricted tables)
+        tables = [t for t in response["data"] if t.get("should_index", True)]
+        return tables
+
+    def get_table(self, table_name: str) -> dict:
+        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:
+        try:
+            self.get_table(table_name)
+            return True
+        except IndexError:
+            return False
+
+    def get_table_metadata(self, table_name: str, language="en") -> dict:
+        payload = {"data": {"id": table_name, "language": language}}
+        response = self.execute_post_operation(payload, "data/metadata/")
+        return response
+
+    def does_indicator_ref_exist(self, indicator_ref: str) -> bool:
+        indicator_info = self.get_indicator_by_ref(indicator_ref, page_size=1)
+        return bool(indicator_info)
+
+    def all_indicators(self, page: int = 1, page_size: int = 2_500) -> list[dict]:
+        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]:
+        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 get_indicator_by_ref(
+        self, indicator_ref: str, page: int = 1, page_size: int = 2_500
+    ) -> dict:
+        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") -> dict:
+        payload = {"query": query, "language": language}
+        response = self.execute_post_operation(payload, "leah/")
+        parsed_response = parse_leah(response)
+        return parsed_response
+
+    def get_saved_query_with_query_name(self, query_name: str) -> list[dict]:
+        BODY = {
+            "resource": "query",
+            "operation": "view",
+            "filter_by": {"name": query_name},
+            "page_size": 10_000,
+        }
+
+        response = self.execute_post_operation(BODY, "visualizations/queries")
+        return response["data"]
+
+    def get_query_from_id(self, query_id: str) -> dict:
+        BODY = {
+            "resource": "query",
+            "operation": "view",
+            "id": query_id,
+        }
+
+        response = self.execute_post_operation(BODY, "visualizations/queries")
+        data = response["data"]
+        query = next(x for x in data if x["id"] == query_id)
+        return query
+
+    def get_reference_flat_tree(
+        self, table_name: str, reference: str, only_in_table: bool = False
+    ) -> pd.DataFrame:
+        """
+        Get all available values for a reference (column/category) in a table.
+
+        Args:
+            table_name: The table ID
+            reference: The reference/column name
+            only_in_table: If True, only return values that exist in the data
+
+        Returns:
+            DataFrame with columns: raw, ref, name, name_en, parent_ref, order, in_table
+        """
+        url = f"{self.env}data/visualizations/flat-tree/{table_name}/{reference}/?export=csv"
+        headers = {
+            "Authorization": f"token {self.token}",
+        }
+        response = requests.get(url, headers=headers, timeout=20)
+        if response.status_code >= 300:
+            raise Exception(f"Failed to get reference values: {response.text}")
+
+        # Decode response with proper encoding (API returns UTF-8 but sometimes needs fixing)
+        text = response.content.decode("utf-8")
+        df = pd.read_csv(StringIO(text), sep="|")
+        if only_in_table:
+            df = df[df["in_table"] == True]
+        return df
+
+
+def wrapped_partial(func, *args, **kwargs) -> Callable:
+    partial_func = partial(func, *args, **kwargs)
+    update_wrapper(partial_func, func)
+    return partial_func
+
+
+def parse_leah(response: dict) -> dict:
+    ans = []
+    for element in response["openai_completion"]:
+        table_metadata = element["metadata"]["data_table"]
+        ans.append(
+            {
+                "id": table_metadata["id"],
+                "description": table_metadata["description"],
+                "name": table_metadata["name"],
+            }
+        )
+    return ans

tukan_python-0.2.1.dist-info/METADATA

@@ -0,0 +1,351 @@
+Metadata-Version: 2.4
+Name: tukan_python
+Version: 0.2.1
+Summary: SDK de Python para acceder a datos oficiales de México a través de la API de Tukan.
+Author-email: TukanMx <contacto@tukanmx.com>
+License-Expression: MIT
+Project-URL: Homepage, https://tukanmx.com
+Project-URL: Repository, https://github.com/TukanMx/tukan_python
+Project-URL: Documentation, https://github.com/TukanMx/tukan_python#readme
+Keywords: tukan,mexico,data,api,inegi,banxico,cnbv,analytics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: python-dotenv>=1.0.0
+Dynamic: license-file
+
+# Tukan Python SDK
+
+[![PyPI version](https://badge.fury.io/py/tukan_python.svg)](https://badge.fury.io/py/tukan_python)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+[Tukan](https://tukanmx.com) es la plataforma de datos más completa de México.
+
+Si estás en búsqueda de una forma sencilla y eficiente para acceder a todas las estadísticas oficiales de la economía mexicana desde Python, esta es la solución para ti.
+
+## Descripción
+
+Tukan agrega y estandariza fuentes oficiales de datos públicos como INEGI, Banxico, CNBV, CNSF, CONSAR, entre otras. 
+
+Este SDK permite consultar y analizar estos datos de forma sencilla desde Python.
+
+Para acceder a la gran variedad de datos disponibles es necesario contar con un token y una suscripción activa en [Tukan](https://tukanmx.com). Sin embargo, algunas tablas pueden ser consultadas de forma gratuita.
+
+
+## Instalación
+
+```bash
+pip install tukan_python
+```
+
+## Autenticación
+
+Para obtener tu token debes primero regidstrarte en [Tukan](https://app.tukanmx.com/user/register).
+
+Luego, podrás encontrar tu token en el [panel de usuario](https://app.tukanmx.com/account/).
+
+![Token panel](images/token_panel.png)
+
+Una vez obtenido tu token, puedes configurarlo como una variable de entorno
+
+```bash
+export API_TUKAN="tu_token_aqui"
+```
+
+o en un archivo `.env`:
+
+```
+API_TUKAN=tu_token_aqui
+```
+
+Otra alternativa es pasar el token directamente al inicializar el cliente:
+
+```python
+from tukan_python import Tukan
+
+tukan = Tukan(token="tu_token_aqui")
+```
+
+## Inicio rápido
+
+```python
+from tukan_python import Query
+
+# Consultar tipo de cambio FIX (MXN por USD)
+q = Query()
+q.set_table_name("mex_banxico_cf102")
+q.add_date_filter("date", "2025-01-01", "2025-01-15")
+q.add_date_reference_to_group_by("date", level="as_is")
+q.add_aggregate("be08668718242ff", ["identity"])  # Tipo de cambio FIX
+q.set_language("es")
+
+resultado = q.execute_query()
+print(resultado["df"])
+```
+
+Salida:
+```
+         date        indicator    value
+0  2025-01-02  be08668718242ff  20.6917
+1  2025-01-03  be08668718242ff  20.6708
+2  2025-01-06  be08668718242ff  20.3195
+3  2025-01-07  be08668718242ff  20.3440
+4  2025-01-08  be08668718242ff  20.3823
+...
+```
+
+## Ejemplos
+
+### 1. Explorar tablas disponibles
+
+```python
+from tukan_python import Tukan
+
+tukan = Tukan()
+
+# Listar todas las tablas
+tablas = tukan.all_tables()
+print(f"Tablas disponibles: {len(tablas)}")
+
+# Filtrar tablas de CNBV y ordenar alfabéticamente
+cnbv = [t for t in tablas if t["id"].startswith("mex_cnbv")]
+cnbv.sort(key=lambda x: x["id"])
+
+for t in cnbv[:5]:
+    print(f"- {t['id']}: {t['name']}")
+```
+
+Salida:
+```
+Tablas disponibles: 150+
+- mex_cnbv_cb_balance_sheet_ifrs9: Instituciones de Banca Múltiple - Balance General Detallado (IFRS9)
+- mex_cnbv_cb_capital_ratios: Instituciones de Banca Múltiple - Índice de Capitalización
+- mex_cnbv_cb_ccl: Instituciones de Banca Múltiple - Coeficiente de Cobertura de Liquidez
+- mex_cnbv_cb_claims_by_channel_and_status: Instituciones de Banca Múltiple - Reclamaciones por Estatus y Canal
+- mex_cnbv_cb_clients_per_product: Clientes por Producto Financiero
+```
+
+### 2. Obtener metadata de una tabla
+
+Antes de consultar datos, es útil explorar la estructura de la tabla:
+
+```python
+from tukan_python import Tukan
+
+tukan = Tukan()
+
+# Obtener metadata
+meta = tukan.get_table_metadata("mex_cnbv_cb_orig_by_gender_monthly", language="es")
+
+print("Nombre:", meta["data_table"]["name"])
+print("Referencias:", [r["id"] for r in meta["data_table_references"]])
+print("Rango de fechas:", meta["data_table"]["date_ranges"])
+
+# Ver indicadores disponibles
+indicadores = tukan.all_indicators_for_table("mex_cnbv_cb_orig_by_gender_monthly")
+for ind in indicadores:
+    print(f"- {ind['ref']}: {ind['name']}")
+```
+
+Salida:
+```
+Nombre: Banca Múltiple - Colocación de Créditos Empresariales y de Vivienda, por Sexo
+Referencias: ['end_date', 'sex', 'start_date', 'institutions', 'geography', ...]
+Rango de fechas: {'end_date': {'max': '2025-11-30', 'min': '2019-12-31'}}
+
+- 05451c0b6d5ea78: Monto colocado
+- 78256b18c54451f: Número de créditos
+- b577c6dfc51ebef: Tasa ponderada
+```
+
+### 3. Consultar colocación de crédito bancario por sexo
+
+```python
+from tukan_python import Query
+
+q = Query()
+q.set_table_name("mex_cnbv_cb_orig_by_gender_monthly")
+q.add_date_filter("end_date", "2024-01-01", "2024-06-30")
+q.add_standard_filter("institutions", ["0c959ae6bc0d063"])  # Banca múltiple (agregado)
+q.add_date_reference_to_group_by("end_date", level="monthly")
+q.add_non_date_reference_to_group_by("sex")
+q.add_aggregate("05451c0b6d5ea78", ["sum"])  # Monto colocado
+q.set_language("es")
+
+resultado = q.execute_query()
+print(resultado["df"])
+```
+
+Salida:
+```
+       sex__ref    end_date             indicator         value       sex
+0  34e63c6a4f88758  2024-01-01  05451c0b6d5ea78__sum  1.468993e+10  Femenino
+1  34e63c6a4f88758  2024-02-01  05451c0b6d5ea78__sum  1.721803e+10  Femenino
+2  653a519004568cb  2024-01-01  05451c0b6d5ea78__sum  3.000290e+10  Masculino
+3  653a519004568cb  2024-02-01  05451c0b6d5ea78__sum  3.302666e+10  Masculino
+...
+```
+
+### 4. Consultar el INPC (inflación)
+
+El INPC requiere filtrar por producto. Primero exploramos el catálogo:
+
+```python
+from tukan_python import Tukan, Query
+
+tukan = Tukan()
+
+# Ver productos disponibles
+productos = tukan.get_reference_flat_tree(
+    table_name="mex_inegi_inpc_original_product_monthly",
+    reference="mex_inegi_cpi_product_structure",
+    only_in_table=True
+)
+print(productos[["ref", "name"]].head(10))
+```
+
+Salida:
+```
+                ref                                   name
+0   9329306b0b5268c                    Todos los productos
+1   a38da228dc862e7            Alimentos, bebidas y tabaco
+2   714d22fe124b834                              Alimentos
+3   1c70d647c151be7                               Vivienda
+4   da9ee7065e99719                             Transporte
+...
+```
+
+Ahora consultamos el índice general:
+
+```python
+q = Query()
+q.set_table_name("mex_inegi_inpc_original_product_monthly")
+q.add_date_filter("date", "2024-01-01", "2024-06-30")
+q.add_standard_filter("mex_inegi_cpi_product_structure", ["9329306b0b5268c"])  # Todos los productos
+q.add_date_reference_to_group_by("date", level="monthly")
+q.add_aggregate("c572db59b8cd109", ["identity"])  # INPC
+q.set_language("es")
+
+resultado = q.execute_query()
+print(resultado["df"])
+```
+
+Salida:
+```
+         date        indicator    value
+0  2024-01-01  c572db59b8cd109  133.555
+1  2024-02-01  c572db59b8cd109  133.681
+2  2024-03-01  c572db59b8cd109  134.065
+3  2024-04-01  c572db59b8cd109  134.336
+4  2024-05-01  c572db59b8cd109  134.087
+5  2024-06-01  c572db59b8cd109  134.594
+```
+
+### 5. Explorar catálogos jerárquicos
+
+Las referencias estándar tienen estructura jerárquica (país → estado → municipio). El catálogo incluye columnas importantes como `raw` (ID original de la fuente) e `in_table` (si el valor tiene datos en la tabla):
+
+```python
+from tukan_python import Tukan
+
+tukan = Tukan()
+
+# Obtener catálogo de geografía
+df_geo = tukan.get_reference_flat_tree(
+    table_name="mex_inegi_census_people_reduced",
+    reference="geography"
+)
+
+print(df_geo[["raw", "ref", "name", "parent_ref", "in_table"]].head(10))
+```
+
+Salida:
+```
+      raw              ref                   name       parent_ref  in_table
+0      wd  2064d512d0da97d                  Mundo            FALSE     False
+1      na  e5fc8e04967fe49           Norteamérica  2064d512d0da97d     False
+2     mex  b815762a2c6a283                 México  e5fc8e04967fe49      True
+3  mex_10  db3b32c946ffd13                Durango  b815762a2c6a283      True
+4  mex_21  bd8b4a37deee845                 Puebla  b815762a2c6a283      True
+5  mex_11  a3aa918bd45ac53             Guanajuato  b815762a2c6a283      True
+6  mex_24  468bc66c95ecfe6        San Luis Potosí  b815762a2c6a283      True
+...
+```
+
+La columna `raw` contiene el ID original (ej: `mex_10` para Durango), mientras que `ref` es el ID interno de Tukan. Usa `only_in_table=True` para filtrar solo valores con datos.
+
+### 6. Motor Blizzard para consultas pesadas
+
+Para consultas con grandes volúmenes de datos, usa el motor Blizzard:
+
+```python
+from tukan_python import Query
+
+q = Query(engine="blizzard")
+q.set_table_name("mex_cnbv_cb_orig_by_gender_monthly")
+# ... configurar filtros y agregaciones ...
+resultado = q.execute_query()
+```
+
+## Conceptos clave
+
+### Tablas
+Cada tabla representa una fuente de datos específica. Los IDs siguen el patrón general:
+`{pais}_{fuente}_{dataset}`
+
+Ejemplos:
+- `mex_inegi_inpc_original_product_monthly` - INPC de INEGI
+- `mex_cnbv_cb_orig_by_gender_monthly` - Colocación de créditos de CNBV
+- `mex_inegi_census_people_reduced` - Censo de población de INEGI
+- `mex_shcp_budget_expenditures_by_fc` - Gastos presupuestarios de SHCP
+
+### Indicadores
+Son las métricas o valores que se pueden consultar. Cada tabla tiene sus propios indicadores con IDs únicos (ej: `c572db59b8cd109` para el INPC).
+
+### Referencias
+Son las dimensiones que contextualizan los datos:
+- **date**: Fechas (pueden tener diferentes nombres como `date`, `end_date`, `start_date`)
+- **standard**: Catálogos jerárquicos como `geography`, `sex`, `economic_activity`
+- **free**: Texto libre
+- **numeric**: Valores numéricos adicionales
+
+### Operaciones de agregación
+- `identity`: Valor original sin modificar
+- `sum`: Suma de valores
+- `avg`: Promedio
+
+## Fuentes de datos
+
+Tukan integra datos de múltiples fuentes oficiales mexicanas:
+
+| Fuente | Datos disponibles |
+|--------|-------------------|
+| **INEGI** | Censos, INPC, PIB, encuestas económicas |
+| **Banxico** | Tasas de interés, tipo de cambio, agregados monetarios |
+| **CNBV** | Estados financieros de bancos, SOFOMES, aseguradoras |
+| **SHCP** | Finanzas públicas, presupuesto, deuda |
+| **CONAPO** | Proyecciones de población |
+
+## Licencia
+
+MIT License - ver [LICENSE](LICENSE) para más detalles.
+
+## Links
+
+- [Sitio web](https://tukanmx.com)
+- [Documentación](https://github.com/TukanMx/tukan_python#readme)
+- [Reportar issues](https://github.com/TukanMx/tukan_python/issues)
+

tukan_python-0.2.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+tukan_python/__init__.py,sha256=pCYrURHfbVrGS_7FuII0l-3lz0TS7TaNGY2dfJ0NCNk,117
+tukan_python/query.py,sha256=xXm7OB1PKpg5f1PYdkWrnrLJ4L-t_TeAMHq0piZvwuY,7829
+tukan_python/tukan.py,sha256=DH61_iGFBDukWsjVfz7SOc_9_iQhlz2Ta5MGpMcmRJc,7326
+tukan_python-0.2.1.dist-info/licenses/LICENSE,sha256=4-KXxjgpAywK6yAHKLHmKoSJ2KqqKzOZYTcey0B0xGY,1064
+tukan_python-0.2.1.dist-info/METADATA,sha256=iVGf15amCtZBfaAradLA7D-qqBfOp76OE4A8CDRhrwg,11428
+tukan_python-0.2.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+tukan_python-0.2.1.dist-info/top_level.txt,sha256=64Ewy3_aoQ0bzlFumNTozOHZ60jP-EGxgC-duqmPlnM,13
+tukan_python-0.2.1.dist-info/RECORD,,

tukan_python-0.2.1.dist-info/WHEEL

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

tukan_python-0.2.1.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.2.1.dist-info/top_level.txt

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