Metadata-Version: 2.4
Name: cpfhub
Version: 1.0.0
Summary: Official Python SDK for CPFHub.io — Brazilian CPF lookup API. Get name, gender and date of birth from any CPF in ~300ms.
Project-URL: Homepage, https://cpfhub.io
Project-URL: Documentation, https://cpfhub.io/documentacao
Project-URL: Repository, https://github.com/cpfhub/cpfhub-python
Project-URL: Bug Tracker, https://github.com/cpfhub/cpfhub-python/issues
Project-URL: Changelog, https://github.com/cpfhub/cpfhub-python/blob/main/CHANGELOG.md
Author-email: "CPFHub.io" <contato@cpfhub.io>
License: MIT
Keywords: api-client,brasil,brazil,cpf,cpf-api,cpf-consulta,cpf-lookup,cpf-validation,cpfhub,fintech,identity-verification,kyc,lgpd,onboarding,receita-federal,sdk,validacao-cpf
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Requires-Dist: requests>=2.28.0
Description-Content-Type: text/markdown

# cpfhub

**Official Python SDK for [CPFHub.io](https://cpfhub.io) — Brazilian CPF Lookup API**

> SDK oficial Python para a [CPFHub.io](https://cpfhub.io) — API de consulta de CPF

[![PyPI version](https://img.shields.io/pypi/v/cpfhub)](https://pypi.org/project/cpfhub/)
[![Python](https://img.shields.io/pypi/pyversions/cpfhub)](https://pypi.org/project/cpfhub/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

---

## What is CPFHub.io?

CPFHub.io is a REST API that returns name, gender, and date of birth from any Brazilian CPF number — in ~300ms, with 99.9% uptime, and full LGPD compliance.

> CPFHub.io é uma API REST que retorna nome, gênero e data de nascimento a partir de qualquer CPF brasileiro — em ~300ms, com 99,9% de uptime e total conformidade com a LGPD.

**10M+ CPFs queried · 1,300+ active companies · 99.9% uptime**

---

## Installation / Instalação

```bash
pip install cpfhub
```

---

## Quick Start

```python
from cpfhub import CPFHub

client = CPFHub(api_key="YOUR_API_KEY")

result = client.lookup("00000000000")

print(result.name)       # "Fulano de Tal"
print(result.gender)     # "M"
print(result.birth_date) # "15/06/1990"
```

Get your free API key at [app.cpfhub.io](https://app.cpfhub.io) — no credit card required.

> Obtenha sua chave gratuita em [app.cpfhub.io](https://app.cpfhub.io) — sem cartão de crédito.

---

## Async Support

```python
import asyncio
from cpfhub import AsyncCPFHub

async def main():
    client = AsyncCPFHub(api_key="YOUR_API_KEY")
    result = await client.lookup("00000000000")
    print(result.name)

asyncio.run(main())
```

---

## API Reference

### `CPFHub(api_key, timeout=10, base_url=None)`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `api_key` | `str` | Yes | — | Your CPFHub API key |
| `timeout` | `int` | No | `10` | Request timeout in seconds |
| `base_url` | `str` | No | `https://api.cpfhub.io` | API base URL |

### `client.lookup(cpf: str) -> CPFResult`

Looks up a CPF and returns the associated data.

Accepts CPF with or without formatting (`000.000.000-00` or `00000000000`).

#### `CPFResult` attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `cpf` | `str` | CPF number (digits only) |
| `name` | `str` | Full name — `"Fulano de Tal"` |
| `name_upper` | `str` | Full name in uppercase |
| `gender` | `str` | `"M"` or `"F"` |
| `birth_date` | `str` | Date of birth — `"DD/MM/YYYY"` |
| `day` | `int` | Birth day |
| `month` | `int` | Birth month |
| `year` | `int` | Birth year |

---

## Error Handling

```python
from cpfhub import CPFHub, CPFHubError

client = CPFHub(api_key="YOUR_API_KEY")

try:
    result = client.lookup("00000000000")
    print(result.name)
except CPFHubError as e:
    print(f"Error {e.status_code}: {e.message}")
    # 400 — Invalid CPF format
    # 401 — Invalid or missing API key
    # 404 — CPF not found
    # 429 — Rate limit exceeded
    # 500 — Server error
    # 503 — Service temporarily unavailable
```

---

## Examples

### requests (sync)

```python
from cpfhub import CPFHub

client = CPFHub(api_key="YOUR_API_KEY", timeout=5)
result = client.lookup("00000000000")
print(result.name)
```

### httpx (async)

```python
import asyncio
from cpfhub import AsyncCPFHub

async def verify_cpf(cpf: str):
    client = AsyncCPFHub(api_key="YOUR_API_KEY")
    return await client.lookup(cpf)

result = asyncio.run(verify_cpf("00000000000"))
print(result.name)
```

### FastAPI

```python
from fastapi import FastAPI
from cpfhub import AsyncCPFHub

app = FastAPI()
client = AsyncCPFHub(api_key="YOUR_API_KEY")

@app.get("/cpf/{cpf}")
async def lookup_cpf(cpf: str):
    result = await client.lookup(cpf)
    return {"name": result.name, "gender": result.gender}
```

### Django

```python
# views.py
from django.http import JsonResponse
from cpfhub import CPFHub

client = CPFHub(api_key="YOUR_API_KEY")

def lookup_cpf(request, cpf):
    result = client.lookup(cpf)
    return JsonResponse({"name": result.name, "gender": result.gender})
```

---

## Rate Limits / Limites de Requisição

| Plan / Plano | Limit / Limite |
|---|---|
| Free / Grátis | 1 request every 2 seconds · 50 requests/month |
| Pro | 1 request per second · 1,000 requests/month |
| Corporate / Corporativo | Custom / Personalizado |

The SDK automatically retries on `429` with exponential backoff (up to 3 attempts).

> O SDK faz retry automático em `429` com backoff exponencial (até 3 tentativas).

---

## Plans & Pricing / Planos e Preços

| Plan | Price | Included | Extra |
|------|-------|----------|-------|
| **Free** | R$ 0/month | 50 lookups | — |
| **Pro** | R$ 149/month | 1,000 lookups | R$ 0,15/lookup |
| **Corporate** | Custom | Custom | Custom |

[View full pricing at cpfhub.io →](https://cpfhub.io#pricing)

---

## Requirements / Requisitos

- Python 3.8+
- `requests` (sync) or `httpx` (async) — installed automatically

---

## Links

- [Documentation / Documentação](https://cpfhub.io/documentacao)
- [Dashboard / Painel](https://app.cpfhub.io)
- [Status Page](https://app.cpfhub.io/status)
- [Pricing / Preços](https://cpfhub.io#pricing)
- [LGPD Compliance](https://cpfhub.io/lgpd)

---

## License / Licença

MIT © [CPFHub.io](https://cpfhub.io)
