JSON en Python: leer y escribir archivos, CSV, pathlib y codificación UTF-8

Trabajar con JSON en Python no requiere bibliotecas externas: el módulo json forma parte de la biblioteca estándar y convierte diccionarios y listas en texto y viceversa. Junto a él casi siempre hacen falta otras tres cosas: la función open con la sentencia with, el módulo pathlib para las rutas y el módulo csv para las tablas. A continuación lo vemos todo en orden, con código que funciona y con las trampas en las que más se tropieza.

La función open en Python: modos y codificación

Cualquier archivo de texto se abre con la función integrada open(ruta, modo, encoding=...). Devuelve un objeto de archivo con los métodos read, readline y write, y que se puede recorrer línea a línea en un bucle.

Para qué sirve with

Los archivos hay que cerrarlos: si no, los datos pueden no llegar al disco y el sistema mantiene ocupado el descriptor. La sentencia with cierra el archivo automáticamente, incluso si dentro del bloque se produce un error.

with open("notas.txt", "w", encoding="utf-8") as f:
    f.write("Primera línea\n")
    f.write("Segunda línea\n")

with open("notas.txt", encoding="utf-8") as f:
    for linea in f:
        print(linea.rstrip("\n"))

Recorrer el archivo en un bucle lee una línea cada vez y no carga todo en memoria, así que de este modo se pueden procesar registros de gigabytes. El método f.read() devuelve todo el contenido en una sola cadena, y f.readlines(), una lista de líneas.

Cómo escribir una línea sin borrar lo anterior

El error más frecuente de los principiantes es abrir el archivo en modo "w" para «añadir» una línea. El modo "w" vacía el archivo en el momento de abrirlo, antes de la primera escritura. Para añadir al final use "a", y para no sobrescribir nunca un archivo ajeno, "x".

with open("registro.txt", "a", encoding="utf-8") as f:
    f.write("nueva entrada\n")

Tenga en cuenta que write no añade el salto de línea por sí mismo: el "\n" se escribe de forma explícita. También se puede usar print(..., file=f), que pone el salto por usted.

Codificación UTF-8: de dónde salen los caracteres ilegibles

Hasta Python 3.15, la función open() sin el parámetro encoding usaba la codificación del sistema. En Linux y macOS es UTF-8, pero en Windows con configuración regional en ruso era cp1251. Un script que funcionaba bien en el servidor mostraba en el portátil de un compañero algo como «Café» en lugar de «Café», o fallaba con UnicodeDecodeError.

En Python 3.15, según la PEP 686, el modo UTF-8 está activado por defecto: open() sin encoding lee y escribe UTF-8 en todos los sistemas operativos. Para volver al comportamiento anterior se puede usar la variable de entorno PYTHONUTF8=0 o el indicador -X utf8=0, y para pedir expresamente la codificación del sistema, encoding="locale".

import sys
print(sys.flags.utf8_mode)   # 1 en Python 3.15

open("heredado.txt", encoding="locale")    # codificación del sistema
open("excel_antiguo.csv", encoding="cp1251")  # archivo guardado en cp1251

El reverso de la moneda: un CSV antiguo de Excel o de un script de Windows, guardado en cp1251, ahora se leerá como UTF-8 y provocará UnicodeDecodeError. La solución es leerlo con encoding="cp1251" y volver a guardarlo en UTF-8. La buena práctica no cambia: indique encoding siempre de forma explícita, y el código se comportará igual en cualquier versión.

pathlib en Python: rutas como objetos

Unir rutas con cadenas ("datos" + "/" + nombre) es incómodo y se rompe entre sistemas operativos. El módulo pathlib ofrece la clase Path, en la que las rutas se unen con el operador / y los objetos tienen propiedades claras.

from pathlib import Path

datos = Path("datos")
ruta_csv = datos / "gastos.csv"

print(ruta_csv.name)    # gastos.csv
print(ruta_csv.stem)    # gastos
print(ruta_csv.suffix)  # .csv
print(ruta_csv.parent)  # datos
print(ruta_csv.exists())

datos.mkdir(parents=True, exist_ok=True)
(datos / "hola.txt").write_text("Hola", encoding="utf-8")
print((datos / "hola.txt").read_text(encoding="utf-8"))

for p in datos.glob("*.csv"):
    print(p)

Los métodos read_text y write_text sustituyen la combinación open + with para archivos pequeños. Un objeto Path se puede pasar tanto a open como a json o a csv; todos lo admiten. Para obtener una ruta relativa al propio script y no a la carpeta actual se escribe Path(__file__).parent / "datos".

En Python 3.14, Path ganó los métodos copy() y move(), así que para copiar de forma sencilla ya no hace falta shutil. En esa misma versión se añadió a la biblioteca estándar el módulo compression.zstd para la compresión Zstandard (PEP 784).

JSON en Python: load, dump, loads, dumps

JSON es un formato de texto para intercambiar datos: lo entregan las API y en él se guardan configuraciones e informes. El módulo json hace dos operaciones: serialización (objeto de Python → texto JSON) y deserialización (texto → objeto). Son cuatro funciones, y confundirlas es una pregunta muy frecuente.

Para recordarlo: la s final significa string, es decir, trabajo con una cadena; sin ella, trabajo con un archivo.

Correspondencia de tipos

Al leer de nuevo, una tupla se convierte en lista, pero el módulo no sabe trabajar con conjuntos, fechas ni Decimal, y produce TypeError: Object of type ... is not JSON serializable.

Cómo guardar JSON en un archivo

import json
from pathlib import Path

informe = {
    "mes": "2026-10",
    "total": 15230.5,
    "categorias": {"comida": 8200, "transporte": 2100},
    "etiquetas": ["casa", "trabajo"],
}

ruta = Path("datos/informe.json")
ruta.parent.mkdir(parents=True, exist_ok=True)
with ruta.open("w", encoding="utf-8") as f:
    json.dump(informe, f, ensure_ascii=False, indent=2)

El parámetro ensure_ascii=False guarda los acentos tal cual. Sin él, en el archivo aparecería "comida" escrito con secuencias \u, lo cual es JSON correcto, pero ilegible para una persona. indent=2 aplica un formato con sangrías.

Cómo leer JSON de un archivo

with open("datos/informe.json", encoding="utf-8") as f:
    datos = json.load(f)

print(datos["total"])                 # 15230.5
print(datos["categorias"]["comida"])  # 8200

El resultado es un diccionario o una lista normales, con los que se trabaja con las herramientas habituales. Si el archivo no es JSON o está cortado, se produce la excepción json.JSONDecodeError con el número de línea y de posición; conviene capturarla cuando los datos llegan desde fuera.

Análisis de una cadena JSON y salida con formato

import json

bruto = '{"nombre": "Ana", "habilidades": ["python", "sql"], "activo": true}'
usuario = json.loads(bruto)
print(usuario["habilidades"][0])   # python

print(json.dumps(usuario, ensure_ascii=False, indent=2, sort_keys=True))

sort_keys=True ordena las claves al mostrarlas, lo que facilita comparar archivos en git. Para dar formato a un archivo desde la terminal existe una utilidad integrada: python -m json.tool datos/informe.json.

La respuesta de una API HTTP también es una cadena JSON. La biblioteca requests la analiza con el método response.json(), y por dentro es el mismo json.loads.

Trampa: las claves de JSON siempre son cadenas

d = {1: "enero", 2: "febrero"}
vuelta = json.loads(json.dumps(d))
print(vuelta == d)   # False
print(vuelta)        # {'1': 'enero', '2': 'febrero'}
# vuelta[1] -> KeyError, hay que usar vuelta["1"]

corregido = {int(k): v for k, v in vuelta.items()}

En JSON, las claves de un objeto solo pueden ser cadenas, así que las claves numéricas se convierten en cadenas después de un ciclo de serialización. Al leer, vuelva a convertirlas.

Tipos propios: fechas y Decimal

import json
from datetime import date

def valor_por_defecto(obj):
    if isinstance(obj, date):
        return obj.isoformat()
    raise TypeError(f"no sé serializar {type(obj).__name__}")

print(json.dumps({"dia": date(2026, 10, 1)}, default=valor_por_defecto))
# {"dia": "2026-10-01"}

La función del parámetro default se llama con cada objeto desconocido. Para casos complejos se puede heredar de json.JSONEncoder y sobrescribir el método default.

Cómo añadir un elemento a un array JSON

En JSON no se puede añadir al final como en un registro de texto: hay que leer el archivo, modificarlo y escribirlo completo.

ruta = Path("datos/elementos.json")
elementos = json.loads(ruta.read_text(encoding="utf-8")) if ruta.exists() else []
elementos.append({"id": len(elementos) + 1, "titulo": "nuevo"})
ruta.write_text(json.dumps(elementos, ensure_ascii=False, indent=2), encoding="utf-8")

Si hay muchos registros que se añaden de forma continua, conviene el formato JSON Lines: un objeto JSON por línea, y el archivo se abre en modo "a".

CSV en Python: el módulo csv

CSV es una tabla en un archivo de texto: las filas son registros y los valores van separados por comas. El módulo csv gestiona bien las comillas, las comas dentro de los valores y los saltos de línea, algo que no hace un split(",") manual.

import csv

with open("datos/gastos.csv", newline="", encoding="utf-8") as f:
    lector = csv.DictReader(f)
    total = 0.0
    for fila in lector:
        total += float(fila["importe"])
        print(fila["fecha"], fila["categoria"], fila["importe"])
print("Total:", total)

csv.DictReader convierte cada línea en un diccionario según la cabecera del archivo. Todos los valores son cadenas: los números y las fechas hay que convertirlos (float, int, date.fromisoformat). Un archivo con separador «;» (así lo guarda Excel en muchas configuraciones regionales europeas) se lee con el parámetro delimiter=";".

filas = [
    {"fecha": "2026-10-01", "categoria": "comida", "importe": 450},
    {"fecha": "2026-10-02", "categoria": "transporte", "importe": 60},
]
with open("datos/salida.csv", "w", newline="", encoding="utf-8") as f:
    escritor = csv.DictWriter(f, fieldnames=["fecha", "categoria", "importe"])
    escritor.writeheader()
    escritor.writerows(filas)

Al escribir es obligatorio newline="": sin él, en Windows aparecerían líneas vacías entre las filas. Si el archivo se va a abrir en Excel, use encoding="utf-8-sig": la marca BOM ayuda a Excel a reconocer UTF-8.

De CSV a JSON: ejemplo completo

import csv
import json
from collections import defaultdict
from pathlib import Path

origen = Path("datos/gastos.csv")
destino = Path("datos/informe.json")

por_categoria = defaultdict(float)
with origen.open(newline="", encoding="utf-8") as f:
    for fila in csv.DictReader(f):
        por_categoria[fila["categoria"]] += float(fila["importe"])

informe = {"total": sum(por_categoria.values()), "categorias": dict(por_categoria)}
destino.write_text(json.dumps(informe, ensure_ascii=False, indent=2), encoding="utf-8")
print(destino.read_text(encoding="utf-8"))

Este es el núcleo de cualquier script de informes: entrada desde CSV, agregación en un diccionario y salida en JSON.

Errores típicos

• FileNotFoundError: la ruta es relativa y se calcula desde la carpeta desde la que se lanza el programa, no desde el script. Use Path(__file__).parent.
• El archivo se ha vaciado: se abrió en "w" en lugar de "a".
• UnicodeDecodeError: el archivo tiene otra codificación; indíquela de forma explícita (cp1251, utf-8-sig).
• TypeError: Object of type set is not JSON serializable: convierta el conjunto en lista o pase default.
• KeyError después de cargar JSON: las claves numéricas se convirtieron en cadenas.
• Un archivo propio se llama json.py o csv.py: tapa el módulo estándar y import json importa ese archivo.

Resumen

Para JSON en Python basta con la biblioteca estándar: json.load y json.dump para archivos, loads y dumps para cadenas, ensure_ascii=False e indent para una salida legible. Abra los archivos con with y con la codificación indicada, construya las rutas con pathlib y lea las tablas con csv.DictReader. En el curso de Python este tema se practica en la práctica: el registro de gastos lee los importes de un CSV y guarda el informe en JSON.