wsbuilder

wsbuilder es una libreria Python 3.11+ para construir servicios HTTP, WebSocket y utilidades de infraestructura en un paquete pequeno, modular y sin dependencias de runtime.

Sirve para crear:

APIs JSON y vistas HTML.
canales WebSocket.
servicios con SQLite embebido y ORM ligero.
cache clave-valor y cache HTTP de vistas.
rate limiting, ACL, listas de IP y bloqueo temporal.
metricas JSON, stream NDJSON, logs y tareas en background.
DNS local, reverse proxy y balanceo.
prediccion simple y redes neuronales basicas desde Python puro.

Ruta de documentacion

La documentacion esta organizada por nivel:

Principiantes: instala, crea la primera app y entiende rutas view y api.
Intermedios: agrega SQLite, cache, seguridad, metricas, logs y tareas.
Avanzados: configura limites HTTP, TLS, worker pools, DNS, ProxyI, replicas SQLite y operacion.

Tambien puedes leer:

Instalacion rapida

python -m pip install --upgrade pip
python -m pip install wsbuilder

En Debian, Kali, Ubuntu y otros entornos que aplican PEP 668, pip puede rechazar la instalacion sobre el Python del sistema con externally-managed-environment. Usa un entorno virtual:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install wsbuilder

Verifica:

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

Inicio rapido

from wsbuilder import App, Response

app = App(cors_allow_origin="*")
app.enable_metrics()
app.enable_docs(path="/docs", json_path="/docs.json")

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

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

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
http://127.0.0.1:8765/docs
http://127.0.0.1:8765/api/metrics

Demo incluida

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/

Mapa de modulos

Area	Modulos	APIs principales
HTTP	`app.py`, `http.py`, `server.py`	`App`, `Request`, `Response`, `HTTPServer`
WebSocket	`ws.py`	`WebSocket`, `parse_close_payload`, handshake
Datos	`orm.py`, `db_replicas.py`	`Database`, `Model`, `QuerySet`, `OptimizedDatabase`
Cache	`cache.py`, `caches.py`	`SQLiteMemoryCache`, `ViewResponseCache`
Seguridad	`security.py`	`SecurityPolicy`, `ACLRule`, `SecurityDecision`
Observabilidad	`metrics.py`, `logs.py`, `tasks.py`	`AppMetrics`, `NDJSONLog`, `TaskManager`
Red y edge	`dns.py`, `proxyi.py`	`LocalDNSServer`, `ProxyI`
IA y prediccion	`ia.py`, `predicts.py`	`DataSet`, `NeuralNetwork`, `Predictor`

Ejemplo con datos

from datetime import UTC, datetime
from wsbuilder import App, Database, DateTimeField, IntegerField, Model, Response, TextField

class Note(Model):
    __tablename__ = "notes"

    id = IntegerField(primary_key=True, auto_increment=True)
    title = TextField(unique=True, null=False, index=True)
    created_at = DateTimeField(default=lambda: datetime.now(UTC), null=False)

app = App(cors_allow_origin="*")
app.db = Database("data/app.sqlite3", enable_wal=True)
Note.create_table(app.db)

@app.api("/api/notes", methods=("GET", "POST"))
def notes(request):
    if request.method == "GET":
        rows = [note.to_dict() for note in Note.objects(app.db).order_by("-id").all()]
        return {"items": rows}

    payload = request.json() or {}
    title = str(payload.get("title", "")).strip()
    if not title:
        return Response.json({"message": "title is required"}, status=400)
    note = Note.create(app.db, title=title)
    return Response.json(note.to_dict(), status=201)

Instalacion local y offline

Desde este repositorio:

python -m pip install .

Instalacion editable para desarrollo:

python -m pip install -e .

Compilar wheel sin red, si ya tienes build, setuptools>=77 y wheel disponibles:

python -m build --no-isolation
python -m pip install --no-index dist/wsbuilder-*.whl

La guia completa esta en docs/install.md.

Desarrollo

Comandos utiles del repositorio:

python -m pip install -e .
PYTHONPATH=src pytest -q
python -m build
python -m twine check dist/*
mkdocs build --strict

Estado del proyecto

El paquete esta marcado como Development Status :: 3 - Alpha. Es adecuado para servicios internos, prototipos, demos y laboratorios controlados. Antes de usarlo fuera de localhost, revisa limites de transporte, TLS, seguridad, logs, observabilidad y apagado de recursos.

Contribucion y soporte

Crea ramas desde main usando prefijos como feat/, fix/ o docs/.
Mantiene cada PR enfocado en un solo cambio logico.
Ejecuta las validaciones relevantes antes de abrir PR.
Reporta vulnerabilidades de forma privada.

Soporte opcional

Si wsbuilder te resulta util y quieres apoyar el mantenimiento del proyecto, puedes donar en BTC:

bc1q3lhxpr9yantvefmvhpd2h4lu0ykf3t45zvuve2

Red: BTC mainnet (Native SegWit).

Metadata

Release files for wsbuilder 0.25.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wsbuilder 0.25.8
File	Size	Uploaded
wsbuilder-0.25.8.tar.gz	183.4 kB	Aug 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for wsbuilder 0.25.8
File	Interpreter	ABI	Platform	Reset
wsbuilder-0.25.8-py3-none-any.whl 123.1 kB Aug 28, 2026	Python 3	none	any	Details

Total release size: 306.5 kB

Release files / wsbuilder-0.25.8.tar.gz

Download URL	wsbuilder-0.25.8.tar.gz
Size	183.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`024631d98d33e7931a55bd4f8f5d4b453a85f78f3115232941abcd3191988f68`
BLAKE2b-256 checksum How to use checksums	`21d11e73685c3e65590856d931ab6e0fe394bb5792177c1a9d03de0254d8da68`
Upload date	Aug 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / wsbuilder-0.25.8-py3-none-any.whl

Download URL	wsbuilder-0.25.8-py3-none-any.whl
Size	123.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`184ced96d6245017b5f6d9f9c2717b070e9013c3b8f8c89026190da080c0c45d`
BLAKE2b-256 checksum How to use checksums	`9a67dbbf20698ccd3dca0cf3c4374ae4c4af109f67b229d5f423588c1b46691a`
Upload date	Aug 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`