Python Peewee – ORM Minimalista e Fácil

O Python Peewee é uma biblioteca ORM (Object-Relational Object) cujo objetivo é trabalhar com bancos de dados relacionais sem ter que se preocupar com instruções SQL. Em suma, você apenas se preocupa em criar uma representação de seus dados orientada a objetos e o Peewee se encarrega da comunicação com o banco de dados escolhido

Projetado para simplicidade e produtividade, é uma biblioteca fácil de aprender e configurar. Além disso, oferece maior flexibilidade e desempenho em operações mais simples. Desse modo, é excelente para projetos pequenos e médios, possui suporte aos bancos de dados SQLite, Postgress e Maria DB/MySQL.

O conteúdo a seguir traz uma breve introdução ao Peewee, fornecendo o básico para a criação de um CRUD. Contudo, a biblioteca tem muito mais a oferecer como recursos mais refinados de busca, filtros, ordenação, agregação, relacionamentos e assim por diante. O material completo de referência pode ser acessado diretamente no site do projeto.

Instalação do Python Peewee e Criação do Modelo

O pacote do Peewee pode ser instalado da maneira tradicional via pip:

pip install peewee

A definição do modelo é bastante simples e intuitiva. Vamos criar o modelo Pessoa:

from peewee import *

db = SqliteDatabase('pessoas.db')

class Pessoa(Model):
    nome = CharField()
    nascimento = DateField()

    class Meta:
        database = db # Utiliza o banco de dados SQLite chamado pessoa.db

Neste exemplo, a classe Pessoa indica ao Peewee para criar/usar a tabela Pessoa com os campos nome e nascimento, do tipo Char e Date, respectivamente. Contudo, apenas com esse código, nenhum resultado será produzido. Assim sendo, é necessário pedir ao Peewee que crie o banco e a tabela em questão:

db.connect()
db.create_tables([Pessoa])
db.close() # Importante sempre fechar as conexões criadas

Vale ressaltar que o método create_tables apenas cria o banco bem como suas tabelas se não existirem. Portanto, a execução repetida deste método não sobrescreve os dados já existentes.

Armazenando Dados

Primeiramente vamos incluir uma pessoa no banco dados através do código abaixo:

mochileiro = Pessoa(nome="Mochileiro T.I", nascimento=date(2025, 2, 17))
mochileiro.save()
# Retorna o valor 1, corresponde ao número de linhas afetadas

Do mesmo modo, podemos fazer isso através do método create() que pertence classe pessoa:

mochileiro = Pessoa.create(nome="Outro Mochileiro T.I", nascimento=date(2025, 2, 17))
# Também retorna 1, referente ao número de linhas afetadas

Agora vamos supor que cometemos um erro ao digitar a data de nascimento e queremos alterá-la. Nesse sentido, se ainda tivermos a nossa instância da classe pessoa referenciada, podemos alterar diretamente o atributo nascimento e salvar novamente o objeto:

mochileiro.nascimento = date(1900,1,1)
mochileiro.save()

Por outro lado, se não tivermos mais nosso objeto, devemos recuperá-lo através de uma consulta. Veremos como fazer isso na próxima seção!

Recuperando Dados

Consultar dados torna-se uma tarefa muito simples no Peewee, conforme é demonstrado no trecho de código abaixo:

mochileiro = Pessoa.get(nome='Mochileiro T.I')
print(f'Nome: {mochileiro.nome} Nascimento: {mochileiro.nascimento}')

De maneira idêntica, se você tiver familiaridade com SQL, podemos fazer a mesma consulta deste jeito:

mochileiro = Pessoa.select().where(Pessoa.nome == 'Mochileiro T.I').get()
print(f'Nome: {mochileiro.nome} Nascimento: {mochileiro.nascimento}')

Agora vamos imaginar que temos a necessidade listar todo o conteúdo da tabela Pessoa, de modo que consigamos listar todas as pessoas e seus nascimentos:

for pessoa in Pessoas.select():
  print(f'Nome: {pessoa.nome} Nascimento: {pessoa.nascimento}')

Por fim, vamos imaginar que por qualquer motivo precisamos de todas as pessoas nascidas antes de 1970. Para isso, podemos fazer a consulta da seguinte maneira:

data1970 = date(1970, 1, 1)
consulta = Pessoa.select().where(Pessoa.nascimento < data1970)
for pessoa in consulta:
    print(f'Nome: {pessoa.nome} Nascimento: {pessoa.nascimento}')

Apagando Dados

Por último, vamos apagar o registro de uma pessoa no nosso banco dados. Assim como em todos os outros trechos de código, este não poderia ser mais simples:

# Primeiramente vamos recuperar a instância
mochileiro = Pessoa.get(nome='Mochileiro T.I')
# Agora apagamos
mochileiro.delete_instance()

Conclusão

Conforme demonstrado ao longo deste artigo, o Peewee é uma ferramente muito acessível devido sua facilidade e simplicidade. Ideal para projetos pequenos e médios, onde não existe a necessidade consultas performáticas.

Em contrapartida, para projetos médios e grande, onde existe a necessidade de escalonabilidade, grande flexibilidade, total controle e maior performance em consultas complexas, o SQLAlchemy torna-se uma solução mais viável.

Espero ter ajudado!

Até a próxima!