faturapt 0.1.0__tar.gz

faturapt-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+      - run: uv run pytest
+      - run: uv build

faturapt-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+# Publica no PyPI quando se cria uma tag vX.Y.Z. Usa trusted publishing: no PyPI,
+# registar este repositório, o workflow release.yml e o ambiente "pypi".
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - name: A tag tem de ser igual à versão
+        run: |
+          version=$(uv run --no-project python -c "import re;print(re.search(r'__version__ = \"(.+)\"', open('src/faturapt/__init__.py').read())[1])")
+          test "v$version" = "$GITHUB_REF_NAME"
+      - run: uv sync --locked --all-extras && uv run pytest
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

faturapt-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/

faturapt-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Alterações
+
+O formato segue o [Keep a Changelog](https://keepachangelog.com/pt-PT/1.1.0/) e as versões o [Semantic Versioning](https://semver.org/lang/pt-PT/).
+
+## [Por publicar]
+
+## [0.1.0] - 2026-10-21
+
+Primeira versão.
+
+### Adicionado
+
+- `parse`, para ler o texto do código QR das faturas (Portaria n.º 195/2020), e `check`, para confirmar o conteúdo: ordem dos campos, duas casas decimais, NIFs, ATCUD (o número no fim tem de ser o do documento, e o documento em G tem de ser do tipo D) e contas.
+- `InvoiceQR.to_text()`, para gerar o texto do QR, com testes de ida e volta (Hypothesis).
+- `read_image`, para encontrar e ler o QR numa fotografia ou digitalização, com as dependências opcionais `faturapt[image]` (Pillow e zxing-cpp).
+- `is_valid_nif`, `nif_type` e `normalize_nif`.
+- Linha de comandos `faturapt`, a partir do texto ou de uma imagem (`-i`/`--imagem`).
+- Regras conferidas com as especificações técnicas da AT (versão 1.0, agosto de 2020), com os quatro exemplos do documento nos testes.
+
+[Por publicar]: https://github.com/JoseFerrao20/faturapt/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/JoseFerrao20/faturapt/releases/tag/v0.1.0

faturapt-0.1.0/CLAUDE.md

@@ -0,0 +1,22 @@
+# faturapt
+
+Biblioteca Python (≥ 3.10, sem dependências) que lê e valida o código QR das faturas portuguesas (`src/faturapt/qr.py`) e NIFs (`src/faturapt/nif.py`), com a linha de comandos em `__main__.py`. A leitura de imagens (`image.py`) usa as dependências opcionais `faturapt[image]` (Pillow e zxing-cpp), importadas só dentro do `read_image`: `import faturapt` tem de funcionar sem elas. Projeto de portfólio de José Ferrão.
+
+## Comandos
+
+```bash
+uv sync --all-extras
+uv run pytest                                  # inclui os exemplos do README (doctest) e cobertura ≥ 95 %
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+uv build
+```
+
+## Convenções
+
+- README, CHANGELOG, mensagens de erro e descrições de PR em **português de Portugal**; nomes no código e mensagens de commit em inglês.
+- API pública só pelo que está em `faturapt.__all__`; mudar algo que já lá está é uma versão nova *major* (ou *minor* antes da 1.0) e entra no `CHANGELOG.md`.
+- `parse` só recusa o que está mal formado; problemas de conteúdo (NIFs, contas) vão para `check`, que devolve uma lista e nunca lança.
+- Valores em `Decimal`, nunca `float`.
+- Nos testes de imagem, os QR são gerados com o `segno` e não com o escritor do zxing, para o leitor não ser testado contra si próprio.
+- `to_text` e `parse` são inversos: `parse(fatura.to_text()) == fatura` (teste com o Hypothesis em `tests/test_build.py`). Um campo novo entra nos dois.
+- Cada alteração num PR a partir de um ramo, com o CI verde.

faturapt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José Ferrão
+
+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.

faturapt-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.5
+Name: faturapt
+Version: 0.1.0
+Summary: Leitura e validação do código QR das faturas portuguesas (AT) e de NIFs.
+Project-URL: Repository, https://github.com/JoseFerrao20/faturapt
+Project-URL: Changelog, https://github.com/JoseFerrao20/faturapt/blob/main/CHANGELOG.md
+Author: José Ferrão
+License-Expression: MIT
+License-File: LICENSE
+Keywords: atcud,autoridade tributária,fatura,invoice,nif,portugal,qr code
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Portuguese
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: image
+Requires-Dist: pillow>=10; extra == 'image'
+Requires-Dist: zxing-cpp>=3.0; extra == 'image'
+Description-Content-Type: text/markdown
+
+# faturapt
+
+[![CI](https://github.com/JoseFerrao20/faturapt/actions/workflows/ci.yml/badge.svg)](https://github.com/JoseFerrao20/faturapt/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/faturapt)](https://pypi.org/project/faturapt/)
+[![Versões de Python](https://img.shields.io/pypi/pyversions/faturapt)](https://pypi.org/project/faturapt/)
+[![Licença: MIT](https://img.shields.io/badge/licen%C3%A7a-MIT-blue)](LICENSE)
+
+Lê e valida o **código QR das faturas portuguesas** (o que a AT exige desde 2022, Portaria n.º 195/2020) e **NIFs**. Python puro, sem dependências obrigatórias, com tipos.
+
+```python
+>>> import faturapt
+>>> inv = faturapt.parse("A:500000000*B:999999990*C:PT*D:FS*E:N*F:20261015*G:FS 01/1234"
+...                      "*H:JJ3XY2KD-1234*I1:PT*I7:10.00*I8:2.30*N:2.30*O:12.30*Q:Ab1z*R:1234")
+>>> inv.document_type_name, inv.document_date, inv.total
+('Fatura simplificada', datetime.date(2026, 10, 15), Decimal('12.30'))
+>>> inv.is_final_consumer
+True
+>>> faturapt.check(inv)      # NIFs e contas; lista vazia = tudo certo
+[]
+>>> faturapt.nif_type("PT 123 456 789")
+<NifType.INDIVIDUAL: 'pessoa singular'>
+
+```
+
+## Instalar
+
+```bash
+pip install faturapt             # só texto: sem dependências
+pip install 'faturapt[image]'    # também lê fotografias (Pillow e zxing-cpp)
+```
+
+```python
+>>> fatura = faturapt.read_image("talao.jpg")    # doctest: +SKIP
+>>> fatura.total, faturapt.check(fatura)          # doctest: +SKIP
+(Decimal('12.30'), [])
+```
+
+## O que faz
+
+- **`parse(texto)`**: converte o texto do QR num `InvoiceQR` (datas em `date`, valores em `Decimal`, IVA por espaço fiscal: continente, Açores e Madeira). Lança `QRCodeError`, com a mensagem em português, se faltarem campos obrigatórios, houver campos repetidos, desconhecidos ou acima do tamanho máximo, ou valores mal formados.
+- **`check(fatura)`**: devolve os problemas de conteúdo: campos fora de ordem, valores sem duas casas decimais, NIFs inválidos, ATCUD que não acaba no número do documento (G) ou documento (G) de outro tipo que não o D, total de impostos (N) diferente de IVA + selo, ou total (O) diferente de bases + não sujeito + impostos.
+- **`fatura.to_text()`**: o caminho inverso, para quem gera faturas: escreve o texto do QR pela ordem da especificação, com duas casas decimais, e recusa valores acima do tamanho máximo. `parse(fatura.to_text())` devolve sempre a mesma fatura (os testes confirmam-no com o Hypothesis, em faturas geradas ao acaso).
+- **`is_valid_nif`, `nif_type`, `normalize_nif`**: dígito de controlo, prefixos e tipo de contribuinte (pessoa singular, coletiva, condomínio, …). Aceita espaços, pontos e o prefixo `PT`.
+- **`read_image(imagem)`**: encontra o QR da fatura numa fotografia ou digitalização (caminho, `bytes` ou imagem do Pillow) e lê-o com o `parse`. Respeita a orientação EXIF do telemóvel e, se houver outros QR na imagem (um site, uma promoção), escolhe o da fatura. Precisa de `faturapt[image]`.
+- **Linha de comandos**: `faturapt "A:...*B:..."` (ou pelo stdin) ou `faturapt -i talao.jpg` mostra a fatura em JSON. Sai com 0 se estiver tudo certo, com 1 se houver problemas e com 2 se o texto ou a imagem não tiverem um QR válido.
+
+As regras seguem as [especificações técnicas da AT](https://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/Novas_regras_faturacao/Documents/Especificacoes_Tecnicas_Codigo_QR.pdf) (versão 1.0, agosto de 2020), e os quatro exemplos do documento fazem parte dos testes. O `parse` recusa o que não se consegue ler (campos desconhecidos, repetidos ou acima do tamanho máximo, obrigatórios em falta); o `check` aponta o resto (campos fora de ordem, valores sem duas casas decimais, NIFs e contas).
+
+
+## Campos do QR
+
+| Chave | Campo | `InvoiceQR` |
+|---|---|---|
+| A, B, C | NIF do emitente, NIF e país do adquirente | `issuer_nif`, `buyer_nif`, `buyer_country` |
+| D, E, F, G | Tipo, estado, data e identificação do documento | `document_type`, `document_status`, `document_date`, `document_id` |
+| H | ATCUD | `atcud` |
+| I1–I8, J1–J8, K1–K8 | IVA por espaço fiscal (isento, reduzida, intermédia, normal) | `taxes` (`TaxBreakdown`) |
+| L, M, N, O, P | Não sujeito, selo, total de impostos, total, retenção na fonte | `non_taxable`, `stamp_duty`, `total_taxes`, `total`, `withholding` |
+| Q, R, S | 4 caracteres do hash, n.º do certificado, outras informações | `hash_chars`, `certificate`, `other_info` |
+
+## Desenvolvimento
+
+```bash
+uv sync --all-extras                      # ambiente com as dependências de desenvolvimento e de imagem
+uv run pytest                             # testes, com cobertura mínima de 95 %
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+O CI corre o mesmo em Python 3.10 a 3.14. Para publicar uma versão: atualizar `__version__`, passar as entradas de "Por publicar" do `CHANGELOG.md` para a versão nova, com a data, e criar uma tag `vX.Y.Z`. O workflow `release.yml` publica no PyPI por *trusted publishing* (sem tokens guardados no GitHub).
+
+## Licença
+
+MIT.

faturapt-0.1.0/README.md

@@ -0,0 +1,73 @@
+# faturapt
+
+[![CI](https://github.com/JoseFerrao20/faturapt/actions/workflows/ci.yml/badge.svg)](https://github.com/JoseFerrao20/faturapt/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/faturapt)](https://pypi.org/project/faturapt/)
+[![Versões de Python](https://img.shields.io/pypi/pyversions/faturapt)](https://pypi.org/project/faturapt/)
+[![Licença: MIT](https://img.shields.io/badge/licen%C3%A7a-MIT-blue)](LICENSE)
+
+Lê e valida o **código QR das faturas portuguesas** (o que a AT exige desde 2022, Portaria n.º 195/2020) e **NIFs**. Python puro, sem dependências obrigatórias, com tipos.
+
+```python
+>>> import faturapt
+>>> inv = faturapt.parse("A:500000000*B:999999990*C:PT*D:FS*E:N*F:20261015*G:FS 01/1234"
+...                      "*H:JJ3XY2KD-1234*I1:PT*I7:10.00*I8:2.30*N:2.30*O:12.30*Q:Ab1z*R:1234")
+>>> inv.document_type_name, inv.document_date, inv.total
+('Fatura simplificada', datetime.date(2026, 10, 15), Decimal('12.30'))
+>>> inv.is_final_consumer
+True
+>>> faturapt.check(inv)      # NIFs e contas; lista vazia = tudo certo
+[]
+>>> faturapt.nif_type("PT 123 456 789")
+<NifType.INDIVIDUAL: 'pessoa singular'>
+
+```
+
+## Instalar
+
+```bash
+pip install faturapt             # só texto: sem dependências
+pip install 'faturapt[image]'    # também lê fotografias (Pillow e zxing-cpp)
+```
+
+```python
+>>> fatura = faturapt.read_image("talao.jpg")    # doctest: +SKIP
+>>> fatura.total, faturapt.check(fatura)          # doctest: +SKIP
+(Decimal('12.30'), [])
+```
+
+## O que faz
+
+- **`parse(texto)`**: converte o texto do QR num `InvoiceQR` (datas em `date`, valores em `Decimal`, IVA por espaço fiscal: continente, Açores e Madeira). Lança `QRCodeError`, com a mensagem em português, se faltarem campos obrigatórios, houver campos repetidos, desconhecidos ou acima do tamanho máximo, ou valores mal formados.
+- **`check(fatura)`**: devolve os problemas de conteúdo: campos fora de ordem, valores sem duas casas decimais, NIFs inválidos, ATCUD que não acaba no número do documento (G) ou documento (G) de outro tipo que não o D, total de impostos (N) diferente de IVA + selo, ou total (O) diferente de bases + não sujeito + impostos.
+- **`fatura.to_text()`**: o caminho inverso, para quem gera faturas: escreve o texto do QR pela ordem da especificação, com duas casas decimais, e recusa valores acima do tamanho máximo. `parse(fatura.to_text())` devolve sempre a mesma fatura (os testes confirmam-no com o Hypothesis, em faturas geradas ao acaso).
+- **`is_valid_nif`, `nif_type`, `normalize_nif`**: dígito de controlo, prefixos e tipo de contribuinte (pessoa singular, coletiva, condomínio, …). Aceita espaços, pontos e o prefixo `PT`.
+- **`read_image(imagem)`**: encontra o QR da fatura numa fotografia ou digitalização (caminho, `bytes` ou imagem do Pillow) e lê-o com o `parse`. Respeita a orientação EXIF do telemóvel e, se houver outros QR na imagem (um site, uma promoção), escolhe o da fatura. Precisa de `faturapt[image]`.
+- **Linha de comandos**: `faturapt "A:...*B:..."` (ou pelo stdin) ou `faturapt -i talao.jpg` mostra a fatura em JSON. Sai com 0 se estiver tudo certo, com 1 se houver problemas e com 2 se o texto ou a imagem não tiverem um QR válido.
+
+As regras seguem as [especificações técnicas da AT](https://info.portaldasfinancas.gov.pt/pt/apoio_contribuinte/Novas_regras_faturacao/Documents/Especificacoes_Tecnicas_Codigo_QR.pdf) (versão 1.0, agosto de 2020), e os quatro exemplos do documento fazem parte dos testes. O `parse` recusa o que não se consegue ler (campos desconhecidos, repetidos ou acima do tamanho máximo, obrigatórios em falta); o `check` aponta o resto (campos fora de ordem, valores sem duas casas decimais, NIFs e contas).
+
+
+## Campos do QR
+
+| Chave | Campo | `InvoiceQR` |
+|---|---|---|
+| A, B, C | NIF do emitente, NIF e país do adquirente | `issuer_nif`, `buyer_nif`, `buyer_country` |
+| D, E, F, G | Tipo, estado, data e identificação do documento | `document_type`, `document_status`, `document_date`, `document_id` |
+| H | ATCUD | `atcud` |
+| I1–I8, J1–J8, K1–K8 | IVA por espaço fiscal (isento, reduzida, intermédia, normal) | `taxes` (`TaxBreakdown`) |
+| L, M, N, O, P | Não sujeito, selo, total de impostos, total, retenção na fonte | `non_taxable`, `stamp_duty`, `total_taxes`, `total`, `withholding` |
+| Q, R, S | 4 caracteres do hash, n.º do certificado, outras informações | `hash_chars`, `certificate`, `other_info` |
+
+## Desenvolvimento
+
+```bash
+uv sync --all-extras                      # ambiente com as dependências de desenvolvimento e de imagem
+uv run pytest                             # testes, com cobertura mínima de 95 %
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+O CI corre o mesmo em Python 3.10 a 3.14. Para publicar uma versão: atualizar `__version__`, passar as entradas de "Por publicar" do `CHANGELOG.md` para a versão nova, com a data, e criar uma tag `vX.Y.Z`. O workflow `release.yml` publica no PyPI por *trusted publishing* (sem tokens guardados no GitHub).
+
+## Licença
+
+MIT.

faturapt-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "faturapt"
+dynamic = ["version"]
+description = "Leitura e validação do código QR das faturas portuguesas (AT) e de NIFs."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "José Ferrão" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["portugal", "fatura", "invoice", "qr code", "nif", "atcud", "autoridade tributária"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Natural Language :: Portuguese",
+  "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",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Office/Business :: Financial :: Accounting",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/JoseFerrao20/faturapt"
+Changelog = "https://github.com/JoseFerrao20/faturapt/blob/main/CHANGELOG.md"
+
+[project.scripts]
+faturapt = "faturapt.__main__:main"
+
+[project.optional-dependencies]
+image = [
+    "pillow>=10",
+    "zxing-cpp>=3.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "hypothesis>=6.100",
+    "segno>=1.6.6",
+]
+
+[tool.hatch.version]
+path = "src/faturapt/__init__.py"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "S", "SIM", "RUF"]
+
+[tool.ruff.lint.isort]
+known-local-folder = ["test_qr"]  # os testes importam os exemplos uns dos outros
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "E402"]  # assert nos testes; imports depois do importorskip
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+addopts = "--doctest-glob=README.md --cov=faturapt --cov-report=term-missing --cov-fail-under=95"

faturapt-0.1.0/src/faturapt/__init__.py

@@ -0,0 +1,22 @@
+"""Leitura e validação do código QR das faturas portuguesas e de NIFs."""
+
+from .image import read_image
+from .nif import InvalidNIF, NifType, is_valid_nif, nif_type, normalize_nif
+from .qr import DOCUMENT_TYPES, InvoiceQR, QRCodeError, TaxBreakdown, check, parse
+
+__all__ = [
+    "DOCUMENT_TYPES",
+    "InvalidNIF",
+    "InvoiceQR",
+    "NifType",
+    "QRCodeError",
+    "TaxBreakdown",
+    "check",
+    "is_valid_nif",
+    "nif_type",
+    "normalize_nif",
+    "parse",
+    "read_image",
+]
+
+__version__ = "0.1.0"

faturapt-0.1.0/src/faturapt/__main__.py

@@ -0,0 +1,53 @@
+"""``faturapt "A:...*B:..."`` ou ``faturapt -i talao.jpg``: mostra a fatura em JSON e os
+problemas encontrados."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from datetime import date
+from decimal import Decimal
+from typing import Any
+
+from .image import read_image
+from .qr import QRCodeError, check, parse
+
+
+def _json(value: Any) -> Any:
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, date):
+        return value.isoformat()
+    raise TypeError(type(value).__name__)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="faturapt", description=__doc__)
+    source = parser.add_mutually_exclusive_group()
+    source.add_argument("qr", nargs="?", help="texto do código QR (por omissão, lido do stdin)")
+    source.add_argument(
+        "-i", "--imagem", help="fotografia ou digitalização da fatura (precisa de faturapt[image])"
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        if args.imagem is not None:
+            invoice = read_image(args.imagem)
+        else:
+            invoice = parse(args.qr if args.qr is not None else sys.stdin.read())
+    except (QRCodeError, ImportError, OSError) as exc:
+        print(f"erro: {exc}", file=sys.stderr)
+        return 2
+
+    data = asdict(invoice)
+    data.pop("fields")
+    data["document_type_name"] = invoice.document_type_name
+    data["problems"] = check(invoice)
+    print(json.dumps(data, default=_json, ensure_ascii=False, indent=2))
+    return 1 if data["problems"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

faturapt-0.1.0/src/faturapt/image.py

@@ -0,0 +1,61 @@
+"""Leitura do código QR a partir de uma imagem (fotografia ou digitalização da fatura).
+
+Precisa das dependências opcionais: ``pip install 'faturapt[image]'``.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+from typing import TYPE_CHECKING
+
+from .qr import InvoiceQR, QRCodeError, parse
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+
+__all__ = ["read_image"]
+
+_MISSING = "Para ler imagens, instalar com: pip install 'faturapt[image]'"
+
+
+def read_image(image: str | os.PathLike[str] | bytes | Image) -> InvoiceQR:
+    """Encontra o código QR da fatura numa imagem e lê-o com :func:`parse`.
+
+    Aceita o caminho de um ficheiro, o conteúdo em ``bytes`` ou uma imagem do Pillow.
+    Respeita a orientação EXIF das fotografias do telemóvel. Se houver vários códigos
+    (por exemplo, o QR de um site ao lado), devolve o primeiro que seja de uma fatura.
+
+    Lança :class:`QRCodeError` se não houver nenhum QR de fatura na imagem, e
+    ``ImportError`` se faltarem as dependências opcionais.
+    """
+    try:
+        import zxingcpp
+        from PIL import Image as PILImage
+        from PIL import ImageOps
+    except ImportError as exc:
+        raise ImportError(_MISSING) from exc
+
+    picture: Image
+    if isinstance(image, bytes):
+        picture = PILImage.open(io.BytesIO(image))
+    elif isinstance(image, (str, os.PathLike)):
+        picture = PILImage.open(image)
+    else:
+        picture = image
+    picture = ImageOps.exif_transpose(picture).convert("L")
+
+    codes = zxingcpp.read_barcodes(
+        picture, formats=zxingcpp.BarcodeFormats(zxingcpp.BarcodeFormat.QRCode)
+    )
+    if not codes:
+        raise QRCodeError("Não encontrei nenhum código QR na imagem")
+    errors = []
+    for code in codes:
+        try:
+            return parse(code.text)
+        except QRCodeError as exc:
+            errors.append(str(exc))
+    raise QRCodeError(
+        f"Há {len(codes)} código(s) QR na imagem, mas nenhum é de uma fatura ({errors[0]})"
+    )

faturapt-0.1.0/src/faturapt/nif.py

@@ -0,0 +1,91 @@
+"""Validação do NIF (Número de Identificação Fiscal) português."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+__all__ = ["InvalidNIF", "NifType", "is_valid_nif", "nif_type", "normalize_nif"]
+
+
+class InvalidNIF(ValueError):
+    """O valor não é um NIF português válido."""
+
+
+class NifType(str, Enum):
+    """Tipo de contribuinte, pelo prefixo do NIF."""
+
+    INDIVIDUAL = "pessoa singular"
+    NON_RESIDENT_INDIVIDUAL = "pessoa singular não residente"
+    COMPANY = "pessoa coletiva"
+    PUBLIC_ADMINISTRATION = "administração pública"
+    UNDIVIDED_INHERITANCE = "herança indivisa"
+    NON_RESIDENT_COMPANY = "pessoa coletiva não residente"
+    INVESTMENT_FUND = "fundo de investimento"
+    OFFICIAL_ASSIGNMENT = "atribuição oficiosa"
+    EXCEPTIONAL_REGIME = "regime excecional"
+    SOLE_TRADER = "empresário em nome individual"
+    CONDOMINIUM_OR_IRREGULAR = "condomínio ou sociedade irregular"
+    NON_RESIDENT_NO_ESTABLISHMENT = "não residente sem estabelecimento estável"
+    CIVIL_PARTNERSHIP = "sociedade civil sem personalidade jurídica"
+
+
+# Prefixos de dois dígitos primeiro: "45" tem de ganhar a "4" (que não existe sozinho).
+_PREFIXES: tuple[tuple[str, NifType], ...] = (
+    ("45", NifType.NON_RESIDENT_INDIVIDUAL),
+    ("70", NifType.UNDIVIDED_INHERITANCE),
+    ("71", NifType.NON_RESIDENT_COMPANY),
+    ("72", NifType.INVESTMENT_FUND),
+    ("74", NifType.UNDIVIDED_INHERITANCE),
+    ("75", NifType.UNDIVIDED_INHERITANCE),
+    ("77", NifType.OFFICIAL_ASSIGNMENT),
+    ("79", NifType.EXCEPTIONAL_REGIME),
+    ("90", NifType.CONDOMINIUM_OR_IRREGULAR),
+    ("91", NifType.CONDOMINIUM_OR_IRREGULAR),
+    ("98", NifType.NON_RESIDENT_NO_ESTABLISHMENT),
+    ("99", NifType.CIVIL_PARTNERSHIP),
+    ("1", NifType.INDIVIDUAL),
+    ("2", NifType.INDIVIDUAL),
+    ("3", NifType.INDIVIDUAL),
+    ("5", NifType.COMPANY),
+    ("6", NifType.PUBLIC_ADMINISTRATION),
+    ("8", NifType.SOLE_TRADER),
+)
+
+
+def normalize_nif(value: str | int) -> str:
+    """Tira espaços, pontos, hífenes e o prefixo ``PT``.
+
+    Não valida: ``normalize_nif(" PT 123 456 789 ")`` dá ``"123456789"``.
+    """
+    text = str(value).strip().upper()
+    if text.startswith("PT"):
+        text = text[2:]
+    return "".join(ch for ch in text if ch not in " .-")
+
+
+def _check_digit(first_eight: str) -> int:
+    total = sum(int(d) * w for d, w in zip(first_eight, range(9, 1, -1), strict=True))
+    remainder = total % 11
+    return 0 if remainder < 2 else 11 - remainder
+
+
+def nif_type(value: str | int) -> NifType:
+    """Devolve o tipo de contribuinte, ou lança :class:`InvalidNIF`."""
+    nif = normalize_nif(value)
+    if len(nif) != 9 or not nif.isdigit():
+        raise InvalidNIF(f"O NIF tem de ter 9 dígitos: {value!r}")
+    kind = next((t for prefix, t in _PREFIXES if nif.startswith(prefix)), None)
+    if kind is None:
+        raise InvalidNIF(f"O NIF começa por um prefixo que não existe: {value!r}")
+    if int(nif[8]) != _check_digit(nif[:8]):
+        raise InvalidNIF(f"O dígito de controlo do NIF não confere: {value!r}")
+    return kind
+
+
+def is_valid_nif(value: str | int) -> bool:
+    """``True`` se o valor (depois de :func:`normalize_nif`) for um NIF válido."""
+    try:
+        nif_type(value)
+    except InvalidNIF:
+        return False
+    return True