Manejo de archivos en Python — Leer y escribir correctamente

El manejo de archivos integrado de Python es una de las verdaderas fortalezas del lenguaje — no se necesitan importaciones para operaciones básicas de lectura/escritura, y la API es lo suficientemente clara como para aprenderla en una tarde. Pero hay una brecha real entre la versión del tutorial y lo que realmente desplegarías en producción. La versión del tutorial abre un archivo, lo lee y lo cierra. La versión de producción lidia con incompatibilidades de codificación que corrompen datos silenciosamente, rutas que funcionan en macOS pero explotan en Windows, y archivos de registro que consumen silenciosamente toda tu memoria si llamas a read() en un archivo de 2 GB. Este artículo cubre los patrones que funcionan — no solo el camino feliz.

La sentencia with — Úsala siempre

Cada ejemplo de manejo de archivos en Python debería usar un gestor de contexto — el bloque with que garantiza que el archivo se cierra incluso si se lanza una excepción en medio de la lectura. Un gestor de contexto es un objeto que define qué ocurre al entrar y salir de un bloque with; para archivos, la salida significa que close() se llama automáticamente. He aquí por qué importa en la práctica:

# ❌ Manual close — works until it doesn't
f = open('app.log')
data = f.read()   # if this raises an exception...
f.close()         # ...this line never runs. File handle leaks.

# ✅ Context manager — close() is guaranteed
with open('app.log') as f:
    data = f.read()
# file is closed here, no matter what happened inside the block

En servidores de larga ejecución esto no es académico — filtrar descriptores de archivo eventualmente causa OSError: [Errno 24] Too many open files. La sentencia with no cuesta nada y previene completamente esa clase de error. Úsala en todas partes.

Leer archivos — Cuatro formas, una herramienta correcta para cada caso

Python te da varios métodos en un objeto de archivo, y elegir el correcto importa más de lo que la mayoría de los tutoriales admiten:

• f.read() — lee todo el archivo en una sola cadena. Correcto para archivos de configuración pequeños, peligroso para los grandes.
• f.readline() — lee una línea a la vez, avanzando el puntero interno. Útil cuando necesitas control manual sobre la iteración.
• f.readlines() — lee todas las líneas en una lista. Conveniente, pero aún carga todo el archivo en memoria.
• for line in f: — el protocolo iterador. Lee una línea a la vez sin cargar el archivo completo. Este es el que debes usar por defecto.

Aquí hay un ejemplo realista: leer un archivo de configuración estilo .env y convertirlo en un diccionario. Este es el tipo de cosa que realmente escribes, no una demo artificial de "leer hello.txt":

from pathlib import Path

def load_config(path: str) -> dict:
    """Read a key=value config file, ignoring comments and blank lines."""
    config = {}
    with open(path, encoding='utf-8') as f:
        for line in f:
            line = line.strip()
            if not line or line.startswith('#'):
                continue
            if '=' not in line:
                continue
            key, _, value = line.partition('=')
            config[key.strip()] = value.strip()
    return config

# Usage
settings = load_config('config/app.conf')
db_host = settings.get('DB_HOST', 'localhost')

Escritura y adición — Conoce qué modo destruye datos

El segundo argumento de open() es el modo. Dos modos generan problemas repetidamente:

• 'w' — modo escritura. Abre el archivo para escritura. Si el archivo ya existe, se trunca a cero bytes inmediatamente — antes de que escribas un solo carácter. Esto es destrucción silenciosa de datos si abres la ruta equivocada.
• 'a' — modo adición. Abre el archivo y mueve el puntero de escritura al final. El contenido existente nunca se toca. Las nuevas escrituras van después de lo que ya estaba allí.

Un buen caso de uso para el modo adición es escribir un archivo de registro estructurado con marcas de tiempo. Aquí hay un patrón útil en scripts y servicios pequeños:

import datetime

LOG_FILE = 'logs/pipeline.log'

def log_event(level: str, message: str) -> None:
    timestamp = datetime.datetime.utcnow().isoformat() + 'Z'
    line = f"[{timestamp}] {level.upper()}: {message}\n"
    with open(LOG_FILE, 'a', encoding='utf-8') as f:
        f.write(line)

log_event('info', 'Pipeline started')
log_event('warning', 'Retrying connection to database')
log_event('error', 'Failed to parse row 4821 — skipping')

Codificación — El error que muerde a todos tarde o temprano

Esta es la fuente única más común de corrupción silenciosa de datos en el manejo de archivos de Python. La codificación predeterminada de Python 3 cuando llamas a open() sin especificar una está determinada por locale.getpreferredencoding() — que en Windows es típicamente cp1252, y en Linux/macOS suele ser UTF-8. Eso significa que el código que funciona perfectamente en tu Mac puede silenciosamente corromper o fallar en un servidor Windows cuando el archivo contiene cualquier carácter fuera de ASCII. La solución es un argumento extra:

# ❌ Platform-dependent — works on Linux, corrupts on Windows
with open('customers.csv') as f:
    data = f.read()

# ✅ Explicit UTF-8 — same behavior on every platform
with open('customers.csv', encoding='utf-8') as f:
    data = f.read()

# For files exported from Excel on Windows — may have a BOM (byte order mark)
# utf-8-sig strips the BOM automatically on read
with open('export.csv', encoding='utf-8-sig') as f:
    data = f.read()

El problema BOM es particularmente común con archivos CSV exportados desde Microsoft Excel — el archivo comienza con un carácter oculto \ufeff que aparece como  si se lee con la codificación incorrecta, o hace que el primer encabezado de columna se vea como name en lugar de name. Usar encoding='utf-8-sig' lo maneja de forma transparente. Consulta la documentación de codecs de Python para la lista completa de nombres de codificación.

Trabajar con rutas — Usa pathlib

La forma antigua de construir rutas de archivo en Python era la concatenación de cadenas o os.path.join(). La forma moderna es pathlib.Path, disponible desde Python 3.4 y completamente maduro desde la 3.6. Maneja los separadores de ruta correctamente en Windows y Unix sin que tengas que pensar en ello, y reemplaza un puñado de llamadas os.path con acceso a atributos legible.

from pathlib import Path

# Build a path relative to the current script — works on Windows and Unix
base_dir = Path(__file__).parent
data_dir = base_dir / 'data'
input_file = data_dir / 'records.csv'

# Check existence before opening
if not input_file.exists():
    raise FileNotFoundError(f"Input file not found: {input_file}")

# Create a directory (including parents) without error if it already exists
output_dir = base_dir / 'output' / 'reports'
output_dir.mkdir(parents=True, exist_ok=True)

# Iterate over all JSON files in a directory
for json_file in data_dir.glob('*.json'):
    print(json_file.name)       # just the filename: 'records.json'
    print(json_file.stem)       # filename without extension: 'records'
    print(json_file.suffix)     # extension: '.json'
    print(json_file.parent)     # parent directory as a Path

# The / operator builds paths — no os.path.join needed
report_path = output_dir / f"report_{input_file.stem}.txt"

El operador / no es división aquí — Path lo redefine para significar unión de rutas. Esto se lee de forma natural y elimina los problemas de comillas y separadores que vienen con la construcción de rutas basada en cadenas. Un método más útil: path.read_text(encoding='utf-8') es un atajo para el patrón abrir/leer/cerrar cuando solo quieres el contenido del archivo como cadena.

Leer archivos grandes sin saturar la memoria

Cuando un archivo es pequeño — digamos, menos de unos pocos megabytes — f.read() o f.readlines() está bien. Cuando es un registro de servidor de 500 MB o una exportación de datos de varios gigabytes, cargar todo en memoria es un camino rápido hacia un MemoryError o una terminación del proceso por el SO. La solución es la iteración línea por línea:

from pathlib import Path
from collections import Counter

def count_error_levels(log_path: str) -> dict:
    """
    Process a large log file line by line.
    Memory usage stays roughly constant regardless of file size.
    """
    counts = Counter()
    with open(log_path, encoding='utf-8') as f:
        for line in f:
            # Each line is fetched from disk as needed — not loaded all at once
            if ' ERROR ' in line:
                counts['error'] += 1
            elif ' WARN ' in line:
                counts['warning'] += 1
            elif ' INFO ' in line:
                counts['info'] += 1
    return dict(counts)

results = count_error_levels('/var/log/app/server.log')
print(f"Errors: {results.get('error', 0)}, Warnings: {results.get('warning', 0)}")

El patrón for line in f: funciona porque el objeto de archivo de Python implementa el protocolo iterador — recupera líneas del disco de una en una usando un búfer interno, por lo que el uso de memoria es esencialmente constante independientemente del tamaño del archivo. Para archivos verdaderamente masivos (decenas de gigabytes) donde incluso la iteración línea por línea no es suficientemente rápida, mmap te permite mapear el archivo en memoria y buscarlo con expresiones regulares sin leerlo en absoluto — pero para la mayoría de los casos de uso, el iterador de líneas es todo lo que necesitas.

Leer y escribir JSON y CSV

Dos formatos aparecen constantemente en el trabajo real de Python, y ambos tienen módulos dedicados de la stdlib que manejan correctamente las comillas, el escape y la estructura — no los analices con divisiones de cadenas.

import json
import csv
from pathlib import Path

# --- JSON ---
# Reading
with open('config/settings.json', encoding='utf-8') as f:
    settings = json.load(f)            # parsed directly from the file object

# Writing (indent=2 gives readable output)
with open('output/results.json', 'w', encoding='utf-8') as f:
    json.dump(results, f, indent=2, ensure_ascii=False)

# --- CSV ---
# Reading
with open('data/customers.csv', encoding='utf-8-sig', newline='') as f:
    reader = csv.DictReader(f)         # each row is a dict keyed by header
    for row in reader:
        process_customer(row['email'], row['plan'])

# Writing
fieldnames = ['id', 'email', 'plan', 'created_at']
with open('output/export.csv', 'w', encoding='utf-8', newline='') as f:
    writer = csv.DictWriter(f, fieldnames=fieldnames)
    writer.writeheader()
    for record in records:
        writer.writerow(record)

Algunas cosas que vale la pena notar: pasa newline='' al abrir archivos CSV — el módulo csv maneja sus propios finales de línea, y dejar que el modo de nueva línea universal de Python interfiera causa filas en blanco duplicadas en Windows. Para JSON, ensure_ascii=False permite que los caracteres no ASCII (letras acentuadas, caracteres CJK, etc.) se escriban tal cual en lugar de escaparse a secuencias \uXXXX — salida mucho más legible. Si trabajas con datos JSON o CSV y quieres inspeccionarlos o transformarlos visualmente, el Formateador JSON y el Formateador CSV de este sitio son buenos complementos al enfoque de código.

Manejo de errores — Las tres excepciones que verás

Las operaciones de archivo fallan de formas predecibles. Manejar cada caso explícitamente te da mensajes de error que son realmente útiles en lugar de un traceback genérico:

import json
from pathlib import Path

def load_json_config(path: str) -> dict:
    """
    Load a JSON config file with explicit error handling.
    Returns the parsed config or raises with a clear message.
    """
    config_path = Path(path)

    try:
        with open(config_path, encoding='utf-8') as f:
            return json.load(f)

    except FileNotFoundError:
        raise FileNotFoundError(
            f"Config file not found: {config_path.resolve()}\n"
            f"Create it or set CONFIG_PATH to the correct location."
        )

    except PermissionError:
        raise PermissionError(
            f"No read permission on {config_path.resolve()}\n"
            f"Check file ownership and mode (chmod 644 on Linux)."
        )

    except UnicodeDecodeError as e:
        raise ValueError(
            f"Encoding error reading {config_path}: {e}\n"
            f"Try opening with encoding='utf-8-sig' if the file came from Windows."
        )

    except json.JSONDecodeError as e:
        raise ValueError(
            f"Invalid JSON in {config_path} at line {e.lineno}, col {e.colno}: {e.msg}"
        )

Las cuatro excepciones cubren casi todos los modos de fallo reales: el archivo no existe, no tienes permiso, la codificación es incorrecta, o el contenido está malformado. Cada mensaje le dice al próximo desarrollador (o a ti a las 2 de la mañana) exactamente qué salió mal y dónde buscar. Capturar una Exception desnuda e imprimir "algo salió mal" no es manejo de errores útil — solo mueve la confusión más adelante.

Conclusión

La versión corta de todo lo anterior: siempre usa bloques with, siempre pasa encoding='utf-8', usa pathlib.Path para la construcción de rutas, e itera líneas en lugar de leer archivos completos cuando el tamaño es desconocido. Estos cuatro hábitos eliminan la gran mayoría de los errores de manejo de archivos antes de que lleguen a producción.

Para lectura más profunda: la sección del tutorial de Python sobre lectura y escritura de archivos cubre los conceptos básicos exhaustivamente. La documentación de pathlib vale la pena marcarlo como favorito — es una de las partes más útiles de la stdlib y la mayoría de los desarrolladores Python la subutilizan. La documentación del módulo csv y la documentación del módulo json ambas tienen buenos ejemplos para los casos límite (delimitadores personalizados, JSON en streaming, etc.) que vale la pena leer si trabajas con esos formatos regularmente.