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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tukan_python
-Version: 0.3.1
+Version: 0.5.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
@@ -337,6 +337,49 @@ sq.save_sql_query(name="Tipo de cambio FIX", language="es")
 
 Parámetros opcionales: `description`, `tags` (lista de strings).
 
+## Tukan Atlas (beta)
+
+El módulo Atlas da acceso a la [API de Tukan Atlas](https://docs.tukanmx.com/es/atlas): más de 420 indicadores geoespaciales, lugares comerciales, polígonos e isócronas para México. Requiere acceso al beta (contacto@tukanmx.com).
+
+```python
+from tukan_python import Tukan
+
+atlas = Tukan().atlas
+
+# ¿Qué marcas hay a 1 km de un punto?
+df = atlas.places_count(group_by="brand", latitude=19.4326, longitude=-99.1332, radius_km=1)
+
+# Población menor de 5 años por municipio de la CDMX
+df = atlas.latest(indicator_ids=[18], entity_type="MUNICIPALITY", within=("STATE", "09"))
+
+# Coordenada → jerarquía geográfica completa
+info = atlas.pinpoint(19.4326, -99.1332)
+```
+
+Los filtros de ubicación aceptan `latitude`/`longitude`/`radius_km`, `address`, `zipcode`/`municipality`/`state`, `entity_type`/`entity_codes`, o un dict `geo_filter=` crudo. Los polígonos aceptan GeoJSON o cualquier objeto con `__geo_interface__` (shapely, geopandas) — sin dependencias geoespaciales adicionales.
+
+## Manejo de errores
+
+Desde la versión 0.4.0, los errores de la API **lanzan excepciones tipadas** (antes podían regresar como diccionarios):
+
+```python
+from tukan_python import Tukan, TukanAPIError, TukanValidationError
+
+client = Tukan()
+try:
+    result = client.sql("SELECT * FROM tukan_db.source_of_truth_full.mex_banxico_cf102 LIMIT 10")
+except TukanValidationError as e:
+    print(f"Consulta rechazada: {e.detail}")  # ej. SQL inválido (HTTP 400)
+except TukanAPIError as e:
+    print(f"Error de la API {e.status_code}: {e}")
+```
+
+- `TukanAuthError` — token inválido o sin permisos (HTTP 401/403)
+- `TukanValidationError` — consulta rechazada por la API (HTTP 400/422)
+- `TukanAPIError` — cualquier otro error, o API inaccesible tras reintentos
+
+Las tres heredan de `ValueError`, por lo que el código existente que hace `except ValueError` sigue funcionando. Los reintentos son automáticos (3 intentos con backoff) solo para fallas de red y errores 5xx.
+
 ## Conceptos clave
 
 ### Tablas

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

@@ -309,6 +309,49 @@ sq.save_sql_query(name="Tipo de cambio FIX", language="es")
 
 Parámetros opcionales: `description`, `tags` (lista de strings).
 
+## Tukan Atlas (beta)
+
+El módulo Atlas da acceso a la [API de Tukan Atlas](https://docs.tukanmx.com/es/atlas): más de 420 indicadores geoespaciales, lugares comerciales, polígonos e isócronas para México. Requiere acceso al beta (contacto@tukanmx.com).
+
+```python
+from tukan_python import Tukan
+
+atlas = Tukan().atlas
+
+# ¿Qué marcas hay a 1 km de un punto?
+df = atlas.places_count(group_by="brand", latitude=19.4326, longitude=-99.1332, radius_km=1)
+
+# Población menor de 5 años por municipio de la CDMX
+df = atlas.latest(indicator_ids=[18], entity_type="MUNICIPALITY", within=("STATE", "09"))
+
+# Coordenada → jerarquía geográfica completa
+info = atlas.pinpoint(19.4326, -99.1332)
+```
+
+Los filtros de ubicación aceptan `latitude`/`longitude`/`radius_km`, `address`, `zipcode`/`municipality`/`state`, `entity_type`/`entity_codes`, o un dict `geo_filter=` crudo. Los polígonos aceptan GeoJSON o cualquier objeto con `__geo_interface__` (shapely, geopandas) — sin dependencias geoespaciales adicionales.
+
+## Manejo de errores
+
+Desde la versión 0.4.0, los errores de la API **lanzan excepciones tipadas** (antes podían regresar como diccionarios):
+
+```python
+from tukan_python import Tukan, TukanAPIError, TukanValidationError
+
+client = Tukan()
+try:
+    result = client.sql("SELECT * FROM tukan_db.source_of_truth_full.mex_banxico_cf102 LIMIT 10")
+except TukanValidationError as e:
+    print(f"Consulta rechazada: {e.detail}")  # ej. SQL inválido (HTTP 400)
+except TukanAPIError as e:
+    print(f"Error de la API {e.status_code}: {e}")
+```
+
+- `TukanAuthError` — token inválido o sin permisos (HTTP 401/403)
+- `TukanValidationError` — consulta rechazada por la API (HTTP 400/422)
+- `TukanAPIError` — cualquier otro error, o API inaccesible tras reintentos
+
+Las tres heredan de `ValueError`, por lo que el código existente que hace `except ValueError` sigue funcionando. Los reintentos son automáticos (3 intentos con backoff) solo para fallas de red y errores 5xx.
+
 ## Conceptos clave
 
 ### Tablas

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tukan_python"
-version = "0.3.1"
+version = "0.5.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" }
@@ -40,6 +40,10 @@ Documentation = "https://github.com/TukanMx/tukan_python#readme"
 [tool.setuptools.packages.find]
 include = ["tukan_python*"]
 
+[tool.black]
+# Strings should be single quoted.
+skip-string-normalization = true
+
 [dependency-groups]
 dev = [
     "build>=1.4.0",

tukan_python-0.5.0/tests/test_atlas.py

@@ -0,0 +1,354 @@
+'''Tests for the Atlas module through the transport seam — no network.'''
+
+import pandas as pd
+import pytest
+
+from conftest import FakeTransport
+from tukan_python import Tukan
+from tukan_python.atlas import Atlas
+from tukan_python.atlas.client import _as_geojson, _build_geo_filter
+
+
+def make_atlas(responses=None):
+    transport = FakeTransport(responses)
+    return Atlas(Tukan(token='test-token', transport=transport)), transport
+
+
+# --- geo filter builder -------------------------------------------------
+
+
+def test_geo_filter_point():
+    gf = _build_geo_filter(latitude=19.43, longitude=-99.13, radius_km=2)
+    assert gf == {'latitude': 19.43, 'longitude': -99.13, 'radius_km': 2}
+
+
+def test_geo_filter_address():
+    assert _build_geo_filter(address='Reforma 222') == {'address': 'Reforma 222'}
+
+
+def test_geo_filter_zipcode_shortcut():
+    gf = _build_geo_filter(zipcode='06600')
+    assert gf == {'entity_type': 'ZIPCODE', 'entity_codes': ['06600']}
+
+
+def test_geo_filter_municipality_list():
+    gf = _build_geo_filter(municipality=['09015', '09016'])
+    assert gf == {'entity_type': 'MUNICIPALITY', 'entity_codes': ['09015', '09016']}
+
+
+def test_geo_filter_entity_type():
+    gf = _build_geo_filter(entity_type='STATE', entity_codes='09')
+    assert gf == {'entity_type': 'STATE', 'entity_codes': ['09']}
+
+
+def test_geo_filter_passthrough():
+    raw = {'latitude': 1, 'longitude': 2, 'future_field': 3}
+    assert _build_geo_filter(geo_filter=raw) is raw
+
+
+def test_geo_filter_rejects_mixed_modes():
+    with pytest.raises(ValueError, match='only one location mode'):
+        _build_geo_filter(latitude=19.4, longitude=-99.1, zipcode='06600')
+
+
+def test_geo_filter_rejects_lat_without_lng():
+    with pytest.raises(ValueError, match='together'):
+        _build_geo_filter(latitude=19.4)
+
+
+def test_geo_filter_rejects_bad_entity_type():
+    with pytest.raises(ValueError, match='entity_type must be one of'):
+        _build_geo_filter(entity_type='POSTAL_CODE', entity_codes=['06600'])
+
+
+def test_geo_filter_rejects_passthrough_plus_keywords():
+    with pytest.raises(ValueError, match='cannot be combined'):
+        _build_geo_filter(geo_filter={'address': 'x'}, zipcode='06600')
+
+
+def test_geo_filter_requires_a_mode():
+    with pytest.raises(ValueError, match='exactly one location'):
+        _build_geo_filter()
+    assert _build_geo_filter(required=False) is None
+
+
+# --- polygon normalization ----------------------------------------------
+
+
+def test_as_geojson_accepts_dict():
+    poly = {'type': 'Polygon', 'coordinates': [[[0, 0], [1, 0], [1, 1], [0, 0]]]}
+    assert _as_geojson(poly) == poly
+
+
+def test_as_geojson_accepts_geo_interface():
+    class FakeShape:
+        __geo_interface__ = {
+            'type': 'Polygon',
+            'coordinates': [[[0, 0], [1, 1], [0, 1], [0, 0]]],
+        }
+
+    assert _as_geojson(FakeShape())['type'] == 'Polygon'
+
+
+def test_as_geojson_rejects_non_polygon():
+    with pytest.raises(ValueError, match='GeoJSON'):
+        _as_geojson({'type': 'Point', 'coordinates': [0, 0]})
+
+
+# --- catalogs and pagination --------------------------------------------
+
+
+def test_indicators_returns_dataframe():
+    atlas, transport = make_atlas(
+        {
+            'tukan-atlas/indicators/': {
+                'count': 2,
+                'results': [
+                    {'indicator_id': 1, 'mnemonic': 'a'},
+                    {'indicator_id': 2, 'mnemonic': 'b'},
+                ],
+            }
+        }
+    )
+    df = atlas.indicators(search='crime')
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 2
+    assert df.attrs['count'] == 2
+    method, endpoint, params = transport.calls[0]
+    assert method == 'GET'
+    assert params['search'] == 'crime'
+    assert params['page'] == 1
+
+
+def test_catalog_paginates_until_count():
+    page1 = {'count': 3, 'results': [{'id': 1}, {'id': 2}]}
+    page2 = {'count': 3, 'results': [{'id': 3}]}
+    atlas, transport = make_atlas({'tukan-atlas/brands/': [page1, page2]})
+    df = atlas.brands()
+    assert len(df) == 3
+    assert transport.calls[1][2]['page'] == 2
+
+
+def test_borders():
+    atlas, _ = make_atlas(
+        {
+            'tukan-atlas/geo-entities/42/borders/': {
+                'count': 1,
+                'results': [{'entity_code': '09014'}],
+            }
+        }
+    )
+    df = atlas.borders(42)
+    assert df.iloc[0]['entity_code'] == '09014'
+
+
+# --- statistics ---------------------------------------------------------
+
+
+def test_latest_builds_geo_filter_with_within():
+    atlas, transport = make_atlas(
+        {
+            'tukan-atlas/latest/': {
+                'count': 1,
+                'results': [{'entity_code': '06600', 'value': 5}],
+            }
+        }
+    )
+    df = atlas.latest(
+        indicator_ids=[2], entity_type='ZIPCODE', within=('MUNICIPALITY', '09015')
+    )
+    assert len(df) == 1
+    payload = transport.calls[0][2]
+    assert payload['indicator_ids'] == [2]
+    assert payload['geo_filter'] == {
+        'entity_type_id': 'ZIPCODE',
+        'within': {'entity_type_id': 'MUNICIPALITY', 'entity_code': '09015'},
+    }
+
+
+def test_latest_requires_indicators_or_collections():
+    atlas, _ = make_atlas()
+    with pytest.raises(ValueError, match='indicator_ids and/or collection_ids'):
+        atlas.latest()
+
+
+def test_latest_entity_type_requires_within():
+    atlas, _ = make_atlas()
+    with pytest.raises(ValueError, match='within is required'):
+        atlas.latest(indicator_ids=[1], entity_type='ZIPCODE')
+
+
+def test_polygon_context():
+    atlas, transport = make_atlas(
+        {'tukan-atlas/polygon-context/': {'data': {'101': 5000}, 'context': {}}}
+    )
+    poly = {'type': 'Polygon', 'coordinates': [[[0, 0], [1, 0], [1, 1], [0, 0]]]}
+    result = atlas.polygon_context(poly, indicator_ids=[101])
+    assert result['data'] == {'101': 5000}
+    assert transport.calls[0][2] == {'polygon': poly, 'indicators': [101]}
+
+
+# --- places -------------------------------------------------------------
+
+
+def test_places_count():
+    atlas, transport = make_atlas(
+        {
+            'tukan-atlas/places/grouped/': {
+                'count': 2,
+                'geo_context': {'zipcode': '06600'},
+                'results': [
+                    {'brand': 'OXXO', 'total': 12},
+                    {'brand': 'Soriana', 'total': 1},
+                ],
+            }
+        }
+    )
+    df = atlas.places_count(group_by='brand', zipcode='06600')
+    assert len(df) == 2
+    assert df.attrs['geo_context'] == {'zipcode': '06600'}
+    payload = transport.calls[0][2]
+    assert payload['geo_filter'] == {
+        'entity_type': 'ZIPCODE',
+        'entity_codes': ['06600'],
+    }
+
+
+def test_places_count_rejects_bad_group_by():
+    atlas, _ = make_atlas()
+    with pytest.raises(ValueError, match='group_by'):
+        atlas.places_count(group_by='color', zipcode='06600')
+
+
+def test_places_paginates_and_filters():
+    page1 = {'count': 3, 'results': [{'id': 1}, {'id': 2}]}
+    page2 = {'count': 3, 'results': [{'id': 3}]}
+    atlas, transport = make_atlas({'tukan-atlas/places/detail/': [page1, page2]})
+    df = atlas.places(zipcode='06600', brand_ids=[7], page_size=2)
+    assert len(df) == 3
+    first_payload = transport.calls[0][2]
+    assert first_payload['filters'] == {'brand_ids': [7]}
+    assert transport.calls[1][2]['page'] == 2
+
+
+def test_places_isochrone_flattens_nested_places():
+    # The API returns one result per ORIGIN with its places nested inside.
+    atlas, transport = make_atlas(
+        {
+            'tukan-atlas/places/isochrone/': {
+                'results': [
+                    {
+                        'index': 0,
+                        'latitude': 19.43,
+                        'longitude': -99.13,
+                        'area_km2': 0.42,
+                        'places_count': 2,
+                        'places': [{'brand_name': 'OXXO'}, {'brand_name': 'Soriana'}],
+                    }
+                ],
+                'isochrone_errors': [],
+            }
+        }
+    )
+    df = atlas.places_isochrone(
+        coordinates=(19.43, -99.13), travel_mode='WALK', duration_minutes=10
+    )
+    assert len(df) == 2
+    assert df.iloc[0]['brand_name'] == 'OXXO'
+    assert df.iloc[0]['origin_index'] == 0
+    assert df.iloc[1]['origin_latitude'] == 19.43
+    assert df.attrs['origins'][0]['area_km2'] == 0.42
+    payload = transport.calls[0][2]
+    assert payload['coordinates'] == [[19.43, -99.13]]
+    assert payload['travel_mode'] == 'WALK'
+
+
+def test_places_isochrone_validates_travel_mode():
+    atlas, _ = make_atlas()
+    with pytest.raises(ValueError, match='travel_mode'):
+        atlas.places_isochrone(coordinates=(1, 2), travel_mode='TELEPORT')
+
+
+# --- pinpoint -----------------------------------------------------------
+
+
+def test_pinpoint_single_returns_dict():
+    atlas, transport = make_atlas(
+        {
+            'tukan-atlas/pinpoint/': {
+                'count': 1,
+                'results': [{'state': 'Ciudad de México'}],
+            }
+        }
+    )
+    result = atlas.pinpoint(19.43, -99.13)
+    assert result == {'state': 'Ciudad de México'}
+    assert transport.calls[0][2]['latitude'] == 19.43
+
+
+def test_pinpoint_batch_paginates():
+    page1 = {
+        'count': 3,
+        'results': [
+            {'latitude': 1, 'longitude': 2, 'state': 'A'},
+            {'latitude': 3, 'longitude': 4, 'state': 'B'},
+        ],
+    }
+    page2 = {'count': 3, 'results': [{'latitude': 5, 'longitude': 6, 'state': 'C'}]}
+    atlas, transport = make_atlas(
+        {
+            'tukan-atlas/pinpoint/?page=1&page_size=2': page1,
+            'tukan-atlas/pinpoint/?page=2&page_size=2': page2,
+        }
+    )
+    df = atlas.pinpoint_batch(coordinates=[(1, 2), (3, 4), (5, 6)], page_size=2)
+    assert len(df) == 3
+    assert df['state'].tolist() == ['A', 'B', 'C']
+
+
+def test_pinpoint_batch_reexpands_deduplicated_rows():
+    # The API dedupes repeated coordinates (the-tukan #1444); the SDK must
+    # return one row per input, in input order, safe for positional joins.
+    atlas, _ = make_atlas(
+        {
+            'tukan-atlas/pinpoint/?page=1&page_size=1000': {
+                'count': 2,
+                'results': [
+                    {'latitude': 19.43, 'longitude': -99.13, 'state': 'CDMX'},
+                    {'latitude': 20.66, 'longitude': -103.35, 'state': 'Jalisco'},
+                ],
+            }
+        }
+    )
+    df = atlas.pinpoint_batch(
+        coordinates=[(19.43, -99.13), (20.66, -103.35), (19.43, -99.13)]
+    )
+    assert len(df) == 3
+    assert df['state'].tolist() == ['CDMX', 'Jalisco', 'CDMX']
+    assert df['input_index'].tolist() == [0, 1, 2]
+
+
+def test_pinpoint_batch_marks_missing_coordinates():
+    atlas, _ = make_atlas(
+        {
+            'tukan-atlas/pinpoint/?page=1&page_size=1000': {
+                'count': 1,
+                'results': [{'latitude': 19.43, 'longitude': -99.13, 'state': 'CDMX'}],
+            }
+        }
+    )
+    df = atlas.pinpoint_batch(coordinates=[(19.43, -99.13), (0.0, 0.0)])
+    assert len(df) == 2
+    assert df.iloc[1]['error'] == 'No result returned by the API for this coordinate'
+
+
+# --- access pattern -----------------------------------------------------
+
+
+def test_tukan_atlas_property_is_lazy_and_cached():
+    t = Tukan(token='test-token', transport=FakeTransport())
+    assert t._atlas is None
+    atlas = t.atlas
+    assert isinstance(atlas, Atlas)
+    assert t.atlas is atlas
+    assert atlas._transport is t._transport

tukan_python-0.5.0/tests/test_mcp_contract.py

@@ -0,0 +1,141 @@
+'''Contract tests: the interface the customer-facing MCP server consumes.
+
+The Tukan MCP (the-tukan/tukan_mcp) crosses the SDK seam at exactly the
+members tested here. If any of these tests break, the MCP breaks — change
+the MCP first, then the test, never the other way around.
+
+All tests run against FakeTransport: fast, no token, no network.
+'''
+
+import pandas as pd
+import pytest
+
+from tukan_python import (
+    SQLQuery,
+    Tukan,
+    TukanAPIError,
+    TukanValidationError,
+    __version__,
+)
+from conftest import FakeTransport
+
+
+def make_sql_query(sql, responses):
+    sq = SQLQuery.__new__(SQLQuery)
+    sq.tukan = Tukan(token='test-token', transport=FakeTransport(responses))
+    sq._sql = sql
+    return sq
+
+
+def test_tukan_constructor_accepts_token():
+    t = Tukan(token='abc')
+    assert t.token == 'abc'
+
+
+def test_tukan_constructor_requires_some_token(monkeypatch):
+    monkeypatch.delenv('API_TUKAN', raising=False)
+    with pytest.raises(ValueError):
+        Tukan()
+
+
+def test_sqlquery_execute_returns_df_and_data():
+    sq = make_sql_query(
+        'SELECT 1',
+        {SQLQuery.ENDPOINT: {'data': [{'x': 1}], 'has_more_data': False}},
+    )
+    result = sq.execute()
+    # The MCP reads result['df'] and result['data'].
+    assert set(result.keys()) == {'df', 'data'}
+    assert isinstance(result['df'], pd.DataFrame)
+    assert isinstance(result['data'], list)
+
+
+def test_sqlquery_execute_raises_valueerror_on_api_rejection():
+    # The MCP catches ValueError around execute(); TukanValidationError must
+    # remain a ValueError subclass.
+    sq = make_sql_query(
+        'DROP TABLE x',
+        {
+            SQLQuery.ENDPOINT: TukanValidationError(
+                'Raw SQL validation failed', status_code=400
+            )
+        },
+    )
+    with pytest.raises(ValueError):
+        sq.execute()
+
+
+def test_sqlquery_endpoint_is_blizzard():
+    assert SQLQuery.ENDPOINT == 'data/retrieve/?engine=blizzard'
+
+
+def test_save_sql_query_signature_and_response():
+    sq = make_sql_query('SELECT 1', {'visualizations/query/': {'saved': True}})
+    response = sq.save_sql_query(name='n', language='es', description='d')
+    assert response == {'saved': True}
+
+
+def test_tukan_sql_convenience():
+    t = Tukan(
+        token='test-token',
+        transport=FakeTransport(
+            {SQLQuery.ENDPOINT: {'data': [{'x': 1}], 'has_more_data': False}}
+        ),
+    )
+    result = t.sql('SELECT x FROM table')
+    assert isinstance(result['df'], pd.DataFrame)
+    assert len(result['data']) == 1
+
+
+def test_get_table_metadata_returns_response_dict():
+    t = Tukan(
+        token='test-token',
+        transport=FakeTransport({'data/metadata/': {'data_table': {'id': 't'}}}),
+    )
+    assert t.get_table_metadata('t')['data_table']['id'] == 't'
+
+
+def test_all_indicators_for_table_returns_list():
+    t = Tukan(
+        token='test-token',
+        transport=FakeTransport({'data/': {'data': [{'ref': 'a'}, {'ref': 'b'}]}}),
+    )
+    indicators = t.all_indicators_for_table('t')
+    assert indicators == [{'ref': 'a'}, {'ref': 'b'}]
+
+
+def test_get_reference_flat_tree_returns_dataframe():
+    csv = 'raw|ref|name|in_table\n1|abc|Foo|True\n2|def|Bar|False'
+    t = Tukan(
+        token='test-token',
+        transport=FakeTransport({'data/visualizations/flat-tree/t/geography/': csv}),
+    )
+    df = t.get_reference_flat_tree('t', 'geography')
+    assert list(df.columns) == ['raw', 'ref', 'name', 'in_table']
+    only = t.get_reference_flat_tree('t', 'geography', only_in_table=True)
+    assert len(only) == 1
+
+
+def test_get_catalog_tables_returns_json():
+    t = Tukan(
+        token='test-token',
+        # Outer list is FakeTransport's response queue; the response is a list.
+        transport=FakeTransport({'data/catalogue_table/': [[{'id': 'cat1'}]]}),
+    )
+    assert t.get_catalog_tables() == [{'id': 'cat1'}]
+
+
+def test_execute_post_operation_still_available():
+    # Deprecated but documented; kept as a thin forwarder.
+    t = Tukan(token='test-token', transport=FakeTransport({'data/': {'ok': 1}}))
+    assert t.execute_post_operation({'p': 1}, 'data/') == {'ok': 1}
+
+
+def test_exceptions_are_exported():
+    from tukan_python import TukanAuthError  # noqa: F401
+
+    assert issubclass(TukanAPIError, ValueError)
+
+
+def test_version():
+    assert __version__ == '0.5.0'