tukan-python 0.2.1__tar.gz → 0.3.1__tar.gz

{tukan_python-0.2.1/tukan_python.egg-info → tukan_python-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tukan_python
-Version: 0.2.1
+Version: 0.3.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
@@ -300,6 +300,43 @@ q.set_table_name("mex_cnbv_cb_orig_by_gender_monthly")
 resultado = q.execute_query()
 ```
 
+### 7. Consultas SQL con `SQLQuery`
+
+Si prefieres escribir SQL directamente, puedes usar la clase `SQLQuery`. Las consultas se ejecutan con el motor Blizzard y la paginación se maneja automáticamente:
+
+```python
+from tukan_python import SQLQuery
+
+sq = SQLQuery(sql="""
+    SELECT
+        END_DATE AS end_date,
+        INSTITUTIONS_REF AS institutions,
+        INSTITUTIONS_NAME AS institutions__name,
+        INDICATOR_REF AS indicator,
+        INDICATOR_NAME AS indicator__name,
+        VALUE as value
+    FROM tukan_db.source_of_truth_full.mex_tukan_retail_sales_by_company
+    WHERE END_DATE = '2022-12-31'
+    LIMIT 100000 OFFSET 0
+""")
+
+resultado = sq.execute()
+print(resultado["df"])
+```
+
+Las tablas disponibles en SQL se encuentran en el esquema `tukan_db.source_of_truth_full`.
+
+#### Guardar una consulta SQL en tu perfil
+
+Puedes guardar tus consultas SQL para acceder a ellas desde la [aplicación web](https://app.tukanmx.com):
+
+```python
+sq = SQLQuery(sql="SELECT * FROM tukan_db.source_of_truth_full.mex_banxico_cf102 LIMIT 100")
+sq.save_sql_query(name="Tipo de cambio FIX", language="es")
+```
+
+Parámetros opcionales: `description`, `tags` (lista de strings).
+
 ## Conceptos clave
 
 ### Tablas

{tukan_python-0.2.1 → tukan_python-0.3.1}/README.md

@@ -272,6 +272,43 @@ q.set_table_name("mex_cnbv_cb_orig_by_gender_monthly")
 resultado = q.execute_query()
 ```
 
+### 7. Consultas SQL con `SQLQuery`
+
+Si prefieres escribir SQL directamente, puedes usar la clase `SQLQuery`. Las consultas se ejecutan con el motor Blizzard y la paginación se maneja automáticamente:
+
+```python
+from tukan_python import SQLQuery
+
+sq = SQLQuery(sql="""
+    SELECT
+        END_DATE AS end_date,
+        INSTITUTIONS_REF AS institutions,
+        INSTITUTIONS_NAME AS institutions__name,
+        INDICATOR_REF AS indicator,
+        INDICATOR_NAME AS indicator__name,
+        VALUE as value
+    FROM tukan_db.source_of_truth_full.mex_tukan_retail_sales_by_company
+    WHERE END_DATE = '2022-12-31'
+    LIMIT 100000 OFFSET 0
+""")
+
+resultado = sq.execute()
+print(resultado["df"])
+```
+
+Las tablas disponibles en SQL se encuentran en el esquema `tukan_db.source_of_truth_full`.
+
+#### Guardar una consulta SQL en tu perfil
+
+Puedes guardar tus consultas SQL para acceder a ellas desde la [aplicación web](https://app.tukanmx.com):
+
+```python
+sq = SQLQuery(sql="SELECT * FROM tukan_db.source_of_truth_full.mex_banxico_cf102 LIMIT 100")
+sq.save_sql_query(name="Tipo de cambio FIX", language="es")
+```
+
+Parámetros opcionales: `description`, `tags` (lista de strings).
+
 ## Conceptos clave
 
 ### Tablas

{tukan_python-0.2.1 → tukan_python-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tukan_python"
-version = "0.2.1"
+version = "0.3.1"
 description = "SDK de Python para acceder a datos oficiales de México a través de la API de Tukan."
 authors = [
     { name = "TukanMx", email = "contacto@tukanmx.com" }

tukan_python-0.3.1/tests/test_sql_query.py

@@ -0,0 +1,204 @@
+import base64
+
+import pandas as pd
+import pytest
+from unittest.mock import patch, MagicMock
+
+from tukan_python.query import SQLQuery
+from tukan_python.tukan import Tukan
+
+
+# --- Initialization ---
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+def test_sql_query_init_with_sql(mock_init):
+    sq = SQLQuery(sql="SELECT 1")
+    assert sq.sql == "SELECT 1"
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+def test_sql_query_init_without_sql(mock_init):
+    sq = SQLQuery()
+    assert sq.sql is None
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+def test_set_sql(mock_init):
+    sq = SQLQuery()
+    sq.set_sql("SELECT * FROM table")
+    assert sq.sql == "SELECT * FROM table"
+
+
+# --- Base64 encoding ---
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+def test_encode_sql(mock_init):
+    sq = SQLQuery(sql="SELECT 1")
+    encoded = sq._encode_sql()
+    decoded = base64.b64decode(encoded).decode("utf-8")
+    assert decoded == "SELECT 1"
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+def test_encode_sql_unicode(mock_init):
+    sq = SQLQuery(sql="SELECT * FROM tabla WHERE nombre = 'México'")
+    encoded = sq._encode_sql()
+    decoded = base64.b64decode(encoded).decode("utf-8")
+    assert "México" in decoded
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+def test_encode_sql_raises_when_no_sql(mock_init):
+    sq = SQLQuery()
+    with pytest.raises(ValueError, match="SQL query not set"):
+        sq._encode_sql()
+
+
+# --- Payload ---
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+def test_build_payload_no_offset(mock_init):
+    sq = SQLQuery(sql="SELECT 1")
+    payload = sq._build_payload()
+    assert "raw_sql" in payload
+    assert "offset" not in payload
+    assert base64.b64decode(payload["raw_sql"]).decode("utf-8") == "SELECT 1"
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+def test_build_payload_with_offset(mock_init):
+    sq = SQLQuery(sql="SELECT 1")
+    payload = sq._build_payload(offset=100)
+    assert payload["offset"] == 100
+    assert "raw_sql" in payload
+
+
+# --- Execution (mocked) ---
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+@patch.object(Tukan, "execute_post_operation")
+def test_execute_single_page(mock_post, mock_init):
+    mock_post.return_value = {
+        "data": [{"col1": "a", "col2": 1}, {"col1": "b", "col2": 2}],
+        "has_more_data": False,
+    }
+
+    sq = SQLQuery(sql="SELECT col1, col2 FROM table")
+    result = sq.execute()
+
+    assert isinstance(result["df"], pd.DataFrame)
+    assert len(result["df"]) == 2
+    assert len(result["data"]) == 2
+    assert result["data"][0]["col1"] == "a"
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+@patch.object(Tukan, "execute_post_operation")
+def test_execute_with_pagination(mock_post, mock_init):
+    mock_post.side_effect = [
+        {"data": [{"id": 1}, {"id": 2}], "has_more_data": True},
+        {"data": [{"id": 3}], "has_more_data": False},
+    ]
+
+    sq = SQLQuery(sql="SELECT id FROM table")
+    result = sq.execute()
+
+    assert len(result["df"]) == 3
+    assert len(result["data"]) == 3
+    assert mock_post.call_count == 2
+    # Verify offset was passed in the second call
+    second_call_payload = mock_post.call_args_list[1][0][0]
+    assert second_call_payload["offset"] == 2
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+@patch.object(Tukan, "execute_post_operation")
+def test_execute_empty_result(mock_post, mock_init):
+    mock_post.return_value = {"data": [], "has_more_data": False}
+
+    sq = SQLQuery(sql="SELECT 1 WHERE 1=0")
+    result = sq.execute()
+
+    assert len(result["df"]) == 0
+    assert result["data"] == []
+
+
+# --- API validation errors ---
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+@patch.object(Tukan, "execute_post_operation")
+def test_execute_raises_on_validation_error(mock_post, mock_init):
+    mock_post.return_value = {
+        "detail": "Raw SQL validation failed: Query must start with SELECT or WITH (for CTEs)"
+    }
+
+    sq = SQLQuery(sql="DROP TABLE users")
+    with pytest.raises(ValueError, match="Raw SQL validation failed"):
+        sq.execute()
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+@patch.object(Tukan, "execute_post_operation")
+def test_execute_raises_on_pagination_error(mock_post, mock_init):
+    mock_post.side_effect = [
+        {"data": [{"id": 1}], "has_more_data": True},
+        {"detail": "Some server error"},
+    ]
+
+    sq = SQLQuery(sql="SELECT id FROM table")
+    with pytest.raises(ValueError, match="Some server error"):
+        sq.execute()
+
+
+# --- String representation ---
+
+
+@patch.object(Tukan, "__init__", return_value=None)
+def test_str(mock_init):
+    sq = SQLQuery(sql="SELECT 1")
+    assert "SELECT 1" in str(sq)
+    assert "SELECT 1" in repr(sq)
+
+
+# --- Tukan.sql() convenience ---
+
+
+@patch.object(Tukan, "execute_post_operation")
+def test_tukan_sql_convenience(mock_post):
+    mock_post.return_value = {"data": [{"x": 1}], "has_more_data": False}
+
+    t = Tukan.__new__(Tukan)
+    t.token = "test_token"
+    t.env = "https://client.tukanmx.com/"
+    result = t.sql("SELECT x FROM table")
+
+    assert isinstance(result["df"], pd.DataFrame)
+    assert len(result["data"]) == 1
+    # Verify the endpoint used
+    call_args = mock_post.call_args
+    assert call_args[0][1] == "data/retrieve/?engine=blizzard"
+
+
+# --- Endpoint ---
+
+
+def test_endpoint_includes_engine_param():
+    assert SQLQuery.ENDPOINT == "data/retrieve/?engine=blizzard"
+
+
+# --- _from_tukan classmethod ---
+
+
+def test_from_tukan():
+    t = Tukan.__new__(Tukan)
+    t.token = "test"
+    t.env = "https://client.tukanmx.com/"
+
+    sq = SQLQuery._from_tukan(t, "SELECT 1")
+    assert sq.tukan is t
+    assert sq.sql == "SELECT 1"

tukan_python-0.3.1/tukan_python/__init__.py

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

{tukan_python-0.2.1 → tukan_python-0.3.1}/tukan_python/query.py

@@ -1,3 +1,4 @@
+import base64
 from typing import Literal, Optional
 
 import pandas as pd
@@ -207,3 +208,120 @@ class Query:
         if "indicators" in response:
             result["indicators"] = response["indicators"]
         return result
+
+
+class SQLQuery:
+    """Execute raw SQL queries against the Tukan API (blizzard engine).
+
+    The SQL string is base64-encoded and sent to the blizzard engine endpoint.
+    Pagination is handled automatically when the result set exceeds a single page.
+
+    Usage:
+        sq = SQLQuery(sql="SELECT * FROM tukan_db.source_of_truth_full.table_name LIMIT 1000")
+        result = sq.execute()
+        df = result["df"]
+    """
+
+    ENDPOINT = "data/retrieve/?engine=blizzard"
+
+    def __init__(self, token: Optional[str] = None, sql: Optional[str] = None):
+        self.tukan = Tukan(token)
+        self._sql = sql
+
+    def set_sql(self, sql: str) -> None:
+        self._sql = sql
+
+    @property
+    def sql(self) -> Optional[str]:
+        return self._sql
+
+    def _encode_sql(self) -> str:
+        if self._sql is None:
+            raise ValueError(
+                "SQL query not set. Call set_sql() or pass sql= to the constructor."
+            )
+        return base64.b64encode(self._sql.encode("utf-8")).decode("utf-8")
+
+    def _build_payload(self, offset: int = 0) -> dict:
+        payload = {"raw_sql": self._encode_sql()}
+        if offset > 0:
+            payload["offset"] = offset
+        return payload
+
+    def execute(self) -> dict:
+        """Execute the SQL query and return results with pagination.
+
+        Returns:
+            dict with keys:
+                - "df": pandas DataFrame with all result rows
+                - "data": raw list of dicts
+
+        Raises:
+            ValueError: If the API rejects the SQL (e.g. validation failure).
+        """
+        payload = self._build_payload()
+        response = self.tukan.execute_post_operation(payload, self.ENDPOINT)
+
+        if isinstance(response, dict) and "detail" in response:
+            raise ValueError(response["detail"])
+
+        all_data = response.get("data", [])
+        offset = len(all_data)
+
+        while response.get("has_more_data", False):
+            payload = self._build_payload(offset=offset)
+            response = self.tukan.execute_post_operation(payload, self.ENDPOINT)
+            if isinstance(response, dict) and "detail" in response:
+                raise ValueError(response["detail"])
+            page_data = response.get("data", [])
+            all_data.extend(page_data)
+            offset += len(page_data)
+
+        df = pd.DataFrame(all_data)
+        return {"df": df, "data": all_data}
+
+    @classmethod
+    def _from_tukan(cls, tukan_instance: "Tukan", sql: str) -> "SQLQuery":
+        instance = cls.__new__(cls)
+        instance.tukan = tukan_instance
+        instance._sql = sql
+        return instance
+
+    def save_sql_query(
+        self,
+        name: str,
+        language: str = "es",
+        description: str = "",
+        tags: Optional[list[str]] = None,
+    ) -> dict:
+        """Save this SQL query to the user's profile.
+
+        Args:
+            name: Display name for the saved query.
+            language: Language code (default "es").
+            description: Optional description.
+            tags: Optional list of tag strings.
+
+        Returns:
+            API response dict.
+        """
+        body = {
+            "name": name,
+            "description": description,
+            "language": language,
+            "query": {
+                "name": name,
+                "raw_sql": self._encode_sql(),
+                "language": language,
+                "retrieve_engine": "blizzard",
+                "use_vertical_mode": False,
+            },
+            "tags": tags if tags is not None else [],
+        }
+        return self.tukan.execute_post_operation(body, "visualizations/query/")
+
+    def __str__(self) -> str:
+        return f"SQLQuery(sql={self._sql!r})"
+
+    def __repr__(self) -> str:
+        return self.__str__()

{tukan_python-0.2.1 → tukan_python-0.3.1}/tukan_python/tukan.py

@@ -198,6 +198,76 @@ class Tukan:
         return df
 
 
+    def get_catalog_tables(
+        self, page: int = 1, page_size: int = 40, language: str = "es"
+    ) -> list[dict]:
+        """List available catalog tables.
+
+        Args:
+            page: Page number (1-indexed).
+            page_size: Number of results per page.
+            language: Language code ('es' or 'en').
+
+        Returns:
+            List of catalog table dicts.
+        """
+        url = f"{self.env}data/catalogue_table/"
+        headers = {"Authorization": f"token {self.token}"}
+        params = {
+            "page_size": page_size,
+            "current": page,
+            "api": "data",
+            "resource": "catalogue_table",
+            "language": language,
+        }
+        request_partial = wrapped_partial(
+            requests.get, url=url, headers=headers, params=params, timeout=30
+        )
+        response = self.persistent_request(request_partial)
+        if response.status_code >= 300:
+            raise Exception(f"Failed to list catalog tables: {response.text}")
+        return response.json()
+
+    def export_catalog_table(self, catalogue_id: str) -> pd.DataFrame:
+        """Export a catalog table as a DataFrame.
+
+        Args:
+            catalogue_id: The catalog table ID to export.
+
+        Returns:
+            DataFrame with the catalog table data.
+        """
+        url = f"{self.env}data/retrieve_json_catalogue/{catalogue_id}/{self.token}/"
+        request_partial = wrapped_partial(requests.get, url=url, timeout=30)
+        response = self.persistent_request(request_partial)
+        if response.status_code >= 300:
+            raise Exception(f"Failed to export catalog table: {response.text}")
+        data = response.json()
+        return pd.DataFrame(data)
+
+    def sql(self, query: str) -> dict:
+        """Execute a raw SQL query against the Tukan API.
+
+        The SQL string is base64-encoded and sent to the blizzard engine.
+        Pagination is handled automatically for large result sets.
+
+        Args:
+            query: SQL query string
+                (e.g. "SELECT * FROM tukan_db.source_of_truth_full.table_name LIMIT 1000")
+
+        Returns:
+            dict with keys:
+                - "df": pandas DataFrame with query results
+                - "data": raw list of dicts
+
+        Raises:
+            ValueError: If the API rejects the SQL (e.g. validation failure).
+        """
+        from tukan_python.query import SQLQuery
+
+        return SQLQuery._from_tukan(self, query).execute()
+
+
 def wrapped_partial(func, *args, **kwargs) -> Callable:
     partial_func = partial(func, *args, **kwargs)
     update_wrapper(partial_func, func)

{tukan_python-0.2.1 → tukan_python-0.3.1/tukan_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tukan_python
-Version: 0.2.1
+Version: 0.3.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
@@ -300,6 +300,43 @@ q.set_table_name("mex_cnbv_cb_orig_by_gender_monthly")
 resultado = q.execute_query()
 ```
 
+### 7. Consultas SQL con `SQLQuery`
+
+Si prefieres escribir SQL directamente, puedes usar la clase `SQLQuery`. Las consultas se ejecutan con el motor Blizzard y la paginación se maneja automáticamente:
+
+```python
+from tukan_python import SQLQuery
+
+sq = SQLQuery(sql="""
+    SELECT
+        END_DATE AS end_date,
+        INSTITUTIONS_REF AS institutions,
+        INSTITUTIONS_NAME AS institutions__name,
+        INDICATOR_REF AS indicator,
+        INDICATOR_NAME AS indicator__name,
+        VALUE as value
+    FROM tukan_db.source_of_truth_full.mex_tukan_retail_sales_by_company
+    WHERE END_DATE = '2022-12-31'
+    LIMIT 100000 OFFSET 0
+""")
+
+resultado = sq.execute()
+print(resultado["df"])
+```
+
+Las tablas disponibles en SQL se encuentran en el esquema `tukan_db.source_of_truth_full`.
+
+#### Guardar una consulta SQL en tu perfil
+
+Puedes guardar tus consultas SQL para acceder a ellas desde la [aplicación web](https://app.tukanmx.com):
+
+```python
+sq = SQLQuery(sql="SELECT * FROM tukan_db.source_of_truth_full.mex_banxico_cf102 LIMIT 100")
+sq.save_sql_query(name="Tipo de cambio FIX", language="es")
+```
+
+Parámetros opcionales: `description`, `tags` (lista de strings).
+
 ## Conceptos clave
 
 ### Tablas

{tukan_python-0.2.1 → tukan_python-0.3.1}/tukan_python.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 tests/test_query.py
+tests/test_sql_query.py
 tukan_python/__init__.py
 tukan_python/query.py
 tukan_python/tukan.py

tukan_python-0.2.1/tukan_python/__init__.py

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