Descriptors são um protocolo poderoso da linguagem Python.
Eles permitem personalizar o acesso a atributos de classes.
Basicamente, um descriptor implementa métodos como __get__ e __set__.
Quando você acessa um atributo, o Python chama esses métodos automaticamente.
Isso foi projetado para reutilizar lógica de validação ou conversão.
Por exemplo, você pode criar um descriptor que valida idades.
Assim, evita repetir o mesmo código em vários lugares.
Além disso, descriptors são a base de properties e @property.
Portanto, entender eles eleva seu domínio sobre Python.
O protocolo descriptor: métodos especiais
Três métodos principais compõem o protocolo descriptor.
__get__(self, instance, owner) recupera o valor do atributo.
__set__(self, instance, value) define ou altera o valor.
__delete__(self, instance) remove o atributo quando necessário.
Cada método recebe a instância da classe dona.
Assim, o descriptor sabe qual objeto está sendo manipulado.
Somente a implementação de __get__ já qualifica um descriptor como não-dados.
Adicione __set__ ou __delete__ e ele se torna um descriptor de dados.
Essa distinção influencia a precedência na busca de atributos.
Por essa razão, descriptors de dados são mais prioritários.
Uma representação simples do fluxo é:
Quando utilizar descriptors no seu código
Use descriptors para validar dados repetidamente em várias classes. Por exemplo, campos de formulários ou modelos de banco de dados. Eles também resolvem problemas de conversão de tipos. Um caso clássico é garantir que uma temperatura esteja em Celsius. Outro exemplo é converter automaticamente moedas em valores numéricos. Além disso, descriptors servem para implementar lazy loading. Isso significa carregar um recurso pesado apenas quando acessado. Frameworks ORM como SQLAlchemy usam descriptors intensamente. Então, você encontra esse padrão em código profissional. Evite descriptors para lógica muito simples ou pontual. Nesses casos, um property comum já resolve bem.
Primeiro, identifique atributos que compartilham a mesma regra. Depois, crie um descriptor único que encapsule essa regra. Assim, você aplica a mesma validação em várias classes. Por exemplo, campos de email com formato específico. Ou campos de CPF que precisam de dígitos verificadores. O descriptor centraliza a lógica e facilita futuras mudanças. Consequentemente, o código fica mais seco e testável. Portanto, descriptors são ferramentas para abstração reutilizável.
Exemplo prático: validação de idade com descriptor
O código abaixo mostra um descriptor completo com __get__ e __set__.
Ele valida que a idade seja um número entre 0 e 150.
Além disso, armazena o valor em um dicionário interno.
Isso evita conflitos com o dicionário __dict__ da instância.
Duas classes diferentes usam o mesmo descriptor.
Perceba como a lógica de validação não se repete.
Esse padrão é útil em sistemas de cadastro.
Por exemplo, pessoas, funcionários ou usuários.
Teste você mesmo o comportamento no seu ambiente.
Observe que tentar definir idade negativa levanta uma exceção.
Isso protege a integridade dos seus dados.
Assim, você ganha robustez sem esforço repetitivo.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 |
class IdadeDescriptor: """Descriptor que valida idade entre 0 e 150.""" def __init__(self, nome_armazenado="idade"): self.nome_armazenado = nome_armazenado def __get__(self, instance, owner=None): if instance is None: return self # Acesso pela classe # Recupera o valor salvo no dicionário da instância return instance.__dict__.get(self.nome_armazenado, None) def __set__(self, instance, value): if not isinstance(value, int): raise TypeError(f"Idade deve ser inteiro, recebido {type(value).__name__}") if value < 0 or value > 150: raise ValueError(f"Idade inválida: {value}. Deve estar entre 0 e 150.") # Armazena o valor validado instance.__dict__[self.nome_armazenado] = value def __delete__(self, instance): raise AttributeError("Não é permitido deletar a idade") class Pessoa: idade = IdadeDescriptor() # Aplicando o descriptor def __init__(self, nome, idade): self.nome = nome self.idade = idade # Aqui chama __set__ do descriptor def __repr__(self): return f"Pessoa(nome='{self.nome}', idade={self.idade})" class Funcionario: idade = IdadeDescriptor() # Reutilizando o mesmo descriptor def __init__(self, nome, cargo, idade): self.nome = nome self.cargo = cargo self.idade = idade def __repr__(self): return f"Funcionario({self.nome}, {self.cargo}, {self.idade}) anos" # Testando o comportamento print("=== Testando Pessoa ===") p1 = Pessoa("Ana", 30) print(p1) # Pessoa(nome='Ana', idade=30) p1.idade = 35 print(f"Idade atualizada: {p1.idade}") try: p2 = Pessoa("Bob", -5) # Isso levantará exceção except ValueError as e: print(f"Erro capturado: {e}") try: p1.idade = 200 except ValueError as e: print(f"Erro capturado: {e}") print("\n=== Testando Funcionario ===") f1 = Funcionario("Carlos", "Analista", 28) print(f1) f1.idade = 29 print(f"Funcionario com idade {f1.idade} anos") try: f1.idade = "trinta" except TypeError as e: print(f"Erro capturado: {e}") # Acesso pela classe retorna o próprio descriptor print(f"\nDescriptor na classe: {Pessoa.idade}") print(f"Tipo do descriptor: {type(Pessoa.idade).__name__}") |
No exemplo, a classe IdadeDescriptor controla totalmente o atributo.
Cada instância de Pessoa ou Funcionario herda essa validação.
O método __get__ retorna o valor armazenado em instance.__dict__.
O método __set__ valida o tipo e a faixa antes de guardar.
Foi usado um dicionário interno para evitar conflitos de nomes.
Além disso, a implementação respeita o princípio de encapsulamento.
Assim, você não precisa escrever getters e setters manualmente.
Descriptors também funcionam com herança normalmente.
Portanto, eles se integram bem ao modelo de classes Python.
Primeiro, comece com propriedades simples.
Depois, evolua para descriptors quando a repetição aparecer.
Isso torna seu código mais limpo e profissional.
Outro benefício importante é a documentação implícita.
Um descriptor bem nomeado comunica sua intenção claramente.
Por exemplo, IdadeDescriptor já sugere validação.
Assim, outros desenvolvedores entendem o comportamento rapidamente.
Além disso, você pode estender descriptors para logging automático.
Ou para rastrear mudanças de valores (observadores).
A flexibilidade é enorme quando você domina esse padrão.
Finalmente, recomendo estudar a implementação do @property.
Ela é um caso especial de descriptor embutido no Python.
Com esse conhecimento, você escreve APIs mais expressivas.
Portanto, explore descriptors em seus próximos projetos.