Saltar a contenido

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.

pip install "tai-storage[data]"        # pandas, numpy, openpyxl, xlrd, pyarrow
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

  1. 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 y col_<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.
  2. 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.
  3. Lo declarado manda. Un valor que no encaja con el tipo de columns= es un ColumnTypeError que 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

ventas.csv
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.
  • 001 y 08001 siguen siendo códigos.
  • Las dos fechas, cada una en un formato, son fechas.
  • importe se queda como texto por pendiente, 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