Como acrescentar dados a um ficheiro CSV com Pandas

Use Pandas to_csv() com mode="a" para acrescentar linhas de um DataFrame às linhas já existentes num ficheiro CSV. O modo de anexação preserva o conteúdo do ficheiro. Defina header=False quando o ficheiro já tiver um cabeçalho e index=False quando não quiser que o índice do DataFrame se torne uma coluna CSV adicional.

Acrescentar um DataFrame a um ficheiro CSV existente

Este exemplo cria um ficheiro CSV inicial e acrescenta-lhe um segundo DataFrame. No seu próprio código, use o caminho do seu ficheiro CSV. Mantenha as colunas acrescentadas pela mesma ordem das colunas do CSV existente: os ficheiros CSV não armazenam um esquema que reorganize automaticamente os valores pelo nome das colunas.

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

from pathlib import Path
from tempfile import TemporaryDirectory

import pandas as pd

with TemporaryDirectory() as directory:
    path = Path(directory) / "records.csv"
    original = pd.DataFrame({"name": ["Ava"], "score": [8]})
    added = pd.DataFrame({"name": ["Noah"], "score": [9]})

    original.to_csv(path, index=False)
    added.to_csv(path, mode="a", header=False, index=False)
    print(path.read_text(), end="")

A primeira escrita cria o ficheiro e o respetivo cabeçalho. A segunda usa mode="a" para acrescentar uma linha no fim, com header=False para não repetir os nomes das colunas e index=False para impedir que o Pandas adicione o índice da linha. O ficheiro final contém a linha original seguida da linha acrescentada. Se quiser incluir o índice do DataFrame como coluna, omita index=False e tenha essa coluna adicional em conta ao ler o CSV.

Escrever o cabeçalho apenas quando o ficheiro CSV está vazio

Quando o destino pode estar vazio ou ainda não existir, abra-o em modo de anexação e verifique a posição atual no ficheiro. Abrir um caminho inexistente com mode="a" cria o ficheiro. A chamada tell() indica a posição atual; imediatamente após abrir em modo de anexação, uma posição de 0 significa que o ficheiro está vazio. Escreva o cabeçalho apenas nesse caso.

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

from pathlib import Path
from tempfile import TemporaryDirectory

import pandas as pd

with TemporaryDirectory() as directory:
    path = Path(directory) / "records.csv"
    rows = pd.DataFrame({"name": ["Mia"], "score": [7]})

    with path.open("a", encoding="utf-8", newline="") as csv_file:
        write_header = csv_file.tell() == 0
        rows.to_csv(csv_file, header=write_header, index=False)

Isto funciona tanto com um ficheiro novo como com um CSV existente: um ficheiro recém-criado ou vazio recebe os nomes das colunas, enquanto um ficheiro com conteúdo recebe apenas a nova linha. Use a mesma ordem de colunas e campos compatíveis sempre que acrescentar dados. Os nomes das colunas usados no exemplo permanecem em inglês no código. Se o seu programa tiver vários processos que possam atualizar o mesmo ficheiro em simultâneo, coordene as escritas para impedir que a verificação do cabeçalho e a escrita da linha se intercalem com as operações de outro processo.

Verificar as linhas acrescentadas e evitar erros comuns

Leia o CSV depois de escrever quando precisar de confirmar o conteúdo. No primeiro exemplo, o ficheiro tem um cabeçalho seguido dos registos original e acrescentado. A instrução print(path.read_text(), end="") apresenta o conteúdo exato do ficheiro como texto selecionável quando executar o exemplo. Os valores e nomes de colunas apresentados pelo código permanecem em inglês.

Ao adaptar os exemplos, verifique estes detalhes:

• As colunas do DataFrame acrescentado têm de corresponder às colunas do CSV e estar pela mesma ordem. O Pandas escreve os valores pela posição; durante a anexação, não associa as colunas do CSV pelos respetivos nomes.
• Use header=False num ficheiro não vazio que já tenha cabeçalho. Um cabeçalho repetido seria lido como uma linha de dados normal.
• Escolha index=False se o índice das linhas não fizer parte dos seus dados. Caso contrário, inclua a coluna do índice na estrutura do ficheiro e tenha-a em conta.
• O modo de anexação acrescenta texto ao fim do ficheiro; não valida nem corrige colunas, delimitadores ou codificações incompatíveis. Mantenha essas definições consistentes com o CSV existente.
• Se o ficheiro estiver vazio, escreva o cabeçalho uma vez antes da primeira linha de dados. A verificação com tell() acima usa a posição do ficheiro aberto em modo de anexação para decidir se deve escrever o cabeçalho.

Para uma verificação rápida em Python, carregue o ficheiro resultante com pd.read_csv(path) e inspecione as linhas e os nomes das colunas. Assim, verifica a tabela analisada e também o texto escrito no disco.