gss-bi-udfs 0.1.0__py3-none-any.whl → 0.1.1__py3-none-any.whl

gss_bi_udfs/__init__.py

@@ -0,0 +1,11 @@
+from . import io
+from . import merges
+from . import transforms
+from . import utils
+
+__all__ = [
+    "io",
+    "merges",
+    "transforms",
+    "utils",
+]

gss_bi_udfs/io.py

@@ -0,0 +1,376 @@
+from .utils import get_env, get_table_info
+
+# def load_latest_file_bronze(spark, data_base, schema, table, env=None):
+def load_latest_parquet(spark, data_base, schema, table, env=None):
+    """
+    Carga el último archivo Parquet para la tabla especificada y retorna un DataFrame.
+    
+    Parámetros:
+      spark (SparkSession): Sesión activa de Spark.
+      data_base (str): Nombre de la base de datos.
+      schema (str): Nombre del esquema.
+      table (str): Nombre de la tabla.
+      env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                           Si no se proporciona, se obtiene usando get_env().
+    
+    Retorna:
+      DataFrame de Spark cargado desde el archivo Parquet más reciente.
+    """
+    env = env or get_env()
+    base_path = f"/Volumes/bronze/{data_base}_{schema}/{env}/{table}/"
+
+    try:
+        files = dbutils.fs.ls(base_path) # type: ignore
+
+        parquet_files = [f for f in files if table in f.name]
+        
+        if not parquet_files:
+            return None
+        
+        latest_file = sorted(parquet_files, key=lambda f: f.name, reverse=True)[0]
+        df = spark.read.parquet(latest_file.path)
+        return df
+             
+    except Exception as e:
+        print("Error al procesar los archivos:", e)
+        return None
+
+    
+def return_parquets_and_register_temp_views(spark, tables_load, verbose=False, env=None):
+    """
+    Carga dataframes a partir de un diccionario de definición de tablas y materializa vistas temporales.
+    Retorna un diccionario con los dataframes.
+    
+    Parámetros:
+        spark (SparkSession): Sesión activa de Spark.
+        tables_load (dict): Diccionario que define las tablas a cargar y sus vistas temporales.
+        verbose (bool): Si es True, imprime mensajes de estado durante la carga.
+        env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                             Si no se proporciona, se obtiene usando get_env().
+                             
+    Retorna:
+        dict: Diccionario donde las claves son nombres completos de tablas y los valores son DataFrames.
+    """
+    dataframes = {}
+
+    for data_base, schemas in tables_load.items():
+        for schema, tables in schemas.items():
+            for t in tables:
+                table = t['table']
+                view = t['view']
+
+                # Cargar el dataframe usando la función que proveés
+                df = load_latest_parquet(spark, data_base, schema, table, env)
+                
+                # Guardar en el diccionario
+                key = f"{data_base}.{schema}.{table}"
+                dataframes[key] = df
+
+                # Materializar la vista (esto no necesita asignación en Python)
+                try:
+                    df.createOrReplaceTempView(view)
+                    if verbose:
+                        print(f'Tabla "{key}" cargada y vista "{view}" materializada')
+                except Exception as e:
+                    print(f"Error al materializar la vista '{view} tabla {key}': {e}")
+                
+    return dataframes
+
+
+def parquets_register_temp_views(spark, tables_load, verbose=False, env=None):
+    """
+    Lee los últimos parquets y materializa vistas temporales en Spark. Sin retorna nada.
+    Parámetros:
+        spark (SparkSession): Sesión activa de Spark.
+        tables_load (dict): Diccionario que define las tablas a cargar y sus vistas temporales.
+            La estructura esperada del parámetro `tables_load` es un diccionario
+            anidado con el siguiente formato:
+
+                {
+                    "<base_de_datos>": {
+                        "<schema>": [
+                            {
+                                "table": "<nombre_tabla>",
+                                "view": "<nombre_vista_temporal>"
+                            },
+                            ...
+                        ]
+                    },
+                    ...
+                }
+            Ejemplo:
+                tables_load = {
+                    "bup": {
+                        "bup": [
+                            {"table": "naturalpersons", "view": "vw_naturalpersons"},
+                            {"table": "maritalstatus", "view": "vw_maritalstatus"},
+                            {"table": "genders", "view": "vw_genders"},
+                            {"table": "legalpersons", "view": "vw_legalpersons"},
+                            {"table": "phones", "view": "vw_phones"},
+                            {"table": "emails", "view": "vw_emails"},
+                            {"table": "addresses", "view": "vw_addresses"},
+                            {"table": "persons", "view": "vw_persons"},
+                            {"table": "administrativefreezeperiods", "view": "vw_administrativefreezeperiods"},
+                            {"table": "fraudrisklevels", "view": "vw_fraudrisklevels"},
+                        ],
+                    },
+                    "oraculo": {
+                        "dbo": [
+                            {"table": "ml_segmentacion", "view": "vw_segmentacion"},
+                        ],
+                    },
+                    "timepro": {
+                        "insudb": [
+                            {"table": "logauth0user", "view": "vw_logauth0user"},
+                            {"table": "benefitprogramadhesion", "view": "vw_benefitprogramadhesion"},
+                        ],
+                    },
+                    "dwgssprotmp": {
+                        "dwo": [
+                            {"table": "int_dim_clientactive_bds", "view": "vw_int_dim_cliente_active"},
+                        ],
+                    },
+                    "odscommon": {
+                        "employee": [
+                            {"table": "vw_active_employee", "view": "vw_active_employee"},
+                        ],
+                    },
+                }
+        verbose (bool): Si es True, imprime mensajes de estado durante la carga.
+        env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                             Si no se proporciona, se obtiene usando get_env().
+    Retorna:
+        None
+    """
+    for data_base, schemas in tables_load.items():
+        for schema, tables in schemas.items():
+            for t in tables:
+                table = t['table']
+                view = t['view']
+                try:
+                    df = load_latest_parquet(spark, data_base, schema, table, env)
+                    df.createOrReplaceTempView(view)
+                    if verbose:
+                        print(f'Vista "{view}" materializada desde {data_base}.{schema}.{table}')
+                except Exception as e:
+                    print(f"Error al materializar la vista '{view}' desde {data_base}.{schema}.{table}: {e}")
+
+
+def load_latest_excel(spark, source_file, env=None):
+    
+    """
+    Carga el último archivo de Excel (aunque no tenga extensión visible) para la carpeta especificada
+    y retorna un DataFrame.
+    
+    Parámetros:
+      spark (SparkSession): Sesión activa de Spark.
+      source_file (str): Nombre de la carpeta.
+        env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                            Si no se proporciona, se obtiene usando get_env().
+    Retorna:
+      DataFrame de Spark cargado desde el archivo Excel más reciente (en formato xls).
+    """
+    
+    import pandas as pd
+    
+    env = env or get_env()
+    base_path = f"/Volumes/bronze/excel/{env}/{source_file}/"
+    print("Ruta base:", base_path)
+    
+    try:
+        files = dbutils.fs.ls(base_path) # type: ignore
+        print("Archivos encontrados:", [f.name for f in files])     
+        excel_candidates = [f for f in files if f.isFile()]
+
+        if not excel_candidates:
+            print(f"No se encontraron archivos en la carpeta: {source_file}")
+            return None
+        
+        latest_file = sorted(excel_candidates, key=lambda f: f.name, reverse=True)[0]
+        
+        file_path = latest_file.path.replace("dbfs:", "")
+
+        pdf = pd.read_excel(file_path, header=0, engine='xlrd')
+        
+        return spark.createDataFrame(pdf)
+    
+    except Exception as e:
+        return None
+
+
+def return_excels_and_register_temp_views(spark, files_load, verbose=False, env=None):
+    """
+    Carga dataframes a partir de un diccionario de definición de excels y materializa vistas temporales.
+    Retorna un diccionario con los dataframes.
+    
+    Parámetros:
+        spark (SparkSession): Sesión activa de Spark.
+        files_load (dict): Diccionario que define las tablas a cargar y sus vistas temporales.
+            La estructura esperada del parámetro `files_load` es un diccionario
+            anidado con el siguiente formato:
+
+                {
+                    "<Dominio>": {
+                        "<SubDominio>": [
+                            {
+                                "file": "<nombre_archivo>",
+                                "view": "<nombre_vista_temporal>"
+                            },
+                            ...
+                        ]
+                    },
+                    ...
+                }
+            Ejemplo:
+        verbose (bool): Si es True, imprime mensajes de estado durante la carga.
+        env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                             Si no se proporciona, se obtiene usando get_env().
+    
+    Retorna:
+        dict: Diccionario donde las claves son nombres completos de tablas y los valores son DataFrames.
+            Quedando las vistas materializadas en el entorno Spark.
+    """
+    dataframes = {}
+
+    for domain, subdomain in files_load.items():
+        for subdomain, tables in subdomain.items():
+            for t in tables:
+                file = t['file']
+                view = t['view']
+
+                # Cargar el dataframe usando la función que proveés
+                source_file = f"{domain}/{subdomain}/{file}"
+                df = load_latest_excel(spark, source_file, env)
+                
+                # Guardar en el diccionario
+                key = f"{domain}.{subdomain}.{file}"
+                dataframes[key] = df
+
+                # Materializar la vista (esto no necesita asignación en Python)
+                try:
+                    df.createOrReplaceTempView(view)
+                    if verbose:
+                        print(f'El archivo "{key}" cargado y vista "{view}" materializada')
+                except Exception as e:
+                    print(f"Error al materializar la vista '{view} tabla {key}': {e}")
+                
+    return dataframes
+
+
+def excels_register_temp_views(spark, files_load, verbose=False, env=None):
+    """
+    Lee los últimos archivos excels y materializa vistas temporales en Spark. Sin retorna nada.
+    
+    Parámetros:
+        spark (SparkSession): Sesión activa de Spark.
+        files_load (dict): Diccionario que define las tablas a cargar y sus vistas temporales.
+            La estructura esperada del parámetro `files_load` es un diccionario
+            anidado con el siguiente formato:
+
+                {
+                    "<Dominio>": {
+                        "<SubDominio>": [
+                            {
+                                "file": "<nombre_archivo>",
+                                "view": "<nombre_vista_temporal>"
+                            },
+                            ...
+                        ]
+                    },
+                    ...
+                }
+            Ejemplo:
+        verbose (bool): Si es True, imprime mensajes de estado durante la carga.
+        env (str, opcional): Entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+                             Si no se proporciona, se obtiene usando get_env().
+    
+    Retorna:
+        Nada
+    """
+
+    for domain, subdomain in files_load.items():
+        for subdomain, tables in subdomain.items():
+            for t in tables:
+                file = t['file']
+                view = t['view']
+
+                # Cargar el dataframe usando la función que proveés
+                source_file = f"{domain}/{subdomain}/{file}"
+                df = load_latest_excel(spark, source_file, env)
+                
+                # Guardar en el diccionario
+                key = f"{domain}.{subdomain}.{file}"
+
+                # Materializar la vista (esto no necesita asignación en Python)
+                try:
+                    df.createOrReplaceTempView(view)
+                    if verbose:
+                        print(f'El archivo "{key}" leido y vista "{view}" materializada')
+                except Exception as e:
+                    print(f"Error al materializar la vista '{view} tabla {key}': {e}")
+
+
+def load_and_materialize_views(action, **kwargs):    
+    actions_load_bronze = {
+        # Todas las acciones aqui declaradas deberan devolver un diccionario de DataFrames
+        # 'load_notebook': load_notebook,
+        'return_parquets_and_register_temp_views': return_parquets_and_register_temp_views,
+        'parquets_register_temp_views': parquets_register_temp_views,
+        'return_excels_and_register_temp_views': return_excels_and_register_temp_views,
+        'excels_register_temp_views': excels_register_temp_views,
+        # ir agregando más acciones acá
+    }
+    results = {}
+    func = actions_load_bronze.get(action)
+    if func:
+        results = func(**kwargs)
+        # results[action] = result
+    else:
+        print(f"Acción '{action}' no está implementada.")
+    return results
+
+
+def save_table_to_delta(df, catalog, schema, table_name):
+    """
+    Guarda un DataFrame en formato Delta en la ubicación y tabla especificadas,
+    sobrescribiendo los datos existentes y el esquema si es necesario.
+
+    Parámetros:
+      df (DataFrame): DataFrame de Spark que se desea guardar.
+      db_name (str): Nombre del catálogo o base de datos destino.
+      schema (str): Nombre del esquema, capa o entorno destino (ejemplo: 'silver', 'gold').
+      table_name (str): Nombre de la tabla destino.
+
+    Retorna:
+      None
+
+    Lógica:
+      - Utiliza la función auxiliar 'get_table_info' para obtener el path
+        de almacenamiento y el nombre completo de la tabla.
+      - Escribe el DataFrame en formato Delta en la ruta especificada,
+        sobrescribiendo cualquier dato y adaptando el esquema si es necesario.
+      - Registra la tabla como tabla administrada en el metastore con el nombre completo.
+
+    Notas:
+      - El modo 'overwrite' reemplaza todos los datos existentes en la tabla.
+      - La opción 'overwriteSchema' asegura que el esquema de la tabla se actualice si cambió.
+      - Es necesario que la ruta y la tabla existan o sean accesibles en el entorno Spark.
+      - Las opciones
+        `.option("delta.columnMapping.mode", "nameMapping")` y `.option("delta.columnMapping.mode", "name")`
+        permiten especificar el modo de mapeo de columnas para Delta Lake:
+          - **"nameMapping"**: usa un mapeo explícito de columnas por nombre, útil para cambios de nombre o reordenamiento de columnas sin perder datos.
+          - **"name"**: usa el nombre de columna directamente para el mapeo, opción recomendada cuando no se necesita trazabilidad de cambios en los nombres de columna, permite utilizar los acentos en el nombre de las columnas.
+      - Si ambas opciones se usan al mismo tiempo, solo una tendrá efecto (se aplicará la última indicada).
+
+    """
+    dim_destino = get_table_info(catalog=catalog, schema=schema, table=table_name)
+    (
+        df.write
+        .format("delta")
+        .option("path", dim_destino["path"])
+        .mode("overwrite")
+        .option("overwriteSchema", "true")
+        .option("delta.columnMapping.mode", "nameMapping") \
+        .option("delta.columnMapping.mode", "name") \
+        .saveAsTable(dim_destino["full_table_name"])
+    )

gss_bi_udfs/merges.py

@@ -0,0 +1,191 @@
+from pyspark.sql import functions as F
+from .io import save_table_to_delta
+from .utils import get_table_info
+from .transforms import add_hashid
+
+def merge_scd2(
+    spark,
+    df_dim_src,
+    table_name,
+    business_keys,
+    surrogate_key,
+    eow_date="9999-12-31"
+):
+    """
+    Aplica Slowly Changing Dimension Tipo 2 (SCD2) sobre una tabla Delta.
+
+    El DataFrame de entrada (`df_dim_src`) debe representar el estado actual de la dimensión
+    a nivel de negocio, con el MISMO esquema lógico que la tabla destino,
+    excluyendo únicamente la PK física (surrogate key) del Data Warehouse.
+    `df_dim_src` NO debe incluir la clave primaria física (surrogate key).
+    Esta se genera internamente como un hash de (business_keys + valid_from).
+
+    La lógica implementa versionado histórico de registros utilizando fechas de vigencia
+    (valid_from, valid_to), manteniendo una única versión activa por entidad de negocio.
+
+    CONCEPTOS CLAVE Y SUPUESTOS DEL MODELO
+    -------------------------------------
+    1. Clave de negocio (Business Keys):
+       - El parámetro `business_keys` DEBE representar la clave de negocio que identifica
+         unívocamente a la entidad (por ejemplo: nbranch, nproduct).
+       - Esta clave NO debe cambiar en el tiempo.
+       - El merge se realiza exclusivamente contra esta clave de negocio
+         y contra el registro activo (valid_to = eow_date).
+
+    2. Clave primaria física del Data Warehouse:
+       - La dimensión DEBE tener una clave primaria física (surrogate key) propia del DW
+         para identificar cada versión histórica del registro.
+       - Esta PK física NO participa de la lógica de comparación ni del merge funcional,
+         y su generación queda fuera del alcance de esta función.
+
+    3. Columnas comparadas (detección de cambios):
+       - La función compara TODAS las columnas del DataFrame de entrada
+         EXCEPTO:
+           - la clave de negocio (`business_keys`)
+           - las columnas de vigencia (`valid_from`, `valid_to`)
+       - Si cualquiera de las columnas comparadas cambia, se genera una nueva versión
+         del registro (SCD Tipo 2).
+       - Esto implica que cualquier nueva columna agregada al esquema será
+         automáticamente considerada para versionado.
+
+       IMPORTANTE:
+       - Por este motivo, se recomienda que el DataFrame NO incluya columnas técnicas
+         o volátiles (timestamps de carga, ids de proceso, metadatos, etc.),
+         ya que provocarían versionado innecesario.
+
+       - El DataFrame de entrada PUEDE incluir las columnas `valid_from` y `valid_to`;
+         en caso de existir, serán ignoradas para la detección de cambios y
+         recalculadas internamente por la función.
+
+    4. Manejo de fechas de vigencia:
+       - valid_from: DATE inclusiva
+       - valid_to:    DATE inclusiva
+       - El registro activo siempre tiene valid_to = eow_date (por defecto 9999-12-31).
+       - Ante un cambio:
+           * la versión anterior se cierra con valid_to = current_date() - 1
+           * la nueva versión se inserta con valid_from = current_date()
+       - Esto garantiza que no existan solapamientos de vigencia.
+
+       - Si el DataFrame de entrada no contiene `valid_from` y `valid_to`,
+         la función las generará automáticamente durante la carga inicial
+         o incremental.
+
+    5. Carga inicial:
+       - Si la tabla destino no existe, se realiza un full load inicial,
+         asignando valid_from = '1900-01-01' y valid_to = eow_date
+         a todos los registros.
+
+    PARÁMETROS
+    ----------
+    spark : SparkSession
+        SparkSession activo.
+    df_dim_src : DataFrame
+        DataFrame de Spark que contiene los datos a mergear.
+        Debe incluir TODAS las columnas de negocio de la dimensión
+        (clave(s) de negocio + atributos versionables),
+        con el mismo esquema lógico que la tabla destino.
+        NO debe incluir la clave primaria física (surrogate key).
+    table_name : str
+        Nombre completo (catalogo.esquema.tabla) de la tabla Delta destino. 
+    business_keys : str or list[str]
+        Nombre(s) de la(s) columna(s) que representa(n) la clave de negocio.
+        Puede ser una clave simple (str) o compuesta (lista de str).
+    surrogate_key : str
+        Nombre de la clave primaria física (surrogate key) de la dimensión.
+        Se genera internamente como un hash de (business_keys + valid_from).
+    eow_date : str, opcional
+        Fecha de fin de vigencia para registros activos.
+        Por defecto: '9999-12-31'.
+
+    RETORNO
+    -------
+    None
+        La función ejecuta el merge directamente sobre la tabla Delta.
+    """
+
+    # Normalize business_keys to a list (support single column or composite key)
+    if isinstance(business_keys, str):
+        business_keys = [business_keys]
+
+    missing_bk = [c for c in business_keys if c not in df_dim_src.columns]
+    if missing_bk:
+        raise ValueError(f"Columnas de business key inexistentes en df_dim_src: {missing_bk}")
+
+    exclude_cols = set(business_keys) | {"valid_from", "valid_to"}
+    compare_cols = [c for c in df_dim_src.columns if c not in exclude_cols]
+
+    info_table = get_table_info(spark,full_table_name=table_name)
+
+    if not spark.catalog.tableExists(table_name):
+        df_nov = (
+            df_dim_src
+            .withColumn("valid_from", F.to_date(F.lit("1900-01-01")))
+            .withColumn("valid_to",   F.to_date(F.lit(eow_date)))
+        )
+        pk_cols = business_keys + ["valid_from"]
+        df_nov = add_hashid(df_nov, pk_cols, surrogate_key)
+        
+        save_table_to_delta(spark, df_nov, info_table["catalog"], info_table["schema"], info_table["table"])
+        df_nov.write \
+            .format("delta") \
+            .mode("overwrite") \
+            .option("overwriteSchema", "true") \
+            .saveAsTable(table_name)
+        print(f"[FULL LOAD] {table_name} creado con SCD-2")
+        return
+
+    df_nov = (
+        df_dim_src
+        .withColumn("valid_from", F.current_date().cast("date"))
+        .withColumn("valid_to",   F.to_date(F.lit(eow_date)))
+    )
+    pk_cols = business_keys + ["valid_from"]
+    df_nov = add_hashid(df_nov, pk_cols, surrogate_key)
+
+    delta_tgt = info_table["full_table_name"]
+    bk_cond = " AND ".join([f"t.{k} = s.{k}" for k in business_keys])
+    merge_cond = f"{bk_cond} AND t.valid_to = date('{eow_date}')"
+    t_hash = "xxhash64(concat_ws('', " + ", ".join(f"t.{c}" for c in compare_cols) + "))"
+    s_hash = "xxhash64(concat_ws('', " + ", ".join(f"s.{c}" for c in compare_cols) + "))"
+    diff_cond = f"{t_hash} <> {s_hash}"
+
+    (delta_tgt.alias("t")
+        .merge(df_nov.alias("s"), merge_cond)
+        .whenMatchedUpdate(
+            condition=diff_cond,
+            set={"valid_to": "date_sub(current_date(), 1)"}
+        )
+        .whenNotMatchedInsertAll()
+        .whenNotMatchedBySourceUpdate(
+            condition=f"t.valid_to = date('{eow_date}')",
+            set={"valid_to": "date_sub(current_date(), 1)"}
+        )
+        .execute()
+    )
+
+    closed_count = delta_tgt.toDF() \
+        .filter(F.col("valid_to") == F.date_sub(F.current_date(), 1)) \
+        .count()
+    if closed_count > 0:
+        print(f"Se cerraron {closed_count} versiones en {table_name}")
+
+    t_active = (
+        delta_tgt.toDF()
+        .filter(F.col("valid_to") == F.to_date(F.lit(eow_date)))
+    )
+    join_conds = [F.col(f"s.{k}") == F.col(f"t.{k}") for k in business_keys] + [
+        F.col(f"s.{c}") == F.col(f"t.{c}") for c in compare_cols
+    ]
+    df_to_app = df_nov.alias("s").join(
+        t_active.alias("t"), on=join_conds, how="left_anti"
+    )
+
+    new_count = df_to_app.limit(1).count()
+    if new_count > 0:
+        df_to_app.write \
+            .format("delta") \
+            .mode("append") \
+            .saveAsTable(table_name)
+        print(f"Se insertaron nuevas versiones en {table_name}")
+    else:
+        print(f"No hay nuevas versiones para {table_name}")

gss_bi_udfs/transforms.py

@@ -0,0 +1,56 @@
+from pyspark.sql import DataFrame
+from pyspark.sql.functions import xxhash64
+from pyspark.sql.functions import concat_ws, col
+
+
+from .utils import get_default_value_by_type
+
+def add_hashid(
+        df: DataFrame,
+        columns: list[str],
+        new_col_name: str = "hashid"
+    ) -> DataFrame:
+        """
+        Agrega una columna hash (PK) a partir de la concatenación de columnas
+        y reordena el DataFrame dejando el hash como primera columna.
+
+        Parametros:
+            df: DataFrame de Spark de entrada
+            columns: Lista de columnas a concatenar
+            new_col_name: Nombre de la columna hash (default: hashid)
+            
+        Retorna:
+            DataFrame con hash agregado
+        """
+
+        if not columns:
+            raise ValueError("La lista de columnas no puede estar vacía")
+
+        # Concatenación segura
+        concatenated = concat_ws("|", *[col(c).cast("string") for c in columns])
+
+        # Hash rápido y determinístico (ideal para PK técnica)
+        df_with_hash = df.withColumn(new_col_name, xxhash64(concatenated))
+
+        # Reordenar columnas
+        original_cols = [c for c in df.columns if c != new_col_name]
+        new_cols = [new_col_name] + original_cols
+
+        return df_with_hash.select(*new_cols)
+    
+
+def get_default_record(spark, df: DataFrame) -> DataFrame:
+    """
+    Crea un DataFrame con un único registro de valores por defecto según el esquema de df:
+    Parámetros:
+        spark: SparkSession activo.
+        df (DataFrame): DataFrame de Spark del cual se tomará el esquema.
+        
+    Retorna:
+        DataFrame: DataFrame con un único registro con valores por defecto.
+    """
+    defaults = {}
+    for field in df.schema.fields:
+        defaults[field.name] = get_default_value_by_type(field.dataType)
+    
+    return spark.createDataFrame([defaults], schema=df.schema)

gss_bi_udfs/utils.py

@@ -0,0 +1,185 @@
+import os
+from pyspark.sql.types import (IntegerType, LongType, ShortType, ByteType,
+                               DecimalType, DoubleType, FloatType,
+                               DateType, TimestampType, BooleanType, StringType)
+from pyspark.sql.functions import lit, concat_ws, col
+from pyspark.sql import DataFrame, Column
+
+
+def get_env(default="dev"):
+    """
+    Obtiene el entorno de ejecución a partir de la variable de entorno ENV.
+    Si no está definida, retorna el valor por defecto indicado.
+
+    Parámetros:
+    - default (str): entorno por defecto a utilizar si ENV no está definida.
+
+    Retorna:
+    - str: nombre del entorno de ejecución (por ejemplo: 'dev', 'qa', 'prod').
+    """
+    
+    return os.getenv("ENV", default)
+
+def get_env_catalog(catalog):
+    """
+    Genera el nombre del catálogo ajustado al environment.
+
+    Parámetros:
+      catalog (str): Nombre base del catálogo (ej. 'fi_comunes').
+
+    Retorna:
+      str: Nombre del catálogo ajustado al environment.
+           Ejemplo: 'fi_comunes_dev' si ENV='dev'
+                    'fi_comunes' si ENV='pro'
+    """
+    
+    if get_env() == "pro":
+        return catalog
+    else:
+        return f"{catalog}_{get_env()}"
+    
+    
+def get_env_table_path(catalog, table_path):
+    """
+    Genera el path completo de una tabla incluyendo el sufijo de ambiente en el catálogo.
+
+    Parámetros:
+      catalog (str): Nombre base del catálogo (ej. 'fi_comunes').
+      table_path (str): Path de la tabla incluyendo esquema y nombre (ej. 'silver.dim_afiliado').
+
+    Retorna:
+      str: Path completo de la tabla ajustado al environment.
+           Ejemplo: 'fi_comunes_dev.silver.dim_afiliado' si ENV='dev'
+                    'fi_comunes.silver.dim_afiliado' si ENV='pro'
+    """
+
+    # Concatena el catálogo modificado con el path de la tabla
+    return f"{get_env_catalog(catalog)}.{table_path}"
+
+def get_schema_root_location(spark, catalog, schema):
+    """
+    Obtiene la ruta física (RootLocation) de un esquema específico, considerando el catálogo ajustado al ambiente.
+
+    Parámetros:
+      catalog (str): Nombre base del catálogo (ej. 'fi_comunes').
+      schema (str): Nombre del esquema dentro del catálogo (ej. 'silver').
+
+    Retorna:
+      str: Ruta física donde se almacenan los datos del esquema.
+           Ejemplo: 's3://bucket/path/fi_comunes_dev/silver' si ENV='dev'
+    
+    Requiere:
+      - La función get_env_catalog debe estar definida y retornar el nombre de catálogo ajustado al ambiente.
+      - SparkSession activa y permisos para ejecutar `DESCRIBE SCHEMA EXTENDED`.
+
+    Ejemplo:
+      >>> get_schema_root_location("fi_comunes", "silver")
+      's3://mi-bucket/datalake/fi_comunes_dev/silver'
+    """
+    cat = get_env_catalog(catalog)
+    df = spark.sql(f"DESCRIBE SCHEMA EXTENDED {cat}.{schema}")
+    return df.filter("database_description_item = 'RootLocation'") \
+             .select("database_description_value") \
+             .collect()[0][0]
+             
+def get_table_info(
+    spark,
+    *,
+    full_table_name: str = None,
+    catalog: str = None,
+    schema: str = None,
+    table: str = None
+) -> dict:
+    """
+    Devuelve información de una tabla a partir de:
+    - full_table_name (catalog.schema.table)
+    o
+    - catalog + schema + table
+    """
+
+    # -----------------------------
+    # 1. Resolver inputs
+    # -----------------------------
+    if full_table_name:
+        parts = full_table_name.split(".")
+        if len(parts) != 3:
+            raise ValueError(
+                "full_table_name debe tener formato catalog.schema.table"
+            )
+        catalog, schema, table = parts
+
+    elif catalog and schema and table:
+        full_table_name = f"{catalog}.{schema}.{table}"
+
+    else:
+        raise ValueError(
+            "Debe informar full_table_name o catalog + schema + table"
+        )
+
+    # -----------------------------
+    # 2. Environment catalog
+    # -----------------------------
+    catalog_env = get_env_catalog(catalog)
+
+    # -----------------------------
+    # 3. Path físico
+    # -----------------------------
+    root_location = get_schema_root_location(spark, catalog, schema)
+    path = f"{root_location.rstrip('/')}/{table}"
+
+    # -----------------------------
+    # 4. Metadata Spark (si existe)
+    # -----------------------------
+    info = {
+        "catalog": catalog_env,
+        "schema": schema,
+        "table": table,
+        "full_table_name": f"{catalog_env}.{schema}.{table}",
+        "path": path,
+        "exists": False,
+        "provider": None,
+        "table_type": None,
+    }
+
+    if spark.catalog.tableExists(info["full_table_name"]):
+        info["exists"] = True
+
+        desc = (
+            spark.sql(f"DESCRIBE EXTENDED {info['full_table_name']}")
+            .filter("col_name in ('Location', 'Provider', 'Type')")
+            .collect()
+        )
+
+        for row in desc:
+            if row.col_name == "Location":
+                info["path"] = row.data_type
+            elif row.col_name == "Provider":
+                info["provider"] = row.data_type
+            elif row.col_name == "Type":
+                info["table_type"] = row.data_type
+
+    return info
+
+
+    
+def get_default_value_by_type(dtype):
+        """
+        Devuelve "default" por tipo de dato para registros 'default/unknown'.
+        Parámetros:
+            - dtype: Tipo de dato (DataType) de PySpark.
+        Retorna:
+            - valor por defecto correspondiente al tipo de dato.
+        """
+        if isinstance(dtype, (IntegerType, LongType, ShortType, ByteType)):
+            return lit(-999)
+        if isinstance(dtype, (DecimalType, DoubleType, FloatType)):
+            return lit(-999)
+        if isinstance(dtype, (DateType, TimestampType)):
+            return lit("1900-01-01").cast(dtype)
+        if isinstance(dtype, BooleanType):
+            return lit(False)
+        if isinstance(dtype, StringType):
+            return lit("N/A")
+        return lit(None)
+    
+

{gss_bi_udfs-0.1.0.dist-info → gss_bi_udfs-0.1.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gss-bi-udfs
-Version: 0.1.0
+Version: 0.1.1
 Summary: Utilidades reutilizables para Spark y Delta Lake en arquitecturas Lakehouse.
 Author: Geronimo Forconi
 Requires-Python: >=3.8
@@ -8,6 +8,14 @@ Description-Content-Type: text/markdown
 Requires-Dist: pyspark>=3.0.0
 
 # gss-bi-udfs
+
 Creo modulo para guardar UDFs comunes a todas las areas de BI.
 
 
+# para compilar
+
+python3 -m build
+
+# para publicar
+
+python3 -m twine upload dist/*

gss_bi_udfs-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+gss_bi_udfs/__init__.py,sha256=VNj2_l7MHiRGF497XVM4KtU7p6JOX1xddkvFJLG1vUQ,152
+gss_bi_udfs/io.py,sha256=yEqQvpyBod9kIv7p-_5yLtINuIwsi-piWy5rKI3BgQk,15939
+gss_bi_udfs/merges.py,sha256=4YHfw6TWU08ZWEMKBtFlMqj_tzXzjqkuM_CJn0uRNUI,7977
+gss_bi_udfs/transforms.py,sha256=yDg7uvPFSTrGXgy5rOUKDdSrRBBZSubfi9K-6rATCWY,1876
+gss_bi_udfs/utils.py,sha256=ryyqrzhybC6mZFTUWsnnrQXReUcLkVqw6e2gIf4Id_g,5982
+gss_bi_udfs-0.1.1.dist-info/METADATA,sha256=q241xBvvuhhJRUL1wIGB_JKCkTxXAF9HY13yYjV3Ae8,423
+gss_bi_udfs-0.1.1.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+gss_bi_udfs-0.1.1.dist-info/top_level.txt,sha256=jLjGHQoep6-wLbW6wFV611Zx4ak42Q9hKtH_3sUzX9o,12
+gss_bi_udfs-0.1.1.dist-info/RECORD,,

gss_bi_udfs-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+gss_bi_udfs

gss_bi_udfs-0.1.0.dist-info/RECORD

@@ -1,4 +0,0 @@
-gss_bi_udfs-0.1.0.dist-info/METADATA,sha256=ChQSSxNCSDO4zK3mupeVxs9X0rXov2NWzib4n0HAoaM,339
-gss_bi_udfs-0.1.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
-gss_bi_udfs-0.1.0.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-gss_bi_udfs-0.1.0.dist-info/RECORD,,

gss_bi_udfs-0.1.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-