DataFrames¶
file.get_data() convierte un CSV, un Excel, un JSON o un Parquet en un DataFrame de pandas,
venga del origen que venga. Está pensado para que lo que sale se pueda cargar en una base de
datos sin revisarlo a mano.
df = folder.get_file("ventas.csv").get_data().to_dataframe() # el formato, por la extensión
reader = folder.get_file("pedidos.xlsx").get_data()
df = reader.to_dataframe(sheet_name="2024", columns={"cp": "string", "importe": "float"})
print(reader.report) # qué se ha leído y por qué
Las tres garantías¶
- Cada fila y cada columna del fichero acaba en el DataFrame, o hay un error con solución.
- Una columna sin nombre en la cabecera se llama
col_<letra>en Excel ycol_<n>en CSV. - Una cabecera repetida pasa a llamarse
nombre_2. - Las filas en blanco se descartan y se cuentan.
- Los datos a la derecha de la cabecera se leen.
- Una línea de CSV con más o menos campos que la cabecera es un error que dice cuál.
- Una columna sin nombre en la cabecera se llama
- La inferencia de tipos nunca introduce un nulo. Una columna cambia de tipo solo si todos sus valores se convierten sin ambigüedad. Si no, se queda como texto, y el informe dice por qué y con qué valor.
- Lo declarado manda. Un valor que no encaja con el tipo de
columns=es unColumnTypeErrorque dice dónde está: la línea del CSV, la celda de Excel o el registro del JSON.
Por eso no hace falta leer con infer_types=False y convertir después a mano con
errors="coerce", que convierte en vacío lo que no entiende sin decir nada. Se declaran los
tipos en columns= y se deja que falle lo que no encaje.
Un ejemplo¶
codigo;cliente;importe;fecha;cp;;activo
001;Ana;1.234,50;31/01/2024;08001;x;sí
002;Luis;12,00;2024-02-01;28001;y;no
003;Eva;pendiente;01/03/2024;41001;z;sí
from tai_storage.data import read_with_report
df, report = read_with_report(origin.get_file("ventas.csv"))
print(df)
print(report)
codigo cliente importe fecha cp col_6 activo
0 001 Ana 1.234,50 2024-01-31 08001 x True
1 002 Luis 12,00 2024-02-01 28001 y False
2 003 Eva pendiente 2024-03-01 41001 z True
ventas.csv · csv · utf-8 · separador ';'
3 filas (1 fila en blanco descartada)
columna en el fichero tipo vacíos notas
codigo 1 string 0 texto: tiene ceros a la izquierda, como '001' (línea 2, columna 1): es un código
cliente 2 string 0
importe 3 string 0 texto: 'pendiente' (línea 4, columna 3) no es un número en formato 'es'
fecha 4 date 0
cp 5 string 0 texto: tiene ceros a la izquierda, como '08001' (línea 2, columna 5): es un código
col_6 6 string 0
activo 7 boolean 0
aviso: la columna 6 no tiene nombre en la cabecera: se llama 'col_6'
- El separador se ha detectado y la columna sin nombre se ha leído como
col_6. 001y08001siguen siendo códigos.- Las dos fechas, cada una en un formato, son fechas.
importese queda como texto porpendiente, y el informe dice en qué línea está.
Para que sea un número, se declara el tipo, y entonces el texto es un error:
read_with_report(origin.get_file("ventas.csv"), columns={"importe": "float"})
# ColumnTypeError: 1 valor de la columna 'importe' no es un número: 'pendiente' (línea 4, columna 3). Solución: Corrige esos valores en el fichero, declara otro tipo o formato para la columna, o pasa errors='null' para dejarlos vacíos
O, si dejarlo vacío es lo correcto, se pide explícitamente, y se cuenta:
df, report = read_with_report(file, columns={"importe": "float"}, errors="null")
report.column("importe").nulled # 1
Tres formas de leer¶
# 1. Desde un File, con el lector de la 0.1 (los ETL lo usan así)
reader = file.get_data()
df = reader.to_dataframe(sep=";")
df = reader.to_dataframe_from_csv(with_fields=["codigo", "importe"])
df = reader.to_dataframe_from_excel(sheet_name="Pedidos", entrypoint="Código")
reader.report # el informe de la última lectura
# 2. Con las funciones del módulo, desde un File, una ruta local, bytes o un stream
from tai_storage.data import read, read_with_report
df = read("local/ventas.xlsx", sheet_name="2024")
df, report = read_with_report(file, columns={"cp": "string"})
# 3. Varias hojas del mismo Excel: el lector lo descarga una sola vez
reader = file.get_data()
hojas = {nombre: reader.to_dataframe(sheet_name=nombre) for nombre in ["Enero", "Febrero", "Marzo"]}
Cuando falla¶
| Error | Cuándo | Ejemplo |
|---|---|---|
DataFormatError |
El fichero no se puede leer como tabla | La línea 3 de roto.csv tiene 3 campos y la cabecera 2. Solución: Revisa esa línea: un separador de más o de menos, o unas comillas sin cerrar… |
MissingColumnsError |
Falta una columna de with_fields o de columns |
El fichero no tiene la columna 'precio' de with_fields. Solución: Las columnas que tiene son: codigo, cliente, importe, … |
ColumnTypeError |
Un valor no encaja con su tipo declarado | 1 valor de la columna 'importe' no es un número: 'pendiente' (línea 4, columna 3)… |
InvalidRequestError |
Un parámetro que no existe o que no aplica (sheet_name en un CSV) |
— |
ColumnTypeError.details["values"] lleva hasta 20 pares (dónde, valor).
En los logs, cada lectura deja una línea en INFO (Leído 'ventas.csv': 3 filas × 7 columnas) y
cada aviso del informe una en WARNING.
Siguiente: Formatos y parámetros · Números, fechas y tipos · El informe de un DataFrame