phone-utils 0.1.0__py3-none-any.whl

phone_utils/__init__.py

@@ -0,0 +1,6 @@
+from .normalize import normalize_phone
+from .validate import validate_phone
+from .variants import generate_br_variants
+from .exceptions import InvalidPhoneError
+
+__all__ = ["normalize_phone", "validate_phone", "generate_br_variants", "InvalidPhoneError"]

phone_utils/exceptions.py

@@ -0,0 +1,2 @@
+class InvalidPhoneError(Exception):
+    pass

phone_utils/normalize.py

@@ -0,0 +1,8 @@
+import phonenumbers
+
+from .parser import parse_phone
+
+
+def normalize_phone(phone: str) -> str:
+    parsed = parse_phone(phone)
+    return phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.E164)

phone_utils/parser.py

@@ -0,0 +1,50 @@
+import phonenumbers
+
+from .exceptions import InvalidPhoneError
+
+
+def parse_phone(phone: str) -> phonenumbers.PhoneNumber:
+    parsed = _try_parse(phone)
+    if not phonenumbers.is_valid_number(parsed):
+        raise InvalidPhoneError(f"Invalid phone number: {phone!r}")
+    return parsed
+
+
+def parse_phone_lenient(phone: str) -> phonenumbers.PhoneNumber:
+    """Parse accepting legacy BR formats; 12-digit BR numbers get the 9th digit auto-added."""
+    parsed = _try_parse(phone)
+
+    if parsed.country_code == 55:
+        e164 = phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.E164)
+        digits = e164[1:]  # strip "+"
+        if len(digits) == 12:
+            with_ninth = "+" + digits[:4] + "9" + digits[4:]
+            try:
+                candidate = phonenumbers.parse(with_ninth, None)
+                if phonenumbers.is_valid_number(candidate):
+                    return candidate
+            except phonenumbers.NumberParseException:
+                pass
+
+    if not phonenumbers.is_possible_number(parsed):
+        raise InvalidPhoneError(f"Invalid phone number: {phone!r}")
+    return parsed
+
+
+def _try_parse(phone: str) -> phonenumbers.PhoneNumber:
+    if not isinstance(phone, str) or not phone.strip():
+        raise InvalidPhoneError(f"Invalid phone number: {phone!r}")
+
+    cleaned = phone.strip()
+    candidates = [cleaned]
+    if not cleaned.startswith("+"):
+        candidates.append("+" + cleaned)
+
+    last_exc = None
+    for candidate in candidates:
+        try:
+            return phonenumbers.parse(candidate, None)
+        except phonenumbers.NumberParseException as exc:
+            last_exc = exc
+
+    raise InvalidPhoneError(f"Invalid phone number: {phone!r}") from last_exc

phone_utils/validate.py

@@ -0,0 +1,9 @@
+from .normalize import normalize_phone
+
+
+def validate_phone(phone: str) -> bool:
+    try:
+        normalize_phone(phone)
+        return True
+    except Exception:
+        return False

phone_utils/variants.py

@@ -0,0 +1,44 @@
+import phonenumbers
+
+from .exceptions import InvalidPhoneError
+from .normalize import normalize_phone
+from .parser import parse_phone_lenient
+
+_BR_COUNTRY_CODE = 55
+_BR_DDI = "+55"
+_BR_TOTAL_WITH_NINTH = 13
+_BR_TOTAL_WITHOUT_NINTH = 12
+
+
+def generate_br_variants(phone: str) -> list[str]:
+    normalized = _normalize_lenient(phone)
+
+    if not normalized.startswith(_BR_DDI):
+        return [normalized]
+
+    digits = normalized[1:]  # strip "+"
+    ddd = digits[2:4]        # area code after country code "55"
+    local = digits[4:]       # digits after DDD
+    total_digits = len(digits)
+
+    if total_digits == _BR_TOTAL_WITH_NINTH and local.startswith("9"):
+        without_ninth = f"+55{ddd}{local[1:]}"
+        return [normalized, without_ninth]
+
+    if total_digits == _BR_TOTAL_WITHOUT_NINTH and local.startswith("9"):
+        with_ninth = f"+55{ddd}9{local}"
+        return [with_ninth, normalized]
+
+    return [normalized]
+
+
+def _normalize_lenient(phone: str) -> str:
+    """Normalize to E.164; falls back to lenient parsing only for legacy BR formats."""
+    try:
+        return normalize_phone(phone)
+    except InvalidPhoneError:
+        pass
+    parsed = parse_phone_lenient(phone)
+    if parsed.country_code != _BR_COUNTRY_CODE:
+        raise InvalidPhoneError(f"Invalid phone number: {phone!r}")
+    return phonenumbers.format_number(parsed, phonenumbers.PhoneNumberFormat.E164)

phone_utils-0.1.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+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

phone_utils-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+phone_utils/__init__.py,sha256=YEEV8uoHKdxDkYVLb1IvwQNn2eCrYoXVT-uVEYZ7Gug,255
+phone_utils/exceptions.py,sha256=t4d-ktkGeHKn-bi4RHetP4CthvJ1BoJbkpoq8wx52mM,45
+phone_utils/normalize.py,sha256=wPZ4z1RmLVrc1jyNZ5SepySmuRGeYVe08iT5wjBttZE,210
+phone_utils/parser.py,sha256=pWSIEygwzQTBA5Uxn7132uv4VtFF4pbrzTnFq429yFE,1726
+phone_utils/validate.py,sha256=FSjqv47ff-7ZfOvz6kBSme_lfgklwsYwiumHZqq11Jg,184
+phone_utils/variants.py,sha256=PKzxcnQkC1oAjGUGAS_ThSwAh7JF1V-Ybkz6zwmU1jw,1395
+phone_utils-0.1.0.dist-info/METADATA,sha256=Q9jHDO_ovLhgjy-njuUCyXfdbA-mXAZ-aZJ4YMNUa14,3182
+phone_utils-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+phone_utils-0.1.0.dist-info/top_level.txt,sha256=ID1jdHUG0gGyNoQ7QzgEdYnp7qmtOMN8PLPnTvfLRvw,12
+phone_utils-0.1.0.dist-info/RECORD,,

phone_utils-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

phone_utils-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+phone_utils