Metadata-Version: 2.4
Name: PixCanvas
Version: 0.5.0
Summary: SDK Python moderno para Pix estatico, BR Code, validacao e QR customizavel.
Project-URL: Homepage, https://github.com/marlonmartins2/pixcanva-sdk
Project-URL: Repository, https://github.com/marlonmartins2/pixcanva-sdk
Project-URL: Issues, https://github.com/marlonmartins2/pixcanva-sdk/issues
Author-email: Marlon Azevedo Martins <marlon.azevedo.m@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bacen,brcode,pagamentos,pix,pix-copia-e-cola,qrcode
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
Requires-Dist: mypy<2,>=1.14; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: qrcode[pil]>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: segno>=1.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Provides-Extra: qr
Requires-Dist: segno>=1.6; extra == 'qr'
Provides-Extra: qr-artistic
Requires-Dist: pillow>=10.0; extra == 'qr-artistic'
Requires-Dist: qrcode[pil]>=8.0; extra == 'qr-artistic'
Requires-Dist: segno>=1.6; extra == 'qr-artistic'
Provides-Extra: qr-svg
Requires-Dist: cairosvg>=2.7; extra == 'qr-svg'
Provides-Extra: validate
Requires-Dist: opencv-python>=4.9; extra == 'validate'
Description-Content-Type: text/markdown

<p align="center">
  <img src="logo.png" alt="PixCanvas logo" width="240">
</p>

<h1 align="center">PixCanvas</h1>

SDK Python para Pix estatico com foco em BR Code correto, validacao clara, tipagem forte e QR customizavel com salvaguardas de legibilidade.

[![CI](https://github.com/marlonmartins2/pixcanva-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/marlonmartins2/pixcanva-sdk/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](#qualidade)
[![Python](https://img.shields.io/badge/python-3.9%20--%203.13-blue)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://marlonmartins2.github.io/pixcanva-sdk/)

**[📖 Documentação completa](https://marlonmartins2.github.io/pixcanva-sdk/)**

> Status: pre-alpha. A v0.5 organiza docs, exemplos e trilha de compatibilidade para Pix estatico, mas ainda nao deve ser usada em producao sem validacao propria.

## Proposta

PixCanvas nasce para ser um SDK Python moderno para Pix estatico:

- core zero-dependencia para gerar BR Code estatico;
- decode e validacao estrutural de Pix estatico;
- API tipada e imutavel;
- erros claros para payloads invalidos;
- QR opcional via extras, sem poluir quem so precisa do Copia e Cola;
- documentacao honesta sobre compatibilidade bancaria.

Gerar payload Pix e simples. O objetivo do PixCanvas e entregar confiabilidade, DX e validacao de verdade.

## English Summary

PixCanvas is a Python SDK for Brazilian static Pix payments. It generates BR Code payloads, parses and validates static Pix strings, and renders optional QR Codes with safe customization controls. Banking-app compatibility must be tested manually before production use.

## Quickstart

```bash
pip install PixCanvas
```

```python
from decimal import Decimal

from pixcanvas import create_static_pix

pix = create_static_pix(
    pix_key="Fulano@Example.com",
    merchant_name="Fulano de Tal",
    merchant_city="Sao Paulo",
    amount=Decimal("100.00"),
    txid="PEDIDO123",
    description="Pedido 123",
)

print(pix.br_code)
```

O objeto retornado contem o payload `br_code` e os valores normalizados usados na geracao.

Mais exemplos em [`examples/`](examples/):

- [`basic_static_pix.py`](examples/basic_static_pix.py)
- [`parse_validate.py`](examples/parse_validate.py)
- [`qr_png.py`](examples/qr_png.py)
- [`qr_custom_logo.py`](examples/qr_custom_logo.py)
- [`flask_qr_endpoint.py`](examples/flask_qr_endpoint.py)
- [`fastapi_qr_endpoint.py`](examples/fastapi_qr_endpoint.py)

## Parse e validacao

Use `parse_pix` quando payload invalido deve interromper o fluxo com uma excecao especifica:

```python
from pixcanvas import parse_pix

parsed = parse_pix("000201...")

print(parsed.pix_key)
print(parsed.amount)
print(parsed.txid)
```

Use `validate_pix` para conferencias em lote ou APIs que preferem resultado sem excecao:

```python
from pixcanvas import validate_pix

result = validate_pix("000201...")

if result.is_valid:
    print(result.pix)
else:
    print(result.errors)
```

O validador detecta erros comuns como CRC invalido, campo obrigatorio ausente, GUI incorreta, moeda diferente de BRL e pais diferente de BR. Campos EMV desconhecidos geram warnings sem invalidar o payload.

## QR Code

Instale o extra opcional de QR:

```bash
pip install "PixCanvas[qr]"
```

Renderize a partir do objeto `StaticPix`:

```python
pix.to_png("pix.png")
svg = pix.to_svg()
encoded = pix.to_base64()
data_uri = pix.to_data_uri()
```

Ou use as funcoes com uma string BR Code:

```python
from pixcanvas.qr import to_png, to_svg

to_png(pix.br_code, "pix.png")
svg = to_svg(pix.br_code)
```

A v0.3 usa Segno como dependencia opcional e gera PNG, SVG, PDF, EPS, base64 PNG e data URI PNG.

### QR customizavel

Instale o extra artistico para gerar PNG com cores, gradiente, modulos customizados e logo central:

```bash
pip install "PixCanvas[qr-artistic]"
```

```python
from decimal import Decimal

from pixcanvas import QRGradient, QRLogo, QRStyle

pix.to_styled_png(
    "pix-custom.png",
    style=QRStyle(
        fill_color="#111111",
        back_color="#FFFFFF",
        module_drawer="rounded",
        gradient=QRGradient(
            kind="linear",
            start_color="#000000",
            end_color="#003366",
        ),
    ),
    logo=QRLogo(
        "logo.png",
        size_ratio=Decimal("0.22"),
        padding_ratio=Decimal("0.06"),
        background_color="#FFFFFF",
        border_color="#111111",
        border_width=2,
        radius=12,
        fit="contain",
    ),
)
```

Por seguranca, o PixCanvas:

- aceita somente cores hex `#RRGGBB` no modo seguro;
- rejeita contraste abaixo de 4.5:1;
- preserva quiet zone minima de 4 modulos;
- limita logo central a 25% do tamanho do QR;
- sobe error correction automaticamente para `Q` em estilos pesados e `H` quando ha logo.

O centro aceita PNG/JPG/WebP e GIF. Como a saida de `to_styled_png` e PNG estatico, GIFs usam o primeiro frame como imagem central. `QRLogo` permite customizar padding, fundo, borda, raio, modo de encaixe (`contain`, `cover`, `stretch`) e se o alpha da imagem deve ser respeitado.

Para validar o PNG gerado por decoder local, instale o extra de validacao:

```bash
pip install "PixCanvas[validate]"
```

```python
pix.to_styled_png("pix-custom.png", style=QRStyle(), validate=True)
```

`validate=True` confirma que o QR gerado decodifica exatamente para o mesmo BR Code. Isso aumenta a confianca tecnica, mas QR customizado ainda deve ser testado em apps bancarios reais antes de uso em producao.

### QR artistico experimental

A v0.4.x inclui um modo experimental para usar uma imagem PNG/JPG/WebP como mascara, forma de marca ou fundo do QR:

```python
from decimal import Decimal

from pixcanvas import QRArtisticSource, QRArtisticStyle

pix.to_artistic_png(
    "pix-art.png",
    source=QRArtisticSource("logo.png", fit="contain"),
    style=QRArtisticStyle(
        mode="brand_shape",
        accent_color="#003366",
        strength=Decimal("0.65"),
        module_drawer="rounded",
    ),
    validate=True,
)
```

Modos disponiveis:

- `image_mask`: usa a imagem como mascara de intensidade dos modulos.
- `brand_shape`: usa a silhueta/area da imagem como destaque visual.
- `background_blend`: usa a imagem como fundo de baixa opacidade.

SVG e suportado via extra separado:

```bash
pip install "PixCanvas[qr-svg]"
```

Esse modo e experimental: ele preserva finder patterns e quiet zone por padrao, usa error correction `H`, mas ainda precisa ser testado em apps bancarios reais antes de qualquer uso publico.

## Normalizacao

PixCanvas normaliza entradas comuns antes de montar o BR Code:

- CPF/CNPJ podem ser enviados com ou sem pontuacao.
- E-mail e EVP sao normalizados para lowercase.
- Telefone brasileiro aceita `+55`, `55` ou formato local com sinais de telefone, como `(11) 99999-9999`.
- Nome e cidade removem acentos, viram uppercase e respeitam os limites do BR Code.
- `description` fica limitada a 23 caracteres; valores maiores usam os 20 primeiros caracteres + `...`.
- `amount` aceita `Decimal`, `str` decimal com ponto ou `None`; `float` e rejeitado.

Pix dinamico ainda nao esta disponivel nesta fase; veja o desenho planejado em [Pix dinamico (planejado)](https://marlonmartins2.github.io/pixcanva-sdk/dynamic-pix/).

## Instalacao

```bash
pip install PixCanvas
pip install "PixCanvas[qr]"
pip install "PixCanvas[qr-artistic]"
pip install "PixCanvas[qr-svg]"
```

Extras previstos:

- `qr`: renderizacao QR base com Segno.
- `qr-artistic`: QR customizavel com logo, cores e validacoes de legibilidade.
- `qr-svg`: conversao opcional de SVG para QR artistico experimental.
- `validate`: validacao opcional do QR renderizado por decoder local.

Pix dinamico via PSP adapters esta planejado para v2.0; ainda nao ha extra instalavel (veja [Pix dinamico (planejado)](https://marlonmartins2.github.io/pixcanva-sdk/dynamic-pix/)).

## Roadmap

| Fase   | Objetivo                                                      |
| ------ | ------------------------------------------------------------- |
| Fase 0 | Fundacao do pacote, README, CI, coverage 100%, PyPI preparado |
| v0.1   | Core zero-dependencia para gerar Pix estatico                 |
| v0.2   | Decode, parse e validacao estrutural                          |
| v0.3   | QR base como dependencia opcional                             |
| v0.4   | QR customizavel com salvaguardas de legibilidade              |
| v0.4.x | QR artistico experimental com imagem fonte                    |
| v0.5   | Docs, exemplos e tabela de compatibilidade bancaria           |
| v1.0   | API estavel                                                   |
| v2.0   | Pix dinamico (PSP adapters) — em planejamento, sem prazo definido |

## Especificacao

Versao alvo documentada:

- Manual de Padroes para Iniciacao do Pix v2.9.0, divulgado pela IN BCB no. 658/2025.
- Manual do BR Code publicado pelo Banco Central do Brasil.

## Compatibilidade bancaria

Compatibilidade real precisa ser testada em apps bancarios. Conformidade com a especificacao nao garante aceite por todos os PSPs.

| Banco/app       | Payload estatico | QR padrao  | QR customizado seguro | QR artistico | Data       | Observacao |
| --------------- | ---------------- | ---------- | --------------------- | ------------ | ---------- | ---------- |
| Nubank          | Aprovado         | Aprovado   | Aprovado              | Aprovado     | 2026-07-07 | App reconheceu destinatario, instituicao bancaria e dados do Pix corretamente, incluindo QR customizado seguro e QR artistico. |
| Inter           | Aprovado         | Aprovado   | Aprovado              | Aprovado     | 2026-07-07 | App reconheceu destinatario, instituicao bancaria e dados do Pix corretamente, incluindo QR customizado seguro e QR artistico. |
| Banco do Brasil | Aprovado         | Aprovado   | Aprovado              | Aprovado     | 2026-07-07 | App reconheceu destinatario, instituicao bancaria e dados do Pix corretamente, incluindo QR customizado seguro e QR artistico. |
| Itau            | Aprovado         | Aprovado   | Aprovado              | Aprovado     | 2026-07-07 | App reconheceu destinatario, instituicao bancaria e dados do Pix corretamente, incluindo QR customizado seguro e QR artistico. |

Estados aceitos: `Nao testado`, `Aprovado`, `Falhou`, `Parcial`, `Inconclusivo`.

Nenhum banco deve ser marcado como aprovado sem data e teste manual. Testes acima cobrem os bancos disponiveis para teste no momento; mais bancos serao adicionados conforme testados.

Procedimento resumido de teste:

1. Teste o copia-e-cola.
2. Teste o QR padrao.
3. Teste o QR customizado seguro.
4. Teste QR artistico apenas como experimental.
5. Registre banco, data, tipo de QR e resultado.

## Desenvolvimento local

Instale as dependencias de desenvolvimento:

```bash
uv sync --extra dev
```

Rode a suite de qualidade:

```bash
uv run ruff check .
uv run ruff format --check .
uv run mypy .
uv run pytest
```

Exemplos tambem sao cobertos pela suite de testes.

Build da documentacao:

```bash
uv sync --extra dev --extra docs
uv run mkdocs build --strict
```

## Versionamento

Veja [`CHANGELOG.md`](CHANGELOG.md), [`VERSIONING.md`](VERSIONING.md) e [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Qualidade

Coverage de testes e gate permanente em 100%:

```bash
uv run pytest --cov=pixcanvas --cov-report=term-missing --cov-fail-under=100
```

Regras de desenvolvimento:

- cobertura abaixo de 100% bloqueia merge;
- core runtime sem dependencias externas;
- dinheiro sempre com `Decimal`, nunca `float`;
- API publica tipada;
- excecoes especificas para erros de dominio;
- QR e Pix dinamico sempre atras de extras opcionais.

## Licenca

MIT. Veja [LICENSE](LICENSE).
