python-phonenumbers: Google's libphonenumber Port for Python

Introduction

python-phonenumbers is the official Python port of Google's libphonenumber library, a powerful and widely used tool for handling international phone numbers. This library provides a comprehensive suite of functionalities, including parsing, validation, formatting, and extracting metadata for phone numbers from various countries. It's designed to work seamlessly across Python 2.5-2.7 and Python 3.x, offering a consistent experience for developers.

Whether you need to verify user input, standardize phone number displays, or extract geographical information, python-phonenumbers offers a reliable and well-maintained solution, mirroring the capabilities of its Java counterpart.

Installation

Getting started with python-phonenumbers is straightforward. You can install it using pip:

pip install phonenumbers

Examples

Let's explore some of the core functionalities of python-phonenumbers with practical examples.

Parsing and Validation

The library allows you to parse phone numbers from strings and then validate them for possibility and validity.

import phonenumbers

# Parse a number with a known region
x = phonenumbers.parse("020 8366 1177", "GB")
print(x)
# Output: Country Code: 44 National Number: 2083661177 Leading Zero: False

# Parse an E.164 number
y = phonenumbers.parse("+442083661177", None)
print(y)
# Output: Country Code: 44 National Number: 2083661177 Leading Zero: False

# Check if numbers are possible or valid
invalid_number = phonenumbers.parse("+120012301", None)
print(f"Is possible: {phonenumbers.is_possible_number(invalid_number)}") # False
print(f"Is valid: {phonenumbers.is_valid_number(invalid_number)}")     # False

valid_but_unassigned = phonenumbers.parse("+12001230101", None)
print(f"Is possible: {phonenumbers.is_possible_number(valid_but_unassigned)}") # True
print(f"Is valid: {phonenumbers.is_valid_number(valid_but_unassigned)}")     # False (NPA 200 not used)

Formatting Phone Numbers

You can format parsed PhoneNumber objects into various standard formats.

import phonenumbers

number = phonenumbers.parse("+442083661177", None)

print(f"National format: {phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.NATIONAL)}")
# Output: National format: 020 8366 1177

print(f"International format: {phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.INTERNATIONAL)}")
# Output: International format: +44 20 8366 1177

print(f"E.164 format: {phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.E164)}")
# Output: E.164 format: +442083661177

Geocoding and Carrier Information

The library also provides extended functionality to retrieve geographical and carrier information for phone numbers. Note that these require importing specific sub-packages.

from phonenumbers import geocoder, carrier
import phonenumbers

# Geocoding
ch_number = phonenumbers.parse("0431234567", "CH")
print(f"Location (English): {geocoder.description_for_number(ch_number, 'en')}")
# Output: Location (English): Zurich

# Carrier information
ro_number = phonenumbers.parse("+40721234567", "RO")
print(f"Carrier (English): {carrier.name_for_number(ro_number, 'en')}")
# Output: Carrier (English): Vodafone

Why Use python-phonenumbers?

python-phonenumbers is an indispensable library for any application dealing with phone numbers globally. Its key advantages include:

• Accuracy and Reliability: Directly ported from Google's libphonenumbers, it inherits a vast and frequently updated dataset of phone number metadata, ensuring high accuracy in parsing and validation.
• Internationalization: Supports phone numbers from all over the world, handling country codes, national prefixes, and various formatting conventions.
• Comprehensive Features: Beyond basic parsing and formatting, it offers advanced features like "as-you-type" formatting, finding numbers in text, geocoding, and carrier identification.
• Active Maintenance: The library is actively maintained, keeping pace with changes in global telephony standards and data.
• Memory Management: It intelligently loads metadata on-demand, and provides options for managing memory overhead for extended functionalities.

Links

• GitHub Repository: https://github.com/daviddrysdale/python-phonenumbers
• Official Documentation: https://daviddrysdale.github.io/python-phonenumbers/
• PyPI Package: https://pypi.org/project/phonenumbers/