---
name: add_basemap_with_timeout
kind: function
lang: py
domain: geo
version: "1.0.0"
purity: impure
signature: "def add_basemap_with_timeout(ax: Axes, zoom: int = 9, cache_dir: str | Path | None = None, timeout_s: float = 15.0) -> bool"
description: "Igual que add_basemap_osm pero con timeout SIGALRM. Retorna True si cargó el basemap, False si timeout o error. Solo Unix — en Windows retorna False inmediatamente."
tags: [geo, visualization, basemap, osm, contextily, matplotlib, timeout]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: ["contextily", "matplotlib", "signal"]
params:
  - name: ax
    desc: "matplotlib Axes con extensión proyectada en EPSG:3857."
  - name: zoom
    desc: "Nivel de zoom de los tiles (1-19)."
  - name: cache_dir
    desc: "Directorio opcional para cachear tiles."
  - name: timeout_s
    desc: "Segundos máximos para la descarga de tiles. Default 15.0."
output: "True si el basemap se añadió correctamente; False en timeout, error de red, o Windows."
tested: true
tests:
  - "timeout muy corto retorna False sin colgar"
test_file_path: "python/functions/geo/tests/test_add_basemap_with_timeout.py"
file_path: "python/functions/geo/add_basemap_with_timeout.py"
source_repo: "internal:footprint_aurgi"
source_license: "internal-aurgi"
source_file: "ponderacion_isochronas/src/reporte_clientes_aurgi.py:69"
---

## Ejemplo

```python
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
from geo.add_basemap_with_timeout import add_basemap_with_timeout

fig, ax = plt.subplots()
ax.set_xlim(-430000, -350000)
ax.set_ylim(4500000, 4600000)
ok = add_basemap_with_timeout(ax, zoom=10, timeout_s=20.0)
if not ok:
    print("Basemap no disponible (sin red o timeout)")
fig.savefig("mapa.png")
```

## Notas

Limitación: usa SIGALRM que solo está disponible en Unix/Linux/macOS. En Windows retorna False inmediatamente sin intentar la descarga. El timeout usa `signal.setitimer(ITIMER_REAL, ...)` que tiene resolución de microsegundos. El handler original de SIGALRM se restaura en el bloque finally.