A tipagem ganso é uma parte fundamental de Python, mas as ABCs numbers não são suportadas na tipagem estática. Então, mudei o vector_v7.py: métodos do operador * adicionados para usar tipagem pato, em vez de uma checagem explícita usando isinstance contra numbers.Real.^[2]

Na primeira edição do Python Fluente, tratei do operador de multiplicação de matrizes @ como uma mudança futura, pois o Python 3.5 ainda estava em desenvolvimento. Agora o @ está integrado ao fluxo do capítulo na Usando @ como operador infixo. Aproveitei a tipagem ganso para tornar a implementação de __matmul__ mais segura na primeira edição, sem comprometer sua flexibilidade.

A Para saber mais agora inclui algumas novas referências—incluindo um post do blog de Guido van Rossum. Também inclui menções a duas bibliotecas que demonstram usos interessantes da sobrecarga de operadores em contextos não numéricos: pathlib e Scapy.

A sobrecarga de operadores permite que objetos definidos pelo usuário suportem operadores infixos como + e |, ou com operadores unários como - e ~. De forma geral, em Python a notação de invocação de função (f()), o acesso a atributos (p.x) e o acesso a itens e o fatiamento (v[0]) também são operadores, mas este capítulo trata dos operadores unários e infixos.

A sobrecarga de operadores tem má reputação em certos círculos. É um recurso que pode ser abusado, resultando em programadores confusos, bugs, e gargalos de desempenho inesperados. Mas se bem utilizada, possibilita APIs agradáveis de usar e código legível. Python alcança um bom equilíbrio entre flexibilidade, usabilidade e segurança, pela imposição de algumas limitações:

• Não é permitido modificar o significado dos operadores para os tipos embutidos.

• Não é permitido criar novos operadores, apenas sobrecarregar os existentes.

• Alguns poucos operadores não podem ser sobrecarregados: is, and, or e not (mas os operadores ==, &, |, e ~ podem).

No [ch_seq_methods], na classe Vector, já apresentamos um operador infixo: ==, suportado pelo método __eq__. Neste capítulo, vamos melhorar a implementação de __eq__ para lidar melhor com operandos de outros tipos além de Vector. Entretanto, os operadores de comparação rica (==, !=, >, <, >=, {lte}) são casos especiais de sobrecarga de operadores, então começaremos sobrecarregando quatro operadores aritméticos em Vector: os operadores unários - e +, seguido pelos infixos + e *.

Vamos começar pelo tópico mais fácil: operadores unários.

Na Referência da Linguagem Python, a seção Operações aritméticas unárias e bit a bit, cita três operadores unários, listados abaixo com os seus métodos especiais:

- implementado por __neg__

Negativo aritmético unário. Se x é 42 então -x == -42.

+ implementado por __pos__

Positivo aritmético unário. Em geral, x == +x, mas há alguns poucos casos em que isto não ocorre. Veja: Quando x e +x não são iguais (ao final desta seção).

~ implementado por __invert__

Negação binária, ou inversão bit a bit de um inteiro, definida como ~x == -(x+1). Se x é 2 então ~x == -3, porque a representação binária de 2 é 0010 e -3 é 1101. Veja Complemento para dois na Wikipédia para entender esta representação de inteiros com sinal.

O capítulo Modelo de Dados na Referência da Linguagem Python_ também inclui a função embutida abs() como um operador unário. O método especial associado é __abs__, como já vimos.

É fácil suportar operadores unários. Basta implementar o método especial apropriado, que receberá apenas um argumento: self. Use a lógica que fizer sentido na sua classe, mas respeite a regra geral dos operadores: sempre devolva um novo objeto. Em outras palavras, não modifique o receptor (self), mas crie e devolva uma nova instância do tipo adequado.

No caso de - e +, o resultado será provavelmente uma instância da mesma classe de self. Para o + unário, se o receptor for imutável você deveria devolver self; caso contrário, devolva uma cópia de self. Para abs(), o resultado deve ser um número escalar.^[3]

Já no caso de ~, é difícil determinar o que seria um resultado razoável se você não estiver lidando com bits de um número inteiro. No pacote de análise de dados pandas, o til nega condições booleanas de filtragem; veja exemplos na documentação do pandas, em Boolean indexing (indexação booleana).

Como prometido acima, vamos implementar vários novos operadores na classe Vector, do [ch_seq_methods]. O vector_v6.py: operadores unários - e + implementados. mostra o método __abs__, que já estava no [ex_vector_v5] do [ch_seq_methods], e os novos métodos __neg__ e __pos__ para operadores unários.

1. Para computar -v, cria um novo Vector com a negação de cada componente de self.

2. Para computar +v, cria um novo Vector com cada componente de self.

Lembre-se de que instâncias de Vector são iteráveis, e o Vector.__init__ recebe um argumento iterável, por isso as implementações de __neg__ e __pos__ ficaram tão simples.

Não vamos implementar __invert__. Se um usuário tentar escrever ~v para uma instância de Vector, Python vai gerar um TypeError com uma mensagem clara: “bad operand type for unary ~: 'Vector'” (operando inválido para o ~ unário: 'Vector').

O quadro a seguir trata de uma curiosidade que algum dia poderá ajudar você a ganhar uma aposta sobre o + unário.

A classe Vector é um tipo sequência, e a seção Emulando tipos contêineres da documentação oficial do Python diz que sequências devem suportar o operadores + para concatenação e * para repetição. Entretanto, aqui vamos implementar + e * como operações matemáticas de vetores, algo um pouco mais complicado porém mais útil para um tipo Vector.

Somar dois vetores euclidianos resulta em um novo vetor cujos componentes são as somas dos componentes correspondentes dos operandos. Ilustrando:

E o que acontece se tentarmos somar duas instâncias de Vector de tamanhos diferentes? Poderíamos gerar um erro, mas considerando as aplicações práticas (tal como recuperação de informação), é melhor preencher o Vector menor com zeros. Esse é o resultado que queremos:

Dados esses requisitos básicos, podemos implementar __add__ como no Método Vector.__add__, versão #1.

1. pairs é um gerador que produz tuplas (a, b), onde a vem de self e b de other. Se self e other tiverem tamanhos diferentes, fillvalue fornece os valores que faltam no o iterável mais curto.

2. Um novo Vector é criado a partir de uma expressão geradora, produzindo uma soma para cada (a, b) de pairs.

Note que __add__ devolve uma nova instância de Vector, sem modificar self ou other.

O Método Vector.__add__, versão #1 permite somar um Vector a um Vector2d, a uma tupla, como prova o Nossa versão #1 de Vector.__add__ também aceita objetos diferentes de Vector.

Os dois usos de + no Nossa versão #1 de Vector.__add__ também aceita objetos diferentes de Vector funcionam porque __add__ usa zip_longest(…), capaz de consumir qualquer iterável, e a expressão geradora que cria um novo Vector simplesmente efetua a operação a
b com os pares produzidos por zip_longest(…), então qualquer iterável que produza números compatíveis com float servirá.

Entretanto, se trocarmos a ordem dos operandos, a soma de tipos diferentes falha. Veja o A versão #1 de Vector.__add__ falha se o operador da esquerda não for um Vector.

Para suportar operações envolvendo objetos de tipos diferentes, Python implementa um mecanismo especial de despacho para os métodos especiais de operadores infixos. Dada a expressão a + b, o interpretador executará os seguintes passos (veja também a Fluxograma para computar a + b com __add__ e __radd__.):

1. Se a implementa __add__, Python invoca a.__add__(b) e devolve o resultado, a menos que seja NotImplemented.

2. Se a não implementa __add__, ou a chamada a.__add__(b) devolve NotImplemented, Python verifica se b implementa __radd__, e então invoca b.__radd__(a) e devolve o resultado, a menos que seja NotImplemented.

3. Se b não implementa __radd__, ou a chamada b.__radd__(a) devolve NotImplemented, Python gera um TypeError com a mensagem "unsupported operand types" (tipos de operandos não suportados).

Assim, para fazer as somas de tipos diferentes no A versão #1 de Vector.__add__ falha se o operador da esquerda não for um Vector funcionarem, precisamos implementar o método Vector.__radd__, que Python vai invocar como alternativa, se o operando à esquerda não implementar __add__, ou se implementar mas devolver NotImplemented, indicando que não sabe como tratar o operando à direita.

A implementação viável mais simples de __radd__ aparece no Os métodos __add__ e __radd__ de Vector.

1. Nenhuma mudança no __add__ do Método Vector.__add__, versão #1; ele é listado aqui porque é usado por __radd__.

2. __radd__ apenas delega para __add__.

Muitas vezes, __radd__ pode ser simples assim: apenas a invocação do operador apropriado, delegando para __add__ neste caso. Isso se aplica para qualquer operador comutativo. O + é comutativo quando lida com números ou com nossos vetores, mas não é comutativo ao concatenar sequências no Python.

Se __radd__ apenas invoca __add__, aqui está uma forma mais eficiente de obter o mesmo efeito:

Os métodos no Os métodos __add__ e __radd__ de Vector funcionam com objetos Vector ou com qualquer iterável com itens numéricos, tal como um Vector2d, uma tupla de inteiros ou um array de números de ponto flutuante. Mas se alimentado com um objeto não-iterável, __add__ gera uma exceção com uma mensagem não muito útil, como no O método Vector.__add__ precisa de operandos iteráveis.

E pior ainda, recebemos uma mensagem enganosa se um operando for iterável, mas seus itens não puderem ser somados aos itens float no Vector. Veja o O método Vector.__add__ exige um iterável com itens numéricos.

Tentei somar um Vector a uma str, mas a mensagem reclama de float e str.

Na verdade, os problemas no O método Vector.__add__ precisa de operandos iteráveis e no O método Vector.__add__ exige um iterável com itens numéricos são mais profundos que meras mensagens de erro obscuras: se um método especial de operando não é capaz de devolver um resultado válido por incompatibilidade de tipos, ele tem que devolver NotImplemented e não gerar um TypeError. Ao devolver NotImplemented, a porta fica aberta para o outro operando executar a operação, quando Python tentar invocar o método reverso em sua classe.

No espírito da tipagem pato, não vamos testar o tipo do operando other ou o tipo de seus elementos. Vamos capturar as exceções e devolver NotImplemented. Se o interpretador ainda não tiver invertido os operandos, tentará isso em seguida. Se a invocação do método reverso devolver NotImplemented, então Python vai gerar um TypeError com uma mensagem de erro padrão "unsupported operand type(s) for +: 'Vector' and 'str'” (tipos de operandos não suportados para +: Vector e `str`)

A implementação final dos métodos especiais de adição de Vector está no vector_v6.py: métodos do operador + adicionados a vector_v5.py ([ex_vector_v5] do [ch_seq_methods]).

Observe que agora __add__ captura um TypeError e devolve NotImplemented.

Agora que já sobrecarregamos o operador + com segurança, implementando __add__ e __radd__, vamos enfrentar outro operador infixo: *.

O que significa Vector([1, 2, 3]) * x? Se x é um número escalar, isto é uma "multiplicação por escalar", e o resultado deve ser um novo Vector com cada componente multiplicado por x—também conhecida como multiplicação elemento a elemento (elementwise multiplication):

Voltando à nossa multiplicação por escalar, começamos novamente com os métodos __mul__ e __rmul__ mais simples possíveis que possam funcionar:

Estes métodos funcionam, exceto quando recebem operandos incompatíveis.
O argumento scalar precisa ser um número que, quando multiplicado por um float, produz outro float (porque nossa classe Vector armazena um array de números de ponto flutuante). Então um complex não serve, mas pode ser um int, um bool (bool é subclasse de int) ou até uma instância de fractions.Fraction. No vector_v7.py: métodos do operador * adicionados, o método __mul__ não faz nenhuma checagem de tipos explícita com scalar. Em vez disso, o converte para float, e devolve NotImplemented se a conversão falhar. É mais um exemplo prático de tipagem pato.

1. Se scalar não pode ser convertido para float…​

2. …​não temos como lidar com ele, então devolvemos NotImplemented, para permitir ao Python tentar __rmul__ no operando scalar.

3. Neste exemplo, __rmul__ funciona bem apenas executando self * scalar, que delega a operação para o método __mul__.

Com o vector_v7.py: métodos do operador * adicionados, é possível multiplicar um Vector por valores escalares de tipos numéricos comuns e não tão comuns:

Agora que podemos multiplicar Vector por valores escalares, vamos ver como implementar o produto de um Vector por outro Vector.

O símbolo @ é o prefixo de decoradores de função, mas desde 2015 também pode ser usado como um operador infixo.

Por muitos anos, o produto escalar (dot product) era escrito como numpy.dot(a, b) na biblioteca NumPy. A notação de invocação de função faz com que fórmulas mais longas sejam difíceis de traduzir da notação matemática para Python,^[4] então a comunidade de computação numérica fez campanha pela PEP 465—A dedicated infix operator for matrix multiplication (Um operador infixo dedicado para multiplicação de matrizes), que foi implementada no Python 3.5. Hoje podemos escrever a @ b para computar o produto de dois arrays da NumPy.

O operador @ é suportado pelos métodos especiais __matmul__, __rmatmul__ e __imatmul__, cujos nomes derivam de "matrix multiplication". Até o Python 3.10, estes métodos não são usados em lugar algum na biblioteca padrão, mas são reconhecidos pelo interpretador desde o Python 3.5, então nós e os desenvolvedores da NumPy podemos implementar o operador @ em nossas classes. O analisador sintático de Python foi modificado para aceitar o novo operador, pois a @ b era um erro de sintaxe até o Python 3.4.

Estes testes simples mostram como @ deve funcionar com instâncias de Vector:

O resultado de va @ vz no exemplo acima é o mesmo que obtemos no NumPy fazendo o produto escalar de arrays com os mesmos valores:

O vector_v7.py: métodos para o operador @ mostra o código dos métodos especiais relevantes na classe Vector.

1. Ambos os operandos precisam implementar __len__ e __iter__…​

2. …​e ter o mesmo tamanho, para permitir…​

3. …​uma linda aplicação de sum, zip e uma expressão geradora.

O vector_v7.py: métodos para o operador @ é um bom exemplo prático de tipagem ganso. Não usamos isinstance(other, Vector), porque queremos oferecer mais flexibilidade para os usuários. Suportamos operandos que sejam instâncias de abc.Sized e abc.Iterable. Estas duas ABCs implementam o __subclasshook__, portanto qualquer objeto que forneça __len__ e __iter__ satisfaz nosso teste—não há necessidade de criar subclasses concretas dessas ABCs ou sequer registrar-se com elas, como explicado na [subclasshook_sec]. Em particular, nossa classe Vector não é subclasse nem de abc.Sized nem de abc.Iterable, mas passa os testes de isinstance contra aquelas ABCs, pois implementa os métodos necessários.

Vamos revisar os operadores aritméticos suportados pelo Python antes de mergulhar na categoria especial dos operadores de comparação rica (Operadores de comparação rica).

Ao implementar +, *, e @, vimos os padrões de programação mais comuns para operadores infixos. As técnicas descritas são aplicáveis a todos os operadores listados na Nomes dos métodos de operadores infixos (os operadores internos são usados para atribuição aumentada; operadores de comparação estão na [reversed_rich_comp_op_tbl]) (os operadores de atribuição aritmética serão tratados na Operadores de atribuição aumentada).

Operadores de comparação rica usam regras diferentes.

O tratamento dos operadores de comparação rica ==, !=, >, <, >= e {lte} pelo interpretador Python é similar ao que já vimos, com uma importante diferença: não existem métodos reversos com o prefixo __r…__. Os mesmos métodos são usados para invocações diretas ou reversas do operador. As regras estão resumidas na Comparação rica: a última coluna mostra o resultado quando as tentativas devolvem NotImplemented ou o operando não implementa o método..

Por exemplo, no caso de ==, tanto a chamada direta quanto a reversa invocam __eq__, apenas permutando os argumentos. Uma chamada direta a __gt__ pode ser seguida de uma chamada reversa a __lt__, com os argumentos permutados.

Nos casos de == e !=, se o método não existe no segundo operando, ou devolve NotImplemented, os métodos correspondentes __eq__ e __ne__ herdados da classe object comparam os IDs dos objetos, então não ocorre TypeError.

Considerando estas regras, vamos revisar e aperfeiçoar o comportamento do método Vector.__eq__, escrito assim no vector_v5.py ([ex_vector_v5] do [ch_seq_methods]):

Este método produz os resultados do Comparando um Vector a um Vector, a um Vector2d, e a uma tupla.

1. Duas instâncias de Vector com componentes numéricos iguais são iguais.

2. Um Vector e um Vector2d também são iguais se seus componentes são iguais.

3. Um Vector também é considerado igual a uma tupla ou qualquer sequência com itens escalares de valor igual.

O último resultado no Comparando um Vector a um Vector, a um Vector2d, e a uma tupla pode ser indesejável. Queremos mesmo que um Vector seja considerado igual a uma tupla contendo os mesmos números? Não tenho uma regra fixa sobre isso; depende do contexto da aplicação. O "Zen of Python" diz:

Em face da ambiguidade, rejeite a tentação de adivinhar.

Liberalidade excessiva na avaliação de operandos pode levar a resultados surpreendentes, e programadores odeiam surpresas.

Buscando inspiração no próprio Python, vemos que [1, 2] == (1, 2) é False. Então, seremos conservadores e faremos checagem de tipos. Se o segundo operando for uma instância de Vector (ou uma instância de uma subclasse de Vector), então usaremos a mesma lógica do __eq__ atual. Caso contrário, devolvemos NotImplemented e deixamos Python cuidar do caso. Veja o vector_v8.py: __eq__ aperfeiçoado na classe Vector.

1. Se o operando other é uma instância de Vector (ou de uma subclasse de Vector), executa a comparação como antes.

2. Caso contrário, devolve NotImplemented.

Rodando os testes do Comparando um Vector a um Vector, a um Vector2d, e a uma tupla com o novo Vector.__eq__ do vector_v8.py: __eq__ aperfeiçoado na classe Vector, obtemos os resultados do Mesmas comparações do [eq_initial_demo]: o último resultado mudou.

1. Mesmo resultado de antes, como esperado.

2. Mesmo resultado de antes, mas por quê? Explicação a seguir.

3. Resultado diferente; era o que queríamos. Mas por que isso funciona? Continue lendo…​

Dos três resultados no Mesmas comparações do [eq_initial_demo]: o último resultado mudou, o primeiro não é novidade, mas os dois últimos foram causados por __eq__ devolver NotImplemented no vector_v8.py: __eq__ aperfeiçoado na classe Vector. Eis o que acontece no exemplo com um Vector e um Vector2d, vc == v2d, passo a passo:

1. Para avaliar vc == v2d, Python invoca Vector.eq(vc, v2d).

2. Vector.__eq__(vc, v2d) verifica que v2d não é um Vector e devolve NotImplemented.

3. Diante do resultado NotImplemented, Python tenta Vector2d.__eq__(v2d, vc).

4. Vector2d.__eq__(v2d, vc) transforma os dois operandos em tuplas e os compara: o resultado é True (o código de Vector2d.__eq__ está no [ex_vector2d_v3_full] do [ch_pythonic_obj]).

Já para a comparação va == t3, entre Vector e tuple no Mesmas comparações do [eq_initial_demo]: o último resultado mudou, os passos são:

1. Para avaliar va == t3, Python invoca Vector.__eq__(va, t3).

2. Vector.__eq__(va, t3) verifica que t3 não é um Vector e devolve NotImplemented.

3. Diante do resultado NotImplemented, Python tenta tuple.__eq__(t3, va).

4. tuple.__eq__(t3, va) não tem a menor ideia do que seja um Vector, então devolve NotImplemented.

5. No caso especial de ==, se a chamada reversa devolve NotImplemented, Python compara os IDs dos objetos, como último recurso.

Não precisamos implementar __ne__ para !=, pois o comportamento alternativo do __ne__ herdado de object nos serve: quando __eq__ é definido e não devolve NotImplemented, __ne__ devolve a negação booleana do resultado de __eq__.

Em outras palavras, dados os mesmos objetos que usamos no Mesmas comparações do [eq_initial_demo]: o último resultado mudou, os resultados de != são consistentes:

O __ne__ herdado de object funciona como o código abaixo (mas o original é escrito em C):^[6]

Vimos o básico da sobrecarga de operadores infixos. Agora veremos uma categoria diferente: os operadores de atribuição aumentada.

Nossa classe Vector já suporta os operadores de atribuição aumentada {iadd} e *=. Isso acontece porque a atribuição aumentada trabalha com sequências imutáveis criando novas instâncias e re-vinculando a variável à esquerda do operador.

O Usando {iadd} e *= com instâncias de Vector os mostra em ação.

1. Cria um alias, para podermos inspecionar o objeto Vector([1, 2, 3]) mais tarde.

2. Verifica o id do Vector inicial, vinculado a v1.

3. Executa a adição aumentada.

4. O resultado esperado…​

5. …​mas foi criado um novo Vector.

6. Inspeciona v1_alias para confirmar que o Vector original não foi alterado.

7. Executa a multiplicação aumentada.

8. Novamente, o resultado é o esperado, mas um novo Vector foi criado.

Se uma classe não implementa os métodos internos listados na Nomes dos métodos de operadores infixos (os operadores internos são usados para atribuição aumentada; operadores de comparação estão na [reversed_rich_comp_op_tbl]), os operadores de atribuição aumentada funcionam como açúcar sintático: a += b é avaliado exatamente como a = a + b. Este é o comportamento esperado para tipos imutáveis, e se você fornecer __add__, então {iadd} funcionará sem qualquer código adicional.

Entretanto, se você implementar um método interno tal como __iadd__, aquele método será chamado para computar o resultado de a += b. Como indica seu nome, espera-se que esses operadores modifiquem internamente o operando da esquerda^[7], e não criem um novo objeto como resultado.

Para mostrar o código de um método interno de atribuição aumentada, vamos estender a classe BingoCage do [ex_tombola_bingo] do [ch_ifaces_prot_abc] para implementar __add__ e __iadd__.

Vamos chamar a subclasse de AddableBingoCage. Os doctests da classe (O operador + cria uma nova instância de AddableBingoCage) mostram o comportamento esperado do operador +.

1. Cria uma instância de globe com cinco itens (cada uma das vowels).

2. Extrai um dos itens, e verifica que é uma das vowels.

3. Confirma que globe tem agora quatro itens.

4. Cria uma segunda instância, com três itens.

5. Cria uma terceira instância pela soma das duas anteriores. Esta instância tem sete itens.

6. Tentar adicionar uma AddableBingoCage a uma list falha com um TypeError. A mensagem de erro é produzida pelo interpretador de Python quando nosso método __add__ devolve NotImplemented.

Como uma AddableBingoCage é mutável, o Uma AddableBingoCage existente pode ser carregada com {iadd} (continuando do O operador + cria uma nova instância de AddableBingoCage) mostra como ela funcionará quando implementarmos __iadd__.

1. Cria um alias para podermos checar a identidade do objeto mais tarde.

2. globe tem quatro itens aqui.

3. Uma instância de AddableBingoCage pode receber itens de outra instância da mesma classe.

4. O operador à direita de {iadd} também pode ser qualquer iterável.

5. Durante todo esse exemplo, globe sempre se refere ao mesmo objeto que globe_orig.

6. Tentar adicionar um não-iterável a uma AddableBingoCage falha com uma mensagem de erro apropriada.

Observe que o operador {iadd} é mais liberal que + quanto ao segundo operando. Com +, queremos que ambos os operandos sejam do mesmo tipo (neste caso, AddableBingoCage), pois se aceitássemos tipos diferentes, isso poderia causar confusão quanto ao tipo do resultado, violando a propriedade comutativa da adição. Com o {iadd}, a situação é mais clara: o objeto à esquerda do operador é atualizado internamente, então não há dúvida quanto ao tipo do resultado.

Agora que vimos o comportamento desejado para AddableBingoCage, podemos estudar sua implementação no bingoaddable.py: AddableBingoCage é subclasse de BingoCage com suporte aos operadores + e {iadd}. Lembre-se de que BingoCage, ([ex_tombola_bingo] do [ch_ifaces_prot_abc]), é uma subclasse concreta da ABC Tombola do [ex_tombola_abc] do [ch_ifaces_prot_abc].

1. AddableBingoCage estende BingoCage.

2. Nosso __add__ só vai funcionar se o segundo operando for uma instância de Tombola.

3. Em __iadd__, obtém os itens de other, se for uma instância de Tombola.

4. Caso contrário, tenta obter um iterador sobre other (estudaremos a função embutida iter no [ch_generators]).

5. Se aquilo falhar, gera uma exceção explicando o que o usuário deve fazer. Sempre que possível, mensagens de erro devem orientar o usuário para a solução.

6. Se chegamos até aqui, podemos carregar o other_iterable em self.

7. Muito importante: os métodos especiais de atribuição aumentada de objetos mutáveis devem devolver self. É o que os usuários esperam.

Podemos resumir toda a ideia dos operadores de atribuição interna comparando as instruções return que devolvem os resultados em __add__ e em __iadd__ no bingoaddable.py: AddableBingoCage é subclasse de BingoCage com suporte aos operadores + e {iadd}:

__add__: O resultado é computado chamando o construtor AddableBingoCage para criar uma nova instância.

__iadd__: O resultado é self, após ele ter sido modificado.

Uma última observação sobre o bingoaddable.py: AddableBingoCage é subclasse de BingoCage com suporte aos operadores + e {iadd}: não implementei __radd__ em AddableBingoCage, porque não há necessidade. O método direto __add__ só vai lidar com operandos do mesmo tipo à direita, então se Python tentar computar a + b, onde a é uma AddableBingoCage e b não, devolvemos NotImplemented—talvez a classe de b possa fazer isso funcionar. Mas se a expressão for b + a e b não for uma AddableBingoCage, e devolver NotImplemented, então é melhor deixar Python desistir e gerar um TypeError, pois não temos como tratar b.

Assim terminamos nossa exploração de sobrecarga de operadores no Python.

Começamos o capítulo revisando algumas restrições impostas pelo Python à sobrecarga de operadores: é impossível redefinir operadores nos tipos embutidos, a sobrecarga está limitada aos operadores existentes, e alguns operadores não podem ser sobrecarregados (is, and, or, not).

Colocamos a mão na massa com os operadores unários, implementando __neg__ e __pos__. A seguir vieram os operadores infixos, começando por +, suportado pelo método __add__. Vimos que operadores unários e infixos devem produzir resultados criando novos objetos, sem nunca modificar seus operandos. Para suportar operações com outros tipos, devolvemos o valor especial NotImplemented (não uma exceção) permitindo ao interpretador tentar novamente chamando o método especial reverso do segundo operando (por exemplo, __radd__). O algoritmo usado pelo Python para tratar operadores infixos está resumido no fluxograma da Fluxograma para computar a + b com __add__ e __radd__..

Misturar operandos de mais de um tipo exige detectar os operandos que não podemos tratar. Neste capítulo fizemos isso de duas maneiras: ao modo da tipagem pato, apenas fomos em frente e tentamos a operação, capturando uma exceção de TypeError se ela acontecesse; mais tarde, em __mul__ e __matmul__, usamos um teste isinstance explícito. Há prós e contras nas duas abordagens: tipagem pato é mais flexível, mas a checagem explícita de tipo é mais previsível.

De modo geral, bibliotecas devem aproveitar a tipagem pato para lidar objetos de diferentes tipos, desde que eles suportem as operações necessárias. Entretanto, o algoritmo de despacho de operadores de Python pode produzir mensagens de erro enganosas ou resultados inesperados quando combinado com a tipagem pato. Por essa razão, a disciplina da checagem de tipos com invocações de isinstance contra ABCs é muitas vezes útil quando escrevemos métodos especiais para sobrecarga de operadores. Esta é a técnica batizada de tipagem ganso (goose typing) por Alex Martelli—como vimos na [goose_typing_sec]. A tipagem ganso é um compromisso entre a flexibilidade e a segurança, porque os tipos definidos pelo usuário, existentes ou futuros, podem ser declarados como subclasses reais ou virtuais de uma ABC. Além disso, se uma ABC implementa o __subclasshook__, objetos podem então passar por checagens com isinstance contra aquela ABC apenas fornecendo os métodos exigidos—sem necessidade de ser uma subclasse ou de se registrar com a ABC.

O próximo tópico tratado foram os operadores de comparação rica. Implementamos == com __eq__ e descobrimos que Python oferece uma implementação conveniente de != no __ne__ herdado da classe base object. A forma como Python avalia esses operadores, bem como >, <, >=, e {lte}, é um pouco diferente, com uma lógica especial para a escolha do método reverso, e um tratamento alternativo para == e != que nunca gera erros, pois a classe object já implementa os métodos necessários.

Na última seção, nos concentramos nos operadores de atribuição aumentada. Vimos que Python os trata, por default, como uma combinação do operador simples seguido de uma atribuição: a {iadd} b é avaliado exatamente como
a = a + b. Isto sempre cria um novo objeto, então funciona para tipos mutáveis ou imutáveis.

Para objetos mutáveis, podemos implementar métodos especiais de atualização interna, tal como __iadd__ para {iadd}, e alterar o valor do operando à esquerda. Para demonstrar isto na prática, implementamos uma subclasse de BingoCage, suportando {iadd} para adicionar itens ao reservatório de itens para sorteio, de modo similar à forma como o tipo embutido list suporta {iadd} como um atalho para o método list.extend(). Vimos que + tende a ser mais estrito que {iadd} em relação aos tipos aceitos. Em sequências, + normalmente exige que ambos os operandos sejam do mesmo tipo, enquanto {iadd} muitas vezes aceita qualquer iterável como o operando à direita do operador.

Guido van Rossum escreveu uma boa apologia da sobrecarga de operadores em Why operators are useful (Porque operadores são úteis). Trey Hunner postou Tuple ordering and deep comparisons in Python (Ordenação de tuplas e comparações profundas em Python), argumentando que os operadores de comparação rica de Python são mais flexíveis e poderosos do que os programadores vindos de outras linguagens costumam pensar.

A sobrecarga de operadores é uma área da programação em Python onde testes com isinstance são comuns. A melhor prática relacionada a tais testes é a tipagem ganso, tratada na [goose_typing_sec]. Se você pulou essa parte, assegure-se de voltar lá e ler aquela seção.

A principal referência para os métodos especiais de operadores é o capítulo Modelo de Dados na documentação de Python. Outra leitura relevante é Implementando as operações aritméticas no módulo numbers da biblioteca padrão de Python.

Um exemplo brilhante de sobrecarga de operadores apareceu no pacote pathlib, a partir do Python 3.4. Sua classe Path sobrecarrega o operador / para construir caminhos do sistema de arquivos a partir de strings, como mostra o exemplo abaixo, da documentação:

Outro exemplo não aritmético de sobrecarga de operadores está na biblioteca Scapy, usada para "enviar, farejar, dissecar e forjar pacotes de rede". Na Scapy, o operador / cria pacotes empilhando campos de diferentes camadas da rede. Veja Stacking layers (Empilhando camadas) para mais detalhes.

Se você está prestes a implementar operadores de comparação, estude functools.total_ordering. Esse é um decorador de classes que gera automaticamente os métodos para todos os operadores de comparação rica em qualquer classe que defina ao menos alguns deles. Veja a documentação do módulo functools.

Se tiver curiosidade sobre o despacho de métodos de operadores em linguagens com tipagem dinâmica, duas leituras fundamentais são A Simple Technique for Handling Multiple Polymorphism (Uma técnica simples para tratar polimorfismo múltiplo), de Dan Ingalls (membro da equipe original de Smalltalk), e Arithmetic and Double Dispatching in Smalltalk-80 (Aritmética e despacho duplo no Smalltalk-80), de Kurt J. Hebel e Ralph Johnson (Johnson ficou famoso como um dos autores do livro Padrões de Projetos original).

Os dois artigos discutem em profundidade o poder do polimorfismo em linguagens com tipagem dinâmica, como Smalltalk, Python e Ruby. Python não implementa despacho duplo exatamente como descrito naqueles artigos. O algoritmo de despacho duplo em Python, usando operadores diretos e reversos, é mais fácil de suportar em classes definidas pelo usuário que o despacho duplo clássico, mas exige tratamento especial pelo interpretador. Por outro lado, o despacho duplo clássico é uma técnica geral, que pode ser usada no Python ou em qualquer linguagem orientada a objetos, para além do contexto específico de operadores infixos. E, de fato, Ingalls, Hebel e Johnson usam exemplos muito diferentes para descrever essa técnica.

O texto The C Family of Languages: Interview with Dennis Ritchie, Bjarne Stroustrup, and James Gosling (A Família de Linguagens C: entrevista com Dennis Ritchie, Bjarne Stroustrup, e James Gosling), de onde tirei a epígrafe deste capítulo, apareceu na Java Report, 5(7), julho de 2000, e na C++ Report, 12(7), julho/agosto de 2000, juntamente com outros trechos que usei no Ponto de Vista deste capítulo (logo adiante). Se você se interessa pelo design de linguagens de programação, faça um favor a si mesmo e leia aquela entrevista.