Puedes leer sin crear un espacio. Créalo solo cuando quieras guardar.
Guardar progresoLección 1 de 5
Estructura src y separación de I/O
Separa lógica de negocio, adaptadores Databricks y puntos de entrada para que el mismo código pueda probarse sin ejecutar un notebook completo.
17 min aprox.
01Modelo mentalEstructura src y separación de I/O
Separa lógica de negocio, adaptadores Databricks y puntos de entrada para que el mismo código pueda probarse sin ejecutar un notebook completo.
+
Estructura src y separación de I/O
Separa lógica de negocio, adaptadores Databricks y puntos de entrada para que el mismo código pueda probarse sin ejecutar un notebook completo.
Un proyecto mantenible sitúa el paquete importable bajo `src/`, las pruebas bajo `tests/` y deja los notebooks como orquestadores finos. La lógica que transforma DataFrames vive en funciones con entradas y salidas explícitas; acceso a widgets, secretos, paths y escritura se encapsula en adaptadores. Así un cambio de notebook no es la única unidad desplegable ni verificable.
`pyproject.toml` declara el paquete, versión de Python, dependencias y herramientas. El layout `src/` evita importar accidentalmente el código desde el directorio de trabajo en vez del artefacto instalado. En Databricks Runtime 16.0 o superior, un notebook no debe usarse como módulo Python: refactoriza código compartido a archivos `.py` o a una wheel.
# src/orders/transforms.py
from pyspark.sql import DataFrame, functions as F
def valid_orders(df: DataFrame) -> DataFrame:
return (
df.where(F.col("order_id").isNotNull())
.where(F.col("net_amount") >= 0)
.withColumn("order_date", F.to_date("ordered_at"))
.select("order_id", "customer_id", "order_date", "net_amount")
)La función no conoce catálogo, widgets ni modo de escritura; esas decisiones pertenecen al entry point del job.
¿Por qué una función de transformación no debería leer directamente `dbutils.widgets`?
Profundiza
Un notebook es una interfaz de trabajo, no una frontera arquitectónica. La lógica de negocio debería vivir en funciones y módulos puros que reciben DataFrames o valores y devuelven resultados; los adaptadores se ocupan de spark.table, widgets, secrets, escritura y APIs; el punto de entrada conecta ambos. Esta separación crea seams donde los tests sustituyen catálogos y servicios sin simular un workspace entero. También hace explícitas las dependencias y evita estado oculto de celdas ejecutadas fuera de orden. Un proyecto autosuficiente conserva notebooks delgados para exploración u orquestación, pero el comportamiento crítico se importa desde un paquete versionado que puede ejecutarse localmente, en CI y en Jobs con el mismo código.
Función cuya salida depende sólo de entradas explícitas y no realiza lecturas, escrituras ni acceso oculto a configuración externa.
Puede probarse con datos pequeños y reutilizarse en notebook, job o pipeline sin preparar todo el entorno.Componente que traduce entre la lógica interna y una dependencia concreta como Unity Catalog, REST, secrets o almacenamiento.
Aísla cambios de plataforma y permite sustituir la dependencia en tests unitarios sin falsear reglas de negocio.Punto de ejecución que carga configuración, crea dependencias y coordina lectura, transformación, validación y publicación del workload.
Mantiene orchestration visible y evita que módulos importados ejecuten efectos secundarios de forma accidental.Resumen
Puntos clave
- Notebooks coordinan; módulos Python implementan lógica reutilizable.
- Separa transformaciones puras de lectura, escritura, widgets y secretos.
- Usa layout `src/` para probar el paquete que realmente distribuyes.
Evita
- Encapsular toda la pipeline en un notebook con variables globales y orden de celdas implícito.
- Importar un notebook como módulo cuando el runtime moderno exige archivos Python para código compartido.