formatação

ramalho · ramalho · commit cfc79e6a01a0 · 2025-09-18T12:11:54.000-03:00
diff --git a/vol1/cap01.adoc b/vol1/cap01.adoc
@@ -11,10 +11,10 @@ que ninguém jamais usaria.
 Mas Guido é uma daquelas raras pessoas capazes de criar uma linguagem só um pouco menos teoricamente linda que,
 por isso mesmo, é uma delícia para programar.
 footnote:[Traduzido de
-«Story of Jython» [.small]#&#91;fpy.li/1-1&#93;# (EN),
+«Story of Jython» [.small]#&#91;fpy.li/1-1&#93;#,
 prefácio de
-«Jython Essentials» [.small]#&#91;fpy.li/1-2&#93;#
-(EN), de Samuele Pedroni e Noel Rappin (O'Reilly).]
+«Jython Essentials» [.small]#&#91;fpy.li/1-2&#93;#,
+de Samuele Pedroni e Noel Rappin (O'Reilly).]
 ____
 
 Uma das melhores qualidades de Python é sua consistência.
@@ -328,8 +328,8 @@ startref="len01")))((("", startref="pycard01")))((("", startref="SMgetitem01")))
 Como foi implementado até aqui, um `FrenchDeck` não pode ser embaralhado,
 porque as cartas e suas posições não podem ser alteradas,
 exceto violando o encapsulamento e manipulando o atributo `_cards` diretamente.
-No Capítulo 13 [.small]#&#91;vol.2, fpy.li/4q&#93;# vamos corrigir isso acrescentando um método `+__setitem__+`
-de uma linha.
+No «Capítulo 13» [.small]#&#91;vol.2, fpy.li/4q&#93;#
+vamos corrigir isso acrescentando um método `+__setitem__+` de uma linha.
 Você consegue imaginar como ele seria implementado?
 =====================================================================
 
@@ -384,7 +384,7 @@ Na próxima seção veremos alguns dos usos mais importantes dos métodos especi
 Vários((("special methods", "emulating numeric types", id="SMnumeric01")))((("numeric types",
 "emulating using special methods", id="NTemul01")))
 métodos especiais permitem que objetos criados pelo usuário respondam a operadores como `+`.
-Vamos tratar disso com mais detalhes no Capítulo 16 [.small]#&#91;vol.2, fpy.li/4r&#93;#.
+Vamos tratar disso com mais detalhes no «Capítulo 16» [.small]#&#91;vol.2, fpy.li/4r&#93;#.
 Aqui nosso objetivo é continuar ilustrando o uso dos métodos especiais, através de outro exemplo simples.
 
 Vamos((("vectors", "representing two-dimensional", id="Vtwo01"))) implementar uma classe para representar
@@ -395,7 +395,7 @@ vetores bidimensionais—isto é, vetores euclidianos como aqueles usados em mat
 ======
 O tipo embutido `complex` pode ser usado para representar vetores bidimensionais,
 mas nossa classe pode ser estendida para representar vetores N-dimensionais.
-Faremos isso no Capítulo 17 [.small]#&#91;vol.3, fpy.li/4s&#93;#.
+Faremos isso no «Capítulo 17» [.small]#&#91;vol.3, fpy.li/4s&#93;#.
 ======
 
 [[vectors_fig]]
@@ -463,14 +463,14 @@ para demonstrar o uso básico de `+__add__+` e `+__mul__+`.
 Nos dois casos, os métodos criam e devolvem uma nova instância de `Vector`,
 e não modificam nenhum dos operandos: `self` e `other` são apenas lidos.
 Esse é o comportamento esperado de operadores infixos: criar novos objetos e não tocar em seus operandos.
-Vou falar mais sobre esse tópico no Capítulo 16 [.small]#&#91;vol.2, fpy.li/4r&#93;#.
+Vou falar mais sobre esse tópico no «Capítulo 16» [.small]#&#91;vol.2, fpy.li/4r&#93;#.
 
 [WARNING]
 ====
 Da forma como está implementado, o <<ex_vector2d>> permite multiplicar um `Vector` por um número,
 mas não um número por um `Vector`,
 violando a propriedade comutativa da multiplicação escalar.
-Vamos consertar isso com o método especial `+__rmul__+` no Capítulo 16 [.small]#&#91;vol.2, fpy.li/4r&#93;#.
+Vamos consertar isso com o método especial `+__rmul__+` no «Capítulo 16» [.small]#&#91;vol.2, fpy.li/4r&#93;#.
 ====
 
 Nas seções seguintes vamos discutir os outros métodos especiais em
@@ -521,8 +521,9 @@ Programadores com experiência anterior em linguagens que contém o método `toS
 tendem a implementar `+__str__+` e não `+__repr__+`.
 Se você for implementar apenas um desses métodos especiais, escolha `+__repr__+`.
 
-https://fpy.li/1-5["What is the difference between `+__str__+` and `+__repr__+` in Python?"
-(_Qual a diferença entre `+__str__+` e `+__repr__+` em Python?_)] (EN)
+«_What is the difference between `+__str__+` and `+__repr__+` in Python?_
+(Qual a diferença entre `+__str__+` e `+__repr__+` em Python?)»
+[.small]#&#91;fpy.li/1-5&#93;#
 é uma questão no Stack Overflow  com excelentes contribuições dos pythonistas
 Alex Martelli e Martijn Pieters.((("", startref="repr01")))
 ====
@@ -553,7 +554,7 @@ porque qualquer objeto pode ser usado em um contexto booleano.
 
 Observe que o método especial `+__bool__+` permite que seus objetos sigam as
 regras de teste do valor verdade definidas no
-«capítulo "Tipos Embutidos"» [.small]#&#91;fpy.li/2g&#93;#
+capítulo «Tipos Embutidos» [.small]#&#91;fpy.li/2g&#93;#
 da documentação da _Biblioteca Padrão de Python_.
 
 [NOTE]
@@ -589,7 +590,7 @@ id="SMcollection01")))((("Collection API", id="Cspeical01")))((("ABCs (abstract
 as interfaces dos tipos de coleções essenciais na linguagem.
 Todas as classes no diagrama são ABCs—_classes base abstratas_
 (_ABC_ é sigla para _Abstract Base Class_).
-As ABCs e o módulo `collections.abc` são tratados no Capítulo 13 [.small]#&#91;vol.2, fpy.li/4q&#93;#.
+As ABCs e o módulo `collections.abc` são tratados no «Capítulo 13» [.small]#&#91;vol.2, fpy.li/4q&#93;#.
 O objetivo dessa pequena seção é dar uma visão panorâmica das interfaces das coleções mais importantes de Python,
 mostrando como elas são criadas a partir de métodos especiais.
 
@@ -640,7 +641,7 @@ Python.((("", startref="PDMspecmeth01")))((("", startref="SMcollection01")))((("
 
 O((("Python Data Model", "special methods overview", id="PDMspmtov01")))((("special methods",
 "special method names (operators excluded)")))
-«capítulo "Modelo de Dados"» [.small]#&#91;fpy.li/2j&#93;#
+capítulo «Modelo de Dados» [.small]#&#91;fpy.li/2j&#93;#
 de _A Referência da Linguagem Python_ lista mais de 80 nomes de métodos especiais.
 Mais da metade deles implementa operadores aritméticos, de comparação, ou bit-a-bit.
 Para ter uma visão geral do que está disponível, veja as tabelas a seguir.
@@ -672,7 +673,7 @@ Operadores infixos e numéricos são suportados pelos métodos especiais listado
 <<special_operators_tbl>>.
 Aqui os nomes mais recentes são `+__matmul__+`, `+__rmatmul__+`, e `+__imatmul__+`,
 adicionados no Python 3.5 para suportar o uso de `@` como operador de multiplicação de matrizes,
-como veremos no Capítulo 16 [.small]#&#91;vol.2, fpy.li/4r&#93;#.((("special methods", "special method names and symbols for operators")))
+como veremos no «Capítulo 16» [.small]#&#91;vol.2, fpy.li/4r&#93;#.((("special methods", "special method names and symbols for operators")))
 
 [[special_operators_tbl]]
 .Nomes e símbolos de métodos especiais para operadores
@@ -695,15 +696,17 @@ Python invoca um método especial de operador reverso no segundo argumento
 quando o método especial correspondente não pode ser usado no primeiro operando.
 Atribuições aumentadas são um atalho combinando um operador infixo com uma atribuição de variável, por exemplo `a += b`.
 
-O Capítulo 16 [.small]#&#91;vol.2, fpy.li/4r&#93;# explica em detalhes os operadores reversos e a atribuição aumentada.((("", startref="PDMspmtov01")))
+O «Capítulo 16» [.small]#&#91;vol.2, fpy.li/4r&#93;#
+explica em detalhes os operadores reversos e a atribuição aumentada.((("", startref="PDMspmtov01")))
 ====
 
 
 === Por que len não é um método?
 
 Em 2013, fiz((("Python Data Model", "making len work with custom objects")))((("&#x005F;&#x005F;len&#x005F;&#x005F;")))
 essa pergunta a Raymond Hettinger, um dos desenvolvedores principais do Python,
-e sua resposta foi basicamente uma citação do «"The Zen of Python" (_O Zen do Python_)» [.small]#&#91;fpy.li/1-8&#93;# (EN): "a praticidade vence a pureza."
+e sua resposta foi basicamente uma citação do
+«"The Zen of Python" (_O Zen do Python_)» [.small]#&#91;fpy.li/1-8&#93;#: "a praticidade vence a pureza."
 Na <<how_special_used>>, descrevi como `len(x)` roda muito rápido quando `x` é uma instância de um tipo embutido.
 Nenhum método é chamado para os objetos embutidos do CPython: o tamanho é simplesmente lido de um campo em uma struct C.
 Obter o número de itens em uma coleção é uma operação comum, e precisa funcionar de forma eficiente para tipos tão básicos e diferentes como
@@ -743,43 +746,43 @@ uma para depuração e registro (_log_), outra para apresentar aos usuários fin
 Emular sequências, como mostrado com o exemplo do `FrenchDeck`, é um dos usos mais comuns dos métodos especiais.
 Por exemplo, bibliotecas de banco de dados frequentemente devolvem resultados de consultas na forma de coleções similares a sequências.
 Tirar o máximo proveito dos tipos de sequências existentes é o assunto do <<ch_sequences>>.
-Como implementar suas próprias sequências será visto no Capítulo 12 [.small]#&#91;vol.2, fpy.li/4t&#93;#,
+Como implementar suas próprias sequências será visto no «Capítulo 12» [.small]#&#91;vol.2, fpy.li/4t&#93;#,
 onde criaremos uma extensão multidimensional da classe `Vector`.
 
 Graças à sobrecarga de operadores, Python oferece uma rica seleção de tipos numéricos,
 desde os tipos embutidos até `decimal.Decimal` e `fractions.Fraction`,
 todos eles suportando operadores aritméticos infixos.
 A biblioteca de ciência de dados _NumPy_ suporta operadores infixos com matrizes e tensores.
-A implementação de operadores—incluindo operadores reversos e atribuição aumentada—será vista no Capítulo 16 [.small]#&#91;vol.2, fpy.li/4r&#93;#,
+A implementação de operadores—incluindo operadores reversos e atribuição aumentada—será vista no
+«Capítulo 16» [.small]#&#91;vol.2, fpy.li/4r&#93;#,
 usando melhorias do exemplo `Vector`.
 
 Também veremos o uso e a implementação da maioria dos outros métodos especiais do Modelo de Dados de Python ao longo deste livro.
 
 === Para saber mais
 
 O((("Python Data Model", "further reading on")))
-«capítulo "Modelo de Dados"» [.small]#&#91;fpy.li/2j&#93;#
-em _A Referência da Linguagem Python_ é a fonte canônica para o assunto desse capítulo e de uma boa parte deste livro.
+capítulo «Modelo de Dados» [.small]#&#91;fpy.li/2j&#93;#
+em _A Referência da Linguagem Python_ é a fonte canônica
+para o assunto desse capítulo e de uma boa parte deste livro.
 
-«Python in a Nutshell, 3rd ed.» [.small]#&#91;fpy.li/pynut3&#93;#
-(EN), de Alex Martelli, Anna Ravenscroft, e Steve Holden (O'Reilly)
+«Python in a Nutshell, 3rd ed.» [.small]#&#91;fpy.li/pynut3&#93;#,
+de Alex Martelli, Anna Ravenscroft, e Steve Holden (O'Reilly)
 tem uma excelente cobertura do modelo de dados.
 Sua descrição da mecânica de acesso a atributos é a mais competente que já vi,
 perdendo apenas para o próprio código-fonte em C do CPython.
 Martelli também é um contribuidor prolífico do Stack Overflow,
 com mais de 6200 respostas publicadas.
-Veja seu perfil de usuário no
-«Stack Overflow» [.small]#&#91;fpy.li/1-9&#93;#.
+Veja «seu perfil de usuário no _Stack Overflow_» [.small]#&#91;fpy.li/1-9&#93;#.
 
 David Beazley tem dois livros tratando do modelo de dados em detalhes, no contexto de Python 3:
-«Python Essential Reference» [.small]#&#91;fpy.li/2k&#93;#
-(EN), 4th ed. (Addison-Wesley), e
-«Python Cookbook, 3rd ed» [.small]#&#91;fpy.li/pycook3&#93;#
-(EN) (O'Reilly), colaborando com Brian K. Jones.
+«Python Essential Reference» [.small]#&#91;fpy.li/2k&#93;#, 4th ed. (Addison-Wesley), e
+«Python Cookbook, 3rd ed» [.small]#&#91;fpy.li/pycook3&#93;# (O'Reilly), colaborando com Brian K. Jones.
 
-«The Art of the Metaobject Protocol» [.small]#&#91;fpy.li/2m&#93;#
-(EN) (MIT Press) de Gregor Kiczales, Jim des Rivieres, e Daniel G. Bobrow
-explica o conceito de um protocolo de metaobjetos, do qual o Modelo de Dados de Python é um exemplo.
+«The Art of the Metaobject Protocol» [.small]#&#91;fpy.li/2m&#93;# (MIT Press)
+de Gregor Kiczales, Jim des Rivieres, e Daniel G. Bobrow
+explica o conceito de um protocolo de metaobjetos,
+do qual o Modelo de Dados de Python é um exemplo.
 
 <<<
 .Ponto de Vista
@@ -796,17 +799,17 @@ O _Python in a Nutshell_, 3rd ed. de Martelli, Ravenscroft, e Holden, e o _Pytho
 de David Beazley são os melhores livros sobre o Modelo de Dados de Python, mas se referem a ele como o "modelo de objetos."
 Na Wikipedia, a primeira definição de
 «modelo de objetos» [.small]#&#91;fpy.li/1-10&#93;#
-(EN) é: "as propriedades dos objetos em geral em uma linguagem de programação de computadores específica."
+é: "as propriedades dos objetos em geral em uma linguagem de programação de computadores específica."
 É disso que o Modelo de Dados de Python trata.
 Neste livro, usarei "modelo de dados" porque esse é o título do
-«capítulo de _A Referência da Linguagem Python_» [.small]#&#91;fpy.li/2j&#93;#
+«capítulo de A Referência da Linguagem Python» [.small]#&#91;fpy.li/2j&#93;#
 mais relevante para nossas discussões.
 
 [role="soapbox-title"]
 **Métodos de "trouxas"**
 
-«_The Original Hacker's Dictionary_ (_Dicionário Hacker Original_)» [.small]#&#91;fpy.li/1-11&#93;#
-(EN) define ((("Soapbox sidebars", "magic methods")))((("magic methods"))) _mágica_ como
+«_The Original Hacker's Dictionary_ (Dicionário Hacker Original)» [.small]#&#91;fpy.li/1-11&#93;#
+define ((("Soapbox sidebars", "magic methods")))((("magic methods"))) _mágica_ como
 "algo ainda não explicado ou muito complicado para explicar" ou "uma funcionalidade,
 em geral não divulgada, que permite fazer algo que de outra forma seria impossível."
 
@@ -845,8 +848,8 @@ e o autor inicial do AspectJ, uma extensão de Java implementando aquele paradig
 A programação orientada a aspecto é mais fácil de implementar em uma linguagem dinâmica como Python,
 e alguns frameworks fazem exatamente isso.
 Um exemplo importante é a
-«_zope.interface_» [.small]#&#91;fpy.li/1-12&#93;#
-(EN), parte do framework Zope sobre o qual o sistema de gerenciamento de conteúdo
-«Plone» [.small]#&#91;fpy.li/2n&#93;# é construído.
+«_zope.interface_» [.small]#&#91;fpy.li/1-12&#93;#,
+parte do framework Zope sobre o qual o sistema de gerenciamento de conteúdo
+«_Plone_» [.small]#&#91;fpy.li/2n&#93;# é construído.
 ****
 
