xref wip

Author: ramalho

calango/pyproject.toml

@@ -13,7 +13,7 @@ dependencies = [
 
 [project.scripts]
 calango = "calango:main"
-farxrefs = "calango:xrefs"
+hello = "calango:hello"
 
 [build-system]
 requires = ["hatchling"]

calango/src/calango/__init__.py

@@ -1,2 +1,4 @@
 def main() -> None:
     print("Hello from calango!")
+
+

calango/src/calango/xrefs.py

@@ -1,7 +1,8 @@
-import xml.etree.ElementTree as ET
+import subprocess
 from enum import Enum, auto
 from dataclasses import dataclass
 from bs4 import BeautifulSoup
+from pathlib import Path
 
 
 class Kind(Enum):
@@ -86,3 +87,36 @@ def validate(xref):
 
 CHAPTER_NUMBER = {i:n for (n, i) in CHAPTER_ID.items()}
 
+
+def find_git_root():
+    path = Path(__file__).resolve()
+    while path != path.parent:
+        if (path / '.git').is_dir():
+            return path
+        path = path.parent
+    raise LookupError(f'no .git dir found in {path} or parents')
+
+
+INVALID_MSG = 'asciidoctor: INFO: possible invalid reference: '
+
+def list_invalid_xrefs() -> list[str]:
+    adoc = find_git_root() / 'vol1/vol1.adoc'
+    cmd = f'''asciidoctor -v {adoc} -o lixo'''
+    print(cmd)
+    result = subprocess.run(cmd, shell=True, stderr=subprocess.PIPE, text=True)
+    seen = set()
+    xrefs = []
+    for line in result.stderr.splitlines():
+        assert line.startswith(INVALID_MSG), '? msg: ' + line
+        xref = line[len(INVALID_MSG):].strip()
+        if xref not in seen:
+            xrefs.append(xref)
+            seen.add(xref)
+            if xref.endswith('_ex'):
+                print(xref)
+
+    return xrefs
+
+
+if __name__ == '__main__':
+    list_invalid_xrefs()

online/cap03.adoc

@@ -822,7 +822,7 @@ import builtins
 pylookup = ChainMap(locals(), globals(), vars(builtins))
 ----
 
-O <<environment_class_ex>> mostra uma subclasse de `ChainMap` usada para implementar
+A <<lispy_environ_sec>> explica uma subclasse de `ChainMap` usada para implementar
 um interpretador parcial da linguagem de programação Scheme.
 
 

online/cap08.adoc

@@ -83,7 +83,7 @@ def tokenize(s: str) -> list[str]:
 
 A assinatura informa que a função `tokenize` recebe uma `str`
 e devolve `list[str]`: uma lista de strings.
-A utilidade dessa função será explicada no <<lis_parser_ex>>.
+A utilidade dessa função será explicada na <<lispy_parser_sec>>.
 
 Um sistema de tipagem gradual:
 
@@ -2101,8 +2101,10 @@ Arquivos stub não contém valores default, em vez disso eles usam `\...`.
 O tipo de `__status` é `object`, o que significa que pode também ser `None`,
 assim seria redundante escrever `Optional[object]`.
 
-Na <<ch_class_metaprog>>,
-o <<checked_class_bottom_ex>> usa `NoReturn` em `__flag_unknown_attrs`, um método projetado para produzir uma mensagem de erro completa e amigável, e então levanta um `AttributeError`.
+Na <<enhancing_with_init_subclass_sec>>,
+o método `__flag_unknown_attrs` tem o tipo de retorno `NoReturn`,
+pois sua função é produzir uma mensagem de erro detalhada e amigável,
+e então levantar `AttributeError`.
 
 A última seção desse capítulo épico é sobre parâmetros posicionais e variádicos
 ((("", startref="THTusable08")))((("", startref="FTHusable08")))

online/cap18.adoc

@@ -446,6 +446,7 @@ não há um tipo de dados string, com operações como fatiamento (_slicing_), d
 
 `Expression`:: Os componentes básicos de programas Scheme são expressões feitas de átomos e listas, possivelmente aninhados.
 
+[[lispy_parser_sec]]
 ==== O parser
 
 O parser (_analisador sintático_)((("lis.py interpreter", "parser", id="lispyparser18"))) de Norvig tem 36 linhas de código que
@@ -495,6 +496,7 @@ uma representação conveniente de um programa Scheme como listas aninhadas form
 .Uma expressão `lambda` de Scheme, representada como código-fonte (sintaxe concreta de expressões-S), como uma árvore, e como uma sequência de objetos Python (sintaxe abstrata).
 image::../images/flpy_1801.png["Código Scheme, im diagram de árvore e objetos Python"]
 
+[[lispy_environ_sec]]
 ==== O ambiente
 
 A((("lis.py interpreter", "Environment class", id="lispyenv18"))) classe `Environment` estende `collections.ChainMap`, acrescentando o método `change`, para atualizar um valor dentro de um dos dicts encadeados que as instâncias de `ChainMap` mantém em uma lista de mapeamentos: o atributo `self.maps`.

online/cap24.adoc

@@ -230,7 +230,7 @@ Instâncias de classes criadas por `record_factory` não são serializáveis--is
 Vamos ver agora como emular fábricas de classes mais modernas, como `typing.NamedTuple`, que recebe uma classe definida pelo usuário, escrita com o comando `class`, e a melhora automaticamente, acrescentando funcionalidade.((("", startref="CMfacfun24")))
 
 
-[[enhancing_with_init_subclass]]
+[[enhancing_with_init_subclass_sec]]
 === Apresentando pass:[__init_subclass__]
 
 Tanto((("class metaprogramming", "__init_subclass__", id="CMinitsub24", secondary-sortas="init")))((("__init_subclass__", id="initsub24"))) `+__init_subclass__+` quanto `+__set_name__+` foram propostos na

print/xrefs/formatos.adoc

@@ -85,34 +85,9 @@ Ex. do cap03, l.825
 O <<environment_class_ex>> mostra uma subclasse
 ----
 
-[source, html]
-----
-<div id="environment_class_ex" class="exampleblock">
-<div class="title">Exemplo 349. <em>lis.py</em>: a classe <code>Environment</code></div>
-<div class="content">
-<div class="listingblock">
-<div class="content">
-<pre class="highlight"><code class="language-py" data-lang="py">class Environment(ChainMap[Symbol, Any]):
-    "A ChainMap that allows changing an item in-place."
-
-    def change(self, key: Symbol, value: Any) -&gt; None:
-        "Find where key is defined and change the value there."
-        for map in self.maps:
-            if key in map:
-                map[key] = value  # type: ignore[index]
-                return
-        raise KeyError(key)</code></pre>
-</div>
-</div>
-</div>
-</div>
-----
-
-Saída:
-
-O Exemplo 349 [cap.18, vol.2, fpy.li/xyz].
-
-Onde fpy.li/xyz direciona para:
+Decisão: no volume 1 havia só 3 referências para exemplos em outros volumes,
+a solução é complexa, e a numeração de exemplos não inclui o número capítulo,
+então editei tais ocorrências para apontar para a seção que
+contém o exemplo.
 
-https://pythonfluente.com/2/#environment_class_ex
 

vol1/cap03.adoc

@@ -822,7 +822,7 @@ import builtins
 pylookup = ChainMap(locals(), globals(), vars(builtins))
 ----
 
-O <<environment_class_ex>> mostra uma subclasse de `ChainMap` usada para implementar
+A <<lispy_environ_sec>> explica uma subclasse de `ChainMap` usada para implementar
 um interpretador parcial da linguagem de programação Scheme.
 
 

vol1/cap08.adoc

@@ -83,7 +83,7 @@ def tokenize(s: str) -> list[str]:
 
 A assinatura informa que a função `tokenize` recebe uma `str`
 e devolve `list[str]`: uma lista de strings.
-A utilidade dessa função será explicada no <<lis_parser_ex>>.
+A utilidade dessa função será explicada no <<lispy_parser_sec>>.
 
 Um sistema de tipagem gradual:
 
@@ -2101,8 +2101,10 @@ Arquivos stub não contém valores default, em vez disso eles usam `\...`.
 O tipo de `__status` é `object`, o que significa que pode também ser `None`,
 assim seria redundante escrever `Optional[object]`.
 
-Na <<ch_class_metaprog>>,
-o <<checked_class_bottom_ex>> usa `NoReturn` em `__flag_unknown_attrs`, um método projetado para produzir uma mensagem de erro completa e amigável, e então levanta um `AttributeError`.
+Na <<enhancing_with_init_subclass_sec>>,
+o método `__flag_unknown_attrs` tem o tipo de retorno `NoReturn`,
+pois sua função é produzir uma mensagem de erro detalhada e amigável,
+e então levantar `AttributeError`.
 
 A última seção desse capítulo épico é sobre parâmetros posicionais e variádicos
 ((("", startref="THTusable08")))((("", startref="FTHusable08")))