Ir al contenido
wannacode

Builder

En resumen: Builder arma un objeto complejo paso a paso, con un nombre para cada campo, y lo valida en build(); en Python los argumentos con nombre y la dataclass suelen hacer lo mismo.

Problema

Nueve parámetros y dos palabras intercambiadas

La tienda envía un correo cuando un pedido sale. El correo tiene nueve campos: a quién va, la dirección para las respuestas, el asunto, el texto, una copia, una copia oculta, un adjunto, si es importante y si se rastrea su apertura.

class Email:
    def __init__(self, to, reply_to, subject, body, cc, bcc,
                 attachment, high_priority, track_opens):
        self.to = to
        self.reply_to = reply_to
        self.subject = subject
        self.body = body
        self.cc = cc
        self.bcc = bcc
        self.attachment = attachment
        self.high_priority = high_priority
        self.track_opens = track_opens


    def send(self):
        print(f"Para: {self.to}")
        if self.reply_to:
            print(f"Responder a: {self.reply_to}")
        print(f"Asunto: {self.subject}")
        if self.attachment:
            print(f"Adjunto: {self.attachment}")
        if self.high_priority:
            print("Prioridad alta")

Así se envía la confirmación del pedido 1042:

email = Email("support@shop.example", "maria@example.com", "El pedido 1042 ha sido enviado",
              "Tu paquete está en camino.", None, None, "invoice-1042.pdf", True, False)
email.send()
Salida
Para: support@shop.example
Responder a: maria@example.com
Asunto: El pedido 1042 ha sido enviado
Adjunto: invoice-1042.pdf
Prioridad alta

El correo fue al soporte de la tienda, y María no recibió nada. Los dos primeros argumentos están intercambiados. Los dos son texto, así que el lenguaje no tiene forma de saberlo. ¿Y cuál es true y cuál false al final? Para averiguarlo, cuentas posiciones en el constructor. Dos None guardan el lugar de campos que este correo no tiene.

Python tiene argumentos con nombre (reply_to="…"), pero nada te obliga a usarlos: la llamada posicional se ejecuta sin error.

Cada campo nuevo, digamos el idioma del correo, cambia el constructor y cada lugar que lo llama.

La idea

Builder: por nombre, por pasos, con comprobación

El objeto no se crea con una llamada de nueve posiciones, sino por pasos, cada uno con un nombre: .to(…), .subject(…). Los pasos van a un objeto aparte, el builder. Él reúne los valores, y al final build():

  • comprueba los campos obligatorios (aquí: destinatario, asunto y texto) y lanza una excepción si falta alguno;
  • crea un objeto inmutable: después el correo ya no puede cambiar.

Este es el patrón Builder. Los papeles:

  • el producto: Email, inmutable;
  • el builder: EmailBuilder, con un método para cada campo. El método devuelve el propio builder, así que las llamadas se alinean una tras otra en una cadena;
  • build(): el único lugar donde se comprueba y se crea el producto.
En Python el problema de la primera tarjeta tiene también una respuesta más corta: los argumentos con nombre. Está en la tarjeta «Sin builder». El builder de aquí es para el caso en que el correo se arma por pasos, en distintos lugares del código.

Míralo

La cadena y build()

@dataclass(frozen=True, kw_only=True)
class Email:
    to: str
    reply_to: str | None = None
    subject: str
    body: str
    cc: str | None = None
    bcc: str | None = None
    attachment: str | None = None
    high_priority: bool = False
    track_opens: bool = False


    def send(self):
        print(f"Para: {self.to}")
        if self.reply_to:
            print(f"Responder a: {self.reply_to}")
        print(f"Asunto: {self.subject}")
        if self.attachment:
            print(f"Adjunto: {self.attachment}")
        if self.high_priority:
            print("Prioridad alta")




class EmailBuilder:
    def __init__(self):
        self.fields = {}


    def to(self, value):
        self.fields["to"] = value
        return self


    def reply_to(self, value):
        self.fields["reply_to"] = value
        return self


    def subject(self, value):
        self.fields["subject"] = value
        return self


    def body(self, value):
        self.fields["body"] = value
        return self


    def cc(self, value):
        self.fields["cc"] = value
        return self


    def bcc(self, value):
        self.fields["bcc"] = value
        return self


    def attachment(self, value):
        self.fields["attachment"] = value
        return self


    def high_priority(self):
        self.fields["high_priority"] = True
        return self


    def track_opens(self):
        self.fields["track_opens"] = True
        return self


    def build(self):
        if "to" not in self.fields:
            raise ValueError("Falta el destinatario")
        if "subject" not in self.fields:
            raise ValueError("Falta el asunto")
        if "body" not in self.fields:
            raise ValueError("Falta el texto")
        return Email(**self.fields)

Un builder cuesta código: cada campo se escribe tanto en el correo como en el método del builder. Por eso no se hace para cada clase.

@dataclass(frozen=True, kw_only=True) escribe __init__ por ti: frozen=True prohíbe los cambios después de la creación, y kw_only=True toma los campos solo por nombre. **self.fields pasa el diccionario como argumentos con nombre.
email = (
    EmailBuilder()
    .to("maria@example.com")
    .subject("El pedido 1042 ha sido enviado")
    .body("Tu paquete está en camino.")
    .attachment("invoice-1042.pdf")
    .high_priority()
    .build()
)
email.send()


draft = (
    EmailBuilder()
    .to("peter@example.com")
    .body("Tu paquete está en camino.")
)
try:
    draft.build()
except ValueError as e:
    print(e)
Salida
Para: maria@example.com
Asunto: El pedido 1042 ha sido enviado
Adjunto: invoice-1042.pdf
Prioridad alta
Falta el asunto

email = (
    EmailBuilder()
    .to("maria@example.com")
    .subject("El pedido 1042 ha sido enviado")
    .body("Tu paquete está en camino.")
    .attachment("invoice-1042.pdf")
    .high_priority()
    .build()
)
email.send()


draft = (
    EmailBuilder()
    .to("peter@example.com")
    .body("Tu paquete está en camino.")
)
try:
    draft.build()
except ValueError as e:
    print(e)
Paso a paso, en palabras
  1. EmailBuilder(): un plano vacío con nueve casillas. Las tres obligatorias (to, subject, body) están marcadas.
  2. .to(…) rellena una casilla y devuelve el mismo builder, así que la cadena continúa.
  3. Cada llamada tiene un nombre: un valor no puede acabar en la casilla equivocada, como pasaba con las posiciones del constructor.
  4. .body(…): las tres casillas obligatorias están rellenas.
  5. Los campos opcionales se escriben solo cuando hacen falta. high_priority() no lleva argumento: ya no hay un true en el octavo lugar.
  6. build() comprueba las casillas obligatorias y estampa un Email. Sus campos son frozen=True: el objeto ya no cambia.
  7. El correo sale hacia María, con la factura, con prioridad alta.
  8. Un builder nuevo, un plano vacío nuevo. Aquí alguien olvidó el asunto.
  9. draft.build() llega a la casilla vacía subject y se detiene con una excepción. Un correo sin asunto ni siquiera llega a existir.
  10. El error dice qué falta. No se ha enviado nada.

El correo sin asunto nunca llega al correo postal: build() lo detiene ya en el armado.

Míralo

Sin builder: lo que ofrece el lenguaje

Python lo tiene en el propio lenguaje. Los campos con valor por defecto son opcionales, y kw_only=True permite llamar solo por nombre. Una comprobación que la dataclass no hace por sí sola va en __post_init__:
@dataclass(frozen=True, kw_only=True)
class Email:
    to: str
    reply_to: str | None = None
    subject: str
    body: str
    cc: str | None = None
    bcc: str | None = None
    attachment: str | None = None
    high_priority: bool = False
    track_opens: bool = False


    def __post_init__(self):
        if "@" not in self.to:
            raise ValueError(f"Dirección incorrecta: {self.to}")
email = Email(
    to="maria@example.com",
    subject="El pedido 1042 ha sido enviado",
    body="Tu paquete está en camino.",
    attachment="invoice-1042.pdf",
    high_priority=True,
)
print(email.to, "/", email.subject, "/", email.high_priority)
Salida
maria@example.com / El pedido 1042 ha sido enviado / True
La llamada posicional de la primera tarjeta ya no pasa:
email = Email("support@shop.example", "maria@example.com", "El pedido 1042 ha sido enviado")
Error
TypeError: Email.__init__() takes 1 positional argument but 4 were given

Cuándo vale la pena un builder de todos modos:

  • el correo se arma por pasos, en distintas partes del código: el adjunto se añade solo si hay factura, la copia solo para empresas;
  • hay una comprobación entre campos: por ejemplo, la copia oculta no puede ser la dirección del destinatario;
  • hay muchos campos, la mayoría opcionales, y el armado tiene que pasar de un lugar a otro antes de estar listo.

Pruébalo

Predice la salida

Un builder, dos llamadas a build(). ¿Qué imprime el programa?

builder = (
    EmailBuilder()
    .to("maria@example.com")
    .subject("El pedido 1042 ha sido enviado")
    .body("Tu paquete está en camino.")
)
first = builder.build()
builder.high_priority()
second = builder.build()
print(first.high_priority, second.high_priority)
Respuesta

Pruébalo

Encuentra el error

La tienda envía los correos de los pedidos enviados en un bucle. Solo el primer pedido tiene factura:

orders = [
    ("maria@example.com", 1042, "invoice-1042.pdf"),
    ("peter@example.com", 1043, None),
]
builder = EmailBuilder().reply_to("support@shop.example")
for email, order_id, invoice in orders:
    builder.to(email).subject(f"El pedido {order_id} ha sido enviado")
    builder.body("Tu paquete está en camino.")
    if invoice:
        builder.attachment(invoice)
    builder.build().send()
Salida
Para: maria@example.com
Responder a: support@shop.example
Asunto: El pedido 1042 ha sido enviado
Adjunto: invoice-1042.pdf
Para: peter@example.com
Responder a: support@shop.example
Asunto: El pedido 1043 ha sido enviado
Adjunto: invoice-1042.pdf

Peter recibió la factura de María. ¿En qué línea está el error?

Elige la línea con el error.

La idea

Cuándo no lo necesitas

Builder duplica el código de la clase. No compensa cuando:

  • hay dos o tres campos y todos son obligatorios: un constructor simple es más claro;
  • los argumentos con nombre y una dataclass hacen lo mismo sin una segunda clase;
  • el objeto no tiene nada que comprobar y no se arma por pasos.

Compensa cuando hay muchos campos y la mayoría son opcionales, cuando hay una comprobación entre ellos, o cuando el objeto se arma por pasos, en distintas partes del código.

Ejercicio

Un paquete para el mensajero

Resuelve la tarea en tu editor.

Un builder para un paquete. El mensajero quiere un paquete con destinatario, teléfono, dirección y peso (obligatorios), y opcionalmente: frágil y contra reembolso. Escribe Shipment y un builder para él. build() comprueba que los campos obligatorios estén puestos y que el peso sea mayor que 0 y de hasta 30 kg. Crea un paquete para María (2,5 kg, frágil, contra reembolso 42,90 €), imprímelo y prueba un paquete de 45 kg:

Salida
Paquete para María, 0888 123 456
Dirección: Calle Mayor 5, Madrid
Peso: 2.5 kg, frágil
Contra reembolso: 42.90 €
El peso debe ser mayor que 0 y de hasta 30 kg

Más tareas

  • Arregla el bucle. Arregla el programa de «Encuentra el error» para que cada correo lleve solo su propia factura. La dirección de respuesta debe quedar para todos los correos.
  • Una copia con un cambio. Añade un método que convierta un correo terminado en un builder con los mismos valores (en Java suele llamarse toBuilder()). Envía el mismo correo a otro destinatario.
  • El camino del lenguaje. Escribe Shipment como en la tarjeta «Sin builder» y compara las dos versiones. ¿Cuál es más corta, y qué pierdes?

Test

Ponte a prueba

1. Email("support@…", "maria@…", …) se ejecuta sin error, y el correo va a otro sitio. ¿Por qué no ayudó Python?
2. ¿Qué hace build()?
3. El builder se crea antes del bucle y se usa para cada correo. El segundo correo recibió el adjunto del primero. ¿Por qué?
4. ¿Cuándo vale la pena Builder de todos modos?
5. ¿Qué resuelve en Python el problema de los nueve argumentos posicionales?

Creado por Ivo Gergov como parte de la campaña de Evo Tech por una educación accesible en programación ·