phone-utils 0.1.0

Biblioteca para normalização, validação e geração de variantes de números telefônicos.

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

pip install phone-utils

Uso

from phone_utils import normalize_phone, validate_phone, generate_br_variants, InvalidPhoneError

Normalização

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

normalize_phone("[phone]")  # → "[phone]"
normalize_phone("5511999999999")         # → "[phone]"
normalize_phone("[phone]")    # → "[phone]"

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:

validate_phone("[phone]")   # → True
validate_phone("[phone]")     # → 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:

# Com 9º dígito → gera variante sem
generate_br_variants("[phone]")
# → ["[phone]", "[phone]"]

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

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

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

Tratamento de erros

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	[phone]
Sem + (com DDI)	5511999999999
Com máscara	[phone]
Com espaços	[phone]
Internacional	[phone]

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 >= 9.0.0