fakeforge-br 0.1.0__tar.gz

fakeforge_br-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache
+.mypy_cache
+.ruff_cache
+dist
+build
+*.egg-info
+.DS_Store
+.env

fakeforge_br-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Everton Paula
+
+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.

fakeforge_br-0.1.0/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.5
+Name: fakeforge-br
+Version: 0.1.0
+Summary: SDK oficial do FakeForge para gerar dados brasileiros válidos (CPF, CNPJ, CEP, PIX, cartão de crédito) em testes de software. Zero dependências runtime.
+Project-URL: Homepage, https://fakeforge.com.br
+Project-URL: Documentation, https://fakeforge.com.br/docs
+Project-URL: Repository, https://github.com/everpaula/fakeforge-br
+Project-URL: Issues, https://github.com/everpaula/fakeforge-br/issues
+Author-email: Everton Paula <hey@fakeforge.com.br>
+License: MIT
+License-File: LICENSE
+Keywords: brasil,brazil,brazilian,cep,cnpj,cpf,fake-data,faker,fixture,gerador,mock,pix,python,seed,test-data,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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.8
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fakeforge
+
+SDK oficial do [FakeForge](https://fakeforge.com.br) para Python — gera dados brasileiros válidos (CPF, CNPJ, CEP, PIX, cartão de crédito) para testes de software.
+
+- ✅ **Zero dependências runtime** (usa `urllib` nativo)
+- ✅ **Type hints completos** (compatível com mypy strict)
+- ✅ **Python 3.8+**
+- ✅ **Validação real** — todos os documentos passam mod-11 da Receita Federal, Luhn, ANATEL
+- ✅ **Presets correlacionados** — pessoa completa com CPF + email + endereço + telefone em 1 chamada
+- ✅ **CNPJ alfanumérico 2026** — cobertura do novo formato (IN RFB 2.229)
+- ✅ **Grátis** — 50 chamadas/dia sem API key, ou 10.000/dia com plano Dev (R$29/mês)
+
+## Instalação
+
+```bash
+pip install fakeforge-br
+```
+
+```bash
+poetry add fakeforge
+```
+
+```bash
+uv add fakeforge
+```
+
+## Uso rápido
+
+```python
+from fakeforge import FakeForge
+
+ff = FakeForge()
+
+# CPFs válidos (mod-11 da Receita Federal)
+cpfs = ff.cpf(10)
+# ['123.456.789-09', '987.654.321-00', ...]
+
+# CNPJs válidos (mod-11)
+cnpjs = ff.cnpj(5)
+
+# Chave PIX no formato BACEN
+pix = ff.pix_key(3)
+
+# Cartão de crédito com Luhn válido
+cards = ff.credit_card(5)
+# [{'number': '...', 'brand': 'visa', 'cvv': '123', 'expiry': '12/28'}, ...]
+
+# Pessoa completa correlacionada
+[pessoa] = ff.person(1)
+print(pessoa["name"], pessoa["cpf"], pessoa["email"])
+```
+
+## Presets: dados correlacionados em 1 chamada
+
+Presets retornam objetos com múltiplos campos que se relacionam — email deriva do nome, DDD bate com o estado do endereço, etc.
+
+```python
+customers = ff.preset("customer", 100)
+
+for c in customers:
+    print({
+        "name": c["name"],
+        "cpf": c["cpf"],
+        "email": c["email"],
+        "phone": c["phone"],
+        "address": c["address"],
+    })
+```
+
+Presets disponíveis:
+
+| Preset | Retorna |
+|---|---|
+| `customer` | pessoa + endereço + email + telefone + PIX |
+| `employee` | pessoa + conta bancária + PIX |
+| `company` | empresa + endereço + contato |
+| `ecommerce_order` | cliente + cartão + entrega |
+| `contact_list` | nome + email + telefone |
+
+## Comparação com faker (pt-BR) e python-brasilidades
+
+| Recurso | faker (pt-BR) | python-brasilidades | fakeforge |
+|---|---|---|---|
+| CPF com mod-11 válido | ❌ | ✅ | ✅ |
+| CNPJ com mod-11 válido | ❌ | ✅ | ✅ |
+| CNPJ alfanumérico 2026 | ❌ | ❌ | ✅ |
+| Cartão com Luhn | ❌ | ❌ | ✅ |
+| PIX BACEN (4 formatos) | ❌ | ❌ | ✅ |
+| Correlação nome ↔ email ↔ DDD | ❌ | ❌ | ✅ |
+| DDDs oficiais ANATEL | ❌ | Parcial | ✅ (67 DDDs) |
+| 17 bancos brasileiros com DV | ❌ | ❌ | ✅ |
+| Presets bundle (customer, employee, etc) | ❌ | ❌ | ✅ |
+| API HTTP (sem instalar dep em outra linguagem) | ❌ | ❌ | ✅ |
+
+**fakeforge** é o único com API HTTP + SDK Python que permite escalar geração em CI/CD sem instalar dep de biblioteca em cada linguagem do stack. Perfeito pra times que usam Python no backend mas Node no frontend.
+
+## Uso com pytest
+
+### Fixture reutilizável
+
+```python
+# conftest.py
+import pytest
+from fakeforge import FakeForge
+
+@pytest.fixture(scope="session")
+def customers():
+    """100 customers correlacionados. Escopo session pra reutilizar entre testes."""
+    ff = FakeForge()
+    return ff.preset("customer", 100)
+
+
+@pytest.fixture(scope="session")
+def cpfs_validos():
+    """1000 CPFs válidos pra teste de load."""
+    ff = FakeForge()
+    return ff.cpf(1000)
+```
+
+```python
+# test_checkout.py
+def test_checkout_aceita_cpf_valido(customers, client):
+    for customer in customers[:20]:
+        response = client.post("/checkout", json={
+            "cpf": customer["cpf"],
+            "email": customer["email"],
+        })
+        assert response.status_code == 200
+```
+
+### Django ORM seed
+
+```python
+# management/commands/seed_customers.py
+from django.core.management.base import BaseCommand
+from fakeforge import FakeForge
+from myapp.models import Customer
+
+class Command(BaseCommand):
+    help = "Popula banco com 1000 customers via FakeForge"
+
+    def handle(self, *args, **options):
+        ff = FakeForge(api_key="sua_key_dev")  # 10.000/dia no Dev
+        customers = ff.preset("customer", 1000)
+
+        Customer.objects.bulk_create([
+            Customer(
+                cpf=c["cpf"],
+                name=c["name"],
+                email=c["email"],
+                phone=c["phone"],
+            )
+            for c in customers
+        ])
+
+        self.stdout.write(f"✓ {len(customers)} customers inseridos")
+```
+
+### FastAPI mock
+
+```python
+# tests/conftest.py
+import pytest
+from httpx import AsyncClient
+from fakeforge import FakeForge
+
+@pytest.fixture
+def fake_customer():
+    ff = FakeForge()
+    return ff.preset("customer", 1)[0]
+
+@pytest.mark.asyncio
+async def test_signup(fake_customer, client: AsyncClient):
+    response = await client.post("/signup", json=fake_customer)
+    assert response.status_code == 201
+```
+
+## API key opcional (plano Dev/Team)
+
+Sem API key: 50 chamadas/dia por IP, até 100 items por chamada. Perfeito pra dev local.
+
+Com API key do plano [Dev (R$29/mês)](https://fakeforge.com.br/pricing?plan=dev): 10.000 chamadas/dia, até 10.000 items por chamada. Ideal pra CI/CD, seed em produção, load test.
+
+```python
+import os
+from fakeforge import FakeForge
+
+ff = FakeForge(api_key=os.environ["FAKEFORGE_API_KEY"])
+cpfs = ff.cpf(10_000)  # no Dev, cabe em 1 chamada
+```
+
+Pegue sua API key em [fakeforge.com.br/dashboard](https://fakeforge.com.br/dashboard).
+
+## Tratamento de erros
+
+```python
+from fakeforge import FakeForge, FakeForgeError
+
+ff = FakeForge()
+
+try:
+    cpfs = ff.cpf(1000)
+except FakeForgeError as e:
+    if e.status == 429:
+        print(f"Rate limit: {e.used_today}/{e.daily_limit}")
+        print(f"Upgrade: {e.upgrade_url}")
+    else:
+        raise
+```
+
+## API completa
+
+### Documentos pessoais
+
+- `cpf(quantity=1, formatted=True) -> list[str]`
+- `cnpj(quantity=1, formatted=True) -> list[str]`
+- `cnpj_alfa(quantity=1, formatted=True) -> list[str]` — novo formato 2026
+- `cnh(quantity=1, formatted=True) -> list[str]`
+- `rg(quantity=1, formatted=True) -> list[str]`
+- `pis(quantity=1, formatted=True) -> list[str]`
+- `renavam(quantity=1, formatted=True) -> list[str]`
+- `titulo_eleitor(quantity=1, formatted=True) -> list[str]`
+- `placa(quantity=1) -> list[str]`
+
+### Contato
+
+- `email(quantity=1) -> list[str]`
+- `phone(quantity=1, formatted=True) -> list[str]` — celular ANATEL
+- `landline(quantity=1, formatted=True) -> list[str]` — fixo
+
+### Endereço
+
+- `cep(quantity=1, formatted=True) -> list[str]`
+- `address(quantity=1, formatted=True) -> list[dict]`
+
+### Pessoa completa
+
+- `person(quantity=1, formatted=True) -> list[dict]`
+- `full_name(quantity=1) -> list[str]`
+
+### Financeiro
+
+- `credit_card(quantity=1, formatted=True) -> list[dict]`
+- `pix_key(quantity=1) -> list[str]`
+- `bank_account(quantity=1, formatted=True) -> list[dict]`
+
+### Empresa
+
+- `company(quantity=1, formatted=True) -> list[dict]`
+
+### Presets
+
+- `preset(name, quantity=1, formatted=True) -> list[dict]`
+
+### Genérico
+
+- `generate(type_, quantity=1, formatted=True) -> list[Any]`
+
+## Perguntas frequentes
+
+### É legal usar CPFs/CNPJs gerados em testes?
+
+Sim. Gerar números que passam validação matemática (mod-11) pra fins de teste é prática padrão em desenvolvimento. Crime é usar CPF/CNPJ (fake ou real) pra fraude, sonegação ou cadastro em nome de terceiro.
+
+### Os dados batem no DICT/SPC/Serasa?
+
+Não. São dados matematicamente válidos mas não existem em nenhuma base oficial. Perfeito pra teste de formato, validação de schema e seed de staging. Não serve pra teste com API externa que consulta base real.
+
+### Como configurar em CI (GitHub Actions)?
+
+```yaml
+- name: Rodar testes com FakeForge
+  env:
+    FAKEFORGE_API_KEY: ${{ secrets.FAKEFORGE_API_KEY }}
+  run: pytest
+```
+
+Cache dos dados na primeira chamada evita esgotar quota:
+
+```python
+# tests/fixtures.py
+import json
+from pathlib import Path
+from fakeforge import FakeForge
+
+CACHE = Path(__file__).parent / "customers.json"
+
+def get_customers():
+    if CACHE.exists():
+        return json.loads(CACHE.read_text())
+
+    ff = FakeForge()
+    customers = ff.preset("customer", 100)
+    CACHE.write_text(json.dumps(customers, indent=2, ensure_ascii=False))
+    return customers
+```
+
+## Suporte
+
+- 📚 Docs completos: [fakeforge.com.br/docs](https://fakeforge.com.br/docs)
+- 💬 Email direto: `hey@fakeforge.com.br`
+- 🐛 Issues: [github.com/everpaula/fakeforge-br/issues](https://github.com/everpaula/fakeforge-br/issues)
+
+## Licença
+
+MIT — veja [LICENSE](./LICENSE) para detalhes.
+
+---
+
+Feito por [Everton Paula](https://fakeforge.com.br) — engenheiro brasileiro que precisou de dados válidos pra testar checkout PIX e escreveu essa lib porque nenhuma outra funcionava direito.

fakeforge_br-0.1.0/README.md

@@ -0,0 +1,310 @@
+# fakeforge
+
+SDK oficial do [FakeForge](https://fakeforge.com.br) para Python — gera dados brasileiros válidos (CPF, CNPJ, CEP, PIX, cartão de crédito) para testes de software.
+
+- ✅ **Zero dependências runtime** (usa `urllib` nativo)
+- ✅ **Type hints completos** (compatível com mypy strict)
+- ✅ **Python 3.8+**
+- ✅ **Validação real** — todos os documentos passam mod-11 da Receita Federal, Luhn, ANATEL
+- ✅ **Presets correlacionados** — pessoa completa com CPF + email + endereço + telefone em 1 chamada
+- ✅ **CNPJ alfanumérico 2026** — cobertura do novo formato (IN RFB 2.229)
+- ✅ **Grátis** — 50 chamadas/dia sem API key, ou 10.000/dia com plano Dev (R$29/mês)
+
+## Instalação
+
+```bash
+pip install fakeforge-br
+```
+
+```bash
+poetry add fakeforge
+```
+
+```bash
+uv add fakeforge
+```
+
+## Uso rápido
+
+```python
+from fakeforge import FakeForge
+
+ff = FakeForge()
+
+# CPFs válidos (mod-11 da Receita Federal)
+cpfs = ff.cpf(10)
+# ['123.456.789-09', '987.654.321-00', ...]
+
+# CNPJs válidos (mod-11)
+cnpjs = ff.cnpj(5)
+
+# Chave PIX no formato BACEN
+pix = ff.pix_key(3)
+
+# Cartão de crédito com Luhn válido
+cards = ff.credit_card(5)
+# [{'number': '...', 'brand': 'visa', 'cvv': '123', 'expiry': '12/28'}, ...]
+
+# Pessoa completa correlacionada
+[pessoa] = ff.person(1)
+print(pessoa["name"], pessoa["cpf"], pessoa["email"])
+```
+
+## Presets: dados correlacionados em 1 chamada
+
+Presets retornam objetos com múltiplos campos que se relacionam — email deriva do nome, DDD bate com o estado do endereço, etc.
+
+```python
+customers = ff.preset("customer", 100)
+
+for c in customers:
+    print({
+        "name": c["name"],
+        "cpf": c["cpf"],
+        "email": c["email"],
+        "phone": c["phone"],
+        "address": c["address"],
+    })
+```
+
+Presets disponíveis:
+
+| Preset | Retorna |
+|---|---|
+| `customer` | pessoa + endereço + email + telefone + PIX |
+| `employee` | pessoa + conta bancária + PIX |
+| `company` | empresa + endereço + contato |
+| `ecommerce_order` | cliente + cartão + entrega |
+| `contact_list` | nome + email + telefone |
+
+## Comparação com faker (pt-BR) e python-brasilidades
+
+| Recurso | faker (pt-BR) | python-brasilidades | fakeforge |
+|---|---|---|---|
+| CPF com mod-11 válido | ❌ | ✅ | ✅ |
+| CNPJ com mod-11 válido | ❌ | ✅ | ✅ |
+| CNPJ alfanumérico 2026 | ❌ | ❌ | ✅ |
+| Cartão com Luhn | ❌ | ❌ | ✅ |
+| PIX BACEN (4 formatos) | ❌ | ❌ | ✅ |
+| Correlação nome ↔ email ↔ DDD | ❌ | ❌ | ✅ |
+| DDDs oficiais ANATEL | ❌ | Parcial | ✅ (67 DDDs) |
+| 17 bancos brasileiros com DV | ❌ | ❌ | ✅ |
+| Presets bundle (customer, employee, etc) | ❌ | ❌ | ✅ |
+| API HTTP (sem instalar dep em outra linguagem) | ❌ | ❌ | ✅ |
+
+**fakeforge** é o único com API HTTP + SDK Python que permite escalar geração em CI/CD sem instalar dep de biblioteca em cada linguagem do stack. Perfeito pra times que usam Python no backend mas Node no frontend.
+
+## Uso com pytest
+
+### Fixture reutilizável
+
+```python
+# conftest.py
+import pytest
+from fakeforge import FakeForge
+
+@pytest.fixture(scope="session")
+def customers():
+    """100 customers correlacionados. Escopo session pra reutilizar entre testes."""
+    ff = FakeForge()
+    return ff.preset("customer", 100)
+
+
+@pytest.fixture(scope="session")
+def cpfs_validos():
+    """1000 CPFs válidos pra teste de load."""
+    ff = FakeForge()
+    return ff.cpf(1000)
+```
+
+```python
+# test_checkout.py
+def test_checkout_aceita_cpf_valido(customers, client):
+    for customer in customers[:20]:
+        response = client.post("/checkout", json={
+            "cpf": customer["cpf"],
+            "email": customer["email"],
+        })
+        assert response.status_code == 200
+```
+
+### Django ORM seed
+
+```python
+# management/commands/seed_customers.py
+from django.core.management.base import BaseCommand
+from fakeforge import FakeForge
+from myapp.models import Customer
+
+class Command(BaseCommand):
+    help = "Popula banco com 1000 customers via FakeForge"
+
+    def handle(self, *args, **options):
+        ff = FakeForge(api_key="sua_key_dev")  # 10.000/dia no Dev
+        customers = ff.preset("customer", 1000)
+
+        Customer.objects.bulk_create([
+            Customer(
+                cpf=c["cpf"],
+                name=c["name"],
+                email=c["email"],
+                phone=c["phone"],
+            )
+            for c in customers
+        ])
+
+        self.stdout.write(f"✓ {len(customers)} customers inseridos")
+```
+
+### FastAPI mock
+
+```python
+# tests/conftest.py
+import pytest
+from httpx import AsyncClient
+from fakeforge import FakeForge
+
+@pytest.fixture
+def fake_customer():
+    ff = FakeForge()
+    return ff.preset("customer", 1)[0]
+
+@pytest.mark.asyncio
+async def test_signup(fake_customer, client: AsyncClient):
+    response = await client.post("/signup", json=fake_customer)
+    assert response.status_code == 201
+```
+
+## API key opcional (plano Dev/Team)
+
+Sem API key: 50 chamadas/dia por IP, até 100 items por chamada. Perfeito pra dev local.
+
+Com API key do plano [Dev (R$29/mês)](https://fakeforge.com.br/pricing?plan=dev): 10.000 chamadas/dia, até 10.000 items por chamada. Ideal pra CI/CD, seed em produção, load test.
+
+```python
+import os
+from fakeforge import FakeForge
+
+ff = FakeForge(api_key=os.environ["FAKEFORGE_API_KEY"])
+cpfs = ff.cpf(10_000)  # no Dev, cabe em 1 chamada
+```
+
+Pegue sua API key em [fakeforge.com.br/dashboard](https://fakeforge.com.br/dashboard).
+
+## Tratamento de erros
+
+```python
+from fakeforge import FakeForge, FakeForgeError
+
+ff = FakeForge()
+
+try:
+    cpfs = ff.cpf(1000)
+except FakeForgeError as e:
+    if e.status == 429:
+        print(f"Rate limit: {e.used_today}/{e.daily_limit}")
+        print(f"Upgrade: {e.upgrade_url}")
+    else:
+        raise
+```
+
+## API completa
+
+### Documentos pessoais
+
+- `cpf(quantity=1, formatted=True) -> list[str]`
+- `cnpj(quantity=1, formatted=True) -> list[str]`
+- `cnpj_alfa(quantity=1, formatted=True) -> list[str]` — novo formato 2026
+- `cnh(quantity=1, formatted=True) -> list[str]`
+- `rg(quantity=1, formatted=True) -> list[str]`
+- `pis(quantity=1, formatted=True) -> list[str]`
+- `renavam(quantity=1, formatted=True) -> list[str]`
+- `titulo_eleitor(quantity=1, formatted=True) -> list[str]`
+- `placa(quantity=1) -> list[str]`
+
+### Contato
+
+- `email(quantity=1) -> list[str]`
+- `phone(quantity=1, formatted=True) -> list[str]` — celular ANATEL
+- `landline(quantity=1, formatted=True) -> list[str]` — fixo
+
+### Endereço
+
+- `cep(quantity=1, formatted=True) -> list[str]`
+- `address(quantity=1, formatted=True) -> list[dict]`
+
+### Pessoa completa
+
+- `person(quantity=1, formatted=True) -> list[dict]`
+- `full_name(quantity=1) -> list[str]`
+
+### Financeiro
+
+- `credit_card(quantity=1, formatted=True) -> list[dict]`
+- `pix_key(quantity=1) -> list[str]`
+- `bank_account(quantity=1, formatted=True) -> list[dict]`
+
+### Empresa
+
+- `company(quantity=1, formatted=True) -> list[dict]`
+
+### Presets
+
+- `preset(name, quantity=1, formatted=True) -> list[dict]`
+
+### Genérico
+
+- `generate(type_, quantity=1, formatted=True) -> list[Any]`
+
+## Perguntas frequentes
+
+### É legal usar CPFs/CNPJs gerados em testes?
+
+Sim. Gerar números que passam validação matemática (mod-11) pra fins de teste é prática padrão em desenvolvimento. Crime é usar CPF/CNPJ (fake ou real) pra fraude, sonegação ou cadastro em nome de terceiro.
+
+### Os dados batem no DICT/SPC/Serasa?
+
+Não. São dados matematicamente válidos mas não existem em nenhuma base oficial. Perfeito pra teste de formato, validação de schema e seed de staging. Não serve pra teste com API externa que consulta base real.
+
+### Como configurar em CI (GitHub Actions)?
+
+```yaml
+- name: Rodar testes com FakeForge
+  env:
+    FAKEFORGE_API_KEY: ${{ secrets.FAKEFORGE_API_KEY }}
+  run: pytest
+```
+
+Cache dos dados na primeira chamada evita esgotar quota:
+
+```python
+# tests/fixtures.py
+import json
+from pathlib import Path
+from fakeforge import FakeForge
+
+CACHE = Path(__file__).parent / "customers.json"
+
+def get_customers():
+    if CACHE.exists():
+        return json.loads(CACHE.read_text())
+
+    ff = FakeForge()
+    customers = ff.preset("customer", 100)
+    CACHE.write_text(json.dumps(customers, indent=2, ensure_ascii=False))
+    return customers
+```
+
+## Suporte
+
+- 📚 Docs completos: [fakeforge.com.br/docs](https://fakeforge.com.br/docs)
+- 💬 Email direto: `hey@fakeforge.com.br`
+- 🐛 Issues: [github.com/everpaula/fakeforge-br/issues](https://github.com/everpaula/fakeforge-br/issues)
+
+## Licença
+
+MIT — veja [LICENSE](./LICENSE) para detalhes.
+
+---
+
+Feito por [Everton Paula](https://fakeforge.com.br) — engenheiro brasileiro que precisou de dados válidos pra testar checkout PIX e escreveu essa lib porque nenhuma outra funcionava direito.

fakeforge_br-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fakeforge-br"
+version = "0.1.0"
+description = "SDK oficial do FakeForge para gerar dados brasileiros válidos (CPF, CNPJ, CEP, PIX, cartão de crédito) em testes de software. Zero dependências runtime."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Everton Paula", email = "hey@fakeforge.com.br" }
+]
+keywords = [
+    "cpf", "cnpj", "cep", "pix", "gerador", "brazilian", "brazil",
+    "faker", "testing", "mock", "fixture", "seed", "fake-data",
+    "test-data", "python", "brasil"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "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.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Testing",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://fakeforge.com.br"
+Documentation = "https://fakeforge.com.br/docs"
+Repository = "https://github.com/everpaula/fakeforge-br"
+Issues = "https://github.com/everpaula/fakeforge-br/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "mypy>=1.0",
+    "ruff>=0.1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fakeforge"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/fakeforge",
+    "README.md",
+    "LICENSE",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.mypy]
+python_version = "3.8"
+strict = true

fakeforge_br-0.1.0/src/fakeforge/__init__.py

@@ -0,0 +1,28 @@
+"""
+fakeforge - SDK oficial pra gerar dados brasileiros válidos.
+
+Gere CPFs, CNPJs, CEPs, chaves PIX e cartões de crédito com validação
+real (mod-11, Luhn, ANATEL) para testes de software, seed de banco e
+fixture de QA.
+
+Uso rápido:
+
+    from fakeforge import FakeForge
+
+    ff = FakeForge()
+    cpfs = ff.cpf(10)                          # 10 CPFs válidos
+    customers = ff.preset("customer", 100)     # 100 pessoas correlacionadas
+
+Para volumes maiores, use API key do plano Dev:
+
+    ff = FakeForge(api_key="sua_key")
+    cpfs = ff.cpf(10000)  # até 10.000 por chamada
+
+Homepage: https://fakeforge.com.br
+"""
+
+from fakeforge.client import FakeForge
+from fakeforge.exceptions import FakeForgeError
+
+__version__ = "0.1.0"
+__all__ = ["FakeForge", "FakeForgeError"]

fakeforge_br-0.1.0/src/fakeforge/client.py

@@ -0,0 +1,218 @@
+"""Cliente principal do SDK FakeForge."""
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Optional, TypeVar, cast
+
+from fakeforge.exceptions import FakeForgeError
+
+T = TypeVar("T")
+
+DEFAULT_BASE_URL = "https://fakeforge.com.br"
+DEFAULT_TIMEOUT = 30.0
+USER_AGENT = "fakeforge-python-sdk/0.1.0"
+
+
+class FakeForge:
+    """
+    Cliente principal do SDK FakeForge.
+
+    Example:
+        >>> from fakeforge import FakeForge
+        >>> ff = FakeForge()
+        >>> cpfs = ff.cpf(10)  # 10 CPFs válidos (mod-11)
+        >>> customers = ff.preset("customer", 100)  # pessoa correlacionada
+
+    Example com API key (plano Dev/Team):
+        >>> import os
+        >>> ff = FakeForge(api_key=os.environ["FAKEFORGE_API_KEY"])
+        >>> cpfs = ff.cpf(10000)  # até 10.000 por chamada no Dev
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        """
+        Args:
+            api_key: API key opcional (plano Dev/Team). Sem key, usa tier
+                grátis: 50 chamadas/dia por IP.
+            base_url: URL base da API. Só mude se for self-hosted.
+            timeout: Timeout em segundos pra cada request. Default: 30s.
+        """
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(
+        self,
+        type_or_preset: str,
+        quantity: int = 1,
+        formatted: bool = True,
+        is_preset: bool = False,
+    ) -> list[Any]:
+        params = {
+            "quantity": str(quantity),
+            "formatted": "true" if formatted else "false",
+        }
+        if is_preset:
+            params["preset"] = type_or_preset
+        else:
+            params["type"] = type_or_preset
+
+        url = f"{self.base_url}/api/generate?{urllib.parse.urlencode(params)}"
+
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+
+        req = urllib.request.Request(url, headers=headers, method="GET")
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                status = response.status
+                body_bytes = response.read()
+        except urllib.error.HTTPError as e:
+            status = e.code
+            body_bytes = e.read()
+        except urllib.error.URLError as e:
+            raise FakeForgeError(f"Erro de rede: {e.reason}", status=0)
+        except TimeoutError:
+            raise FakeForgeError(f"Timeout após {self.timeout}s", status=0)
+
+        try:
+            body = json.loads(body_bytes)
+        except json.JSONDecodeError:
+            raise FakeForgeError(f"Resposta inválida ({status})", status=status)
+
+        if status >= 400:
+            message = body.get("message") or body.get("error") or f"HTTP {status}"
+            raise FakeForgeError(message, status=status, body=body)
+
+        data = body.get("data", [])
+        return cast(list[Any], data)
+
+    # === Documentos pessoais ===
+
+    def cpf(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera CPFs válidos (mod-11 da Receita Federal)."""
+        return self._request("cpf", quantity, formatted)
+
+    def cnpj(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera CNPJs numéricos válidos (mod-11)."""
+        return self._request("cnpj", quantity, formatted)
+
+    def cnpj_alfa(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera CNPJs no novo formato alfanumérico (IN RFB 2.229, vigência 01/07/2026)."""
+        return self._request("cnpjAlfa", quantity, formatted)
+
+    def cnh(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera CNHs válidas (mod-11 do DENATRAN)."""
+        return self._request("cnh", quantity, formatted)
+
+    def rg(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera RGs (formato por estado, mod-11)."""
+        return self._request("rg", quantity, formatted)
+
+    def pis(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera PIS/PASEP/NIT/NIS válidos."""
+        return self._request("pis", quantity, formatted)
+
+    def renavam(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera RENAVAMs válidos (mod-11 do DENATRAN)."""
+        return self._request("renavam", quantity, formatted)
+
+    def titulo_eleitor(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera Títulos de Eleitor válidos."""
+        return self._request("tituloEleitor", quantity, formatted)
+
+    def placa(self, quantity: int = 1) -> list[str]:
+        """Gera placas Mercosul (formato LLLNLNN)."""
+        return self._request("placa", quantity)
+
+    # === Contato ===
+
+    def email(self, quantity: int = 1) -> list[str]:
+        """Gera emails com nomes brasileiros e domínios populares."""
+        return self._request("email", quantity)
+
+    def phone(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera celulares ANATEL (11 dígitos com 9 na frente + DDD válido)."""
+        return self._request("phone", quantity, formatted)
+
+    def landline(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera telefones fixos residenciais (10 dígitos, sem 9)."""
+        return self._request("landline", quantity, formatted)
+
+    # === Endereço ===
+
+    def cep(self, quantity: int = 1, formatted: bool = True) -> list[str]:
+        """Gera CEPs válidos por estado."""
+        return self._request("cep", quantity, formatted)
+
+    def address(self, quantity: int = 1, formatted: bool = True) -> list[dict[str, Any]]:
+        """Gera endereços completos (rua, bairro, cidade, estado, CEP)."""
+        return self._request("address", quantity, formatted)
+
+    # === Pessoa completa ===
+
+    def person(self, quantity: int = 1, formatted: bool = True) -> list[dict[str, Any]]:
+        """Gera pessoa completa correlacionada (nome + CPF + email + telefone)."""
+        return self._request("person", quantity, formatted)
+
+    def full_name(self, quantity: int = 1) -> list[str]:
+        """Gera nomes completos brasileiros."""
+        return self._request("fullName", quantity)
+
+    # === Financeiro ===
+
+    def credit_card(self, quantity: int = 1, formatted: bool = True) -> list[dict[str, Any]]:
+        """Gera cartões de crédito com Luhn válido (qualquer bandeira)."""
+        return self._request("creditCard", quantity, formatted)
+
+    def pix_key(self, quantity: int = 1) -> list[str]:
+        """Gera chaves PIX no formato BACEN (CPF, email, telefone ou EVP UUID)."""
+        return self._request("pixKey", quantity)
+
+    def bank_account(self, quantity: int = 1, formatted: bool = True) -> list[dict[str, Any]]:
+        """Gera conta bancária brasileira (banco + agência + conta com DV)."""
+        return self._request("bankAccount", quantity, formatted)
+
+    # === Empresa ===
+
+    def company(self, quantity: int = 1, formatted: bool = True) -> list[dict[str, Any]]:
+        """Gera empresa completa (CNPJ + razão social + endereço)."""
+        return self._request("company", quantity, formatted)
+
+    # === Presets correlacionados ===
+
+    def preset(self, name: str, quantity: int = 1, formatted: bool = True) -> list[dict[str, Any]]:
+        """
+        Gera dados correlacionados via preset.
+
+        Presets disponíveis:
+        - customer: pessoa + endereço + email + telefone + PIX
+        - employee: pessoa + conta bancária + PIX
+        - company: empresa + endereço + contato
+        - ecommerce_order: cliente + cartão + entrega
+        - contact_list: nome + email + telefone
+
+        Example:
+            >>> customers = ff.preset("customer", 100)
+            >>> for c in customers:
+            ...     print(c["name"], c["cpf"], c["email"])
+        """
+        return self._request(name, quantity, formatted, is_preset=True)
+
+    # === Genérico ===
+
+    def generate(self, type_: str, quantity: int = 1, formatted: bool = True) -> list[Any]:
+        """Genérico: chama a API com qualquer type. Útil pra types sem método dedicado."""
+        return self._request(type_, quantity, formatted)

fakeforge_br-0.1.0/src/fakeforge/exceptions.py

@@ -0,0 +1,36 @@
+"""Exceções específicas do FakeForge SDK."""
+
+from typing import Any, Optional
+
+
+class FakeForgeError(Exception):
+    """
+    Erro específico do FakeForge com contexto adicional.
+
+    Attributes:
+        status: Código HTTP retornado pela API (0 se erro de rede).
+        code: Nome do erro (rate_limit_exceeded, quantity_limit_exceeded, etc).
+        upgrade_url: URL do checkout do plano superior, quando aplicável.
+        plan: Plano do user (anon, free, dev, team).
+        daily_limit: Limite diário do plano atual.
+        used_today: Quantas chamadas já foram feitas hoje.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status: int = 0,
+        body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        body = body or {}
+        self.code = str(body.get("error", "unknown"))
+        upgrade_obj = body.get("upgrade")
+        if isinstance(upgrade_obj, dict):
+            self.upgrade_url = upgrade_obj.get("url")
+        else:
+            self.upgrade_url = body.get("upgrade_url")
+        self.plan = body.get("plan")
+        self.daily_limit = body.get("daily_limit")
+        self.used_today = body.get("your_usage_today")