Python 101 (env, tools and Poetry)

TL;DR

Stack a usar:

  • python -> lenguaje e intérprete
  • py -> python launcher para windows
  • pipx -> instalar tools python globales
  • .env -> variables de entorno local; UAT y PROD usar config de donde se despliegue
  • pyenv -> gestor de versiones de Python
  • poetry -> gestor de proyecto. Abstrae pip y sustituye venv y requeriments.txt. Detalles de como usar poetry aquí <- TODO: linkear a post

No usar pero si conocer:

  • pip -> gestor de paquetes - incluye uso de requirements.txt (sustituir por poetry)
  • pip3 -> No usarlo. Leftover histórico de cuando python2 y python3 convivian hasta el 2020
  • venv -> entornos virtuales para aislamiento (sustituir por poetry)
  • conda -> package y environment manager para data science & ML

    Stack a usar

    Python (lenguaje/intérprete)

    Python como tal es el lenguaje y el intérprete. Es un lenguaje interpretado (no compilado) sobre una MV propia. Python por sí mismo no gestiona dependencias ni aislamiento.

Python. Solo. Ejecuta. Código.

(py) python en Windows

Python no es un único ejecutable, puedes tener varios intérpretes instalados a la vez. El caos normalmente viene a que cada uno es una versión distinta, con librerías distintas y sus propios paths.

python.exe
python3.exe
py.exe

Si usas lo que hace el sistema es buscar python en $PATH y usar el primero que encuentre

python main.py

En windows usar siempre py. Está diseñado para gestionar múltiples versiones de Python en windows.

py # lanza la version por defecto. Normalmente el último Python3 instalado
py -3.11
py -0p # muy útil para debuggear todas las instalaciones detectadas

No usar python y py indistintamente

No se puede usar indistintamente python y py ya que son comandos diferentes.

# DON'T DO THIS
python -m venv .venv
.venv/Scripts/activate
pip install fastapi
py main.py # puede ignorar el .venv activado y lanzar un python global distinto

Pipx (instalar tools Python)

pipx sirve para instalar aplicaciones Python, no librerías como pip:

  1. Crea un virtualenv aislado por herramienta
  2. Instala la app ahí dentro
  3. Expone solo el binario en tu PATH

uso

pipx install black

luego la podemos usar directamente

black --version

.env (variables de entorno)

Fichero para guardar valores clave-valor de configuración. NO se hace commit de él. No es un estándar oficial de python.

API_KEY=xxx
DEBUG=true
LOG_LEVEL=info

DOMAIN=something.org
ROOT_URL=${DOMAIN}/app

Usar

  • .env -> local
  • .env.test -> testing
  • variables de entorno o plataforma de Azure para entornos UAT o productivos

ejemplo:

from dotenv import load_dotenv
import os

load_dotenv() # carga .env si existe

api_key = os.getenv("API_KEY")

pyenv

pyenv es un gestor de versiones de Python. Instala, mantiene y selecciona múltiples intérpretes de python en una misma máquina, sin tocar el python del sistema.

Se creó por casos donde:

  • un proyecto usa python 3.8
  • otro requiere 3.11
  • una herramienta legacy funciona con 3.7

pyenv permite que cada proyecto use su versión de Python.

uso básico de pyenv

Ver versiones disponibles

pyenv install --list

Ver que tienes instalado

pyenv versions

Selección GLOBAL para tu user - afecta a todo, salvo que haya algo más específico

pyenv global 3.11.7

Selección local por proyecto

cd mi-proyecto
pyenv local 3.11.7 # esto crea un fichero .python-version que debemos meter en GIT

Poetry

Poetry es una herramienta para gestionar proyectos Python que reemplaza a las siguientes partes por un único archivo y flujo basado en pyproject.toml

  • requirements.txt - sustituido por pyproject.toml + poetry.lock
  • venv - poetry crea y gestiona venvs automáticamente
  • pip - lo sustituye parcialmente (lo abstrae)

Contenido de pyproject.toml

[tool.poetry]
name = "AiLearning"
version = "0.3.0"
description = "Ejemplos de uso programaticos para aprender AI"
authors = ["Mario Codes <something@gmail.com>"]
readme = "README.md"
packages = [
	{ include = "LangChain" },
	{ include = "Rag" },
]

[tool.poetry.dependencies]
python = "^3.14"
python-dotenv = "^1.2.1"
dotenv = "^0.9.9"
pandas = "^2.3.3"
openai = "^2.11.0"
langchain-openai = "^1.1.7"
langchain = "^1.2.3"
azure-cosmos = "^4.15.0"
pypdf = "^6.7.5"
langchain-community = "^0.4.1"
langchain-text-splitters = "^1.1.1"
langchain-experimental = "^0.4.1"

[tool.poetry.scripts]
insert-rag-files = "Rag.ChunkFilesIntoCosmos:main"
ask-rag-question = "Rag.AskWithRagContext:main"

langchain = "LangChain.LangChain:main"
langchain-lcel = "LangChain.LangChainExpressionLanguage:main"

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

El fichero poetry.lock es un fichero autogenerado que se usa para bloquear versiones de dependencias.

venv en Poetry (entornos virtuales)

Poetry sustituye a los venv. El mismo detecta los intérpretes de Python disponibles, crea un venv por proyecto y lo asocia automáticamente al proyecto.

Lo más importante es que poetry no necesita activar el venv manualmente para funcionar correctamente.

pip en Poetry

Poetry no sustituye a pip pero si lo abstrae. Internamente lo usa pero nosotros trabajamos con

poetry add
poetry update
poetry install

No usar pero si conocer

pip (gestor paquetes)

Pip es el gestor de paquetes. NO es parte del lenguaje. Es el equivalente a los NuGets de .NET. Sólo se encarga de instalar paquetes dentro de un intérprete de Python concreto.

Cuando instalas un paquete pip install numpy, descarga el paquete desde PyPI y lo instala en una ubicación concreta, la cual depende del intérprete de python activo.

Error clásico

¡NO hacer esto!

pip install tensorflow
python script.py
# ImportError

Esto pasa porque pip ha instalado TensorFlow en otro python diferente del que ejecuta el script.
(!)IMPORTANTE: Para evitar esto pip debe ir siempre ligado a un python concreto (!).

py -m pip install tensorflow

requirements.txt

Fichero que contiene la lista de dependencias que deben instalarse en un entorno Python. Se recomienda incluir versiones específicas.

requests==2.31.0
fastapi==0.110.0

Se pueden indicar rangos de versiones. Esto es útil para forzar versiones de dependencias transitivas (dependencias de las dependencias)

fastapi>=0.100,<1.0

Se usa mediante

py -m pip install -r requirements.txt

pip3

No usar pip3. Es un leftover histórico de cuando python2 y python3 convivían. Hoy en día Python2 está muerto desde el 2020. Usar pip

venv (entornos virtuales)

(Usar venv. NO usar virtualenv - es una herramienta histórica distinta. Desde Python +3.3 se recomienda usar venv)

En vez de instalar y tener todas las librerías a nivel global y que sus versiones choquen, venv resuelve esto creando un python aislado con sus propias librerías para cada proyecto concreto.
Cuando creas un venv se crea una carpeta .venv/ que contiene:

  • un intérprete Python propio
  • un pip propio ligado a ese intérprete
  • una carpeta site-packages aislada

Activar ese venv solo modifica variables de entorno (PATH; VIRTUAL_ENV)

Es importante saber que un venv está ligado a una versión concreta de Python. Si creas un venv con python3.11 no funcionará con python3.10.

Conda

Conda es un gestor de paquetes y de entornos, el cual NO es exclusivo de python. Es multiplataforma y multilenguaje.

Se suele usar en data science y ML y surgió para gestionar e integrar librerías con las cuales Python no se apaña tan bien.

pip es un package manager. virtualenv un environment manager; Conda es ambos

Se usa en vez de Poetry cuando necesitas usar CUDA, TensorFlow o trabajas en data science o ML.