Salida estructurada en Python

De Python a JSON

En la comparación con PowerShell aparece una diferencia importante de foco. En PowerShell, la salida estructurada suele pensarse para consumo inmediato: verla en consola, filtrarla, proyectarla o encadenarla en el pipeline. En Python, en cambio, muchas veces la estructura se prepara para consumo externo: guardarla en un archivo, enviarla por una API o compartirla con otro sistema.

JSON encaja bien en ese escenario porque ofrece un formato textual simple, portable y fácil de leer desde muchos lenguajes. Por eso es común construir una estructura en memoria y luego convertirla en una representación JSON estable.

from __future__ import annotations

import json
from pathlib import Path
from typing import TypeAlias

JSONValue: TypeAlias = (
    dict[str, "JSONValue"]
    | list["JSONValue"]
    | str
    | int
    | float
    | bool
    | None
)

def save_to_json(data: JSONValue, filename: str | Path) -> None:
    with Path(filename).open("w", encoding="utf-8") as file:
        json.dump(data, file, indent=4, ensure_ascii=False, sort_keys=True)

from __future__ import annotations

import json
from pathlib import Path
from typing import TypeAlias

JSONValue: TypeAlias = (
    dict[str, "JSONValue"]
    | list["JSONValue"]
    | str
    | int
    | float
    | bool
    | None
)

def save_to_json(data: JSONValue, filename: str | Path) -> None:
    with Path(filename).open("w", encoding="utf-8") as file:
        json.dump(data, file, indent=4, ensure_ascii=False, sort_keys=True)

De JSON a @dataclass@dataclass y viceversa

En la lección base, [PSCustomObject][PSCustomObject] marcaba el momento en que la salida dejaba de ser solo un contenedor clave-valor y pasaba a tener una forma más explícita.

Python no ofrece un equivalente directo con la misma integración de consola. Aun así, @dataclass@dataclass suele marcar un cambio parecido: dejamos de usar un contenedor genérico y pasamos a modelar una estructura con significado más claro y más estable.

Ese cambio se vuelve útil cuando la forma del dato deja de ser accidental: conviene nombrarla, acceder a sus campos como atributos y tratarla como parte de una interfaz que otras partes del programa pueden asumir y reutilizar.

from dataclasses import dataclass
import json
from pathlib import Path
from json_utils import JSONValue

@dataclass(frozen=True)
class Comic:
    title: str
    writer: str
    release_year: int

    def to_json_serializable(self) -> JSONValue:
        return self.__dict__

def comic_from_json(file_path: str | Path) -> Comic:
    with Path(file_path).open("r", encoding="utf-8") as file:
        data = json.load(file)
        return Comic(**data)

from dataclasses import dataclass
import json
from pathlib import Path
from json_utils import JSONValue

@dataclass(frozen=True)
class Comic:
    title: str
    writer: str
    release_year: int

    def to_json_serializable(self) -> JSONValue:
        return self.__dict__

def comic_from_json(file_path: str | Path) -> Comic:
    with Path(file_path).open("r", encoding="utf-8") as file:
        data = json.load(file)
        return Comic(**data)

Además de volver más explícita la intención del modelo, @dataclass@dataclass genera automáticamente un constructor y una representación textual útil para depuración. La diferencia importante no es solo cómo se imprime el valor, sino que ahora la estructura tiene nombre y puede formar parte explícita de la interfaz del programa.

{
    "title": "Nightwing: Time of the Titans",
    "writer": "Tom King",
    "release_year": 2024
}

{
    "title": "Nightwing: Time of the Titans",
    "writer": "Tom King",
    "release_year": 2024
}

comic = comic_from_json("comic.json")
print(comic)

comic = comic_from_json("comic.json")
print(comic)

Conclusiones

La idea central de esta lección no es que Python replique el modelo de salida de PowerShell, sino que organiza la salida estructurada con otras prioridades. Mientras PowerShell destaca cuando quieres objetos listos para consola y pipeline, Python suele sobresalir cuando necesitas datos explícitos que luego persistes, intercambias o entregas a otras partes del programa.

En ese recorrido, JSON funciona como uno de los puentes más visibles: una estructura en memoria puede guardarse en un archivo, viajar hacia otra herramienta y volver a levantarse como dato dentro de Python. Cuando esa estructura deja de ser un diccionario ocasional y pasa a tener una forma conocida, @dataclass@dataclass ayuda a nombrarla y tratarla como un modelo más claro y reusable.

La lección propone, entonces, otro criterio de diseño para la salida estructurada: en Python, muchas veces importa más que el dato sea fácil de intercambiar, serializar y reutilizar que presentarlo automáticamente en terminal. La decisión importante no es solo cómo mostrar la salida, sino cuándo basta un contenedor flexible y cuándo conviene declarar un modelo explícito.