Metadata-Version: 2.4
Name: surfia-pedagogia
Version: 0.5.0
Summary: Láminas visuales en español para comprender código Python y sus conceptos
Author: SURF IA
License-Expression: MIT
Keywords: education,python,jupyter,colab,spanish
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Education
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: notebook
Requires-Dist: ipython>=7.34; extra == "notebook"
Provides-Extra: dev
Requires-Dist: ipython>=7.34; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Requires-Dist: nbformat>=5; extra == "dev"
Dynamic: license-file

# SURF IA · Aprende a leer código Python

**0.5.0 · Versión beta · Código abierto · Licencia MIT · Python 3.10 o superior.**

SURF IA acompaña el código con láminas visuales en español: una idea sencilla, los datos que se usan, lo que hace Python y cómo entender el resultado. Combina bloques, flechas, conceptos breves y detalles desplegables para ayudar a quienes están aprendiendo a programar.

Puede usarse en tus propios notebooks y archivos Python; no requiere el proyecto SAG, un dataset concreto, un LLM ni claves de API.

## Instalación

En un notebook de Google Colab, Jupyter o VS Code, ejecuta:

```python
%pip install surfia-pedagogia
```

En la siguiente celda:

```python
import surfia
```

Las próximas celdas generan sus láminas automáticamente. Si actualizas una versión ya importada, reinicia el kernel y vuelve a importar. En VS Code, selecciona el mismo entorno de Python donde instalaste la biblioteca.

Desde una terminal, usa `python -m pip install surfia-pedagogia`. La instalación por nombre requiere que la distribución esté disponible en PyPI. Instala por separado las bibliotecas que use tu código, como NumPy, pandas o Matplotlib.

## Probar con tu código en un notebook

```python
lecturas = [60, 65, 70, 75]
promedio = sum(lecturas) / len(lecturas)
print(promedio)
```

Ejecuta esa celda una vez. Python muestra su resultado y SURF IA añade la explicación. Las láminas no vuelven a ejecutar el código.

- `surfia.desactivar()` detiene las láminas.
- `surfia.activar()` las reactiva.
- `surfia.diagnostico()` muestra versión, estado y motivos de omisión.
- `# surfia: omitir` en una celda omite su lámina.

Jupyter y Colab incluyen IPython. En otro entorno que necesite la integración, usa `python -m pip install "surfia-pedagogia[notebook]"`. El núcleo de SURF IA no tiene dependencias externas. Para ver las láminas automáticamente, ejecuta celdas de un notebook; un script en una terminal puede exportar la explicación a HTML.

## Explicar texto o un archivo sin ejecutarlo

```python
import surfia

html = surfia.generar('total = sum([1, 2, 3])')
surfia.guardar('total = sum([1, 2, 3])', 'explicacion.html')
surfia.explicar_archivo('mi_codigo.py')  # crea mi_codigo.surfia.html
```

Desde una terminal, después de instalar la biblioteca:

```bash
surfia mi_codigo.py --salida explicacion.html
# También funciona:
python -m surfia mi_codigo.py --salida explicacion.html
```

El archivo `.py` se lee como texto: no se ejecuta ni se importa. No hace falta instalar los módulos que aparecen en ese código para explicarlo. Los archivos de salida existentes están protegidos; usa `sobrescribir=True` o `--sobrescribir` solo si quieres reemplazarlos.

## Qué puede explicar

| Código | Explicación disponible |
|---|---|
| Variables, listas, diccionarios y operaciones | Datos, asignaciones, selecciones y expresiones |
| `if` / `elif` / `else` | Caminos posibles, sin afirmar cuál se ejecutó |
| Funciones, bucles, clases, `with`, `try`, `match` | Propósito y lectura de las instrucciones internas en desplegables |
| Imports conocidos | Para qué sirve el recurso y su nombre de uso |
| pandas y operaciones comunes | Lectura, selección, duplicados, resúmenes, dispersión, correlación y exportación |
| StandardScaler reconocido en la misma celda | Ajuste de referencia y cambio de escala con opciones compatibles |
| Funciones o librerías desconocidas | Lectura de su estructura, código íntegro y explicación general |

**No promete comprender cualquier biblioteca ni cualquier intención del autor.** Los nombres de métodos se interpretan según usos habituales; no se comprueban tipos reales. Tampoco se observa el contenido de variables ni se inventan valores calculados. Esos resultados permanecen en las salidas originales.

El diagrama principal no simula bucles, llamadas ni excepciones. Los cuerpos de funciones y estructuras compuestas se explican en detalle separado. Las dependencias entre nombres se limitan a la celda: no resuelven mutaciones, alias ni el estado de otros archivos.

La sintaxis admitida depende de la versión de Python instalada (mínimo 3.10). Las celdas con comandos de IPython como `%pip`, `%%bash` o `!ls`, errores de sintaxis o de ejecución no reciben una lámina normal. Consulta `diagnostico()` si una celda se omite.

Para mantener una lámina legible, el límite es 60 instrucciones (incluidos cuerpos internos), 1500 nodos AST y 60000 caracteres. Divide código extenso en pasos. `nivel` se conserva como metadato, no adapta automáticamente la dificultad.

## API y arquitectura

`analizar(codigo)` produce un modelo serializable; `seleccionar(modelo)` elige representación y concepto; `renderizar(modelo, representacion)` produce HTML/SVG. `generar` reúne esos pasos. Formatos: `auto`, `flujo`, `despiece`, `decisiones`.

El modelo 0.3 agrega `sections` para los cuerpos anidados. `walk_blocks` conserva el recorrido de control exterior; `walk_details` incluye las instrucciones internas. El render no vuelve a analizar el AST ni usa valores de la sesión.

`mostrar(codigo)` presenta una lámina de texto de código mediante IPython. `guardar` produce HTML autónomo; no carga fuentes, scripts o imágenes externos. Los enlaces de referencia solo se abren si el usuario los pulsa.

Importar en IPython activa un único observador. Reimportar no duplica eventos ni revierte una desactivación explícita. `SURFIA_AUTOACTIVAR=0` permite desactivar el inicio automático antes del primer import. Fuera de IPython no se crea una sesión interactiva.

## Desarrollo y publicación

```bash
python -m pip install -e '.[dev]'
python -m unittest discover -s tests -q
python -m build
python -m twine check --strict dist/*
```

Ver `docs/PUBLICACION.md` para el paso separado de publicación. Las pruebas y los comandos anteriores no suben archivos a PyPI. No se incluyen tokens ni credenciales.

## Licencia y datos

El código de la biblioteca se distribuye bajo MIT; consulta `LICENSE`. Esa licencia no se extiende a datasets, presentaciones o documentos de terceros. El CSV y el PPT del caso SAG no se incluyen en el wheel ni en el código público.
