Metadata-Version: 2.4
Name: phone-utils
Version: 0.1.0
Summary: Biblioteca para normalização, validação e geração de variantes de números telefônicos.
Author-email: Alexandre Nahuz <alexandrenahuz@gmail.com>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: phonenumbers>=9.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"

# phone-utils

Biblioteca Python para normalização, validação e geração de variantes de números de telefone internacionais, com suporte especial à regra do 9º dígito brasileiro.

## Instalação

```bash
pip install phone-utils
```

## Uso

```python
from phone_utils import normalize_phone, validate_phone, generate_br_variants, InvalidPhoneError
```

### Normalização

Converte qualquer formato de entrada para E.164 (`+CCDDNNNNNNNNN`):

```python
normalize_phone("+55 (11) 99999-9999")  # → "+5511999999999"
normalize_phone("5511999999999")         # → "+5511999999999"
normalize_phone("+1 (202) 555-0123")    # → "+12025550123"

normalize_phone("11999999999")           # → raise InvalidPhoneError (sem DDI)
normalize_phone("abc")                   # → raise InvalidPhoneError
```

### Validação

Verifica a estrutura do número sem lançar exceção:

```python
validate_phone("+5511999999999")   # → True
validate_phone("+12025550123")     # → True
validate_phone("11999999999")      # → False
validate_phone("")                 # → False
```

### Variantes brasileiras (regra do 9º dígito)

Gera todas as representações válidas de um número brasileiro considerando a presença ou ausência do 9º dígito:

```python
# Com 9º dígito → gera variante sem
generate_br_variants("+5511999999999")
# → ["+5511999999999", "+551199999999"]

# Sem 9º dígito → gera variante com
generate_br_variants("+551199999999")
# → ["+5511999999999", "+551199999999"]

# Sem 9º dígito compatível (não começa com 9) → retorna só o número
generate_br_variants("+5511799999999")
# → ["+5511799999999"]

# Número internacional → retorna só o número normalizado
generate_br_variants("+12025550123")
# → ["+12025550123"]
```

### Tratamento de erros

```python
from phone_utils import InvalidPhoneError

try:
    normalized = normalize_phone("numero-invalido")
except InvalidPhoneError as e:
    print(f"Número inválido: {e}")
```

## Formatos de entrada aceitos

| Formato | Exemplo |
|---|---|
| E.164 | `+5511999999999` |
| Sem `+` (com DDI) | `5511999999999` |
| Com máscara | `+55 (11) 99999-9999` |
| Com espaços | `+55 11 99999 9999` |
| Internacional | `+1 (202) 555-0123` |

## Escopo da biblioteca

**Faz:**
- Normalizar números para E.164
- Validar estrutura conforme regras do país
- Gerar variantes BR para compatibilidade com bases legadas

**Não faz:**
- Verificar se a linha existe ou está ativa
- Consultar operadoras
- Enriquecer dados
- Registrar logs

## Requisitos

- Python >= 3.10
- [phonenumbers](https://github.com/daviddrysdale/python-phonenumbers) >= 9.0.0
