# Referencia del SDK de Python

> El cliente de Python de OpenWAF: argumentos del constructor, firmas de los métodos, opciones de cambio, request, errores y valores devueltos.

`openwaf.py` es un único módulo para Python 3.8 o posterior que solo usa la biblioteca estándar (`urllib`). Descárgalo de `https://dash.openwaf.dev/v1/sdk/openwaf.py` y ponlo junto a tu código o en tu `PYTHONPATH`.

```py
from openwaf import OpenWAF, OpenWAFError
```

## OpenWAF(token=None, base_url=None, org=None, timeout=60.0)

| Argumento | Por defecto |
|---|---|
| `token` | `OPENWAF_TOKEN` |
| `base_url` | `OPENWAF_API_URL`; ponla a `https://dash.openwaf.dev` |
| `org` | `OPENWAF_ORG`; si no, la organización del token |
| `timeout` | 60 segundos por petición |

| Miembro | Significado |
|---|---|
| `base_url`, `token`, `timeout` | Los valores en uso. |
| `org_id() -> str` | La organización que usan los métodos por defecto (se pide una vez si no está configurada). |
| `request(method, path, *, …)` | La llamada genérica que hay detrás de cada método (abajo). |

## Métodos

Cada operación de la API es un método con el nombre de su id de operación en snake_case. Todos los argumentos van con nombre:

```py
owf.list_zones(*, org=None, include=None)
owf.create_record(*, zone, body, reason, org=None, if_match=None, dry_run=None)
owf.revert_zone(*, zone, body, reason, if_match, org=None, dry_run=None)
owf.purge_cache(*, zone, body, org=None, reason=None, dry_run=None)
owf.get_zone_diff(*, zone, org=None, from_=None, to=None)
```

- Los parámetros de ruta y de consulta son argumentos con el mismo nombre. Un parámetro cuyo nombre es una palabra reservada de Python lleva un guion bajo: `from_`.
- `body` es un `dict` (o una lista) que se envía como JSON.
- Los métodos de escritura reciben `reason` (`X-Change-Reason`), `if_match` (`If-Match`, una versión `int` o `str`) y `dry_run` (`?dry_run=1`) cuando su operación los admite; los obligatorios no tienen valor por defecto.
- Cada método devuelve el cuerpo decodificado: un `dict` o una `list` si es JSON, un `str` si es texto y `None` si la respuesta está vacía.

Métodos de uso habitual:

| Tarea | Método |
|---|---|
| Zonas | `list_zones`, `get_zone`, `create_zone`, `delete_zone` |
| Registros DNS | `list_records`, `create_record`, `update_record`, `delete_record`, `batch_records` |
| Ajustes de borde y reglas | `get_zone_edge`, `update_zone_edge`, `list_rules`, `create_rule`, `delete_rule` |
| Historial | `list_zone_versions`, `get_zone_version`, `get_zone_diff`, `revert_zone`, `get_zone_propagation` |
| Caché | `purge_cache`, `list_cache_purges` |
| Auditoría | `list_audit` |

El docstring de cada método da el resumen de la operación y su método y ruta HTTP. La [referencia de la API](https://developers.openwaf.dev/es/api/) enumera todas las operaciones.

## request(method, path, *, …)

```py
res = owf.request("GET", "/v1/orgs/%s/zones" % owf.org_id(), query={"include": "merged"})
```

| Argumento | Significado |
|---|---|
| `query` | Parámetros de consulta; los `None` se omiten y los booleanos pasan a `true`/`false`. |
| `body`, `content_type` | Valor JSON, o texto/bytes con otro `content_type`. |
| `reason`, `if_match`, `dry_run` | Opciones de cambio. |
| `auth` | `False` no envía el token (rutas públicas). |
| `headers` | Cabeceras adicionales. |

## OpenWAFError

| Atributo | Significado |
|---|---|
| `status` | Estado HTTP; `0` si no hubo respuesta de la API. |
| `code` | Código de error de la API, como `not_found`, `invalid`, `version_conflict`; o `no_token`, `org_unresolved`, `unreachable` en los fallos del cliente. |
| `message` | El mensaje. |
| `field` | El campo de un error de validación, cuando se indica. |
| `body` | El cuerpo del error decodificado, como `{"current_version": 9, …}`. |

`str(e)` es `código (HTTP estado): mensaje`. Ver [Gestión de errores](https://developers.openwaf.dev/es/sdk/error-handling/).