Instalacion¶
wsbuilder se distribuye como paquete Python puro y no arrastra dependencias de
runtime. Eso simplifica tanto la instalacion normal con pip como la instalacion
local sin internet.
1. Instalar con pip¶
La ruta recomendada para la mayoria de usuarios es instalar desde PyPI:
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 el error
externally-managed-environment. En esos casos, instala dentro de un entorno
virtual.
En 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
Verificar la instalacion¶
python -c "import wsbuilder; print(wsbuilder.__version__)"
wsbuilder --help
Tambien existe el alias wsbuilder-demo, que ejecuta la misma demo incluida.
Soporte mDNS opcional¶
Para publicar y descubrir servicios en la red local, instala el extra mdns:
python -m pip install 'wsbuilder[mdns]'
Este extra agrega zeroconf; la instalacion base permanece sin dependencias de
runtime. Consulta los ejemplos de mDNS y DNS-SD.
Instalar desde GitHub¶
Para probar lo ultimo que se ha integrado en main, o una version concreta sin
esperar a PyPI, instala directamente desde el repositorio:
# Una version publicada concreta (reproducible)
python -m pip install "git+https://github.com/jorgelsc-dev/wsbuilder@v1.5.0"
# Lo ultimo de main
python -m pip install --upgrade "git+https://github.com/jorgelsc-dev/wsbuilder@main"
# Con extras
python -m pip install "wsbuilder[tls,mdns] @ git+https://github.com/jorgelsc-dev/wsbuilder@main"
La version se calcula a partir de los tags de git (con setuptools-scm): un tag
vX.Y.Z produce X.Y.Z, y cada commit posterior produce una version distinta,
por ejemplo X.Y.(Z+1).dev3+g1a2b3c4. Por eso pip install --upgrade instala el
commit nuevo en cuanto cambia main.
Versiones anteriores a este cambio
Antes, main declaraba la misma version (X.Y.Z.dev0) durante muchos
commits, y pip install --upgrade git+... respondia "Requirement already
satisfied" sin instalar nada nuevo. Si tienes instalada una copia de esa
epoca, fuerza la reinstalacion una vez:
python -m pip install --force-reinstall --no-deps "git+https://github.com/jorgelsc-dev/wsbuilder@main"
Comprueba que version tienes con python -m pip show wsbuilder o
python -c "import wsbuilder; print(wsbuilder.__version__)".
2. Compilar en local e instalar en local sin internet¶
Usa esta ruta cuando ya tienes una copia local del repositorio y no quieres que
pip ni el sistema de build intenten consultar PyPI.
Requisitos previos¶
- Tener el repositorio clonado o copiado en la maquina local.
- Tener Python
3.11+. - Tener disponibles en el entorno
build,setuptools>=77,setuptools-scm>=8ywheel. - Tener el historial y los tags de git (
git clonecompleto). Sin ellos la version sale como0.0.0.dev0; puedes fijarla con la variable de entornoSETUPTOOLS_SCM_PRETEND_VERSION=1.2.3. - Si vas a usar un
venv, crearlo antes de desconectarte o con herramientas ya instaladas localmente.
Compilar el wheel local sin red¶
El flag --no-isolation es importante: evita que build cree un entorno aislado
e intente descargar dependencias de compilacion.
python -m build --no-isolation
El resultado queda en dist/, por ejemplo:
dist/wsbuilder-<version>-py3-none-any.whl
dist/wsbuilder-<version>.tar.gz
<version> se deriva de git: el commit de un tag vX.Y.Z compila X.Y.Z, y
cualquier otro commit compila una version de desarrollo posterior al ultimo tag
(X.Y.(Z+1).devN+g<hash>). Los artefactos publicados en PyPI salen siempre de un
tag.
Instalar el wheel local sin consultar PyPI¶
python -m pip install --no-index dist/wsbuilder-*.whl
Si ese comando falla con externally-managed-environment, el wheel esta bien y
el bloqueo viene del Python del sistema. La ruta soportada es:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --no-index dist/wsbuilder-*.whl
Solo si necesitas forzar una instalacion global en ese Python gestionado por el
sistema, pip ofrece --break-system-packages, pero queda fuera del flujo
recomendado porque puede interferir con paquetes de la distribucion:
python -m pip install --break-system-packages --no-index dist/wsbuilder-*.whl
Instalar desde el codigo fuente local sin wheel¶
Si no quieres pasar por dist/, puedes instalar directamente desde el arbol del
repositorio. El flag --no-build-isolation evita que pip intente construir en
un entorno aislado y el flag --no-deps evita cualquier resolucion externa.
python -m pip install --no-index --no-build-isolation --no-deps .
Verificar la instalacion offline¶
python -c "import wsbuilder; print(wsbuilder.__version__)"
wsbuilder --help
Flujo recomendado para distribuir en una red cerrada¶
- En una maquina de build, ejecuta
python -m build --no-isolation. - Copia el archivo
dist/wsbuilder-*.whla la maquina destino. - En la maquina destino, instala dentro de un
venvconpython -m pip install --no-index dist/wsbuilder-*.whl.
Ese flujo es el mas estable porque instala desde un artefacto ya construido y no depende de herramientas de compilacion en la maquina final.
3. Instalar para desarrollo¶
Desde la raiz del repositorio:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
Validar el paquete:
PYTHONPATH=src pytest -q
ruff check src tests examples
Validar la documentacion:
python -m pip install -r requirements-docs.txt
mkdocs build --strict