Saltar a contenido

Guia para principiantes

Esta guia asume que sabes ejecutar Python, pero no necesitas conocer el codigo interno de wsbuilder.

1. Instalar

La forma mas segura es usar un entorno virtual:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install wsbuilder
py -m venv .venv
.venv\Scripts\Activate.ps1
py -m pip install --upgrade pip
py -m pip install wsbuilder

Verifica:

python -c "import wsbuilder; print(wsbuilder.__version__)"
wsbuilder --help

2. Crear tu primera app

Crea un archivo app.py:

from wsbuilder import App, Response

app = App(cors_allow_origin="*")

@app.view("/")
def home(_request):
    return Response.html("<h1>Hola desde wsbuilder</h1>")

@app.api("/api/health")
def health(_request):
    return {"ok": True}

if __name__ == "__main__":
    app.run("127.0.0.1", 8765)

Ejecuta:

python app.py

Abre:

  • http://127.0.0.1:8765/
  • http://127.0.0.1:8765/api/health

3. Entender rutas view y api

Usa @app.view para HTML, texto o respuestas manuales:

@app.view("/hello")
def hello(request):
    name = request.query.get("name", "mundo")
    return Response.html(f"<p>Hola {name}</p>")

Usa @app.api para JSON:

@app.api("/api/echo", methods=("POST",))
def echo(request):
    payload = request.json() or {}
    return {"received": payload}

Si una ruta api devuelve dict o list, wsbuilder lo convierte a JSON. Si necesitas controlar estado o headers, devuelve Response.json(...).

@app.api("/api/items", methods=("POST",))
def create_item(request):
    payload = request.json() or {}
    if not payload.get("name"):
        return Response.json({"message": "name is required"}, status=400)
    return Response.json({"name": payload["name"]}, status=201)

4. Activar documentacion y metricas

Para una app inicial conviene activar dos superficies de inspeccion:

app.enable_metrics(path="/api/metrics")
app.enable_docs(path="/docs", json_path="/docs.json")

Con eso puedes abrir:

  • /api/metrics: snapshot JSON de la app.
  • /docs: documentacion runtime generada desde la instancia activa.
  • /docs.json: version JSON de esa documentacion.

5. Probar sin abrir un puerto

App.dispatch() permite llamar una ruta directamente. Es util para tests y scripts pequenos.

from wsbuilder import App, Request

app = App()

@app.api("/api/health")
def health(_request):
    return {"ok": True}

request = Request(
    method="GET",
    path="/api/health",
    query_string="",
    headers={},
    body=b"",
    client=("127.0.0.1", 1234),
)

response = app.dispatch(request)
print(response.status)
print(response.body.decode("utf-8"))

6. Usar la demo incluida

Despues de instalar el paquete:

wsbuilder --host 127.0.0.1 --port 8765

La demo incluye:

  • /
  • /monitor
  • /thread-demo
  • /api/health
  • /api/metrics
  • /api/metrics/stream
  • /docs
  • /docs.json
  • /ws/

Problemas comunes

Sintoma Causa probable Solucion
externally-managed-environment El Python del sistema esta protegido por la distribucion Usa un venv
Address already in use Otro proceso usa el puerto Cambia 8765 por otro puerto
404 Not Found La ruta no coincide exactamente Revisa que el path registrado empiece con /
405 Method Not Allowed La ruta existe, pero no para ese metodo Agrega methods=("POST",) o usa el metodo correcto
request.json() devuelve None El cuerpo no es JSON valido Envia JSON y Content-Type: application/json

Siguiente paso

Cuando ya tengas una ruta funcionando, pasa a Intermedios para agregar SQLite, cache, seguridad, logs y tareas.