sophone 0.1.0

Validate & format Somali phone numbers (+252) with provider detection

Sophone 🇸🇴

Professional Somali phone number validation, formatting & operator detection for Python. A comprehensive library with CLI tools, type hints, and beautiful error handling.

Features

• ✅ Validate Somali mobile numbers (+252)
• 🎨 Format numbers in multiple styles (local, international, E.164)
• 🏢 Detect operators (Hormuud, Somtel, Telesom, etc.)
• 🛡️ Type-safe with comprehensive type hints
• 🚀 CLI tools for command-line usage
• 📦 Batch processing for multiple numbers
• 🎯 Zero dependencies - pure Python

Installation

pip install sophone

Quick Start

from sophone import validate, normalize_e164, get_operator

# Validate a number
result = validate("[phone]")
if result.ok:
    print(f"Valid! Operator: {result.value['operator']}")
else:
    print(f"Invalid: {result.error['message']}")

# Format to E.164
e164 = normalize_e164("0611234567")  # "[phone]"

# Get operator
operator = get_operator("[phone]")  # "Hormuud"

API Reference

Core Functions

validate(number: str) -> ValidationResult

Validates a phone number and returns detailed information.

result = validate("[phone]")
# Returns ValidationResult with ok=True/False and value/error

is_valid_somali_mobile(number: str) -> bool

Simple boolean validation.

is_valid = is_valid_somali_mobile("0611234567")  # True

Formatting Functions

normalize_e164(number: str) -> str

Convert to E.164 international format.

e164 = normalize_e164("0611234567")  # "[phone]"

format_local(number: str) -> str

Format to local Somali format.

local = format_local("[phone]")  # "0611 234 567"

format_international(number: str) -> str

Format to international display format.

intl = format_international("0611234567")  # "[phone]"

Operator Detection

get_operator(number: str) -> str

Get the operator name.

operator = get_operator("0611234567")  # "Hormuud"

get_operator_info(number: str) -> dict

Get detailed operator information.

info = get_operator_info("0611234567")
# Returns: {
#   "name": "Hormuud Telecom Somalia",
#   "prefixes": ["61", "77"],
#   "website": "https://hormuud.com",
#   "type": "GSM"
# }

Safe Functions

All functions have "safe" variants that return None instead of raising exceptions:

from sophone import normalize_e164_safe, get_operator_safe

# These return None for invalid numbers instead of raising exceptions
e164 = normalize_e164_safe("invalid")  # None
operator = get_operator_safe("invalid")  # None

Batch Processing

validate_batch(numbers: List[str]) -> List[dict]

Validate multiple numbers at once.

numbers = ["[phone]", "0771234567", "invalid"]
results = validate_batch(numbers)

normalize_batch(numbers: List[str]) -> List[dict]

Normalize multiple numbers to E.164 format.

numbers = ["0611234567", "0771234567"]
results = normalize_batch(numbers)

Utility Functions

get_all_operators() -> List[dict]

Get information about all supported operators.

operators = get_all_operators()

get_operator_by_prefix(prefix: str) -> str

Get operator by prefix code.

operator = get_operator_by_prefix("61")  # "Hormuud"

CLI Usage

The package includes a powerful command-line interface:

# Validate a number
sophone validate "[phone]"

# Format numbers
sophone format "0611234567"           # Local format
sophone e164 "0611234567"             # E.164 format
sophone international "0611234567"    # International format

# Get operator info
sophone operator "0611234567"         # Get operator name
sophone info "0611234567"             # Get detailed info
sophone operators                     # List all operators

# Batch processing
sophone batch numbers.txt             # Process file with numbers

Supported Operators

Operator	Prefixes	Website
Hormuud Telecom Somalia	61, 77	https://hormuud.com
Somtel Network	62, 65, 66	https://somtel.com
Telesom	63	https://telesom.net
SomLink	64	-
SomNet	68	-
NationLink Telecom	69	-
Amtel	71	-

Error Handling

The library provides detailed error information:

from sophone import validate, SomaliPhoneError

try:
    result = normalize_e164("invalid")
except SomaliPhoneError as e:
    print(f"Error: {e}")
    print(f"Code: {e.code}")
    print(f"Details: {e.details}")

Error codes:

• INVALID_INPUT: Invalid input type or empty
• INVALID_LENGTH: Wrong number of digits
• INVALID_PREFIX: Unsupported prefix code

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Related

• JavaScript/Node.js version
• GitHub Repository