Escrevendo DataFrames em arquivos

A análise de dados raramente termina dentro do Python. Você precisa compartilhar conjuntos de dados limpos com as partes interessadas, enviar resultados para outras ferramentas ou arquivar dados processados para garantir a reprodutibilidade. O pandas fornece to_csv(), to_excel(), to_json() e to_parquet() — correspondentes às funções de leitura e aceitando a maioria dos mesmos parâmetros de configuração.

Por padrão, to_csv() grava o índice das linhas como a primeira coluna, criando uma coluna unnamed: 0 quando o arquivo é lido novamente. Passe index=False para omitir o índice — quase sempre a escolha correta, a menos que o próprio índice contenha dados significativos, como datas. Sempre especifique index=False, a menos que tenha um motivo deliberado para incluir o índice.

Passe sep= para gravar um arquivo separado por tabulações ou por ponto e vírgula. Use encoding= para especificar UTF-8 ou outro conjunto de caracteres — algo essencial quando os valores das colunas contêm caracteres que não são ASCII, como acentos ou caracteres chineses. encoding='utf-8-sig' adiciona um BOM (marca de ordem dos bytes) para garantir compatibilidade com o Excel no Windows.

Por padrão, o pandas grava números de ponto flutuante com precisão total. Use float_format='%.2f' para limitar a 2 casas decimais — algo importante para dados financeiros, nos quais casas decimais extras parecem incorretas para os leitores. Passe na_rep='NULL' ou na_rep='' para controlar como os valores NaN são gravados no arquivo de saída.

df.to_excel('file.xlsx', sheet_name='Data', index=False) grava o DataFrame em uma pasta de trabalho do Excel. Assim como em to_csv(), defina index=False, a menos que o índice seja significativo. Os parâmetros startrow= e startcol= permitem posicionar a tabela na planilha — útil para adicionar uma linha de título acima dos dados.

Para gravar vários DataFrames em planilhas diferentes da mesma pasta de trabalho, use pd.ExcelWriter como um gerenciador de contexto. Chame df.to_excel(writer, sheet_name='Name') para cada DataFrame dentro do bloco with. A pasta de trabalho é finalizada e salva quando o contexto é encerrado. Isso evita criar vários arquivos separados para tabelas relacionadas.

df.to_json() serializa um DataFrame em JSON. O parâmetro orient= corresponde ao de read_json: use 'records' para uma lista de dicionários de linhas (maior interoperabilidade), 'columns' para um dicionário de vetores de colunas ou 'index' para um dicionário indexado pelo rótulo da linha. Passe indent=2 para obter uma formatação legível por humanos.

Para adicionar linhas a um CSV existente sem sobrescrevê-lo, abra o arquivo no modo de adição usando mode='a' e defina header=False para evitar duplicar a linha de cabeçalho. Para o Excel, use ExcelWriter com mode='a'. Em fluxos de processamento de transmissão grandes, adicione os dados em partes e grave o cabeçalho apenas na primeira parte.

Uma boa prática antes de exportar é selecionar apenas as colunas de que o destinatário precisa e ordenar as linhas de forma lógica. Isso torna o arquivo de saída mais limpo e evita o vazamento acidental de colunas internas, como IDs internos, características codificadas ou sinalizadores de depuração. Use a seleção por colchetes e sort_values() na mesma expressão de fluxo de processamento antes de gravar.

Depois de gravar, sempre leia o arquivo novamente e verifique-o: confira shape, os nomes das colunas e alguns valores escolhidos aleatoriamente. Em fluxos de integração contínua, compare as somas de verificação. Para exportações financeiras críticas, confirme que os totais agregados correspondem. Isso identifica problemas de codificação, perda de precisão de números de ponto flutuante e problemas de índice antes que o arquivo chegue ao consumidor seguinte.

Para grandes conjuntos de dados analíticos, considere o formato Parquet em vez de CSV. O Parquet armazena os dados em formato colunar, oferece suporte à compactação, preserva os tipos de dados exatamente e faz a leitura de 10 a 100 vezes mais rápido em consultas analíticas. Grave com df.to_parquet('data.parquet') e leia com pd.read_parquet('data.parquet'). É necessário ter pyarrow ou fastparquet instalado.

Teste sua compreensão sobre como gravar DataFrames em arquivos com base nesta lição.

Nesta lição, você aprendeu que: to_csv() e to_excel() exportam DataFrames e ambos incluem o índice por padrão — sempre defina index=False para obter uma saída limpa, ExcelWriter permite gravar vários DataFrames em planilhas separadas de uma única pasta de trabalho e Parquet é uma alternativa mais rápida e eficiente em espaço do que CSV para grandes conjuntos de dados analíticos. Em seguida, carregaremos arquivos CSV remotos a partir de URLs e analisaremos strings CSV na memória com io.StringIO.