Manual y listado de comandos para operara con *poetry*.

basic_commands.md

Comandos básicos

Poetry es una herramienta de gestión de dependencias y empaquetado en Python que simplifica la gestión de proyectos. Aquí tienes algunos comandos básicos para manejar dependencias con Poetry:

1. Inicializar un proyecto nuevo:

poetry init

Este comando te guiará a través de una serie de preguntas para configurar un nuevo proyecto de Poetry. Básicamente crea el archivo pyproject.toml. Este archivo es utilizado para definir las dependencias del proyecto, la versión de Python, la configuración del entorno y otros metadatos del paquete, como el nombre, la versión y el autor.

2. Añadir una dependencia:

poetry add <nombre_paquete>

Por ejemplo, para añadir requests:

poetry add requests

3. Añadir una dependencia de desarrollo:

poetry add --dev <nombre_paquete>

Por ejemplo, para añadir pytest como una dependencia de desarrollo:

poetry add --dev pytest

4. Instalar dependencias:

Para instalar las dependencias princiales contenidas en [tool.poetry.dependencies] en el archivo pyproject.toml:

poetry install

Para instalar las dependencias principales + las dependencias de por ejemplo los grupos dev [tool.poetry.group.dev.dependencies] y test [tool.poetry.group.test.dependencies] en el archivo pyproject.toml:

poetry install --with dev,test

Para instalar las dependencias de algún grupo pero evitando las depedencias principales:

poetry install --no-root --with dev

5. Actualizar dependencias:

poetry update

Actualiza todas las dependencias a sus versiones más recientes permitidas por el archivo pyproject.toml.

6. Remover una dependencia:

poetry remove <nombre_paquete>

Por ejemplo, para remover requests:

poetry remove requests

7. Listar las dependencias:

poetry show

Esto muestra todas las dependencias del proyecto.

8. Ver la información de una dependencia específica:

poetry show <nombre_paquete>

Por ejemplo, para ver la información sobre requests:

poetry show requests

9. Entrar a un shell con el entorno virtual activado:

poetry shell

Esto abre un nuevo shell con el entorno virtual del proyecto activado.

10. Ejecutar un comando dentro del entorno virtual de Poetry:

```sh
poetry run <comando>
```
Por ejemplo, para ejecutar un script de Python:
```sh
poetry run python script.py
```

11. Bloquear las dependencias en poetry.lock:

```sh
poetry lock
```
Esto genera o actualiza el archivo `poetry.lock` con las versiones exactas de las dependencias.

12. Publicar un paquete en PyPI:

```sh
poetry publish
```
Este comando publica el paquete en PyPI. Puedes añadir la opción `--build` para construir el paquete antes de publicarlo:
```sh
poetry publish --build
```

13. Construir un paquete SIN publicar en Pypi:

Ver mas adelante.

dependencies_by_modules.md

Dependencies by modules

En el caso querer tener un solo virtual environment general pero requirimientos diferenciados por módulo tendríamos que hacer lo siguiente.

Estructura del proyecto

repo/
│── pyproject.toml   # Archivo principal de Poetry
│── poetry.lock
│── modulo_a/
│   ├── pyproject.toml  # Dependencias específicas de modulo_a
│   ├── modulo_a/
│       ├── __init__.py
│       ├── main.py
│── modulo_b/
│   ├── pyproject.toml  # Dependencias específicas de modulo_b
│   ├── modulo_b/
│       ├── __init__.py
│       ├── main.py

project.tomlprincipal

[tool.poetry]
name = "repo"
version = "0.1.0"
description = "Repositorio con múltiples módulos"
authors = ["Tu Nombre <[email protected]>"]
packages = [{ include = "modulo_a" }, { include = "modulo_b" }]

[tool.poetry.dependencies]
python = "^3.8"
modulo_a = { path = "./modulo_a", develop = true }
modulo_b = { path = "./modulo_b", develop = true }

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

• path = "./modulo_a": Indica que modulo_a es una dependencia local.
• develop = true: Instala el módulo en modo editable (útil para desarrollo).

pyproject.toml del módulo

[tool.poetry]
name = "modulo_a"
version = "0.1.0"
description = "Módulo A"
authors = ["Tu Nombre <[email protected]>"]

[tool.poetry.dependencies]
python = "^3.8"
numpy = "^1.21"
pandas = "^1.3"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

example_toml_file.md

Ejemplo de pyproject.toml

Claro, aquí tienes un ejemplo de un archivo pyproject.toml que puede ser usado por Poetry para gestionar un proyecto de Python:

[tool.poetry]
name = "mi_proyecto"
version = "0.1.0"
description = "Una breve descripción de mi proyecto."
authors = ["Tu Nombre <[email protected]>"]
license = "MIT"
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.8"
numpy = "^1.21.0"

[tool.poetry.group.dev.dependencies]
ipykernel = "^6.23.0"

[tool.poetry.group.test.dependencies]
pytest = "^6.2.4"

[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

Descripción de las secciones

1. [tool.poetry]: Contiene la información principal sobre tu proyecto.

   • name: El nombre del proyecto.
   • version: La versión actual del proyecto.
   • description: Una breve descripción del proyecto.
   • authors: Una lista de autores del proyecto.
   • license: La licencia del proyecto.
   • readme: El archivo de README del proyecto.

2. [tool.poetry.dependencies]: Lista las dependencias del proyecto.

   • python: La versión de Python requerida.
   • requests y numpy: Ejemplos de dependencias del proyecto con sus versiones especificadas usando el símbolo ^ para indicar la compatibilidad semántica.

3. [tool.poetry.dev-dependencies]: Lista las dependencias de desarrollo, que son necesarias para el desarrollo y pruebas del proyecto pero no para su funcionamiento en producción.

   • pytest y black: Ejemplos de dependencias de desarrollo.

4. [build-system]: Define el sistema de construcción utilizado por Poetry.

   • requires: Lista las dependencias necesarias para construir el proyecto. poetry-core es la biblioteca principal que gestiona la construcción de paquetes.
   • build-backend: Especifica el backend de construcción, en este caso, es poetry.core.masonry.api.

Este archivo pyproject.toml puede ser adaptado según las necesidades específicas de tu proyecto. Puedes agregar o quitar dependencias y ajustar otros valores conforme a tus requisitos.

requirements_for_dev.md

Dependencias para desarrollo: [tool.poetry.dev-dependencies] y [tool.poetry.group.dev.dependencies]

La diferencia principal entre [tool.poetry.dev-dependencies] y [tool.poetry.group.dev.dependencies] radica en cómo se manejan las dependencias de desarrollo en diferentes versiones de Poetry.

1. [tool.poetry.dev-dependencies] (Antiguo, hasta Poetry 1.1)

Se usaba en versiones antiguas de Poetry (≤1.1) para definir dependencias solo necesarias en desarrollo (por ejemplo, pytest, black, mypy). Estas dependencias no se instalaban cuando el paquete se usaba como dependencia en otro proyecto. Ejemplo:

[tool.poetry.dev-dependencies]
pytest = "^7.0"
black = "^22.0"

Obsoleto en Poetry 1.2+, reemplazado por grupos de dependencias.

2. [tool.poetry.group.dev.dependencies] (Nuevo, desde Poetry 1.2+)

En Poetry 1.2+, se introdujeron los grupos de dependencias (group.dev, group.test, etc.). Permite una mejor organización y flexibilidad al definir grupos de dependencias según el entorno. Ejemplo equivalente en Poetry 1.2+:

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
black = "^22.0"

Ventajas de los grupos (group.dev) sobre dev-dependencies

• Puedes definir múltiples grupos de dependencias (group.dev, group.test, group.docs, etc.).
• Mayor flexibilidad en la instalación (poetry install --with dev o poetry install --only dev).
• Más claridad en la organización del pyproject.toml.

Cómo Instalar Dependencias de Desarrollo Si usas Poetry ≤1.1 (obsoleto):

poetry install  # Instala dependencias de producción y desarrollo

Si usas Poetry 1.2+:

poetry install               # Instala todo
poetry install --without dev # Instala todo sin el grupo dev
poetry install --only main   # Instala solo el grupo principal
poetry install --with dev    # Instala dependencias del grupo principal y el grupo dev
poetry install --only dev    # Instala solo las de desarrollo, sin las del grupo principal

virtual_env.md

Configurar la Ubicación del Entorno Virtual y de la Cache

Por defecto, Poetry guarda los entornos virtuales en un directorio gestionado por Poetry. Si prefieres que el entorno virtual se cree dentro del directorio del proyecto, puedes configurar Poetry para hacerlo:

1.1 Configurar Poetry para usar un entorno virtual dentro del proyecto:

poetry config virtualenvs.in-project true

Esto hará que el entorno virtual se cree en una carpeta .venv dentro del directorio de tu proyecto.

1.2 Configurar Poetry para guardar cache en diferente ubicación:

poetry config cache-dir /ruta/a/tu/nuevo/directorio

2. Verificar la configuración:

Para verificar que la configuración se ha aplicado correctamente:

poetry config --list

Deberías ver una línea como esta en la salida:

virtualenvs.in-project = true

3. Recrear el entorno virtual:

Si ya tienes un entorno virtual creado y deseas aplicar esta configuración, primero elimina el entorno virtual existente y luego instálalo nuevamente:

poetry env remove <versión_python>  # Por ejemplo, "poetry env remove 3.8"
poetry install