phone-utils 0.1.0__tar.gz

phone_utils-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,100 @@
+# 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/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=69.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "phone-utils"
+version = "0.1.0"
+description = "Biblioteca para normalização, validação e geração de variantes de números telefônicos."
+readme = "README.md"
+requires-python = ">=3.10"
+
+dependencies = [
+"phonenumbers>=9.0.0"
+]
+
+authors = [
+{ name = "Alexandre Nahuz", email = "alexandrenahuz@gmail.com" }
+]
+
+[project.optional-dependencies]
+dev = [
+"pytest>=8.0.0",
+"pytest-cov>=6.0.0"
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = [
+"tests"
+]
+
+python_files = [
+"test_*.py"
+]
+
+addopts = [
+"-v"
+]

phone_utils-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

phone_utils-0.1.0/src/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-0.1.0/src/phone_utils/exceptions.py

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

phone_utils-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/phone_utils.egg-info/PKG-INFO

@@ -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/src/phone_utils.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/phone_utils/__init__.py
+src/phone_utils/exceptions.py
+src/phone_utils/normalize.py
+src/phone_utils/parser.py
+src/phone_utils/validate.py
+src/phone_utils/variants.py
+src/phone_utils.egg-info/PKG-INFO
+src/phone_utils.egg-info/SOURCES.txt
+src/phone_utils.egg-info/dependency_links.txt
+src/phone_utils.egg-info/requires.txt
+src/phone_utils.egg-info/top_level.txt
+tests/test_normalize.py
+tests/test_validate.py
+tests/test_variants.py

phone_utils-0.1.0/src/phone_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

phone_utils-0.1.0/src/phone_utils.egg-info/requires.txt

@@ -0,0 +1,5 @@
+phonenumbers>=9.0.0
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=6.0.0

phone_utils-0.1.0/src/phone_utils.egg-info/top_level.txt

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

phone_utils-0.1.0/tests/test_normalize.py

@@ -0,0 +1,44 @@
+import pytest
+
+from phone_utils import normalize_phone, InvalidPhoneError
+
+
+class TestNormalizeValid:
+    @pytest.mark.parametrize("input_phone,expected", [
+        ("+5511999999999",    "+5511999999999"),
+        ("5511999999999",     "+5511999999999"),
+        ("+55 (11) 99999-9999", "+5511999999999"),
+        ("+55 11 99999 9999", "+5511999999999"),
+        ("+12025550123",      "+12025550123"),
+        ("+1 (202) 555-0123", "+12025550123"),
+        ("+353871234567",     "+353871234567"),
+        ("+595981123456",     "+595981123456"),
+    ])
+    def test_valid_numbers(self, input_phone, expected):
+        assert normalize_phone(input_phone) == expected
+
+    @pytest.mark.parametrize("input_phone", [
+        "+5511999999999",
+        "+12025550123",
+        "+353871234567",
+        "+595981123456",
+    ])
+    def test_idempotent(self, input_phone):
+        assert normalize_phone(normalize_phone(input_phone)) == normalize_phone(input_phone)
+
+
+class TestNormalizeInvalid:
+    @pytest.mark.parametrize("input_phone", [
+        "11999999999",
+        "999999999",
+        "abc",
+        "telefone123",
+        "",
+        "()-+",
+        "+999123456789",
+        "+5511",
+        "+551199999999999999999999",
+    ])
+    def test_invalid_numbers_raise(self, input_phone):
+        with pytest.raises(InvalidPhoneError):
+            normalize_phone(input_phone)

phone_utils-0.1.0/tests/test_validate.py

@@ -0,0 +1,29 @@
+import pytest
+
+from phone_utils import validate_phone
+
+
+class TestValidateTrue:
+    @pytest.mark.parametrize("phone", [
+        "+5511999999999",
+        "+12025550123",
+        "+353871234567",
+        "+595981123456",
+    ])
+    def test_valid_returns_true(self, phone):
+        assert validate_phone(phone) is True
+
+
+class TestValidateFalse:
+    @pytest.mark.parametrize("phone", [
+        "11999999999",
+        "abc",
+        "",
+        "+999123456789",
+    ])
+    def test_invalid_returns_false(self, phone):
+        assert validate_phone(phone) is False
+
+    def test_never_raises(self):
+        for value in [None, 123, [], {}, object()]:
+            assert validate_phone(value) is False

phone_utils-0.1.0/tests/test_variants.py

@@ -0,0 +1,55 @@
+import pytest
+
+from phone_utils import generate_br_variants, InvalidPhoneError
+
+
+class TestBrVariants:
+    def test_with_ninth_digit(self):
+        result = generate_br_variants("+5511999999999")
+        assert result == ["+5511999999999", "+551199999999"]
+
+    def test_without_ninth_digit(self):
+        result = generate_br_variants("+551199999999")
+        assert result == ["+5511999999999", "+551199999999"]
+
+    def test_without_compatible_ninth_digit(self):
+        result = generate_br_variants("+5511799999999")
+        assert result == ["+5511799999999"]
+
+    def test_no_duplicates_with_ninth(self):
+        result = generate_br_variants("+5511999999999")
+        assert len(result) == len(set(result))
+
+    def test_no_duplicates_without_ninth(self):
+        result = generate_br_variants("+551199999999")
+        assert len(result) == len(set(result))
+
+    def test_order_with_ninth_first(self):
+        result = generate_br_variants("+5511999999999")
+        assert result[0] == "+5511999999999"
+        assert result[1] == "+551199999999"
+
+    def test_order_with_ninth_first_when_input_without(self):
+        result = generate_br_variants("+551199999999")
+        assert result[0] == "+5511999999999"
+        assert result[1] == "+551199999999"
+
+    def test_accepts_formatted_input(self):
+        result = generate_br_variants("+55 (11) 99999-9999")
+        assert result == ["+5511999999999", "+551199999999"]
+
+
+class TestInternationalVariants:
+    def test_us_number_returns_single(self):
+        result = generate_br_variants("+12025550123")
+        assert result == ["+12025550123"]
+
+    def test_ireland_number_returns_single(self):
+        result = generate_br_variants("+353871234567")
+        assert result == ["+353871234567"]
+
+
+class TestVariantsInvalid:
+    def test_invalid_raises(self):
+        with pytest.raises(InvalidPhoneError):
+            generate_br_variants("11999999999")