Terminal básica, rutas, variables de entorno y ficheros .env.

La terminal en cinco minutos

La terminal es un programa que lee órdenes escritas y las ejecuta. Ya la has usado para instalar uv (lección 0.2.1) y crear el proyecto (lección 0.2.2). En el trading sistemático es la herramienta diaria: arranca el backtest, lanza el sistema en un servidor, lee sus logs y lo para.

Dentro de la terminal se ejecuta un intérprete de órdenes (shell): bash o zsh en Linux y macOS, PowerShell en Windows. Cada uno tiene su sintaxis, pero los comandos básicos coinciden casi siempre, porque PowerShell define alias con los nombres de Unix:

Una sesión típica en el proyecto del curso:

cd ~/ppt-curso                 # ~ es tu carpeta personal
ls                             # pyproject.toml, src, datos...
head -3 datos/brutos/sint_diario.csv
uv run python -m ppt.backtest  # ejecuta un módulo de tu paquete

Tres hábitos ahorran horas: el tabulador completa nombres de ficheros y comandos; la flecha arriba recupera los comandos anteriores; y Ctrl+C interrumpe el programa en marcha, que es la forma normal de parar un backtest que tarda demasiado o un sistema en papel.

Rutas: absolutas y relativas

Una ruta dice dónde está un fichero. Es absoluta si empieza en la raíz del disco (/home/ana/ppt-curso/… en Linux, C:\Users\ana\ppt-curso\… en Windows) y relativa si se interpreta desde la carpeta actual (datos/sint_diario.csv). Python tiene un módulo para manejarlas sin pelearse con barras y separadores, pathlib:

from pathlib import Path

ruta = Path("datos") / "brutos" / "sint_diario.csv"
print(ruta)
print(ruta.name, "|", ruta.stem, "|", ruta.suffix)
print(ruta.parent)
print(ruta.parts)

datos/brutos/sint_diario.csv
sint_diario.csv | sint_diario | .csv
datos/brutos
('datos', 'brutos', 'sint_diario.csv')

El operador / une trozos de ruta con el separador del sistema: / en Linux y macOS, \ en Windows. Por eso es mejor que escribir rutas a mano como texto. En Windows, además, la barra invertida tiene una trampa: dentro de una cadena de Python, \n es un salto de línea y \t un tabulador.

from pathlib import PureWindowsPath

mal = "C:\nuevos\ticks.csv"          # \n y \t son caracteres
bien = r"C:\nuevos\ticks.csv"        # r"" = barras literales
print(len(mal), len(bien))
print(PureWindowsPath(bien).name)
print(PureWindowsPath(bien).as_posix())

17 19
ticks.csv
C:/nuevos/ticks.csv

La primera cadena tiene dos caracteres menos: \n y \t se han convertido en un salto de línea y un tabulador, y el fichero ticks.csv no aparecerá nunca. Con el prefijo r (cadena «cruda») o con pathlib el problema desaparece. PureWindowsPath permite manejar rutas de Windows desde cualquier sistema; en tu código basta con Path.

El problema más frecuente con las rutas no es la barra, sino la carpeta actual. Una ruta relativa se resuelve contra la carpeta desde la que se lanzó el programa, no contra la del fichero de código. El código del curso se ejecuta en una carpeta que contiene los datos sueltos, así que:

print(Path("sint_diario.csv").exists())
print(Path("datos/sint_diario.csv").exists())
print(Path("sint_diario.csv").is_absolute())
print(Path("sint_diario.csv").resolve().is_absolute())

True
False
False
True

El mismo script, lanzado desde otra carpeta, por cron o por un servicio del servidor, no encontraría el fichero. La solución es anclar las rutas a algo fijo. En un fichero .py, la variable __file__ es la ruta del propio fichero; a partir de ella se sube hasta la raíz del proyecto:

from pathlib import Path

# src/ppt/rutas.py -> subir dos niveles = raíz del proyecto
RAIZ = Path(__file__).resolve().parents[2]
DATOS_BRUTOS = RAIZ / "datos" / "brutos"
DATOS_PROCESADOS = RAIZ / "datos" / "procesados"

El resto del código importa DATOS_BRUTOS y no vuelve a escribir una ruta. Si mañana los datos se mueven a otro disco, se cambia una línea. Los ficheros CSV, Parquet y JSON con pathlib se ven en la lección 0.4.4.

Variables de entorno

Cada programa recibe al arrancar un conjunto de pares NOMBRE=valor: sus variables de entorno. Algunas las pone el sistema (PATH, la lista de carpetas donde la terminal busca los programas; por eso tras instalar uv había que reabrir la terminal), y otras las pones tú. Son la forma estándar de pasar configuración a un programa sin tocar su código: el modo de operación, el capital, la clave del bróker.

Se definen en la terminal antes de arrancar el programa:

export PPT_MODO=papel                  # Linux y macOS, para la sesión
$env:PPT_MODO = "papel"                # PowerShell, para la sesión
PPT_MODO=real uv run python sistema.py # Linux y macOS, solo esa ejecución

En Python se leen con os.environ, que funciona como un diccionario. Aquí la variable se crea desde Python para que la celda sea reproducible; en tu sistema vendría de la terminal:

import os

os.environ["PPT_MODO"] = "papel"      # en la vida real: export

print(os.environ.get("PPT_MODO"))
print(os.environ.get("PPT_CAPITAL"))             # no existe
print(os.environ.get("PPT_CAPITAL", "25000"))    # por defecto

papel
None
25000

os.environ["PPT_CAPITAL"], con corchetes, lanzaría un KeyError si la variable no existe; .get() devuelve None o el valor por defecto. Usa corchetes para lo obligatorio (que falle pronto) y .get() con un valor por defecto seguro para lo opcional. En trading, seguro significa conservador: si falta el modo, papel, no real.

Las variables de entorno son siempre texto. Un número hay que convertirlo, y un sí/no tiene trampa:

os.environ["PPT_REAL"] = "false"
print(bool(os.environ["PPT_REAL"]))          # ¡cuidado!

def leer_bool(nombre: str, defecto: bool = False) -> bool:
    valor = os.environ.get(nombre)
    if valor is None:
        return defecto
    return valor.strip().lower() in {"1", "true", "si", "sí", "yes"}

print(leer_bool("PPT_REAL"))
capital = float(os.environ.get("PPT_CAPITAL", "25000"))
print(capital * 0.02)                        # riesgo máximo del 2 %

True
False
500.0

bool("false") es True, porque cualquier cadena no vacía es verdadera. Un sistema que decide si opera en real con bool(os.environ[...]) operaría en real con PPT_REAL=false. leer_bool solo acepta un «sí» explícito; todo lo demás, incluida una errata, cuenta como no.

Ficheros .env

Definir diez variables a mano cada vez que abres la terminal no es práctico. La convención es guardarlas en un fichero .env en la raíz del proyecto, una por línea, que el programa lee al arrancar. El .env es de tu máquina: tiene tus claves y tu configuración, está en .gitignore desde el primer commit (lección 0.1.3) y no se comparte. Lo que sí se versiona es un .env.example con los nombres y sin los valores.

Existen librerías para leerlo (python-dotenv, y Pydantic en la lección 0.4.2), pero el formato es tan simple que merece la pena escribir el lector a mano para entender qué hacen. Primero, un .env de ejemplo con claves inventadas:

Path(".env").write_text("""\
# Bróker (cuenta de papel)
BROKER_API_KEY=pk_demo_8f3a91c2e7b4
BROKER_API_SECRET="sk_demo_41d0c9e2a7f35b18"
export PPT_MODO=papel
PPT_CAPITAL=25000

PPT_RIESGO_MAX=0.02
""");

El lector: ignora líneas vacías y comentarios, admite el prefijo export (para que el mismo fichero sirva en bash), separa por el primer = y quita las comillas que rodean el valor:

def leer_env(ruta: Path) -> dict[str, str]:
    valores = {}
    for linea in ruta.read_text().splitlines():
        linea = linea.strip()
        if not linea or linea.startswith("#"):
            continue
        linea = linea.removeprefix("export ")
        clave, igual, valor = linea.partition("=")
        if not igual:
            continue                    # línea sin '=': se ignora
        valor = valor.strip()
        comillas = valor[:1] in ("'", '"')
        if comillas and len(valor) >= 2 and valor[-1] == valor[0]:
            valor = valor[1:-1]
        valores[clave.strip()] = valor
    return valores

env = leer_env(Path(".env"))
print(list(env))

['BROKER_API_KEY', 'BROKER_API_SECRET', 'PPT_MODO', 'PPT_CAPITAL', 'PPT_RIESGO_MAX']

La celda imprime solo los nombres, no los valores. Es deliberado: un valor impreso acaba en la salida del notebook, en un log o en una captura de pantalla. Cuando haga falta mostrar la configuración (por ejemplo, en el log de arranque del sistema), los secretos se enmascaran:

SENSIBLES = ("KEY", "SECRET", "TOKEN", "PASSWORD")

def enmascarar(clave: str, valor: str) -> str:
    if any(s in clave.upper() for s in SENSIBLES):
        return valor[:3] + "***" if len(valor) > 12 else "***"
    return valor

for clave, valor in env.items():
    print(f"{clave:<18} {enmascarar(clave, valor)}")

BROKER_API_KEY     pk_***
BROKER_API_SECRET  sk_***
PPT_MODO           papel
PPT_CAPITAL        25000
PPT_RIESGO_MAX     0.02

Tres caracteres bastan para distinguir una clave de papel (pk_) de otra sin revelar nada útil.

Quién gana: entorno, .env y valores por defecto

Un mismo programa se ejecuta en tu portátil, en un servidor y en los tests. Cada sitio necesita ajustar algo sin tocar el código ni el .env de los demás. La convención, que siguen python-dotenv y uv run --env-file, es una cadena de precedencia en la que cada capa sobrescribe a la anterior:

flowchart TB
  D[Por defecto] --> E[Fichero .env]
  E --> V[Entorno]
  V --> C[Configuración]

Los valores por defecto están en el código y son conservadores; el .env los ajusta para tu máquina; una variable de entorno los cambia para una ejecución concreta. Con el lector anterior, la carga completa queda así, anotando de dónde sale cada valor:

DEFECTO = {"PPT_MODO": "papel", "PPT_CAPITAL": "10000",
           "PPT_RIESGO_MAX": "0.01", "PPT_LOG": "INFO"}

def cargar_config(ruta: Path) -> dict[str, tuple[str, str]]:
    config = {k: (v, "defecto") for k, v in DEFECTO.items()}
    for k, v in leer_env(ruta).items():
        config[k] = (v, ".env")
    for k in config:
        if k in os.environ:
            config[k] = (os.environ[k], "entorno")
    return config

os.environ["PPT_CAPITAL"] = "50000"   # export PPT_CAPITAL=50000
for clave, (valor, origen) in cargar_config(Path(".env")).items():
    print(f"{clave:<18} {enmascarar(clave, valor):<10} {origen}")

PPT_MODO           papel      entorno
PPT_CAPITAL        50000      entorno
PPT_RIESGO_MAX     0.02       .env
PPT_LOG            INFO       defecto
BROKER_API_KEY     pk_***     .env
BROKER_API_SECRET  sk_***     .env

Cada valor lleva su origen: cuando un sistema hace algo inesperado, saber de dónde salió el capital o el modo es la mitad del diagnóstico. PPT_MODO sale del entorno porque una celda anterior la definió con os.environ; es el mismo efecto que tendría un export olvidado en la terminal.

En tus scripts no hace falta llamar a un lector propio: uv carga el .env al arrancar el programa si se lo pides.

uv run --env-file .env python -m ppt.backtest
uv run --env-file .env --env-file .env.servidor python -m ppt.sistema

Las variables del fichero llegan a os.environ y, como en cargar_config, una variable que ya existía en el entorno no se sobrescribe. Con varios ficheros, cada uno sobrescribe al anterior: un .env común y otro con lo propio del servidor. Lo que uv no hace es validar los valores ni enmascarar los secretos al mostrarlos; eso sigue siendo cosa de tu código, como en el segundo ejercicio.

Ejercicios

1. En la terminal, sin usar el explorador de archivos: crea dentro de ppt-curso las carpetas datos/brutos y datos/procesados, copia en datos/brutos el fichero sint_diario.csv de los recursos y muestra sus tres primeras líneas.

2. Amplía cargar_config para que falle con un mensaje claro si falta una variable obligatoria (por ejemplo, BROKER_API_KEY) y para que convierta PPT_CAPITAL y PPT_RIESGO_MAX a float, comprobando que el riesgo está entre 0 y 0,05.

OBLIGATORIAS = ("BROKER_API_KEY", "BROKER_API_SECRET")

def config_validada(ruta: Path) -> dict[str, object]:
    crudo = {k: v for k, (v, _) in cargar_config(ruta).items()}
    faltan = [k for k in OBLIGATORIAS if not crudo.get(k)]
    if faltan:
        raise RuntimeError(f"Faltan variables: {', '.join(faltan)}")
    riesgo = float(crudo["PPT_RIESGO_MAX"])
    if not 0 < riesgo <= 0.05:
        raise ValueError(f"PPT_RIESGO_MAX fuera de rango: {riesgo}")
    return crudo | {"PPT_CAPITAL": float(crudo["PPT_CAPITAL"]),
                    "PPT_RIESGO_MAX": riesgo}

cfg = config_validada(Path(".env"))
print(cfg["PPT_CAPITAL"], cfg["PPT_RIESGO_MAX"])

50000.0 0.02

3. Escribe el .env.example que acompañaría al .env de la lección. ¿Qué diferencia hay entre los dos y cuál va a Git?

# Copia este fichero a .env y rellena los valores
BROKER_API_KEY=
BROKER_API_SECRET=
PPT_MODO=papel
PPT_CAPITAL=25000
PPT_RIESGO_MAX=0.02