Módulos, paquetes y entornos virtuales

Hola! Salgamos del cuaderno

Todo lo de los capítulos anteriores vivía en una celda. Perfecto para aprender, y en algún momento se te queda chico 🌱

Cuando una función te sirve en tres cuadernos distintos, copiarla tres veces es pedir problemas: arreglas una y las otras dos siguen mal. Para eso están los módulos.

Y una pregunta que vale para todo lo que viene: ¿te ha pasado que algo te funcionaba y al día siguiente no, sin haber tocado nada? Casi siempre es una versión que cambió por debajo, y la respuesta a eso está en la segunda mitad del capítulo 🧰

Un módulo es un archivo

Nada más. Si guardas esto como utiles.py:

# utiles.py
IGV = 0.18

def con_igv(monto):
    return round(monto * (1 + IGV), 2)

def limpia_ciudad(texto):
    return texto.strip().title()

Desde otro archivo o cuaderno en la misma carpeta lo traes así:

import utiles

print(utiles.con_igv(100))
print(utiles.IGV)

Ese punto se lee como "de dentro de". utiles.con_igv es "la función con_igv de dentro de utiles".

Las cuatro formas de importar

import math
from math import sqrt
from math import sqrt as raiz
import statistics as stats

print(math.sqrt(16))
print(sqrt(16))
print(raiz(16))
print(stats.mean([10, 20, 30]))

4.0
4.0
4.0
20

Cuál usar:

• 📦 import math cuando vas a usar varias cosas del módulo. Se lee de dónde viene cada una.
• 🎯 from math import sqrt cuando usas una sola y mucho.
• 🏷️ as para acortar. Aquí hay convenciones que todo el mundo respeta: import pandas as pd, import numpy as np. Úsalas, que así tu código se lee igual que el de cualquiera.

Y una que no debes usar aunque la veas por ahí:

from math import *      # NO

Eso trae todo y llena tu espacio de nombres de cosas que no sabes que están. Si dos módulos tienen una función con el mismo nombre, el segundo pisa al primero sin avisarte 🙃

La librería estándar, que ya tienes

Python viene con muchísimo incluido. Estos son los que de verdad vas a usar en datos:

from datetime import date, datetime, timedelta

hoy = date(2026, 8, 15)
compra = date(2026, 5, 30)

print((hoy - compra).days)
print(hoy + timedelta(days=30))
print(hoy.strftime('%d/%m/%Y'))
print(datetime.strptime('29/06/2025', '%d/%m/%Y').date())

77
2026-09-14
15/08/2026
2025-06-29

Esas cuatro líneas son el 80% de lo que se hace con fechas: cuántos días pasaron, sumar días, mostrarla bonita y leerla desde un texto.

strftime convierte fecha a texto y strptime convierte texto a fecha. La p es de "parse". Yo las confundí durante años, así que no te sientas mal 😄

from collections import Counter

canales = ['Web', 'Tienda', 'Web', 'WhatsApp', 'Web', 'Tienda']

conteo = Counter(canales)
print(conteo)
print(conteo.most_common(2))

Counter({'Web': 3, 'Tienda': 2, 'WhatsApp': 1})
[('Web', 3), ('Tienda', 2)]

¿Te acuerdas del bucle con .get(c, 0) + 1 del capítulo 4? Esto hace lo mismo en una línea. Yo te hice escribir el bucle a propósito, para que entiendas qué hay debajo 💜

import json

texto = '{"ciudad": "Lima", "monto": 480.37, "pagado": true}'
venta = json.loads(texto)

print(venta['ciudad'], venta['monto'])
print(type(venta['pagado']), venta['pagado'])

Lima 480.37
<class 'bool'> True

Fíjate en que el true en minúscula del JSON se convirtió en el True de Python. Esa traducción la hace json sola, y es la razón por la que nunca hay que parsear JSON a mano.

Antes de instalar una librería para algo, pregúntate si la estándar ya lo hace. Muchas veces sí 🌸

pathlib: rutas que no se rompen

Las rutas escritas a mano son una fuente clásica de dolor, porque Windows usa barras al revés que Mac y Linux.

from pathlib import Path

carpeta = Path('datos')
archivo = carpeta / 'ventas' / 'enero.csv'

print(archivo)
print(archivo.name)
print(archivo.stem)
print(archivo.suffix)
print(archivo.exists())

datos/ventas/enero.csv
enero.csv
enero
.csv
False

Ese / entre carpetas es magia de pathlib: arma la ruta con el separador correcto de cada sistema.

Y ese .exists() en False es tu mejor amigo. Porque si no preguntas, pasa esto:

open('datos/ventas/enero.csv')

FileNotFoundError: [Errno 2] No such file or directory: 'datos/ventas/enero.csv'

Y ojo con cómo se lee ese mensaje: dice la ruta relativa, así que no te dice desde dónde estaba buscando. Cuando te pase, esta línea te lo aclara en un segundo:

aqui = Path.cwd()
print('Python esta mirando desde una carpeta que existe?', aqui.is_dir())
print('y el nombre de esa carpeta tiene', len(aqui.name), 'letras')
print()
print('en tu maquina, imprime aqui a secas y sale la ruta completa')

Python esta mirando desde una carpeta que existe? True
y el nombre de esa carpeta tiene 11 letras

en tu maquina, imprime aqui a secas y sale la ruta completa

En tu cuaderno eso imprime la ruta entera. Aquí no la enseño porque sería la ruta de mi máquina, y este libro publica salidas que se comprueban: una ruta absoluta cambiaría con cada persona que lo ejecute 📁

Ahí sale la carpeta desde la que Python está mirando. El 90% de los FileNotFoundError son eso: el archivo existe, pero está en otro sitio del que tú creías 📁

Así que la costumbre buena es preguntar antes:

ruta = Path('datos/ventas/enero.csv')

if ruta.exists():
    print('leyendo', ruta)
else:
    print(f'no encuentro {ruta} desde {Path.cwd().name}')

no encuentro datos/ventas/enero.csv desde MissYeraWeb

Entornos virtuales, o "en mi máquina funcionaba"

Esta parte te la explico porque tarde o temprano te va a pasar y quiero que sepas qué es.

Imagina que tienes dos proyectos. Uno viejo que necesita pandas 1.5 y uno nuevo que necesita pandas 2.2. Si instalas todo en el mismo Python, la segunda instalación pisa a la primera y el proyecto viejo deja de funcionar 😖

Un entorno virtual es una carpeta con su propio Python y sus propias librerías. Cada proyecto tiene el suyo y no se pisan.

# Crear el entorno, una sola vez por proyecto
python3 -m venv .venv

# Activarlo (Mac y Linux)
source .venv/bin/activate

# Activarlo (Windows)
.venv\Scripts\activate

# Ya dentro: instalar lo del proyecto
pip install pandas matplotlib

# Guardar la lista exacta
pip freeze > requirements.txt

# Salir
deactivate

Cuando está activado, tu terminal muestra (.venv) al principio de la línea. Esa es la señal de que estás dentro.

Ese requirements.txt es el archivo que hace que otra persona pueda reproducir tu entorno exacto:

pip install -r requirements.txt

Y dos cosas que se olvidan siempre:

• 🚫 La carpeta .venv no se sube a git. Se pone en el .gitignore. Lo que se sube es el requirements.txt.
• 💻 Si usas un editor como VS Code, hay que decirle que use ese Python. Si no, te va a decir que pandas no está instalado aunque lo esté.

En Colab nada de esto aplica: cada cuaderno ya es su propio entorno aislado, y por eso es tan cómodo para aprender.

Organizar tu propio código

Cuando un proyecto crece, esta estructura funciona y es la que yo uso:

mi_proyecto/
    .venv/                  no se sube a git
    datos/
        ventas.csv
    src/
        __init__.py
        limpieza.py
        metricas.py
    cuadernos/
        exploracion.ipynb
    requirements.txt
    README.md

El __init__.py vacío es lo que convierte una carpeta en paquete, y permite importar así:

from src.limpieza import limpia_ciudad
from src.metricas import ticket_promedio

La regla que te va a servir: el cuaderno explora, el módulo guarda. Cuando una función del cuaderno ya funciona bien y la vas a volver a usar, se muda a un .py. Así el cuaderno queda para probar cosas y el código bueno vive en un solo sitio 🌟

El bloque que aparece al final de los scripts

def principal():
    print('esto es el trabajo de verdad')

if __name__ == '__main__':
    principal()

esto es el trabajo de verdad

Ese if significa "corre esto solo si me estás ejecutando a mí directamente, no si me estás importando".

Sin él, importar tu módulo desde otro sitio ejecutaría todo el script entero. Y sí, se ve raro la primera vez. Con verlo tres veces se te queda 😄

El import que no encuentra nada

Este error te lo vas a comer, y no una vez.

import analisis_de_ventas

ModuleNotFoundError: No module named 'analisis_de_ventas'

Python no busca en todo tu disco: busca en una lista de sitios concretos, y el primero de esa lista es la carpeta desde la que lanzaste el programa.

import sys
from pathlib import Path

primero = Path(sys.path[0] or '.').resolve()
print('el primer sitio de la lista es una carpeta de verdad?', primero.is_dir())
print('y esa carpeta es desde donde lanzaste el programa')
print()
print('y despues vienen las carpetas de Python y las de las librerias')
print('instaladas, que son unas cuantas y dependen de tu instalacion')

el primer sitio de la lista es una carpeta de verdad? True
y esa carpeta es desde donde lanzaste el programa

y despues vienen las carpetas de Python y las de las librerias
instaladas, que son unas cuantas y dependen de tu instalacion

De ahí salen los dos casos que te van a pasar 🔍

• 📁 El archivo existe pero estás en otra carpeta. Lo típico al abrir el cuaderno en un sitio y tener el .py en otro.
• 📦 La librería no está instalada en ESE entorno. La instalaste, sí, pero en otro. Es la sección de abajo.

Y un tercero que da más rabia porque el mensaje no ayuda: le pusiste a tu archivo el nombre de una librería. Si guardas un random.py en tu carpeta, el import random de cualquier otro archivo va a encontrar el tuyo primero y a reventar por sitios rarísimos 🙃

Escribir las versiones, que es lo que hace que funcione mañana

Un entorno virtual guarda las librerías. Lo que hay que guardar aparte es qué versión de cada una, y eso vive en un archivo de texto.

import importlib.metadata as metadatos

for paquete in ('pandas', 'numpy'):
    print(f'{paquete}=={metadatos.version(paquete)}')

pandas==3.0.5
numpy==2.4.6

Eso mismo es lo que escribe pip freeze > requirements.txt, y lo que lee pip install -r requirements.txt para dejar la máquina de tu compañera igual que la tuya 📋

Fíjate en el doble igual. No es adorno: pandas a secas instala la última que haya hoy, y la última de dentro de seis meses no es la misma. El día que tu código deje de funcionar sin que tú tocaras nada, va a ser por esto.

Los tres comandos que se usan de verdad, y no hay más:

En Windows el segundo es .venv\\Scripts\\activate, y esa barra al revés es la única diferencia que importa 🪟

Ejercicios

from datetime import date

compra_anterior = date(2026, 1, 15)
compra_nueva = date(2026, 6, 30)

print((compra_nueva - compra_anterior).days, 'días sin comprar')

166 días sin comprar

from datetime import datetime

f = datetime.strptime('29/06/2025', '%d/%m/%Y').date()
print(f, f.strftime('%Y-%m-%d'))

2025-06-29 2025-06-29

from collections import Counter

canales = ['Web', 'Tienda', 'Web', 'WhatsApp', 'Web', 'Marketplace', 'Tienda']
top = Counter(canales).most_common(1)[0]

print(f'{top[0]} con {top[1]} ventas')

Web con 3 ventas

from datetime import date, timedelta

emision = date(2026, 8, 15)
vence = emision + timedelta(days=45)

dias = ['lunes', 'martes', 'miércoles', 'jueves', 'viernes', 'sábado', 'domingo']
print(vence, dias[vence.weekday()])

2026-09-29 martes

import json

respuesta = ('{"ventas": ['
             '{"ciudad": "Lima", "monto": 480.37},'
             '{"ciudad": "Cusco", "monto": 154.83}]}')

datos = json.loads(respuesta)
print(round(sum(v['monto'] for v in datos['ventas']), 2))

635.2

from pathlib import Path

ruta = Path('ventas') / '2026' / 'agosto.csv'
print(ruta, '|', ruta.stem, '|', ruta.suffix)

ventas/2026/agosto.csv | agosto | .csv

import statistics as stats

montos = [120, 150, 180, 200, 5000]

print(stats.mean(montos))
print(stats.median(montos))

1130
180

import re

nota = 'Revisar C0045 y C0325, tambien el pedido de C0260 de ayer'
print(re.findall(r'C\d{4}', nota))

['C0045', 'C0325', 'C0260']

import statistics

publicas = [n for n in dir(statistics) if not n.startswith('_')]
print('cuantas cosas trae:', len(publicas))
print('las primeras diez  :', publicas[:10])
print()
print('y la ayuda de una  :')
print(statistics.median.__doc__.strip().splitlines()[0])

cuantas cosas trae: 44
las primeras diez  : ['Counter', 'Decimal', 'Fraction', 'LinearRegression', 'NormalDist', 'StatisticsError', 'bisect_left', 'bisect_right', 'correlation', 'covariance']

y la ayuda de una  :
Return the median (middle value) of numeric data.

import os
import subprocess
import sys
import tempfile

lineas = [
    "def igv(monto):",
    "    return round(monto * 1.18, 2)",
    "",
    "print('esta linea corre siempre que alguien me importe')",
    "",
    "if __name__ == '__main__':",
    "    print('y esta solo si me ejecutan directamente')",
    "    print('120 con IGV:', igv(120))",
]

carpeta = tempfile.mkdtemp()
ruta = os.path.join(carpeta, 'impuestos.py')
open(ruta, 'w', encoding='utf-8').write('\n'.join(lineas))

print('--- ejecutandolo ---')
print(subprocess.run([sys.executable, ruta], capture_output=True,
                     text=True).stdout.rstrip())

usa = os.path.join(carpeta, 'usa.py')
open(usa, 'w', encoding='utf-8').write(
    'import impuestos\n'
    'print("340 con IGV:", impuestos.igv(340))\n')

print('--- importandolo ---')
print(subprocess.run([sys.executable, usa], capture_output=True, text=True,
                     cwd=carpeta).stdout.rstrip())

--- ejecutandolo ---
esta linea corre siempre que alguien me importe
y esta solo si me ejecutan directamente
120 con IGV: 141.6
--- importandolo ---
esta linea corre siempre que alguien me importe
340 con IGV: 401.2

El archivo con el nombre bonito que rompe el proyecto

Ya sabes cómo Python encuentra lo que importas. Con eso en la cabeza, mira este, que es de los que te dejan mirando la pantalla sin entender nada 🎭

# tienes un archivo tuyo: random.py

import random
print(random.choice([1, 2, 3]))

# AttributeError: module 'random'
# has no attribute 'choice'

Lo que te llevas

• 📄 Un módulo es un archivo .py, y el punto se lee como "de dentro de".
• 🏷️ import pandas as pd y import numpy as np son convenciones: úsalas.
• 🧰 Antes de instalar algo, mira si la librería estándar ya lo hace.
• 📁 pathlib para rutas, siempre, y .exists() antes de leer.
• 🧪 Un entorno virtual por proyecto, requirements.txt al repo y .venv al .gitignore.
• ✍️ El cuaderno explora, el módulo guarda.

Y si de todo el capítulo te llevas una sola frase, que sea esta:

En el capítulo 9 vemos objetos, y te adelanto que va a ser más corto de lo que temes: para datos hace falta entenderlos, no diseñarlos.

Que tengas un hermoso día! 🌟