tiss-hash 0.1.0__tar.gz

tiss_hash-0.1.0/.gitignore

@@ -0,0 +1,177 @@
+# =============================================================================
+# .gitignore — TISS_ANS_hash
+# =============================================================================
+# Regra crítica de segurança: NUNCA commitar XML real com PII de pacientes.
+# Padrão `real_*` bloqueado em qualquer lugar do repo.
+# Vetores sintéticos vivem em conformance/inputs/syn_*.xml (permitidos).
+# =============================================================================
+
+# ----- LGPD: bloqueio de dados reais de pacientes -----
+**/real_envio*.xml
+**/real_*.xml
+_private_*/
+.private/
+*.pii.xml
+
+# ----- Python -----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Excecao: o port Dart usa `lib/` como diretorio de CODIGO-FONTE (convencao
+# pub.dev), nao como artefato de build Python. Re-inclui essa subarvore (a
+# regra `lib/` acima vem do template Python e a excluiria por engano).
+!langs/dart/lib/
+!langs/dart/lib/**
+
+# Virtualenvs
+.venv/
+venv/
+env/
+ENV/
+.python-version
+
+# pytest / coverage / mypy / ruff
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.cache
+.mypy_cache/
+.ruff_cache/
+.pyre/
+.pytype/
+
+# tox / hatch
+.hatch/
+
+# ----- Node.js -----
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-store/
+.npm/
+package-lock.json.bak
+
+# ----- Rust -----
+target/
+Cargo.lock
+**/*.rs.bk
+
+# ----- C / C++ -----
+*.o
+*.obj
+*.a
+*.lib
+*.so
+*.so.*
+*.dylib
+*.dll
+*.exe
+*.out
+*.app
+*.gcda
+*.gcno
+*.gcov
+build/
+build_*/
+cmake-build-*/
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+Makefile.local
+
+# ----- PHP -----
+vendor/
+composer.lock
+composer.phar
+.phpunit.result.cache
+
+# ----- Java / Kotlin -----
+*.class
+*.jar
+*.war
+*.ear
+*.nar
+target/
+.gradle/
+build/
+.kotlin/
+.idea/
+*.iml
+
+# ----- C# / .NET -----
+bin/
+obj/
+*.user
+*.suo
+*.userprefs
+.vs/
+[Dd]ebug/
+[Rr]elease/
+
+# ----- Go -----
+*.test
+*.prof
+go.sum.bak
+
+# ----- WASM -----
+*.wasm
+pkg/
+
+# ----- IDE / Editor -----
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+.vim/
+.helix/
+.zed/
+
+# ----- Logs / temp -----
+*.log
+*.tmp
+*.bak
+*.orig
+*.rej
+
+# ----- OS -----
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+desktop.ini
+
+# ----- Claude Code (manter settings.local fora) -----
+.claude/settings.local.json
+.claude/.cache/
+
+# clang-tidy compile_commands scratch dirs (W4)
+**/build_tidy/

tiss_hash-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Petrus Silva Costa <petrinhu@yahoo.com.br>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tiss_hash-0.1.0/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: tiss-hash
+Version: 0.1.0
+Summary: Hash MD5 do epílogo TISS/ANS (Padrão TISS) — implementação portável zero-dep.
+Project-URL: Homepage, https://github.com/petrinhu/TISS_ANS_hash
+Project-URL: Repository, https://github.com/petrinhu/TISS_ANS_hash
+Project-URL: Mirror (Codeberg), https://codeberg.org/petrinhu/TISS_ANS_hash
+Project-URL: Issues, https://github.com/petrinhu/TISS_ANS_hash/issues
+Project-URL: Changelog, https://github.com/petrinhu/TISS_ANS_hash/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/petrinhu/TISS_ANS_hash/blob/main/docs/USAGE.md
+Author-email: Petrus <petrinhu@yahoo.com.br>
+License: MIT License
+        
+        Copyright (c) 2026 Petrus Silva Costa <petrinhu@yahoo.com.br>
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ans,brasil,epilogo,hash,healthcare,md5,padrao-tiss,saude-suplementar,tiss,xml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Portuguese (Brazilian)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: defusedxml>=0.7.1
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Provides-Extra: lxml
+Requires-Dist: lxml>=4.9; extra == 'lxml'
+Description-Content-Type: text/markdown
+
+# tiss-hash (Python)
+
+Calcula o "hash" do trecho final de um documento TISS/ANS. Vamos por partes,
+sem pressa:
+
+- **XML** é um formato de arquivo de texto que organiza dados em etiquetas
+  (tags) aninhadas, parecido com as caixas dentro de caixas de uma pasta de
+  arquivos. O Padrão TISS é o formato XML que as operadoras de saúde e os
+  consultórios usam para trocar informações de atendimento no Brasil.
+- **Hash** é uma "impressão digital" do conteúdo: uma sequência curta e fixa
+  de caracteres calculada a partir de um texto. Se uma única letra do texto
+  mudar, o hash muda completamente. Serve para conferir que dois lados estão
+  falando do mesmo documento.
+- **MD5** é uma das receitas (algoritmos) que produzem esse hash. Ele sempre
+  devolve 32 caracteres hexadecimais (os dígitos `0-9` e as letras `a-f`).
+- **Epílogo** é a parte final do documento TISS: a etiqueta `<ans:hash>`, onde
+  esse hash precisa ser gravado.
+
+Em uma frase: você entrega os bytes de um XML TISS, esta biblioteca devolve os
+32 caracteres do hash que vão dentro de `<ans:hash>`. (Um **byte** é a menor
+unidade de dado que o computador manipula; um arquivo de texto é uma fila de
+bytes.)
+
+Este é o port Python da biblioteca `lib_hash_ans`. ("Port" = a mesma
+biblioteca reescrita em outra linguagem de programação.) Outras linguagens
+(C, C++, Rust, PHP, Node.js, etc.) seguem o mesmo contrato e os mesmos
+vetores de conformidade. Para entender o problema que esta lib resolve, leia
+[`docs/USAGE.md`](../../docs/USAGE.md) (guia de uso) e
+[`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) (conceitos e visão geral).
+
+## Antes de começar: instalar o Python
+
+Python é a linguagem de programação usada neste port. Se você nunca instalou:
+
+- Baixe e instale pelo site oficial: <https://www.python.org/downloads/>
+  (precisa da versão 3.10 ou mais nova). No Windows, marque a caixa
+  "Add Python to PATH" durante a instalação.
+- No Linux/macOS, o Python costuma já vir instalado. Confira com:
+
+```bash
+python3 --version
+```
+
+Se aparecer algo como `Python 3.12.x`, está pronto. O comando `pip` (gerenciador
+que baixa bibliotecas Python) vem junto com o Python.
+
+## Quickstart
+
+Uma **dependência** é uma biblioteca de terceiros que o seu código usa. O `pip`
+baixa e instala dependências para você.
+
+> Instalação via PyPI (o repositório oficial de pacotes Python) ainda não
+> publicada. Por enquanto, instale a partir do checkout do repositório (isto é,
+> da pasta que você baixou com `git clone`):
+
+```bash
+pip install ./langs/python
+```
+
+Quando publicada, bastará:
+
+```bash
+pip install tiss-hash
+```
+
+Uso:
+
+```python
+from tiss_hash import hash_tiss, hash_tiss_file
+
+# A partir de bytes
+with open("lote_tiss_exemplo.xml", "rb") as fh:
+    digest = hash_tiss(fh.read())
+print(digest)  # hex MD5 de 32 chars, ex.: '3aa0c578c95cdb861a125f480a8a4de5'
+
+# A partir de um caminho de arquivo
+digest = hash_tiss_file("lote_tiss_exemplo.xml")
+```
+
+Tratamento de erro:
+
+```python
+from tiss_hash import InvalidTissXml, hash_tiss
+
+try:
+    hash_tiss(b"<nao-eh-xml")
+except InvalidTissXml as exc:
+    print(f"falhou ao parsear: {exc}")
+```
+
+## API
+
+| Símbolo | Tipo | Descrição |
+| --- | --- | --- |
+| `hash_tiss(xml: bytes) -> str` | função | Hash MD5 (hex, 32 chars) a partir dos bytes do XML. |
+| `hash_tiss_file(path: str \| os.PathLike) -> str` | função | Atalho que lê o arquivo e delega para `hash_tiss`. |
+| `InvalidTissXml` | classe | Exceção (subclasse de `ValueError`) para XML malformado ou rejeitado por política de segurança. |
+| `__version__` | str | Versão do pacote. |
+
+## Algoritmo
+
+Resumo do que `hash_tiss` faz, em prosa. ("Parsear" um XML é ler o texto e
+montar a árvore de etiquetas na memória; o **parser** é o componente que faz
+essa leitura. **Encoding** é a tabela que traduz caracteres em bytes, por
+exemplo UTF-8. **Namespace** é um prefixo que evita confusão entre etiquetas de
+origens diferentes; aqui o namespace TISS identifica a etiqueta `<ans:hash>`.)
+
+1. Parseia o XML (com `defusedxml`, isto é, sem expansão de entidades e
+   sem DOCTYPE externo).
+2. Zera o conteúdo de `<ans:hash>` (namespace
+   `http://www.ans.gov.br/padroes/tiss/schemas`).
+3. Concatena o `.text` de cada elemento-folha (sem filhos) em ordem
+   documental.
+4. Calcula MD5 sobre os bytes **UTF-8** da string resultante.
+5. Devolve o `hexdigest()` minúsculo (32 caracteres).
+
+Atenção: o encoding dos bytes alimentados ao MD5 é **UTF-8**, não
+ISO-8859-1. O manual TISS afirma o contrário, mas o valor que bate com os
+goldens reais é UTF-8.
+
+Especificação canônica completa: `docs/SPEC.md` (na raiz do repositório).
+Implementação de referência: `conformance/reference.py`.
+
+## Conformidade
+
+"Conformidade" aqui significa: provar que este port produz exatamente o mesmo
+hash que a implementação oficial, em todos os casos previstos. Um **vetor de
+conformidade** é um par "arquivo de entrada -> hash esperado": rodamos a lib no
+arquivo e conferimos se o resultado bate. Um vetor **positivo** deve produzir
+um hash; um vetor **negativo** deve ser rejeitado (a lib precisa recusar o
+arquivo, em vez de inventar um hash).
+
+Esta lib passa os **20 vetores de conformidade** em
+`conformance/vectors.json`, todos sintéticos (`source: derived`): 18
+positivos e 2 negativos (que devem ser rejeitados). O conjunto público de
+conformidade é 100% sintético, sem qualquer XML real de paciente. Os 18
+positivos cobrem: mínimo, acentuação, campos vazios, CR/LF embutido,
+múltiplas guias, entidades XML, entidades numéricas, CDATA, comentário,
+atributo de folha, namespace alternativo, namespace default, documento sem
+`<ans:hash>`, whitespace puro, zeros à esquerda, símbolos ISO-8859-1,
+performance e BOM UTF-8. Os 2 negativos (`syn_multi_hash.xml` e
+`syn_utf16.xml`) cobrem rejeição de múltiplos `<ans:hash>` e de UTF-16
+(fora de escopo: encodings suportados são ISO-8859-1 e UTF-8). A lista
+canônica vive em `conformance/vectors.json`.
+
+Rodar os testes localmente, a partir da raiz do repositório:
+
+```bash
+python -m pip install -e ./langs/python[dev]
+pytest langs/python/tests/ -v
+```
+
+Saída esperada: `24 passed`. Desses, 20 testes são os vetores de
+conformidade (um por vetor, parametrizados: 18 positivos comparam o hash,
+2 negativos verificam a rejeição) e 4 são testes de API auxiliares
+(`hash_tiss_file`, XML inválido, tipo de entrada errado e integridade do
+manifesto).
+
+## Dependências
+
+- Runtime: `defusedxml>=0.7.1` (pure-Python, sem deps próprias). Usado
+  no lugar de `xml.etree.ElementTree.parse` da stdlib para mitigar XXE
+  e billion-laughs em XMLs vindos de terceiros.
+- Extra `lxml`: opcional, reservado para uma implementação alternativa
+  mais performática no futuro.
+- Extra `dev`: `pytest`, `pytest-cov`.
+
+## Licença
+
+[MIT](https://github.com/petrinhu/TISS_ANS_hash/blob/main/LICENSE)
+Copyright (c) 2026 Petrus Silva Costa. Licença única do projeto, na raiz
+do repositório.
+
+## Ver também
+
+- Repositório (origin): https://github.com/petrinhu/TISS_ANS_hash
+- Mirror: https://codeberg.org/petrinhu/TISS_ANS_hash
+- [`docs/USAGE.md`](../../docs/USAGE.md): guia de uso, receitas e perguntas
+  frequentes (comece por aqui se você quer só usar a lib).
+- [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md): conceitos e visão geral
+  de como tudo se encaixa.
+- [`docs/SPEC.md`](../../docs/SPEC.md): especificação canônica do algoritmo
+  (a referência precisa, palavra por palavra).
+- [`docs/PORTING_GUIDE.md`](../../docs/PORTING_GUIDE.md): guia para portar para
+  outras linguagens.
+- [`conformance/reference.py`](../../conformance/reference.py): implementação de
+  referência (o "oráculo", isto é, a versão que define a resposta certa).

tiss_hash-0.1.0/README.md

@@ -0,0 +1,187 @@
+# tiss-hash (Python)
+
+Calcula o "hash" do trecho final de um documento TISS/ANS. Vamos por partes,
+sem pressa:
+
+- **XML** é um formato de arquivo de texto que organiza dados em etiquetas
+  (tags) aninhadas, parecido com as caixas dentro de caixas de uma pasta de
+  arquivos. O Padrão TISS é o formato XML que as operadoras de saúde e os
+  consultórios usam para trocar informações de atendimento no Brasil.
+- **Hash** é uma "impressão digital" do conteúdo: uma sequência curta e fixa
+  de caracteres calculada a partir de um texto. Se uma única letra do texto
+  mudar, o hash muda completamente. Serve para conferir que dois lados estão
+  falando do mesmo documento.
+- **MD5** é uma das receitas (algoritmos) que produzem esse hash. Ele sempre
+  devolve 32 caracteres hexadecimais (os dígitos `0-9` e as letras `a-f`).
+- **Epílogo** é a parte final do documento TISS: a etiqueta `<ans:hash>`, onde
+  esse hash precisa ser gravado.
+
+Em uma frase: você entrega os bytes de um XML TISS, esta biblioteca devolve os
+32 caracteres do hash que vão dentro de `<ans:hash>`. (Um **byte** é a menor
+unidade de dado que o computador manipula; um arquivo de texto é uma fila de
+bytes.)
+
+Este é o port Python da biblioteca `lib_hash_ans`. ("Port" = a mesma
+biblioteca reescrita em outra linguagem de programação.) Outras linguagens
+(C, C++, Rust, PHP, Node.js, etc.) seguem o mesmo contrato e os mesmos
+vetores de conformidade. Para entender o problema que esta lib resolve, leia
+[`docs/USAGE.md`](../../docs/USAGE.md) (guia de uso) e
+[`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) (conceitos e visão geral).
+
+## Antes de começar: instalar o Python
+
+Python é a linguagem de programação usada neste port. Se você nunca instalou:
+
+- Baixe e instale pelo site oficial: <https://www.python.org/downloads/>
+  (precisa da versão 3.10 ou mais nova). No Windows, marque a caixa
+  "Add Python to PATH" durante a instalação.
+- No Linux/macOS, o Python costuma já vir instalado. Confira com:
+
+```bash
+python3 --version
+```
+
+Se aparecer algo como `Python 3.12.x`, está pronto. O comando `pip` (gerenciador
+que baixa bibliotecas Python) vem junto com o Python.
+
+## Quickstart
+
+Uma **dependência** é uma biblioteca de terceiros que o seu código usa. O `pip`
+baixa e instala dependências para você.
+
+> Instalação via PyPI (o repositório oficial de pacotes Python) ainda não
+> publicada. Por enquanto, instale a partir do checkout do repositório (isto é,
+> da pasta que você baixou com `git clone`):
+
+```bash
+pip install ./langs/python
+```
+
+Quando publicada, bastará:
+
+```bash
+pip install tiss-hash
+```
+
+Uso:
+
+```python
+from tiss_hash import hash_tiss, hash_tiss_file
+
+# A partir de bytes
+with open("lote_tiss_exemplo.xml", "rb") as fh:
+    digest = hash_tiss(fh.read())
+print(digest)  # hex MD5 de 32 chars, ex.: '3aa0c578c95cdb861a125f480a8a4de5'
+
+# A partir de um caminho de arquivo
+digest = hash_tiss_file("lote_tiss_exemplo.xml")
+```
+
+Tratamento de erro:
+
+```python
+from tiss_hash import InvalidTissXml, hash_tiss
+
+try:
+    hash_tiss(b"<nao-eh-xml")
+except InvalidTissXml as exc:
+    print(f"falhou ao parsear: {exc}")
+```
+
+## API
+
+| Símbolo | Tipo | Descrição |
+| --- | --- | --- |
+| `hash_tiss(xml: bytes) -> str` | função | Hash MD5 (hex, 32 chars) a partir dos bytes do XML. |
+| `hash_tiss_file(path: str \| os.PathLike) -> str` | função | Atalho que lê o arquivo e delega para `hash_tiss`. |
+| `InvalidTissXml` | classe | Exceção (subclasse de `ValueError`) para XML malformado ou rejeitado por política de segurança. |
+| `__version__` | str | Versão do pacote. |
+
+## Algoritmo
+
+Resumo do que `hash_tiss` faz, em prosa. ("Parsear" um XML é ler o texto e
+montar a árvore de etiquetas na memória; o **parser** é o componente que faz
+essa leitura. **Encoding** é a tabela que traduz caracteres em bytes, por
+exemplo UTF-8. **Namespace** é um prefixo que evita confusão entre etiquetas de
+origens diferentes; aqui o namespace TISS identifica a etiqueta `<ans:hash>`.)
+
+1. Parseia o XML (com `defusedxml`, isto é, sem expansão de entidades e
+   sem DOCTYPE externo).
+2. Zera o conteúdo de `<ans:hash>` (namespace
+   `http://www.ans.gov.br/padroes/tiss/schemas`).
+3. Concatena o `.text` de cada elemento-folha (sem filhos) em ordem
+   documental.
+4. Calcula MD5 sobre os bytes **UTF-8** da string resultante.
+5. Devolve o `hexdigest()` minúsculo (32 caracteres).
+
+Atenção: o encoding dos bytes alimentados ao MD5 é **UTF-8**, não
+ISO-8859-1. O manual TISS afirma o contrário, mas o valor que bate com os
+goldens reais é UTF-8.
+
+Especificação canônica completa: `docs/SPEC.md` (na raiz do repositório).
+Implementação de referência: `conformance/reference.py`.
+
+## Conformidade
+
+"Conformidade" aqui significa: provar que este port produz exatamente o mesmo
+hash que a implementação oficial, em todos os casos previstos. Um **vetor de
+conformidade** é um par "arquivo de entrada -> hash esperado": rodamos a lib no
+arquivo e conferimos se o resultado bate. Um vetor **positivo** deve produzir
+um hash; um vetor **negativo** deve ser rejeitado (a lib precisa recusar o
+arquivo, em vez de inventar um hash).
+
+Esta lib passa os **20 vetores de conformidade** em
+`conformance/vectors.json`, todos sintéticos (`source: derived`): 18
+positivos e 2 negativos (que devem ser rejeitados). O conjunto público de
+conformidade é 100% sintético, sem qualquer XML real de paciente. Os 18
+positivos cobrem: mínimo, acentuação, campos vazios, CR/LF embutido,
+múltiplas guias, entidades XML, entidades numéricas, CDATA, comentário,
+atributo de folha, namespace alternativo, namespace default, documento sem
+`<ans:hash>`, whitespace puro, zeros à esquerda, símbolos ISO-8859-1,
+performance e BOM UTF-8. Os 2 negativos (`syn_multi_hash.xml` e
+`syn_utf16.xml`) cobrem rejeição de múltiplos `<ans:hash>` e de UTF-16
+(fora de escopo: encodings suportados são ISO-8859-1 e UTF-8). A lista
+canônica vive em `conformance/vectors.json`.
+
+Rodar os testes localmente, a partir da raiz do repositório:
+
+```bash
+python -m pip install -e ./langs/python[dev]
+pytest langs/python/tests/ -v
+```
+
+Saída esperada: `24 passed`. Desses, 20 testes são os vetores de
+conformidade (um por vetor, parametrizados: 18 positivos comparam o hash,
+2 negativos verificam a rejeição) e 4 são testes de API auxiliares
+(`hash_tiss_file`, XML inválido, tipo de entrada errado e integridade do
+manifesto).
+
+## Dependências
+
+- Runtime: `defusedxml>=0.7.1` (pure-Python, sem deps próprias). Usado
+  no lugar de `xml.etree.ElementTree.parse` da stdlib para mitigar XXE
+  e billion-laughs em XMLs vindos de terceiros.
+- Extra `lxml`: opcional, reservado para uma implementação alternativa
+  mais performática no futuro.
+- Extra `dev`: `pytest`, `pytest-cov`.
+
+## Licença
+
+[MIT](https://github.com/petrinhu/TISS_ANS_hash/blob/main/LICENSE)
+Copyright (c) 2026 Petrus Silva Costa. Licença única do projeto, na raiz
+do repositório.
+
+## Ver também
+
+- Repositório (origin): https://github.com/petrinhu/TISS_ANS_hash
+- Mirror: https://codeberg.org/petrinhu/TISS_ANS_hash
+- [`docs/USAGE.md`](../../docs/USAGE.md): guia de uso, receitas e perguntas
+  frequentes (comece por aqui se você quer só usar a lib).
+- [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md): conceitos e visão geral
+  de como tudo se encaixa.
+- [`docs/SPEC.md`](../../docs/SPEC.md): especificação canônica do algoritmo
+  (a referência precisa, palavra por palavra).
+- [`docs/PORTING_GUIDE.md`](../../docs/PORTING_GUIDE.md): guia para portar para
+  outras linguagens.
+- [`conformance/reference.py`](../../conformance/reference.py): implementação de
+  referência (o "oráculo", isto é, a versão que define a resposta certa).

tiss_hash-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tiss-hash"
+version = "0.1.0"
+description = "Hash MD5 do epílogo TISS/ANS (Padrão TISS) — implementação portável zero-dep."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Petrus", email = "petrinhu@yahoo.com.br" },
+]
+keywords = ["tiss", "ans", "hash", "md5", "xml", "epilogo", "padrao-tiss", "saude-suplementar", "brasil", "healthcare"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Healthcare Industry",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: Portuguese (Brazilian)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Markup :: XML",
+    "Typing :: Typed",
+]
+
+# Dependência runtime obrigatória: defusedxml.
+# Justificativa: parsers XML da stdlib são vulneráveis a XXE e
+# billion-laughs. defusedxml é pure-Python, sem deps próprias, mantido
+# pelo PSF; o custo de adicionar é mínimo e o ganho de segurança é
+# mandatório para uma lib que processa XML potencialmente externo.
+dependencies = [
+    "defusedxml>=0.7.1",
+]
+
+[project.optional-dependencies]
+# Extra opcional para parsing mais rápido em arquivos grandes (futuro).
+# Atualmente o core usa stdlib; este extra está reservado para uma
+# implementação alternativa baseada em lxml caso surja necessidade.
+lxml = ["lxml>=4.9"]
+# Conjunto para desenvolvimento/teste.
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/petrinhu/TISS_ANS_hash"
+Repository = "https://github.com/petrinhu/TISS_ANS_hash"
+"Mirror (Codeberg)" = "https://codeberg.org/petrinhu/TISS_ANS_hash"
+Issues = "https://github.com/petrinhu/TISS_ANS_hash/issues"
+Changelog = "https://github.com/petrinhu/TISS_ANS_hash/blob/main/CHANGELOG.md"
+Documentation = "https://github.com/petrinhu/TISS_ANS_hash/blob/main/docs/USAGE.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tiss_hash"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/tiss_hash",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+    "tests",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+ignore = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["B011"]  # asserts em testes

tiss_hash-0.1.0/src/tiss_hash/__init__.py

@@ -0,0 +1,43 @@
+"""tiss_hash — geração do hash MD5 do epílogo TISS/ANS.
+
+API pública:
+    - :func:`hash_tiss` — calcula o hash a partir dos bytes do XML.
+    - :func:`hash_tiss_file` — atalho para arquivos em disco.
+    - :class:`InvalidTissXml` — exceção para XML malformado.
+    - :data:`__version__` — versão do pacote.
+
+Spec do algoritmo: ver ``docs/SPEC.md`` no repositório e a implementação
+de referência em ``conformance/reference.py``.
+
+Exemplo:
+    >>> from tiss_hash import hash_tiss
+    >>> with open("lote.xml", "rb") as fh:
+    ...     hash_tiss(fh.read())  # valor ilustrativo (vetor syn_minimal)
+    '3aa0c578c95cdb861a125f480a8a4de5'
+"""
+
+from __future__ import annotations
+
+from ._core import InvalidTissXml, hash_tiss, hash_tiss_file
+
+# Versão é resolvida via metadata do pacote instalado (PEP 621 / pyproject).
+# Fallback "0.0.0+unknown" cobre execução direta a partir do source tree
+# (sem ``pip install``), o que é comum em desenvolvimento.
+try:
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _pkg_version
+
+    try:
+        __version__: str = _pkg_version("tiss-hash")
+    except PackageNotFoundError:  # pragma: no cover - execução in-tree
+        __version__ = "0.0.0+unknown"
+except ImportError:  # pragma: no cover - Python <3.8, não suportado
+    __version__ = "0.0.0+unknown"
+
+
+__all__ = [
+    "InvalidTissXml",
+    "__version__",
+    "hash_tiss",
+    "hash_tiss_file",
+]

tiss_hash-0.1.0/src/tiss_hash/_core.py

@@ -0,0 +1,166 @@
+"""Implementação portável do hash MD5 do epílogo TISS/ANS.
+
+Módulo interno; a API pública é exposta por ``tiss_hash`` (ver ``__init__``).
+
+Algoritmo canônico (validado contra goldens reais em ``conformance/``):
+
+1. Parse do XML.
+2. Zerar o conteúdo de ``<ans:hash>`` (não entra no cálculo).
+3. Concatenar o ``.text`` de cada elemento-FOLHA (sem filhos), em ordem
+   de documento. Sem nomes de tag, sem atributos. TISS não tem conteúdo
+   misto, portanto folha = valor.
+4. Calcular MD5 sobre os bytes **UTF-8** da string concatenada.
+5. ``hexdigest()`` minúsculo (32 chars).
+
+Atenção: o encoding dos bytes passados ao MD5 é **UTF-8**, NÃO ISO-8859-1
+(apesar do que diz a prosa do manual TISS). Os arquivos são lidos respeitando
+sua declaração XML (geralmente ISO-8859-1), mas os valores extraídos são
+re-encodados em UTF-8 antes do MD5.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+from xml.etree.ElementTree import ParseError, TreeBuilder
+
+from defusedxml.common import DefusedXmlException
+
+# defusedxml é usado em vez de xml.etree.ElementTree.parse porque os
+# parsers da stdlib são vulneráveis a XXE (XML External Entity) e
+# "billion laughs" / quadratic blowup. Como esta lib pode receber XMLs
+# vindos de operadoras / parceiros externos, parsing seguro é mandatório.
+# defusedxml.ElementTree é drop-in compatível com xml.etree e desabilita
+# por padrão DOCTYPE, entidades externas e expansion de entidades.
+from defusedxml.ElementTree import DefusedXMLParser
+from defusedxml.ElementTree import parse as _safe_parse
+
+__all__ = ["InvalidTissXml", "hash_tiss", "hash_tiss_file"]
+
+# Namespace oficial do padrão TISS/ANS.
+_TISS_NS = "http://www.ans.gov.br/padroes/tiss/schemas"
+
+# Tag do elemento de hash já expandida em notação Clark (``{uri}localname``),
+# que é a forma como ``xml.etree.ElementTree`` representa elementos namespaced.
+_HASH_TAG = f"{{{_TISS_NS}}}hash"
+
+
+class InvalidTissXml(ValueError):
+    """XML de entrada inválido ou não parseável.
+
+    Subclasse de :class:`ValueError` para preservar idiomatismo Python ao
+    mesmo tempo em que permite tratamento específico.
+    """
+
+
+def hash_tiss(xml: bytes) -> str:
+    """Calcula o hash MD5 do epílogo TISS/ANS a partir dos bytes do XML.
+
+    Recebe os bytes brutos do arquivo (a declaração XML interna define o
+    encoding original, geralmente ISO-8859-1) e devolve o hash em hex
+    minúsculo, exatamente como gravado no elemento ``<ans:hash>``.
+
+    Args:
+        xml: bytes do documento XML completo.
+
+    Returns:
+        Hash MD5 em hexadecimal minúsculo, 32 caracteres.
+
+    Raises:
+        InvalidTissXml: se o XML estiver malformado, contiver construções
+            inseguras (DOCTYPE, entidades externas, billion-laughs) ou não
+            puder ser parseado.
+        TypeError: se ``xml`` não for ``bytes``/``bytearray``/``memoryview``.
+    """
+    if not isinstance(xml, (bytes, bytearray, memoryview)):
+        raise TypeError(
+            f"hash_tiss espera bytes-like, recebeu {type(xml).__name__}"
+        )
+
+    raw = bytes(xml)
+
+    # Rejeição por BOM de encoding fora de escopo. O escopo suportado é
+    # ISO-8859-1 + UTF-8 (ver SPEC.md §7 / AMBIGUITY_NOTES.md §11b). UTF-16
+    # e UTF-32 são proibidos pelo padrão TISS. Detectamos pelo BOM nos bytes
+    # de entrada e rejeitamos antes de parsear (o parser XML aceitaria
+    # UTF-16/32 silenciosamente, produzindo um hash inválido).
+    #
+    # ORDEM IMPORTA: o BOM UTF-32 LE (FF FE 00 00) tem como prefixo o BOM
+    # UTF-16 LE (FF FE); por isso checamos UTF-32 (4 bytes) ANTES de UTF-16
+    # (2 bytes), senão um arquivo UTF-32 seria classificado errado.
+    if raw[:4] in (b"\xff\xfe\x00\x00", b"\x00\x00\xfe\xff"):
+        raise InvalidTissXml(
+            "encoding UTF-32 fora de escopo (BOM detectado): "
+            "TISS suporta apenas ISO-8859-1 e UTF-8"
+        )
+    if raw[:2] in (b"\xff\xfe", b"\xfe\xff"):
+        raise InvalidTissXml(
+            "encoding UTF-16 fora de escopo (BOM detectado): "
+            "TISS suporta apenas ISO-8859-1 e UTF-8"
+        )
+
+    # Parser configurado com ``insert_comments=True`` no TreeBuilder para
+    # reproduzir o comportamento da implementação de referência (lxml),
+    # onde nós-comentário são filhos do elemento pai, têm ``len(el) == 0``
+    # e portanto contribuem seu ``.text`` para o concat de folhas.
+    # Ver ``conformance/vectors.json`` vetor ``syn_comentario.xml`` e a
+    # nota ``conformance/AMBIGUITY_NOTES.md``.
+    try:
+        parser = DefusedXMLParser(
+            target=TreeBuilder(insert_comments=True),
+        )
+        tree = _safe_parse(io.BytesIO(raw), parser=parser)
+    except DefusedXmlException as exc:
+        # XXE / DTD externo / entidade proibida / billion-laughs.
+        raise InvalidTissXml(
+            f"XML rejeitado por política de segurança: {exc}"
+        ) from exc
+    except ParseError as exc:
+        raise InvalidTissXml(f"XML inválido: {exc}") from exc
+
+    root = tree.getroot()
+
+    # Localiza TODOS os elementos <ans:hash> do namespace TISS, casando por
+    # URI + nome local (notação Clark ``{uri}hash``) — nunca pelo prefixo
+    # literal. Isso cobre tanto o caso ``ans:hash`` quanto o namespace TISS
+    # declarado como default (``xmlns=...``), pois ElementTree expande ambos
+    # para a mesma tag Clark.
+    #
+    # O padrão TISS define exatamente um <ans:hash> por mensagem. Mais de um
+    # é documento inválido (A-COV2): rejeitamos em vez de adivinhar qual zerar.
+    # ``root.iter(tag)`` percorre a árvore inteira incluindo a própria raiz.
+    hash_els = list(root.iter(_HASH_TAG))
+    if len(hash_els) > 1:
+        raise InvalidTissXml(
+            f"documento contém {len(hash_els)} elementos <ans:hash>; "
+            "o padrão TISS define exatamente 1"
+        )
+
+    # Zera o conteúdo do elemento <ans:hash> antes de calcular (se existir;
+    # documento sem <ans:hash> é válido e concatena tudo).
+    if hash_els:
+        hash_els[0].text = ""
+
+    # Concatena .text de cada elemento-folha (len(el) == 0) em ordem documental.
+    partes = [(el.text or "") for el in root.iter() if len(el) == 0]
+    payload = "".join(partes)
+
+    return hashlib.md5(payload.encode("utf-8")).hexdigest()
+
+
+def hash_tiss_file(path: str | os.PathLike[str]) -> str:
+    """Atalho conveniente que lê o arquivo do disco e calcula o hash.
+
+    Args:
+        path: caminho do arquivo XML (str ou path-like).
+
+    Returns:
+        Hash MD5 em hexadecimal minúsculo, 32 caracteres.
+
+    Raises:
+        InvalidTissXml: se o XML estiver malformado.
+        OSError: se o arquivo não puder ser aberto/lido.
+    """
+    with open(os.fspath(path), "rb") as fh:
+        return hash_tiss(fh.read())

tiss_hash-0.1.0/tests/conftest.py

@@ -0,0 +1,40 @@
+"""Fixtures compartilhadas pela suíte de conformidade da lib ``tiss_hash``.
+
+Resolve o diretório ``conformance/`` na raiz do repositório (independente
+de onde o pytest seja invocado) e expõe-o como fixture, junto com o
+manifesto ``vectors.json`` carregado.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+# tests/conftest.py -> tests/ -> python/ -> langs/ -> repo_root
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_CONFORMANCE_DIR = _REPO_ROOT / "conformance"
+_VECTORS_PATH = _CONFORMANCE_DIR / "vectors.json"
+
+
+@pytest.fixture(scope="session")
+def conformance_dir() -> Path:
+    """Caminho absoluto do diretório ``conformance/`` na raiz do repo."""
+    if not _CONFORMANCE_DIR.is_dir():
+        pytest.fail(
+            f"diretório conformance/ não encontrado em {_CONFORMANCE_DIR}; "
+            "esta suíte deve rodar dentro do checkout completo do repo "
+            "lib_hash_ans, não a partir do wheel instalado."
+        )
+    return _CONFORMANCE_DIR
+
+
+@pytest.fixture(scope="session")
+def vectors_manifest(conformance_dir: Path) -> dict[str, Any]:
+    """Conteúdo parseado de ``conformance/vectors.json``."""
+    if not _VECTORS_PATH.is_file():
+        pytest.fail(f"vectors.json ausente: {_VECTORS_PATH}")
+    with _VECTORS_PATH.open("r", encoding="utf-8") as fh:
+        return json.load(fh)

tiss_hash-0.1.0/tests/test_conformance.py

@@ -0,0 +1,123 @@
+"""Suíte de conformidade: a lib ``tiss_hash`` deve bater os 8 vetores
+canônicos definidos em ``conformance/vectors.json``.
+
+Cada vetor vira um teste parametrizado nomeado com o ``id`` do vetor,
+facilitando ler a saída do ``pytest -v``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from tiss_hash import InvalidTissXml, hash_tiss, hash_tiss_file
+
+# Carregamento do manifesto em import-time para alimentar @parametrize.
+# Replicamos a lógica do conftest aqui porque parametrize precisa dos
+# valores antes da fase de fixtures.
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_CONFORMANCE_DIR = _REPO_ROOT / "conformance"
+_VECTORS_PATH = _CONFORMANCE_DIR / "vectors.json"
+
+if _VECTORS_PATH.is_file():
+    with _VECTORS_PATH.open("r", encoding="utf-8") as _fh:
+        _MANIFEST: dict[str, Any] = json.load(_fh)
+    _VECTORS: list[dict[str, Any]] = _MANIFEST.get("vectors", [])
+else:
+    _VECTORS = []
+
+
+@pytest.mark.skipif(not _VECTORS, reason="vectors.json ausente ou vazio")
+@pytest.mark.parametrize(
+    "vector",
+    _VECTORS,
+    ids=[v["id"] for v in _VECTORS],
+)
+def test_vector_matches_expected(
+    vector: dict[str, Any],
+    conformance_dir: Path,
+) -> None:
+    """Cada vetor: lê o XML do disco e verifica conforme o tipo.
+
+    O campo ``expect`` do manifesto define o tipo do vetor:
+    - ausente ou ``"hash"``: vetor POSITIVO — calcula e compara com
+      ``expected_md5``.
+    - ``"error"``: vetor NEGATIVO — ``hash_tiss`` DEVE rejeitar o input
+      lançando ``InvalidTissXml`` (nunca retornar um hash).
+    """
+    input_path = conformance_dir / vector["input"]
+    assert input_path.is_file(), f"input ausente: {input_path}"
+
+    raw = input_path.read_bytes()
+    expect = vector.get("expect", "hash")
+
+    if expect == "error":
+        assert vector["expected_md5"] is None, (
+            f"vetor negativo {vector['id']} não deveria ter expected_md5"
+        )
+        with pytest.raises(InvalidTissXml):
+            hash_tiss(raw)
+        return
+
+    got = hash_tiss(raw)
+    assert got == vector["expected_md5"], (
+        f"hash divergente para {vector['id']}: "
+        f"obtido {got!r}, esperado {vector['expected_md5']!r}"
+    )
+
+
+@pytest.mark.skipif(not _VECTORS, reason="vectors.json ausente ou vazio")
+def test_manifest_contains_core_vectors() -> None:
+    """Garante que o manifesto contém os vetores núcleo originais.
+
+    O manifesto cresce ao longo do tempo (vetores sintéticos novos),
+    mas estes 8 são considerados o conjunto mínimo de conformidade.
+    """
+    # Vetores reais (real_envio*.xml) NÃO entram no manifesto público
+    # porque contêm PII de pacientes — vivem em diretório privado fora do
+    # repo (ver build_fixture.py: TISS_PRIVATE_XMLS). A validação contra
+    # eles roda apenas em ambiente privado do mantenedor.
+    nucleo = {
+        "syn_minimal.xml",
+        "syn_acento.xml",
+        "syn_empty.xml",
+        "syn_crlf_value.xml",
+        "syn_multi_guia.xml",
+    }
+    presentes = {v["id"] for v in _VECTORS}
+    faltando = nucleo - presentes
+    assert not faltando, (
+        f"vetores núcleo ausentes do manifesto: {sorted(faltando)}"
+    )
+    assert len(_VECTORS) >= 5, (
+        f"esperados ao menos 5 vetores núcleo no manifesto, encontrados {len(_VECTORS)}"
+    )
+
+
+@pytest.mark.skipif(not _VECTORS, reason="vectors.json ausente ou vazio")
+def test_hash_tiss_file_matches_hash_tiss(conformance_dir: Path) -> None:
+    """``hash_tiss_file`` deve produzir o mesmo resultado de ``hash_tiss``."""
+    vec = _VECTORS[0]
+    input_path = conformance_dir / vec["input"]
+    assert hash_tiss_file(str(input_path)) == hash_tiss(input_path.read_bytes())
+    # Também aceita PathLike.
+    assert hash_tiss_file(input_path) == vec["expected_md5"]
+
+
+def test_invalid_xml_raises_invalid_tiss_xml() -> None:
+    """XML malformado deve disparar ``InvalidTissXml`` (subclasse de ValueError)."""
+    with pytest.raises(InvalidTissXml):
+        hash_tiss(b"<isto-nao-fecha>")
+    # Compatibilidade idiomática: também é capturável como ValueError.
+    with pytest.raises(ValueError):
+        hash_tiss(b"<isto-nao-fecha>")
+
+
+def test_non_bytes_input_raises_type_error() -> None:
+    """Input com tipo errado deve falhar cedo com TypeError, não confundir
+    com erro de parsing."""
+    with pytest.raises(TypeError):
+        hash_tiss("string-em-vez-de-bytes")  # type: ignore[arg-type]