Saltar a contenido

Formatos y parámetros

Formato Extensiones Lo lee
CSV .csv, .txt, .tsv el módulo csv de Python, línea a línea, para dar el número de línea de cada error
Excel .xlsx, .xlsm / .xls openpyxl / xlrd
JSON .json, .jsonl, .ndjson json
Parquet .parquet pyarrow

El formato sale de la extensión, o de format="csv" si el nombre no la tiene.

Para todos

Parámetro Por defecto Qué hace
infer_types True Inferir los tipos (ver tipos). Con False, todo lo de un CSV llega como texto
columns — Tipos declarados: {"cp": "string", "importe": Column("float", number_format="en")}
with_fields — Solo esas columnas, en ese orden. Una que no existe es MissingColumnsError
column_names — Renombrar: una lista con un nombre por columna (si no coincide el número, es un error)
normalize_columns False Nombres en minúsculas, sin tildes ni espacios (Código Postal → codigo_postal)
number_format "es" "es" (1.234,56) o "en" (1,234.56)
date_format "es" "es" (día primero), "en" (mes primero) o un formato strftime
errors "raise" "null": lo que no encaja con su tipo declarado se vacía y se cuenta
na_values — Textos que también son vacío, además de los de siempre
strip True Quitar los espacios de los extremos de los textos

Un parámetro que no existe, o que no aplica al formato, es un error que dice cuáles valen:

reader.to_dataframe(sheet_name="Pedidos", sep=";")
# InvalidRequestError: sep no aplica a un fichero xlsx. Solución: Para xlsx valen: column_names, columns, date_format, entrypoint, errors, height, …

Vacíos: las celdas vacías o con solo espacios, los errores de Excel (#N/A, #N/D, #¡VALOR!, #DIV/0!…) y lo que se pase en na_values. NA no es un vacío: puede ser el código de Namibia.

CSV

Parámetro Por defecto Qué hace
sep se detecta Se elige el que más campos da en la cabecera de entre ;, ,, tabulador y \| (en .tsv, el tabulador)
encoding UTF-8, con o sin BOM "latin-1", "cp1252"… para ficheros de Excel en Windows
quotechar " Las comillas que protegen un separador dentro de un campo
df = file.get_data().to_dataframe_from_csv(encoding="cp1252", with_fields=["codigo", "importe"])

Una línea con más o menos campos que la cabecera es un DataFormatError con su número de línea: casi siempre es un separador dentro de un campo sin comillas. El BOM de UTF-8 se quita del nombre de la primera columna. En la 0.1 se quedaba pegado (codigo) y with_fields=["codigo"] no la encontraba.

Excel

Parámetro Por defecto Qué hace
sheet_name la primera hoja El nombre de la hoja
entrypoint la primera celda con datos Dónde empieza la tabla: una celda ("A5") o el texto de la cabecera de su primera columna ("Código")
regex False entrypoint es una expresión regular
width, height hasta la última columna y fila con datos Columnas y filas, cabecera incluida
stop_at_blank_row False Cortar en la primera fila en blanco (para hojas con varias tablas)
reader = file.get_data()
df = reader.to_dataframe(sheet_name="Pedidos", entrypoint="Código")
print(reader.report)
pedidos.xlsx · xlsx · hoja 'Pedidos' · A3:C4
1 fila
columna  en el fichero  tipo    vacíos  notas
Código   A              string  0       texto: tiene ceros a la izquierda, como '0012' (A4): es un código
Cliente  B              string  0
col_C    C              float   0
aviso: la columna C no tiene nombre en la cabecera: se llama 'col_C'
  • Un informe con un título encima de la tabla se lee con entrypoint: la tabla empieza en la celda que lo contiene.
  • La tabla llega hasta la última fila y la última columna con datos, aunque haya filas en blanco o huecos en la cabecera por medio. En la 0.1 se cortaba en la primera fila en blanco y se perdía la columna de después de un hueco.
  • Lo que Excel ya tiene tipado se respeta: números, fechas, horas y booleanos.
  • Leer varias hojas con el mismo reader descarga el fichero una vez.

JSON

Parámetro Por defecto Qué hace
orient "records" "records" ([{…}, {…}]), "columns" ({"col": [...]}) o "index" ({"id": {…}})
lines True en .jsonl y .ndjson JSON Lines: un objeto por línea
flatten False Aplanar objetos anidados: {"cliente": {"id": 1}} da la columna cliente.id

Un registro con una clave que no tienen los demás añade la columna; a los demás les queda vacía.

Parquet

Los tipos de Parquet son los que son: no se infiere nada, tampoco en las columnas de texto. Valen los parámetros comunes: columns para convertir, with_fields, column_names, normalize_columns…

df = file.get_data().to_dataframe_from_parquet(with_fields=["id", "importe"])

Los métodos de la 0.1

FileDataReader mantiene los nombres que usan los ETL:

Método Igual que
to_dataframe(**params) el formato por la extensión
to_dataframe_from_csv(**params), alias to_csv format="csv"
to_dataframe_from_excel(**params), alias to_excel format="xlsx"
to_dataframe_from_json(**params), alias to_json format="json"
to_dataframe_from_parquet(**params), alias to_parquet format="parquet"

infer_dimensions, infer_height e infer_width se aceptan con un DeprecationWarning: lo que hacían es ahora el comportamiento normal.