# Paquetes y entornos virtuales

El lanzador nativo de Elide usa pytools, la biblioteca opcional de herramientas de paquetes de Python de Elide.
Instálela con `elide setup python`; use `elide setup python --force` para reparar una instalación antigua o incompleta.

Cada proyecto tiene un entorno de paquetes automático en `.dev/dependencies/pypi/site-packages`.
Elide lo añade a la ruta de importación de Python sin activación ni `VIRTUAL_ENV`.

El proyecto es el directorio más cercano, a partir del directorio de trabajo, que contiene `elide.pkl`, `pyproject.toml`,
`requirements.txt`, `package.json`, `Gemfile` o `.git`; si no hay ninguno, es el directorio de trabajo. `elide uv`,
`elide install`, `elide python` y `elide run` usan el mismo entorno desde cualquier subdirectorio, también para un
script guardado en otro lugar. `--project PATH` selecciona un proyecto directamente.

```bash
elide uv install attrs
elide python -c 'import attrs; print(attrs.__version__)'
```

Para instalar las dependencias declaradas en `pyproject.toml`, `requirements.txt` o `elide.pkl`:

```bash
elide install --ecosystems=pypi
```

`elide install --workspace` incluye todos los ecosistemas declarados. Un `elide install` sin opciones mantiene su
valor predeterminado de Maven.

## Operaciones con paquetes

`elide uv` acepta `install`, `sync`, `compile`, `check`, `list`, `freeze` y `show`. También se acepta el espacio de
nombres opcional `pip`, por ejemplo `elide uv pip install attrs`.

```bash
elide uv compile requirements.in --generate-hashes --output-file requirements.txt
elide uv sync requirements.txt
elide uv list
elide uv check
```

`compile` fija los requisitos; esta interfaz aún no expone los comandos de proyecto `lock` y `run` de uv, ni la
descarga o la gestión de intérpretes. `sync` elimina los paquetes ausentes del archivo de requisitos. Vaciar un entorno
con un archivo vacío requiere la opción explícita `--allow-empty-requirements` de uv.

`check` valida el directorio de paquetes del proyecto con los diagnósticos de uv sobre dependencias, versión de Python y
compatibilidad de wheels. Devuelve 1 si hay dependencias incompatibles o ausentes.

Use `elide --project PATH uv ...` para seleccionar un proyecto. Elide controla el intérprete y el destino; las opciones
de intérprete y destino de uv no redirigen la instalación a otro entorno. Las opciones de índice, modo sin conexión,
verificación de hashes y caché siguen disponibles. Las compilaciones desde el código fuente están desactivadas; solo se
pueden instalar wheels compatibles. Los wheels compilados para CPython no funcionan.

## Herramientas aisladas

Ejecute un script de consola de Python sin instalar sus dependencias en su proyecto:

```bash
elide uv tool run --from 'httpie==3.2.4' http --help
elide uv tool run --from PACKAGE --with EXTRA_PACKAGE COMMAND ARGS...
elide uv tool list
elide uv tool uninstall ENVIRONMENT_KEY
elide uv tool prune
elide uv tool prune --all
elide uv tool dir
```

Las opciones de la herramienta van antes de `COMMAND`; todo lo que sigue se pasa a la herramienta. `--from` toma por
defecto el nombre del comando. Solo se admiten wheels compatibles; las herramientas que requieren extensiones nativas no
compatibles o compilaciones desde el código fuente fallan de forma explícita. Es un ejecutor de herramientas gestionado
por Elide, no la interfaz de herramientas de uv sin restricciones.

Elide ejecuta los puntos de entrada de consola con su propio intérprete de Python y conserva su directorio de trabajo,
sus argumentos y su código de salida. Las dependencias de la herramienta quedan aisladas de los paquetes del proyecto,
de `PYTHONPATH` y de los entornos virtuales externos, también cuando el intérprete se vuelve a ejecutar. Las
herramientas siguen teniendo los permisos normales del usuario; el aislamiento de dependencias no es un sandbox de
seguridad.

Los entornos residen en `$ELIDE_HOME/python/tools` o en el directorio de datos de usuario existente de Elide
(`$XDG_DATA_HOME/elide`, con `~/.local/share/elide` como alternativa). Las claves de caché incluyen la identidad del
entorno de ejecución de Elide, los requisitos de paquetes y las opciones de índice. Fije los requisitos para obtener
resultados reproducibles; use `tool run --refresh` para volver a resolver, también tras cambiar un wheel local en la
misma ruta. Se admiten `--offline`, `--no-index`, `--index-url` y `--find-links`.

La caché tiene por defecto **2 GiB** y **30 días desde el último uso**. Cada ejecución expulsa las entradas caducadas y,
según haga falta, los entornos inactivos usados menos recientemente. Defina `ELIDE_PYTHON_TOOLS_MAX_BYTES` para ajustar
el límite de tamaño. Las instalaciones que lo superan se descartan; los entornos activos están protegidos, así que una
caché llena de herramientas en ejecución puede rechazar una instalación nueva. El tamaño se comprueba durante las
operaciones de caché; no se impone como cuota del sistema de archivos mientras se ejecuta código arbitrario de una
herramienta.

`tool list` muestra las claves de entorno, los tamaños en bytes y los requisitos. `tool uninstall KEY` elimina un entorno
inactivo. `tool prune` aplica la caducidad y los límites de tamaño; `tool prune --all` elimina todos los entornos
inactivos. El ejecutor evita una segunda caché persistente de descargas de uv y elimina los datos de preparación
incompletos en la siguiente operación de caché. La limpieza nunca toca los entornos de los proyectos.

## Entornos virtuales externos

`VIRTUAL_ENV` sigue siendo compatible para importar paquetes de Python 3.13 compatibles desde un entorno virtual
externo. Los paquetes propios del proyecto tienen prioridad sobre ese entorno. Es opcional; no hace falta para los
paquetes instalados con Elide.

La compatibilidad con Python sigue siendo experimental. La compilación de extensiones nativas
aún no está disponible. pip no se incluye; use los comandos de paquetes anteriores.
