Phonenumbers Module in Python

The phonenumbers module in Python simplifies parsing, formatting, and validation of phone numbers. Based on Google's libphonenumber library, it provides a robust set of tools to handle phone numbers in a standardized manner across different international formats.

This module can extract phone numbers from user inputs, verify their accuracy, and format them according to international standards. Let's explore its key features with practical examples.

Installation

Install the phonenumbers module using pip ?

pip install phonenumbers

Parsing Phone Numbers

The parse() function intelligently interprets phone numbers from various string formats, extracting country code, national number, and extension information ?

import phonenumbers

# Parse a phone number
number = "+14155552671"
parsed_number = phonenumbers.parse(number, None)

# Accessing parsed information
print("Country code:", parsed_number.country_code)
print("National number:", parsed_number.national_number)
print("Extension:", parsed_number.extension)

Country code: 1
National number: 4155552671
Extension: None

Validation of Phone Numbers

Use is_valid_number() to check syntax and structure, and is_possible_number() to verify if a number could potentially be valid ?

import phonenumbers

# Validate phone numbers
valid_number = "+14155552671"
invalid_number = "+1234567890"

valid_parsed = phonenumbers.parse(valid_number, None)
invalid_parsed = phonenumbers.parse(invalid_number, None)

print("Valid number check:", phonenumbers.is_valid_number(valid_parsed))
print("Invalid number check:", phonenumbers.is_valid_number(invalid_parsed))
print("Valid possible:", phonenumbers.is_possible_number(valid_parsed))
print("Invalid possible:", phonenumbers.is_possible_number(invalid_parsed))

Valid number check: True
Invalid number check: False
Valid possible: True
Invalid possible: True

Formatting Phone Numbers

Format parsed numbers using different styles: international, national, and E.164 formats ?

import phonenumbers

# Parse and format phone numbers
parsed_number = phonenumbers.parse("+14155552671", None)

# Different formatting options
international = phonenumbers.format_number(parsed_number, phonenumbers.PhoneNumberFormat.INTERNATIONAL)
national = phonenumbers.format_number(parsed_number, phonenumbers.PhoneNumberFormat.NATIONAL)
e164 = phonenumbers.format_number(parsed_number, phonenumbers.PhoneNumberFormat.E164)

print("International:", international)
print("National:", national)
print("E.164:", e164)

International: +1 415-555-2671
National: (415) 555-2671
E.164: +14155552671

Geographic Information

Extract location information using the geocoder submodule ?

import phonenumbers
from phonenumbers import geocoder

# Parse a phone number
number = "+14155552671"
parsed_number = phonenumbers.parse(number, None)

# Get geographic information
location = geocoder.description_for_number(parsed_number, "en")
print("Location:", location)

# Get region code
region = phonenumbers.region_code_for_number(parsed_number)
print("Region code:", region)

Location: San Francisco, CA
Region code: US

Carrier Information

Retrieve carrier details using the carrier submodule ?

import phonenumbers
from phonenumbers import carrier, geocoder

# Parse a phone number
number = "+14155552671"
parsed_number = phonenumbers.parse(number, None)

# Get carrier information (may be limited for privacy)
carrier_name = carrier.name_for_number(parsed_number, "en")
print("Carrier:", carrier_name if carrier_name else "Not available")

# Get location
location = geocoder.description_for_number(parsed_number, "en")
print("Location:", location)

Carrier: Not available
Location: San Francisco, CA

International Phone Numbers

Handle phone numbers from different countries and format them according to regional conventions ?

import phonenumbers
from phonenumbers import geocoder

# Parse an Irish phone number
number = "+353876543210"
parsed_number = phonenumbers.parse(number, None)

# Get region and location information
region = phonenumbers.region_code_for_number(parsed_number)
location = geocoder.description_for_number(parsed_number, "en")

print("Phone number:", number)
print("Region code:", region)
print("Location:", location)
print("Is valid:", phonenumbers.is_valid_number(parsed_number))

Phone number: +353876543210
Region code: IE
Location: Ireland
Is valid: True

Format Comparison

Best Practices

Security: Always validate phone numbers before processing. Handle user data according to privacy regulations and implement proper access controls.

Error Handling: Use try-catch blocks when parsing numbers, as invalid formats may raise exceptions.

Localization: Specify language parameters when formatting for international applications to ensure proper display conventions.

Conclusion

The phonenumbers module provides comprehensive tools for phone number management in Python applications. Its parsing, validation, formatting, and geographic lookup capabilities make it essential for handling international phone numbers accurately and consistently.