# josedev155/python-builder-pattern-and-pytest-example architecture

> Architecture diagram of the GitHub repository josedev155/python-builder-pattern-and-pytest-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josedev155/python-builder-pattern-and-pytest-example
- Repository: https://github.com/josedev155/python-builder-pattern-and-pytest-example

## Overview

##### Identificación del tipo de proyecto y su propósito
- Este repositorio es un pequeño proyecto de ejemplo en Python que demuestra cómo aplicar el patrón creacional Builder dentro de tests con pytest. No es una aplicación cliente-servidor ni un sistema distribuido, sino un conjunto de scripts de prueba centrados en simplificar la creación de objetos de dominio (`Invoice`) y mantener los tests escalables y fáciles de mantener.

##### Análisis de la estructura de archivos
- Nivel raíz:
- README.md         → Documentación y casos de uso.
- testWithoutBuilder.py → Test original que instancia directamente `Invoice`.
- testWithBuilder.py    → Test mejorado que utiliza `InvoiceBuilder`.
- No hay carpetas adicionales (no hay frontend, backend o configuraciones de despliegue). Todo gira en torno a dos scripts de prueba y la definición de la entidad `Invoice` junto con su builder.

##### Puntos clave extraídos del README
- Dominio: la clase `Invoice` es un dataclass con múltiples atributos (id, product, quantity, price, city, etc.).
- Problema inicial: cada vez que se añade o elimina un campo en `Invoice`, hay que modificar todos los tests que crean instancias manualmente.
- Solución: introducir `InvoiceBuilder` con un estado base y métodos encadenables (`with_price()`, `with_quantity()`, etc.) para construir instancias de `Invoice` centradas únicamente en los valores que importan al test.

##### Componentes principales para el diagrama
A. Entidad de dominio
- Invoice (dataclass)
B. Componente Builder
- InvoiceBuilder
- constructor (`__init__`) crea un `Invoice` base con valores por defecto
- métodos `with_*()` que ajustan atributos específicos
- método `build()` que devuelve la instancia configurada
C. Módulos de prueba
- testWithoutBuilder.py
- testWithBuilder.py
D. Dependencias externas
- pytest (librería de test)

##### Relaciones e interacciones
- En `testWithoutBuilder.py`:
Test → instancia directa de `Invoice` → cálculo de suma → assert.
- En `testWithBuilder.py`:
Test → llama a `InvoiceBuilder()` → aplica `with_*()` (opcional) → `build()` → obtiene `Invoice` → cálculo de suma → assert.
- Ambos tests dependen de la definición de `Invoice`. El segundo test añade una capa intermedia (`InvoiceBuilder`) encargada de manejar la mutabilidad de la estructura de `Invoice`.

##### Patrón y principios de diseño
- Patrón Builder: separa la construcción compleja (o cambiante) de objetos (`Invoice`) de su representación, encapsulando valores por defecto y permitiendo personalizaciones vía métodos encadenables.
- Principio de una única responsabilidad: `InvoiceBuilder` sólo construye, los tests sólo verifican lógica de agregación.

##### Cómo dibujar el diagrama de arquitectura
- Usa rectángulos o cajas para cada componente:
[Invoice]
[InvoiceBuilder]
[testWithoutBuilder.py]
[testWithBuilder.py]
[pytest]
- Con flechas direccionales:
- Indica el flujo “construcción → cálculo → assert”.
- Azul para la entidad de dominio (`Invoice`).
- Verde para el builder.
- Naranja para los módulos de prueba.
- Gris o punteado para la librería externa (pytest).
- Etiqueta cada flecha con la acción principal:
- “new Invoice(…)”
- “build()”
- “with_price()/with_quantity()”
- “sum(…) & assert”

##### Guía rápida para el diagrama final
1. A la izquierda, ubica la entidad de dominio y el builder en un “módulo de modelo”:
[Invoice] ← [InvoiceBuilder]
2. A la derecha, coloca los dos scripts de test:
[testWithoutBuilder.py]
[testWithBuilder.py]
3. Encima o debajo, coloca la dependencia externa:
[pytest]
4. Flechas desde cada test a los módulos que usan:
testWithoutBuilder.py → Invoice
testWithBuilder.py → InvoiceBuilder → Invoice
Ambos tests → pytest
5. Usa colores:
- Entidad: celeste
- Builder: verde
- Tests: amarillo
- External: gris
6. Añade notas cortas:
- “Instancia manual”
- “Uso de patrón Builder”

Con este diagrama, cualquier ingeniero podrá ver de un vistazo: la estructura de pruebas original, la introducción del patrón Builder, la entidad central y su flujo de construcción y validación con pytest. Asegúrate de mostrar claramente los límites—qué parte corresponde al dominio (modelo), qué parte al builder y qué parte a la suite de pruebas—para que la arquitectura quede perfectamente documentada.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Documentación"
        README["README.md"]:::external
    end

    subgraph "Dominio (Modelo)"
        Invoice["Invoice (dataclass)"]:::entity
        InvoiceBuilder["InvoiceBuilder"]:::builder
    end

    subgraph "Suite de Pruebas"
        testWithout["testWithoutBuilder.py"]:::test
        testWith["testWithBuilder.py"]:::test
    end

    pytest["pytest"]:::external

    testWithout -->|"new Invoice(...)"| Invoice
    testWithout -->|"pytest run"| pytest

    testWith -->|"new InvoiceBuilder()"| InvoiceBuilder
    testWith -->|"with_price()/with_quantity()"| InvoiceBuilder
    InvoiceBuilder -->|"build()"| Invoice
    testWith -->|"pytest run"| pytest

    click Invoice "https://github.com/josedev155/python-builder-pattern-and-pytest-example/blob/main/testWithoutBuilder.py"
    click InvoiceBuilder "https://github.com/josedev155/python-builder-pattern-and-pytest-example/blob/main/testWithBuilder.py"
    click testWithout "https://github.com/josedev155/python-builder-pattern-and-pytest-example/blob/main/testWithoutBuilder.py"
    click testWith "https://github.com/josedev155/python-builder-pattern-and-pytest-example/blob/main/testWithBuilder.py"
    click README "https://github.com/josedev155/python-builder-pattern-and-pytest-example/blob/main/README.md"
    click pytest "https://github.com/josedev155/python-builder-pattern-and-pytest-example/blob/main/testWithoutBuilder.py"

    classDef entity fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef builder fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef test fill:#ffd700,stroke:#000,stroke-width:1px;
    classDef external fill:#d3d3d3,stroke-dasharray: 5 5,stroke:#000;
```
