O exemplo do descritor Quantity, na LineItem versão #4: Nomeando atributos de armazenamento automaticamente, ficou muito mais simples graças ao método especial __set_name__, adicionado ao protocolo de descritor no Python 3.6. Naquela mesma seção, removi o exemplo da fábrica de propriedades, pois ele se tornou irrelevante: o ponto ali era mostrar uma solução alternativa para o problema de Quantity, mas com __set_name__ o exemplo ficou redundante. Removi a classe AutoStorage, que aparecia na LineItem versão #5: um novo tipo descritor pelo mesmo motivo.

Como vimos na [coding_prop_factory_sec], uma fábrica de propriedades é uma forma de evitar código repetitivo de getters e setters, aplicando padrões de programação funcional. Uma fábrica de propriedades é uma função de ordem superior que cria um conjunto de funções de acesso parametrizadas e constrói uma instância de propriedade customizada, com clausuras para preservar configurações como storage_name. A forma orientada a objetos de resolver o mesmo problema é uma classe descritora.

Vamos seguir com a série de exemplos LineItem de onde paramos, na [coding_prop_factory_sec], refatorando a fábrica de propriedades quantity em uma classe descritora Quantity. Isso vai torná-la mais fácil de usar.

Recordando, há uma importante assimetria na forma como Python lida com atributos. Em uma classe sem descritores, ler um atributo através de uma instância devolve o atributo definido na instância. Mas se tal atributo não existir na instância, um atributo de classe será obtido. Por outro lado, uma atribuição a um atributo em uma instância cria o atributo na instância, sem afetar a classe de forma alguma.

Esta assimetria também afeta descritores, criando duas grandes categorias de descritores, dependendo do método __set__ estar ou não implementado. Se __set__ estiver presente, a classe é um descritor dominante (overriding descriptor); caso contrário, ela é um descritor não dominante (non-overriding descriptor). Esses termos farão sentido quando examinarmos os comportamentos de descritores nos próximos exemplos.

Usei algumas funções auxiliares definidas no descriptorkinds.py: funções auxiliares para formatar e exibir objetos para observar as diferentes categorias de descritores, Sua lógica não é importante, mas elas são usadas nas invocações a print_args no descriptorkinds.py: classes simples para estudar os comportamentos dominantes de descritores.

Agora vamos criar três classes de descritores, e uma classe Managed onde os descritores são instalados.

1. Uma classe descritora dominante com __get__ e __set__.

2. A função print_args é chamada por todos os métodos do descritor neste exemplo.

3. Um descritor dominante sem um método __get__.

4. Nenhum método __set__ aqui, então este é um descritor não dominante.

5. A classe gerenciada, usando uma instância de cada uma das classes descritoras.

6. O método spam está aqui para efeito de comparação, pois métodos também são descritores.

Nas próximas seções, examinaremos o comportamento de leitura e escrita de atributos na classe Managed e em uma de suas instâncias, passando por cada um dos diferentes descritores definidos.

Uma função dentro de uma classe se torna um método vinculado (bound method) quando invocada em uma instância, porque todas as funções definidas pelo usuário têm um método __get__, e portanto operam como descritores quando associados a uma classe. O Um método é um descritor não dominante demonstra a leitura do método spam, da classe Managed, apresentada no descriptorkinds.py: classes simples para estudar os comportamentos dominantes de descritores.

1. Ler de obj.spam obtém um objeto método vinculado.

2. Mas ler de Managed.spam obtém uma função.

3. Atribuir um valor a obj.spam oculta o atributo de classe, tornando o método spam inacessível a partir da instância obj.

Funções não implementam __set__, portanto não são descritores dominantes, como mostra a última linha do Um método é um descritor não dominante.

A outra lição fundamental do Um método é um descritor não dominante é que obj.spam e Managed.spam devolvem objetos diferentes. Como de hábito com descritores, o __get__ de uma função devolve uma referência para a própria função quando o acesso ocorre através da classe gerenciada. Mas quando o acesso vem através da instância, o __get__ da função devolve um método vinculado: um invocável que embrulha a função e vincula a instância gerenciada (no exemplo, obj) ao primeiro argumento da função (isto é, self), como faz a função functools.partial (que vimos na [functools_partial_sec]). Para um entendimento mais profundo deste mecanismo, dê uma olhada no method_is_descriptor.py: uma classe Text, derivada de UserString.

Vamos então investigar o método Text.reverse. Veja o Experimentos com um método.

1. Seguindo a convenção, o repr de uma instância de Text parece uma chamada ao construtor de Text que criaria uma instância igual.

2. O método reverse devolve o texto escrito de trás para frente.

3. Um método invocado na classe funciona como uma função.

4. Observe os tipos diferentes: function e method.

5. Text.reverse opera como uma função, mesmo ao trabalhar com objetos que não são instâncias de Text.

6. Toda função é um descritor não dominante. Invocar seu __get__ com uma instância obtém um método vinculado àquela instância.

7. Invocar o __get__ da função com None como argumento instance obtém a própria função.

8. A expressão word.reverse invoca Text.reverse.__get__(word), devolvendo o método vinculado, mas sem invocá-lo.

9. O objeto método vinculado tem um atributo __self__, contendo uma referência à instância na qual o método foi invocado.

10. O atributo __func__ do método vinculado é uma referência à função original, implementada na classe gerenciada.

O método vinculado contém um método __call__, que trata a invocação em si. Este método chama a função original, referenciada em __func__, passando o atributo __self__ do método como primeiro argumento. É assim que funciona a vinculação implícita do argumento self convencional.

A conversão de funções em métodos vinculados é um exemplo perfeito de como descritores são usados na infraestrutura da linguagem.

Após este mergulho profundo no funcionamento de descritores e métodos, vamos repassar alguns conselhos práticos sobre seu uso.

A lista a seguir trata de algumas consequências práticas das características dos descritores descritas acima:

Use property para não complicar demais

A classe embutida property cria descritores dominantes, implementando __set__ e __get__, mesmo se um método setter não for definido.^[7] O __set__ default de uma propriedade gera um AttributeError: can’t set attribute (não é permitido setar o atributo), então uma propriedade é a forma mais fácil de criar um atributo somente para leitura, evitando o problema descrito a seguir.

Descritores somente para leitura exigem um __set__

Se você usar uma classe descritora para implementar um atributo somente para leitura, precisa lembrar de programar tanto __get__ quanto __set__. Caso contrário, você terá um descritor não-dominante, e setar um atributo com o mesmo nome em uma instância vai ocultar o descritor. O método __set__ de um atributo somente para leitura deve apenas levantar AttributeError com uma mensagem adequada.^[8]

Descritores de validação podem funcionar apenas com __set__

Em um descritor projetado apenas para validação, o método __set__ deve verificar o argumento value recebido e, se ele for válido, atualizar o __dict__ da instância diretamente, usando o nome da instância do descritor como chave. Dessa forma, ler o atributo de mesmo nome a partir da instância será tão rápido quanto possível, pois não vai precisar de um __get__. Veja o código no bulkfood_v4.py: __set_name__ define o nome para cada instância do descritor Quantity.

Caching pode ser feito eficientemente apenas com __get__

Se você escrever apenas o método __get__, cria um descritor não dominante. Eles são úteis para executar alguma computação custosa e então armazenar o resultado, definindo um atributo com o mesmo nome na instância^[9]. O atributo de mesmo nome na instância vai ocultar o descritor, daí acessos subsequentes àquele atributo vão buscá-lo diretamente no __dict__ da instância, sem acionar mais o __get__ do descritor. O decorador @functools.cached_property constrói um descritor não dominante.

Métodos não especiais podem ser ocultados por atributos de instância

Como funções e métodos implementam apenas __get__, eles são descritores não dominantes. Uma atribuição simples, como meu_obj.o_método = 7, significa que acessos posteriores a o_método através daquela instância irão obter o número 7—sem afetar a classe ou outras instâncias. Isto se aplica aos métodos especiais. O interpretador só acessa métodos especiais na própria classe. Em outras palavras, repr(x) é executado como x.__class__.__repr__(x), então um atributo __repr__, definido em x, não tem efeito em repr(x). Pela mesma razão, a existência de um atributo chamado __getattr__ em uma instância não vai subverter o algoritmo normal de acesso a atributos.

O fato de métodos poderem ser sobrescritos tão facilmente pode soar frágil e propenso a erros. Mas eu, pessoalmente, em mais de 20 anos programando em Python, nunca tive problemas com isso. Por outro lado, se você estiver criando muitos atributos dinâmicos, onde os nomes dos atributos vêm de dados que você não controla (como fizemos na parte inicial desse capítulo), então você precisa estar atenta para isso, e talvez implementar alguma filtragem ou reescrita (escaping) dos nomes dos atributos dinâmicos, para preservar sua sanidade.

Para encerrar esse capítulo, vamos falar de dois recursos que vimos com as propriedades, mas não no contexto dos descritores: documentação e o tratamento de tentativas de excluir um atributo gerenciado.

A docstring de uma classe descritora é usada para documentar todas as instâncias do descritor na classe gerenciada. A Capturas de tela do console de Python após os comandos help(LineItem.weight) e help(LineItem). mostra as telas de ajuda para a classe LineItem com os descritores Quantity e NonBlank, do model_v5.py: Quantity e NonBlank, subclasses concretas de Validated e do bulkfood_v5.py: LineItem usando os descritores Quantity e NonBlank.

Isso é um tanto insatisfatório. No caso de LineItem, seria bom acrescentar, por exemplo, a informação de que weight deve ser expresso em quilogramas. Isso seria trivial com propriedades, pois cada propriedade controla um atributo gerenciado específico. Mas com descritores, a mesma classe descritora Quantity é usada para weight e price.^[10]

O segundo detalhe que discutimos com propriedades, mas não com descritores, é o tratamento de tentativas de apagar um atributo gerenciado. Isso pode ser feito implementando um método __delete__ na classe descritora. Omiti deliberadamente falar de __delete__, porque seu uso no mundo real é raro. Se você precisar disso, por favor consulte a seção «Implementando descritores» na documentação do Modelo de dados de Python. Escrever um exemplo com uma classe descritora boba com __delete__ fica como exercício para o leitor com excesso de tempo livre.

O primeiro exemplo deste capítulo foi uma continuação dos exemplos LineItem do [ch_dynamic_attrs]. No bulkfood_v3.py: descritores Quantity gerenciam atributos em LineItem, substituímos propriedades por descritores. Vimos que um descritor é uma classe que fornece instâncias instaladas como atributos na classe gerenciada. Discutir esse mecanismo exigiu uma terminologia especial, apresentando termos como instância gerenciada e atributo de armazenamento.

Na LineItem versão #4: Nomeando atributos de armazenamento automaticamente, removemos a exigência de descritores Quantity serem instanciados com um storage_name explícito. A solução foi implementar o método especial __set_name__ em Quantity, para preservar o nome da propriedade gerenciada como self.storage_name.

A LineItem versão #5: um novo tipo descritor mostrou como criar uma subclasse de uma classe descritora abstrata, para compartilhar código ao programar descritores especializados com alguma funcionalidade em comum.

Examinamos então os comportamentos diferentes de descritores, fornecendo ou omitindo o método __set__, criando uma distinção fundamental entre descritores dominantes e não dominantes. Por meio de testes detalhados, revelamos quando os descritores estão no controle, e quando são ocultados, contornados ou sobrescritos.

Em seguida, estudamos uma categoria específica de descritores não dominantes: métodos. Experimentos no console revelaram como uma função associada a uma classe se torna um método ao ser acessada através de uma instância, graças ao protocolo de descritores.

Para concluir o capítulo, a Dicas para usar descritores trouxe dicas práticas, e a Docstrings e exclusão de descritores forneceu um rápido olhar sobre como documentar descritores.

Além da referência obrigatória ao capítulo «Modelo de dados», o «Guia de descritores», de Raymond Hettinger, é um recurso valioso-e parte da excelente «coleção de HOWTOS» na documentação oficial de Python.

Como sempre, em se tratando de assuntos relativos ao modelo de objetos de Python, o Python in a Nutshell, 3ª ed. (O’Reilly), de Martelli, Ravenscroft, e Holden é competente e objetivo. Martelli também tem uma apresentação chamada Python’s Object Model (O Modelo de Objetos do Python), tratando com profundidade de propriedades e descritores: «slides» e «video».

Para mais exemplos práticos, o Python Cookbook, 3ª ed., de David Beazley e Brian K. Jones (O’Reilly), traz muitas receitas ilustrando descritores, entre as quais destaco 6.12. Reading Nested and Variable-Sized Binary Structures (Lendo Estruturas Binárias Aninhadas e de Tamanho Variável), 8.10. Using Lazily Computed Properties (Usando Propriedades Computadas de Forma Preguiçosa), 8.13. Implementing a Data Model or Type System (Implementando um Modelo de Dados ou um Sistema de Tipos) e 9.9. Defining Decorators As Classes (Definindo Decoradores como Classes). Essa última receita trata das questões profundas envolvidas na interação entre decoradores de função, descritores e métodos, e de como um decorador de função implementado como uma classe, com __call__, também precisa implementar __get__ se quiser funcionar com métodos.

A PEP 487—Simpler customization of class creation (Customização simplificada da criação de classes) introduziu o método especial __set_name__ e inclui um exemplo de um «descritor de validação».