Como manipular planilhas Excel com Python e openpyxl

Python é uma linguagem de programação de uso geral que dispensa apresentações. Foi originalmente escrito por Guido Van Rossum e teve seu primeiro lançamento no ano de 1991. No momento em que este artigo foi escrito, a versão estável mais recente da linguagem era 3.10. Neste tutorial vemos como utilizá-lo em conjunto com a biblioteca openpyxl para manipular planilhas Excel.

Neste tutorial você aprenderá:

• Como criar uma pasta de trabalho na memória

• Como recuperar, criar, copiar, mover e remover planilhas de uma pasta de trabalho

• Como criar uma pasta de trabalho a partir de um arquivo

• Como acessar um intervalo de células

• Como iterar em linhas e colunas

Requisitos de software e convenções usadas

Instalando a biblioteca openpyxl

Para obter a biblioteca openpyxl em nosso sistema operacional, podemos usar dois métodos: o primeiro consiste em instalar o pacote disponível no repositório de nossa distribuição favorita usando seu gerenciador de pacotes nativo, o segundo método, universal, é fazer uso de pip, o gerenciador de pacotes python. Vamos explorar ambos.

O pacote openpyxl está disponível nos repositórios padrão de algumas das distribuições Linux mais utilizadas, como Debian (e seus derivados), Fedora e Archlinux. Para instalar o pacote nas distribuições mencionadas, podemos executar os seguintes comandos, respectivamente:

# Install openpyxl on Debian and derivatives
$ sudo apt install python3-openpyxl

# Install openpyxl on Fedora
$ sudo dnf install python3-openpyxl

# Install openpyxl on Archlinux
$ sudo pacman -S python-openpyxl

Os comandos acima são específicos da distribuição. Se quisermos usar um método de distribuição cruzada para instalar o openpyxl (ou qualquer outra biblioteca python), podemos usar pip, o gerenciador de pacotes python (o próprio pip deve estar instalado em nosso sistema, é claro) :

$ pip install openpyxl --user

Você pode notar que lançamos o pip sem privilégios administrativos e com a opção --user para instalar o pacote apenas para nosso usuário. Esta é a maneira recomendada de usar o gerenciador de pacotes. Assim que a biblioteca estiver instalada em nosso sistema, podemos começar a trabalhar.

Criando uma planilha simples na memória

Vamos começar com calma. Para criar uma workbook tudo o que precisamos fazer é importar e trabalhar com a classe Workbook, que representa um contêiner para todas as outras partes de um documento. Quando criamos uma instância da classe Workbook, uma nova planilha também é criada por padrão. Podemos acessá-lo através da propriedade active:

from openpyxl import Workbook

workbook = Workbook()
spreadsheet = workbook.active

Quando uma nova planilha é criada, ela não contém células. Eles são criados dinamicamente, por isso é melhor acessá-los diretamente para evitar o desperdício de memória preciosa. Podemos fazer referência a uma célula da planilha como uma chave de dicionário. Por exemplo, para obter o valor da célula ‘A1’, escreveríamos:

a1_value = spreadsheet['A1']

Da mesma forma, para atribuir um valor à mesma célula escreveríamos:

spreadsheet['A1'] = 'Hello World'

Uma maneira alternativa de acessar as células da planilha é usar o método cell() do objeto Worksheet e passar as coordenadas da linha/coluna como argumentos:

# Get the value of the cell
a1_value = spreadsheet.cell(row=1, column=1)

# Populate the cell
spreadsheet.cell(row=1, column=1, value='Hello World')

Para salvar a planilha que criamos e manipulamos, basta utilizar o método save do objeto Workbook, e passar o nome do arquivo de destino como argumento. Por exemplo, para salvar a planilha como worksheet.xlsx, executaríamos:

workbook.save('worksheet.xlsx')

Assim que invocarmos este método, um arquivo com o nome especificado será criado em nosso sistema de arquivos. Aqui está o seu conteúdo (neste caso abri com o Libreoffice calc):

Adicionando uma planilha a uma pasta de trabalho

No exemplo anterior vimos como acessar a planilha ativa de uma pasta de trabalho. Como sabemos, no entanto, uma pasta de trabalho pode conter várias planilhas, e daí se quisermos criar uma nova? Podemos fazer isso através do método create_sheet do objeto Workbook:

new_sheet = workbook.create_sheet('new')

O método create_sheet aceita dois argumentos opcionais: title e index. Podemos usar o primeiro (deve ser uma string) para atribuir um nome à nova planilha, e o último (int) para especificar em que posição a planilha deve ser inserida. O método cria e retorna a nova planilha. No exemplo acima criamos uma nova planilha usando “novo” como título. O título pode ser usado para recuperar posteriormente a planilha:

sheet = workbook['new']

Copiar e mover planilhas

Para copiar uma planilha existente podemos usar o método copy_worksheet e passar como argumento a planilha que deve ser copiada. Para copiar a planilha ativa, por exemplo, escreveríamos:

sheet_copy = workbook.copy_worksheet(workbook.active)

O método retorna a cópia criada da planilha, que neste caso referenciamos através da variável sheet_copy.

Para mover uma planilha existente para uma determinada posição na pasta de trabalho, podemos usar o método move_sheet que aceita dois argumentos. A primeira, planilha, é obrigatória e é a planilha que queremos mover, a segunda é opcional (o padrão é 0) e é o deslocamento para use para especificar a posição da folha. Vejamos um exemplo. Neste caso, a planilha padrão “Planilha” é a primeira da pasta de trabalho. Para movê-lo para a segunda posição, escreveríamos:

workbook.move_sheet(workbook["Sheet"], 1)

Podemos obter uma lista de todas as planilhas pertencentes a uma pasta de trabalho através da propriedade worksheets.

Removendo uma planilha

Para remover uma planilha de uma pasta de trabalho, usamos o método remove da classe Workbook. O método aceita um argumento obrigatório, que é o objeto que representa a planilha que queremos remover. Supondo que desejamos remover a “nova” planilha de nossa pasta de trabalho, escreveríamos:

workbook.remove(workbook['new'])

Criando uma pasta de trabalho a partir de um arquivo

Ler um arquivo de planilha Excel existente é bastante simples com openpyxl. Tudo o que precisamos fazer é carregar a função load_workbook da biblioteca. O único parâmetro obrigatório desta função é filename, que deve ser o caminho do arquivo que queremos abrir. Supondo que este arquivo se chame spreadsheet.xlsx, escreveríamos:

from openpyxl import load_workbook
workbook = load_workbook('spreadsheet.xlsx')

O método aceita também alguns parâmetros opcionais que são úteis para modificar a forma como o arquivo é tratado:

Depois de carregar o arquivo da planilha, podemos acessar a(s) planilha(s) através da instância da classe Workbook retornada por load_workbook.

Acessando várias células

E se quisermos obter o valor de um intervalo de células, em vez do valor de uma única? Tudo o que precisamos fazer é especificar o intervalo com a seguinte sintaxe:

cell_values = spreadsheet['A1':'D1']

O resultado da especificação de um intervalo será uma tupla contendo uma tupla para cada linha especificada. No exemplo acima, há apenas uma linha, já que especificamos células de A1 a D1 (elas estão de fato na mesma linha), então esse seria o resultado:

((<Cell 'Sheet'.A1>, <Cell 'Sheet'.B1>, <Cell 'Sheet'.C1>, <Cell 'Sheet'.D1>),)

Se quiséssemos obter o objeto que representa as células das colunas ‘A’ a ‘D’ das 3 primeiras linhas, escreveríamos:

cell_values = spreadsheet['A1':'D3']

Obteríamos o seguinte resultado:

(
  (<Cell 'Sheet'.A1>, <Cell 'Sheet'.B1>, <Cell 'Sheet'.C1>, <Cell 'Sheet'.D1>),
  (<Cell 'Sheet'.A2>, <Cell 'Sheet'.B2>, <Cell 'Sheet'.C2>, <Cell 'Sheet'.D2>),
  (<Cell 'Sheet'.A3>, <Cell 'Sheet'.B3>, <Cell 'Sheet'.C3>, <Cell 'Sheet'.D3>)
)

A tupla desta vez contém três tuplas, uma para cada linha, como dissemos antes. Para acessar todas as células de uma coluna, especificaríamos apenas o nome da coluna, sem nenhum número de linha. Por exemplo, para obter todas as células da coluna ‘A’ escreveríamos:

cells = spreadsheet['A']

Para obter todas as células das colunas A a D, escreveríamos:

cells = spreadsheet['A':'D']

Da mesma forma, podemos acessar linhas inteiras especificando um intervalo de seus números. Para obter todas as células das duas primeiras linhas, escreveríamos:

cells = spreadsheet[1:3]

Iterar sobre linhas e colunas usando os métodos iter_rows() e iter_cols()

Em vez de especificar um intervalo para acessar o valor de uma série de células, podemos usar os métodos iter_rows() e iter_cols() da planilha. Ambos os métodos aceitam os mesmos argumentos opcionais:

Em ambos os métodos com os parâmetros min_row/max_row e min_col/max_col especificamos o intervalo de linhas e colunas em qual a iteração deve ocorrer. A diferença entre os dois é que iter_rows() retorna as células organizadas por linhas, onde iter_cols(), em vez disso, as retorna organizadas por colunas. Vejamos alguns exemplos práticos. Suponha que queiramos iterar nas três primeiras linhas da primeira à quinta coluna e desejamos obter as células organizadas por linha. Aqui está o que executaríamos:

for i in spreadsheet.iter_rows(min_row=1, max_row=3, min_col=1, max_col=5):
  for cell in i:
    print(cell)

A execução do código acima retorna o seguinte resultado:

<Cell 'Sheet'.A1>
<Cell 'Sheet'.B1>
<Cell 'Sheet'.C1>
<Cell 'Sheet'.D1>
<Cell 'Sheet'.E1>
<Cell 'Sheet'.A2>
<Cell 'Sheet'.B2>
<Cell 'Sheet'.C2>
<Cell 'Sheet'.D2>
<Cell 'Sheet'.E2>
<Cell 'Sheet'.A3>
<Cell 'Sheet'.B3>
<Cell 'Sheet'.C3>
<Cell 'Sheet'.D3>
<Cell 'Sheet'.E3>

Como você pode ver, as células estão organizadas por linha. Para obter as mesmas células, desta vez organizadas por colunas, passaríamos os mesmos argumentos para o método iter_cols():

for i in spreadsheet.iter_rows(min_row=1, max_row=3, min_col=1, max_col=5):
  for cell in i:
    print(i)

As mesmas células são retornadas; desta vez, organizado em colunas:

<Cell 'Sheet'.A1>
<Cell 'Sheet'.A2>
<Cell 'Sheet'.A3>
<Cell 'Sheet'.B1>
<Cell 'Sheet'.B2>
<Cell 'Sheet'.B3>
<Cell 'Sheet'.C1>
<Cell 'Sheet'.C2>
<Cell 'Sheet'.C3>
<Cell 'Sheet'.D1>
<Cell 'Sheet'.D2>
<Cell 'Sheet'.D3>
<Cell 'Sheet'.E1>
<Cell 'Sheet'.E2>
<Cell 'Sheet'.E3>

Conclusões

Neste tutorial aprendemos como trabalhar com arquivos de planilha Excel usando a biblioteca Python openpyxl. Vimos como criar uma pasta de trabalho na memória ou a partir de um arquivo, como recuperar, criar, copiar, mover e remover planilhas, como acessar uma célula e um intervalo de células e, finalmente, como iterar em linhas e colunas. Você está interessado em mais tutoriais como este? Dê uma olhada em nossos artigos sobre Python!