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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tukan_python
-Version: 0.2.1
+Version: 0.3.0
 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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tukan_python"
-version = "0.2.1"
+version = "0.3.0"
 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.0/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.0/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.0}/tukan_python/query.py

@@ -1,3 +1,4 @@
+import base64
 from typing import Literal, Optional
 
 import pandas as pd
@@ -207,3 +208,87 @@ 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 __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.0}/tukan_python/tukan.py

@@ -198,6 +198,29 @@ class Tukan:
         return df
 
 
+    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.0/tukan_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tukan_python
-Version: 0.2.1
+Version: 0.3.0
 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

{tukan_python-0.2.1 → tukan_python-0.3.0}/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__"]