Registros, informes, configuración, exportaciones: tarde o temprano, cada script toca el sistema de archivos. El manejo de archivos Python es sencillo para empezar, pero unos pocos detalles deciden si su código es confiable o destruye datos silenciosamente.

Esta guía cubre archivos de texto, CSV, JSON, datos binarios y rutas, con un enfoque en hábitos seguros. Ejecutamos estos ejemplos en Python 3.13 en una carpeta temporal y el resultado que se muestra proviene de esa ejecución.

Abrir archivos con open() y con

La función incorporada open() devuelve un objeto de archivo. Úselo dentro de un bloque with:

with open("notes.txt", "w", encoding="utf-8") as file:
    file.write("first line\n")
    file.write("second line\n")

print(file.closed)

# True

Cuando finaliza el bloque, Python cierra el archivo, incluso si ocurrió un error dentro de él. Sin with, debe llamar a close() usted mismo y una excepción puede saltarse esa línea. El uso de un archivo después de que se haya cerrado genera un error:

file.read()

# ValueError: I/O operation on closed file.

Modos de archivo

El segundo argumento de open() dice lo que planea hacer:

Agregue b para datos binarios, como en "rb" o "wb". El texto es el predeterminado y también se puede escribir explícitamente como t.

Escribir y adjuntar

write() no agrega un salto de línea, así que incluya \n usted mismo. Agregar mantiene lo que ya está ahí:

with open("notes.txt", "a", encoding="utf-8") as file:
    file.write("third line\n")

Compare eso con el modo "w", que reemplazó nuestras tres líneas por una, sin previo aviso:

with open("notes.txt", "w", encoding="utf-8") as file:
    file.write("replaced\n")

# notes.txt now contains only: replaced

Cuando no deba sobrescribir algo, utilice "x". Planteó FileExistsError en nuestra prueba, ya que notes.txt ya existía.

leer un archivo

Hay varias formas de leer y la elección correcta depende del tamaño del archivo:

with open("notes.txt", encoding="utf-8") as file:
    print(repr(file.read()))

# 'first line\nsecond line\n'

with open("notes.txt", encoding="utf-8") as file:
    for line in file:
        print(line.strip())

# first line
# second line
# third line

Observe los caracteres \n mantenidos en la cadena sin formato. strip() los elimina. Un objeto de archivo también recuerda su posición, por lo que la lectura continúa donde lo dejó:

with open("notes.txt", encoding="utf-8") as file:
    print(file.readline().strip())
    print(file.readlines())

# first line
# ['second line\n', 'third line\n']

Recorrer el archivo es la técnica clave para registros y exportaciones grandes. Lee una línea a la vez, por lo que no es necesario que un archivo de varios gigabytes quepa en la memoria.

Manejar errores de archivos

Es posible que falten archivos, que estén bloqueados o que sean ilegibles, así que planifique esto:

try:
    with open("missing.txt", encoding="utf-8") as file:
        data = file.read()
except FileNotFoundError as error:
    print(error)

# [Errno 2] No such file or directory: 'missing.txt'

Intente abrir el archivo y detectar el error, en lugar de verificar primero con exists(), ya que el archivo podría desaparecer entre la verificación y la apertura. Nuestra guía para el manejo de excepciones de Python cubre este enfoque.

archivos CSV

No divida las líneas CSV con comas, porque los valores entre comillas pueden contener comas. El módulo estándar csv maneja esas reglas. DictWriter y DictReader son las opciones más legibles:

import csv

with open("orders.csv", "w", newline="", encoding="utf-8") as file:
    writer = csv.DictWriter(file, fieldnames=["id", "customer", "total"])
    writer.writeheader()
    writer.writerow({"id": 1, "customer": "Asha", "total": 1200})
    writer.writerow({"id": 2, "customer": "Ben", "total": 300})

with open("orders.csv", newline="", encoding="utf-8") as file:
    rows = list(csv.DictReader(file))

print(rows[0])
print(sum(int(r["total"]) for r in rows))

# {'id': '1', 'customer': 'Asha', 'total': '1200'}
# 1500

Dos detalles importan. Pase newline="" al abrir archivos CSV, como recomienda la documentación, para evitar filas en blanco en Windows. Y cada valor regresa como una cadena, números pares, por eso necesitábamos int() en la suma. Para trabajos pesados ​​con datos, una biblioteca como pandas puede ser una mejor opción.

Archivos JSON

JSON es el formato habitual para la configuración y los datos API. Se asigna claramente a diccionarios de Python y enumera:

import json

config = {"debug": True, "retries": 3, "hosts": ["a", "b"]}

with open("config.json", "w", encoding="utf-8") as file:
    json.dump(config, file, indent=2)

with open("config.json", encoding="utf-8") as file:
    print(json.load(file)["retries"])

# 3

Recuerde el nombre: dump y load trabajan con archivos, mientras que dumps y loads trabajan con cadenas. Los tipos como las fechas no se pueden almacenar directamente, por lo que primero deberá convertirlos en cadenas.

Trabajar con rutas usando pathlib

Pegar caminos junto con cadenas se rompe en los sistemas operativos. El módulo estándar pathlib maneja los separadores por usted y ofrece prácticos atajos:

from pathlib import Path

path = Path("data") / "reports" / "summary.txt"
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text("all good\n", encoding="utf-8")

print(path.read_text(encoding="utf-8").strip())   # all good
print(path.suffix, path.stem, path.exists())      # .txt summary True
print(sorted(p.name for p in Path(".").glob("*.csv")))
# ['orders.csv']

Este último resuelve un dolor de cabeza común. Las rutas relativas se resuelven desde donde ejecutó el script, no desde donde reside el script, por lo que crear rutas desde Path(__file__).parent evita muchas sorpresas de “archivo no encontrado”.

Archivos binarios

Las imágenes, los archivos PDF y los archivos ZIP no son texto. Ábralos con b y podrá leer y escribir bytes, sin codificación involucrada:

with open("pixel.bin", "wb") as file:
    file.write(bytes([255, 0, 128]))

with open("pixel.bin", "rb") as file:
    print(file.read())

# b'\xff\x00\x80'

Escrituras más seguras

Si un programa falla a la mitad de la escritura de un archivo importante, es posible que el resultado esté dañado. Una solución común es escribir primero en un archivo temporal y luego cambiarlo a su lugar:

temp = Path("settings.tmp")
temp.write_text("new", encoding="utf-8")
temp.replace("settings.txt")

print(Path("settings.txt").read_text(), temp.exists())

# new False

replace() sobrescribe el destino. En el mismo sistema de archivos, el cambio de nombre es generalmente atómico, por lo que los lectores ven el archivo antiguo o el nuevo en lugar de una mezcla a medio escribir.

Un ejemplo práctico: resumir un log

Este breve guión reúne varias ideas. Lee un registro una línea a la vez, por lo que su tamaño no importa, cuenta cada nivel usando Counter y escribe un resumen en un nuevo archivo:

from collections import Counter

counts = Counter()
with open("app.log", encoding="utf-8") as file:
    for line in file:
        counts[line.split()[0]] += 1

with open("summary.txt", "w", encoding="utf-8") as out:
    for level, total in counts.most_common():
        out.write(f"{level}: {total}\n")

# summary.txt
# ERROR: 2
# INFO: 2
# WARN: 1

Nuestro registro de muestra tenía cinco líneas. Una línea en blanco rompería line.split()[0], por lo que los scripts reales deberían omitir primero las líneas vacías.

Errores comunes

• Usaste "w" cuando querías decir "a". Tus datos existentes se abren inmediatamente, incluso si nunca escribes nada.
• Omitir la codificación. El valor predeterminado varía según el sistema, por lo que un script que funciona en Linux puede fallar en Windows con texto acentuado o emoji.
• Llamar a read() en archivos grandes. Esto puede agotar la memoria, así que recorre las líneas.
• Olvidar int() en los valores CSV. "10" + "20" da "1020".
• Omitiendo newline="" para CSV. Es posible que obtengas filas en blanco inesperadas en Windows.
• No probar el código del archivo. Utilice el accesorio tmp_path de pytest para que las pruebas nunca toquen archivos reales. Consulte nuestro tutorial de pytest.

Conclusión

Algunos hábitos cubren casi todo aquí: use with, configure la codificación, piense dos veces antes de "w" y deje que csv, json y pathlib hagan las partes difíciles. Para practicar, escriba un pequeño script que lea un CSV, totalice una columna y guarde un resumen JSON en una nueva carpeta.

Preguntas frecuentes

sigue aprendiendo