cap01-06: quebras semanticas

Author: ramalho

capitulos/cap01.adoc

@@ -325,7 +325,8 @@ 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 <<ch_ifaces_prot_abc>> vamos corrigir isso acrescentando um método `+__setitem__+`
-de uma linha. Você consegue imaginar como ele seria implementado?
+de uma linha.
+Você consegue imaginar como ele seria implementado?
 =====================================================================
 
 

capitulos/cap02.adoc

@@ -81,7 +81,8 @@ Sequências planas::
 Uma((("tuples", "simplified memory diagram for")))((("arrays"))) _sequência contêiner_ mantém
 referências para os objetos que contém, que podem ser de qualquer tipo,
 enquanto uma  _sequência plana_ armazena o valor de seu conteúdo em seu próprio espaço de memória,
-e não como objetos Python distintos. Veja a <<container_v_flat_img>>.
+e não como objetos Python distintos.
+Veja a <<container_v_flat_img>>.
 
 [[container_v_flat_img]]
 .Diagramas de memória simplificados mostrando uma `tuple` e um `array`, cada uma com três itens. As células em cinza representam o cabeçalho de cada objeto Python na memória. A `tuple` tem um array de referências para seus itens. Cada item é um objeto Python separado, possivelmente contendo também referências aninhadas a outros objetos Python, como aquela lista de dois itens. Por outro lado, um `array` Python é um único objeto, contendo um array da linguagem C com três números de ponto flutuante`.
@@ -205,12 +206,14 @@ Um loop `for` pode ser usado para muitas coisas diferentes:
 percorrer uma sequência para contar ou encontrar itens, computar valores agregados (somas, médias),
 ou inúmeras outras tarefas.
 O código no <<ex_build_list>> está criando uma lista.
-Uma listcomp, por outro lado, é mais clara. Seu objetivo é sempre criar uma nova lista.
+Uma listcomp, por outro lado, é mais clara.
+Seu objetivo é sempre criar uma nova lista.
 
 Naturalmente, é possível abusar das compreensões de lista para escrever código verdadeiramente incompreensível.
 Já vi código Python usando listcomps apenas para repetir um bloco de código por seus efeitos colaterais.
 Se você não vai fazer alguma coisa com a lista criada, não deveria usar essa sintaxe.
-Além disso, tente manter o código curto. Se uma compreensão ocupa mais de duas linhas,
+Além disso, tente manter o código curto.
+Se uma compreensão ocupa mais de duas linhas,
 provavelmente seria melhor quebrá-la ou reescrevê-la como um bom e velho loop `for`.
 Avalie qual o melhor caminho: em Python, como em português, não existem regras absolutas para se escrever bem.
 
@@ -550,7 +553,8 @@ Agora vamos considerar o uso da classe `tuple` como uma variante imutável da cl
 O((("tuples", "as immutable lists", secondary-sortas="immutable lists", id="Timlist02")))((("lists", "using tuples as immutable",
 id="Ltupple02")))
 interpretador Python e a biblioteca padrão fazem uso extensivo das tuplas como listas imutáveis,
-e você deve seguir o exemplo. Isso traz dois benefícios importantes:
+e você deve seguir o exemplo.
+Isso traz dois benefícios importantes:
 
 Clareza:: Quando você vê uma `tuple` no código, sabe que seu tamanho nunca mudará.
 Desempenho:: Uma `tuple` usa menos memória que uma `list` de mesmo tamanho, e permite ao Python realizar algumas otimizações.
@@ -611,7 +615,8 @@ Apesar dessa ressalva, as tuplas são frequentemente usadas como listas imutáve
 Elas oferecem algumas vantagens de desempenho, explicadas por uma dos desenvolvedores principais de Python,
 Raymond Hettinger, em uma resposta à questão
 https://fpy.li/2-3["Are tuples more efficient than lists in Python?" (_As tuplas são mais eficientes que as listas no Python?_)]
-no StackOverflow. Em resumo, Hettinger escreveu:
+no StackOverflow.
+Em resumo, Hettinger escreveu:
 
 * Para avaliar uma tupla literal, o compilador Python gera bytecode para uma constante tupla em uma operação;
 mas para um literal lista, o bytecode gerado insere cada elemento como uma constante separada na pilha,
@@ -881,12 +886,13 @@ https://fpy.li/2r["Casamento de padrão estrutural"]footnote:[NT: A tradução e
 Python adotou o termo "casamento de padrões" no lugar de _pattern matching_.
 O termo em inglês é usado nas comunidades brasileiras
 de linguagens que implementam _pattern matching_ há muitos anos, como por exemplo Scala,
-Elixir e Haskell. Naturalmente mantivemos os títulos originais nos links externos.]
+Elixir e Haskell.
+Naturalmente mantivemos os títulos originais nos links externos.]
 em https://fpy.li/2s["O que há de novo no Python 3.10"].
 Você pode querer ler aquela revisão rápida.
 Neste livro, dividi o tratamento do casamento de padrões em diferentes capítulos,
 dependendo dos tipos de padrão:
-Na <<pattern_matching_mappings_sec>> e na <<pattern_instances_sec>>.
+na <<pattern_matching_mappings_sec>> e na <<pattern_instances_sec>>.
 E há um exemplo mais longo na <<pattern_matching_case_study_sec>>.
 ====
 
@@ -918,13 +924,15 @@ Então, você poderia usar um método assim para interpretar mensagens naquele f
 ====
 <1> A expressão após a palavra-chave `match` é o sujeito (_subject_).
 O sujeito contém os dados que Python vai comparar aos padrões em cada instrução `case`.
-<2> Esse padrão casa com qualquer sujeito que seja uma sequência de três itens. O primeiro item deve ser a string `BEEPER`.
+<2> Esse padrão casa com qualquer sujeito que seja uma sequência de três itens.
+O primeiro item deve ser a string `BEEPER`.
 O segundo e o terceiro itens podem ser qualquer coisa, e serão vinculados às variáveis `frequency` e `times`, nessa ordem.
 <3> Isso casa com qualquer sujeito com dois itens, se o primeiro for `'NECK'`.
 <4> Isso vai casar com uma sujeito de três itens começando com `LED`.
 Se o número de itens não for correspondente, Python segue para o próximo `case`.
 <5> Outro padrão de sequência começando com `'LED'`, agora com cinco itens—incluindo a constante `'LED'`.
-<6> Esse é o `case` default. Vai casar com qualquer sujeito que não tenha sido capturado por um dos padrões precedentes.
+<6> Esse é o `case` default.
+Vai casar com qualquer sujeito que não tenha sido capturado por um dos padrões precedentes.
 A variável `_` é especial, como logo veremos.
 
 Olhando((("pattern matching", "destructuring"))) superficialmente,
@@ -979,7 +987,7 @@ Um sujeito de `match` de um desses tipos é tratado como um valor "atômico"—a
 e não como uma sequência de dígitos.
 Tratar aqueles três tipos como sequências poderia causar bugs devido a casamentos não intencionais.
 Se você quer usar um objeto daqueles tipos como um sujeito sequência, converta-o na instrução `match`.
-Por exemplo, veja `tuple(phone)` no trecho abaixo, 
+Por exemplo, veja `tuple(phone)` no trecho abaixo,
 que poderia ser usado para separar números de telefone por regiões do mundo com base no prefixo DDI:
 
 [source, py]
@@ -1003,10 +1011,12 @@ list     memoryview    array.array
 tuple    range         collections.deque
 ----
 
-Ao contrário do desempacotamento, padrões não desestruturam iteráveis que não sejam sequências (tal como os iteradores).
+Ao contrário do desempacotamento,
+padrões não desestruturam iteráveis que não sejam sequências (tal como os iteradores).
 
 O((("pattern matching", "&#x005F; symbol")))((("&#x005F; symbol"))) símbolo `+_+` é especial nos padrões:
-ele casa com qualquer item naquela posição, mas nunca é vinculado ao valor daquele item. O valor é descartado.
+ele casa com qualquer item naquela posição, mas nunca é vinculado ao valor daquele item.
+O valor é descartado.
 Além disso, o `+_+` é a única variável que pode aparecer mais de uma vez em um padrão.
 
 Você pode vincular qualquer parte de um padrão a uma variável usando
@@ -1095,18 +1105,24 @@ O próximo exemplo mostra como o _pattern matching_ contribui para a criação d
 [[pattern_matching_seq_interp_sec]]
 ==== Casando padrões de sequência em um interpretador
 
-Peter Norvig((("lis.py interpreter", "pattern matching in", id="lispypattern02")))((("pattern matching", "in lis.py interpreter",
+Peter Norvig((("lis.py interpreter", "pattern matching in", id="lispypattern02")))((("pattern matching",
+"in lis.py interpreter",
 secondary-sortas="lis.py", id="PMinterp02")))((("Scheme language", id="scheme02"))),
 da Universidade de Stanford, escreveu o
 https://fpy.li/2-11[_lis.py_]:
-um interpretador de um subconjunto do dialeto Scheme da linguagem de programação Lisp, em 132 belas linhas de código Python legível.
-Peguei o código fonte de Norvig (publicado sob a licença MIT) e o atualizei para Python 3.10, para exemplificar o _pattern matching_.
-Nessa seção, vamos comparar uma parte fundamental do código de Norvig—que usa `if/elif` e desempacotamento—com uma nova versão usando `match/case`.
-
-As duas funções principais do _lis.py_ são `parse` e `evaluate`.footnote:[A última é chamada `eval` no código original;
-a renomeei para evitar que fosse confundida com a função embutida `eval` de Python.]
+um interpretador de um subconjunto do dialeto Scheme da linguagem de programação Lisp,
+em 132 belas linhas de código Python legível.
+Peguei o código fonte de Norvig (publicado sob a licença MIT) e o atualizei para Python 3.10,
+para exemplificar o _pattern matching_.
+Nessa seção, vamos comparar uma parte fundamental do código de Norvig—que usa `if/elif` e
+desempacotamento—com uma nova versão usando `match/case`.
+
+As duas funções principais do _lis.py_ são `parse` e `evaluate`.footnote:[A última é
+chamada `eval` no código original;
+a renomeei para evitar confusão com a função embutida `eval` de Python.]
 O parser (_analisador sintático_) recebe as expressões entre parênteses do Scheme
-e devolve listas Python. Aqui estão dois exemplos:
+e devolve listas Python.
+Aqui estão dois exemplos:
 
 [source, python]
 ----
@@ -1251,7 +1267,8 @@ Acrescentar essas duas linhas ao `match` cuida da implementação:
 ----
 
 Eu colocaria esse `case` após o `case` da outra forma de `define` no  <<ex_match_eval>>.
-A ordem desses _cases_ de `define` é irrelevante nesse exemplo, pois nenhum sujeito pode casar com esses dois padrões:
+A ordem desses _cases_ de `define` é irrelevante nesse exemplo,
+pois nenhum sujeito pode casar com esses dois padrões:
 o segundo elemento deve ser um `Symbol` na forma original de `define`,
 mas deve ser uma sequência começando com um `Symbol` no atalho de `define` para definição de função.
 
@@ -1662,12 +1679,14 @@ Aqui está uma demonstração de `+*=+` com uma sequência mutável e depois com
 A concatenação repetida de sequências imutáveis é ineficiente, pois ao invés de apenas acrescentar novos itens,
 o interpretador tem que copiar toda a sequência alvo para criar um novo objeto com os novos itens
 concatenados.footnote:[`str` é uma exceção a essa descrição.
-Como criar strings com `+=` em loops é tão comum em bases de código reais, o CPython foi otimizado para esse caso de uso.
+Como criar strings com `+=` em loops é tão comum em bases de código reais,
+o CPython foi otimizado para esse caso de uso.
 Instâncias de `str` são alocadas na memória com espaço extra,
 então a concatenação não exige a cópia da string inteira a cada operação.]
 
 Vimos casos de uso comuns para `+=`.
-A próxima seção mostra um caso lateral intrigante, que realça o real significado de "imutável" no contexto das tuplas.
+A próxima seção mostra um caso lateral intrigante,
+que realça o real significado de "imutável" no contexto das tuplas.
 
 [[tuple_puzzler]]
 ==== Um quebra-cabeça com a atribuição +=
@@ -1726,7 +1745,8 @@ mostrando os estados inicial e final da tupla `t` do <<ex_aug_item_assign_soluti
 .Estados inicial e final do enigma da atribuição de tuplas (diagrama gerado pelo Online Python Tutor).
 image::images/flpy_0205.png[Diagrama de referência]
 
-Se olharmos o bytecode gerado pelo Python para a expressão `s[a] += b` (<<ex_aug_item_assign_bytecode>>), fica claro como isso acontece.
+Se olharmos o bytecode gerado pelo Python para a expressão `s[a] += b` (<<ex_aug_item_assign_bytecode>>),
+fica claro como isso acontece.
 
 [[ex_aug_item_assign_bytecode]]
 .Bytecode para a expressão `s[a] += b`
@@ -1825,7 +1845,8 @@ Aqui estão alguns exemplos para esclarecer o uso dessas funções e dos argumen
 Os exemplos também demonstram que o algoritmo de ordenação de Python é estável
 (isto é, ele preserva a ordem relativa de itens que resultam iguais na comparação):footnote:[O
 principal algoritmo de ordenação de Python se chama Timsort, em homenagem a seu criador,
-Tim Peters. Para curiosidades sobre o Timsort, veja o <<sequences_soapbox>>.]
+Tim Peters.
+Para curiosidades sobre o Timsort, veja o <<sequences_soapbox>>.]
 
 
 [source, pycon]
@@ -1849,7 +1870,8 @@ Tim Peters. Para curiosidades sobre o Timsort, veja o <<sequences_soapbox>>.]
 ----
 <1> Isso produz uma lista de strings ordenadas
 alfabeticamente.footnote:[As palavras nesse exemplo estão ordenadas em ordem alfabética
-porque são 100% constituídas de caracteres ASCII em letras minúsculas. Veja o aviso após o exemplo.]
+porque são 100% constituídas de caracteres ASCII em letras minúsculas.
+Veja o aviso após o exemplo.]
 <2> Inspecionando a lista original, vemos que ela não mudou.
 <3> Isso é a ordenação "alfabética" anterior, invertida.
 <4> Uma nova lista de strings, agora ordenada por tamanho.
@@ -1893,7 +1915,7 @@ Por outro lado, se você está constantemente acrescentando e removendo itens da
 é bom saber que um((("queues", "deque (double-ended queue)")))((("deque (double-ended queue)")))((("FIFO (first in, first out)")))
 `deque` (uma fila com duas pontas) é uma estrutura  de dados
 FIFOfootnote:[Sigla em inglês para "First in, first out"
-(_Primeiro a entrar, primeiro a sair_—o comportamento padrão de filas.] mais eficiente.
+(primeiro a entrar, primeiro a sair), o comportamento padrão de filas.] mais eficiente.
 
 [TIP]
 ====
@@ -1904,7 +1926,8 @@ Eles também são iteráveis, mas não são coleções, porque a ordenação de
 Vamos falar deles no <<ch_dicts_sets>>.
 ====
 
-O restante desse capítulo discute tipos mutáveis de sequências que, em muitos casos, podem substituir as listas. Começamos pelos arrays.
+O restante desse capítulo discute tipos mutáveis de sequências que, em muitos casos, podem substituir as listas.
+Começamos pelos arrays.
 
 [[arrays_sec]]
 ==== Arrays
@@ -1916,7 +1939,7 @@ bem como métodos adicionais para carregamento e armazenamento rápidos, tais co
 
 Um array de Python quase tão enxuto quanto um array do C.
 Como mostrado na <<container_v_flat_img>>, um `array` de valores `float` não contém instâncias completas de `float`,
-mas apenas os bytes representando seus valores em código de máquina—de forma similar a um array de `double` na linguagem C.
+mas apenas os bytes representando seus valores em código de máquina—como um array de `double` na linguagem C.
 Ao criar um `array`, você fornece um código de tipo (_typecode_),
 uma letra que determina o tipo C subjacente usado para armazenar cada item no array.
 Por exemplo, +b+ é o código de tipo para o que o C chama de `signed char`, um inteiro variando de -128 a 127.
@@ -2035,7 +2058,8 @@ Para manter a ordem de um array ordenado ao acrescentar novos itens, use a funç
 ====
 
 Se você trabalha muito com arrays e não conhece `memoryview`,
-está perdendo oportunidades. Veja o próximo tópico.((("", startref="array02")))
+está perdendo oportunidades.
+Veja o próximo tópico.((("", startref="array02")))
 
 
 [[memoryview_sec]]
@@ -2458,7 +2482,9 @@ e mencionamos as outras implementações de filas na biblioteca padrão.
 O((("sequences", "further reading on"))) capítulo 1, "Data Structures" (_Estruturas de Dados_)
 do https://fpy.li/pycook3[Python Cookbook</em>, 3rd ed.]
 (EN) (O'Reilly), de David Beazley e Brian K. Jones, traz muitas receitas usando sequências,
-incluindo a "Recipe 1.11. Naming a Slice" (_Receita 1.11. Nomeando uma Fatia_),
+incluindo a "Recipe 1.11.
+Naming a Slice" (_Receita 1.11.
+Nomeando uma Fatia_),
 onde aprendi o truque de atribuir fatias a variáveis para melhorar a legibilidade,
 como ilustrado no nosso <<flat_file_invoce>>.
 
@@ -2491,9 +2517,10 @@ https://fpy.li/2r["Casamento de padrão estrutural"],
 de Carol Willing, no
 https://fpy.li/2s["O que há de novo no Python 3.10"],
 é uma ótima introdução a esse novo grande recurso, em mais ou menos 1.400 palavras
-(isso é menos de 5 páginas quando o Firefox converte o HTML em PDF).
-A https://fpy.li/pep636[PEP 636—Structural Pattern Matching: Tutorial (_Casamento de Padrões Estrutural: Tutorial_)]
-(EN) também é boa, mas mais longa. A mesma PEP 636 inclui o
+(isso é menos de 5 páginas quando o Firefox converte o HTML em PDF). A
+https://fpy.li/pep636[PEP 636—Structural Pattern Matching: Tutorial (_Casamento de Padrões Estrutural: Tutorial_)]
+(EN) também é boa, mas mais longa.
+A mesma PEP 636 inclui o
 https://fpy.li/2-27["Appendix A—Quick Intro" (_Apêndice A-Introdução Rápida_)] (EN).
 Ele é menor que a introdução de Willing, porque omite as considerações gerais sobre os motivos pelos quais o
 casamento de padrões é útil.