or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-operations.mdgeographic-services.mdindex.mdshort-numbers.mdtext-processing.mdutilities.md
tile.json

tessl/pypi-phonenumbers

Python port of Google's libphonenumber library for parsing, formatting, storing and validating international phone numbers

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/phonenumbers@9.0.x

To install, run

npx @tessl/cli install tessl/pypi-phonenumbers@9.0.0

index.mddocs/

phonenumbers

A comprehensive Python port of Google's libphonenumber library for parsing, formatting, storing and validating international phone numbers. The library provides extensive functionality including phone number parsing from various formats, validation of phone number correctness, formatting for national and international display, geocoding to determine the geographic location of phone numbers, carrier lookup capabilities, and timezone information extraction.

Package Information

  • Package Name: phonenumbers
  • Language: Python
  • Installation: pip install phonenumbers
  • Version: 9.0.13
  • License: Apache License 2.0

Core Imports

import phonenumbers

Common imports for specific functionality:

from phonenumbers import parse, format_number, PhoneNumberFormat
from phonenumbers import is_valid_number, number_type, PhoneNumberType
from phonenumbers import AsYouTypeFormatter

Basic Usage

import phonenumbers
from phonenumbers import PhoneNumberFormat

# Parse a phone number
phone_number = phonenumbers.parse("+442083661177", None)

# Format the number in different ways
national = phonenumbers.format_number(phone_number, PhoneNumberFormat.NATIONAL)
international = phonenumbers.format_number(phone_number, PhoneNumberFormat.INTERNATIONAL)
e164 = phonenumbers.format_number(phone_number, PhoneNumberFormat.E164)

print(national)       # 020 8366 1177
print(international)  # +44 20 8366 1177  
print(e164)          # +442083661177

# Validate a phone number
is_valid = phonenumbers.is_valid_number(phone_number)
print(is_valid)       # True

# Get the number type
num_type = phonenumbers.number_type(phone_number)
print(num_type)       # PhoneNumberType.FIXED_LINE

# Parse with region context
uk_number = phonenumbers.parse("020 8366 1177", "GB")
print(phonenumbers.format_number(uk_number, PhoneNumberFormat.E164))  # +442083661177

Architecture

The phonenumbers library is built around several core components:

  • PhoneNumber: Immutable data structure representing a parsed phone number with country code, national number, and metadata
  • Parsing Engine: Robust parser that handles various input formats and regional contexts
  • Validation System: Multi-level validation including format checking, length validation, and carrier verification
  • Formatting Engine: Flexible formatter supporting multiple output formats (E164, national, international)
  • Geographic Services: Integration with location databases for geocoding and timezone lookup
  • Carrier Services: Access to mobile network operator information
  • Metadata System: Comprehensive database of international dialing rules and number patterns

Capabilities

Core Operations

Essential phone number operations including parsing from strings, formatting to various output formats, and comprehensive validation. These functions form the foundation of all phone number processing.

def parse(number: str, region: str | None = None, keep_raw_input: bool = False, numobj: PhoneNumber | None = None) -> PhoneNumber
def format_number(numobj: PhoneNumber, num_format: int) -> str
def is_valid_number(numobj: PhoneNumber) -> bool
def is_possible_number(numobj: PhoneNumber) -> bool
def number_type(numobj: PhoneNumber) -> int

Core Operations

Geographic Services

Location-based services including geocoding to determine the geographic region of phone numbers, carrier lookup to identify mobile network operators, and timezone detection for scheduling and localization.

def region_code_for_number(numobj: PhoneNumber) -> str | None
def country_code_for_region(region_code: str) -> int
def description_for_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str
def name_for_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str
def time_zones_for_number(numobj: PhoneNumber) -> tuple[str, ...]

Geographic Services

Short Numbers

Specialized handling for short numbers including emergency numbers, service numbers, and premium rate numbers. Provides validation and cost information for short dialing codes.

def is_valid_short_number(numobj: PhoneNumber) -> bool
def is_emergency_number(number: str, region_code: str) -> bool
def expected_cost(numobj: PhoneNumber) -> int
def connects_to_emergency_number(number: str, region_code: str) -> bool

Short Numbers

Text Processing

Phone number discovery and extraction from unstructured text using configurable matching algorithms. Includes as-you-type formatting for user interfaces.

class PhoneNumberMatcher:
    def __init__(self, text: str, region: str | None, leniency: int = Leniency.VALID, max_tries: int = 65535)

class AsYouTypeFormatter:
    def __init__(self, region_code: str)
    def input_digit(self, next_char: str, remember_position: bool = False) -> str

Text Processing

Utilities

Helper functions for string processing, normalization, example number generation, and metadata access. Includes constants and utility functions for advanced use cases.

def normalize_digits_only(number: str, keep_non_digits: bool = False) -> str
def convert_alpha_characters_in_number(number: str) -> str
def example_number(region_code: str) -> PhoneNumber | None
SUPPORTED_REGIONS: set[str]

Utilities

Core Types

class PhoneNumber:
    """Represents an international telephone number."""
    country_code: int | None
    national_number: int | None
    extension: str | None
    italian_leading_zero: bool | None
    number_of_leading_zeros: int | None
    raw_input: str | None
    country_code_source: int
    preferred_domestic_carrier_code: str | None

class FrozenPhoneNumber(PhoneNumber):
    """Immutable version of PhoneNumber that can be used as dictionary keys."""
    def __hash__(self) -> int

class PhoneNumberFormat:
    """Output formats for phone numbers."""
    E164 = 0          # +442083661177
    INTERNATIONAL = 1 # +44 20 8366 1177
    NATIONAL = 2      # 020 8366 1177
    RFC3966 = 3       # tel:+44-20-8366-1177

class PhoneNumberType:
    """Types of phone numbers."""
    FIXED_LINE = 0
    MOBILE = 1
    FIXED_LINE_OR_MOBILE = 2
    TOLL_FREE = 3
    PREMIUM_RATE = 4
    SHARED_COST = 5
    VOIP = 6
    PERSONAL_NUMBER = 7
    PAGER = 8
    UAN = 9
    VOICEMAIL = 10
    UNKNOWN = 99

class CountryCodeSource:
    """Source from which a country code is derived."""
    UNSPECIFIED = 0
    FROM_NUMBER_WITH_PLUS_SIGN = 1
    FROM_NUMBER_WITH_IDD = 5
    FROM_NUMBER_WITHOUT_PLUS_SIGN = 10
    FROM_DEFAULT_COUNTRY = 20

class ValidationResult:
    """Results of phone number possibility validation."""
    IS_POSSIBLE = 0
    IS_POSSIBLE_LOCAL_ONLY = 4
    INVALID_COUNTRY_CODE = 1
    TOO_SHORT = 2
    INVALID_LENGTH = 5
    TOO_LONG = 3

class MatchType:
    """Types of number matching results."""
    NOT_A_NUMBER = 0
    NO_MATCH = 1
    SHORT_NSN_MATCH = 2
    NSN_MATCH = 3
    EXACT_MATCH = 4

class NumberParseException(Exception):
    """Exception thrown when phone number parsing fails."""
    INVALID_COUNTRY_CODE = 0
    NOT_A_NUMBER = 1
    TOO_SHORT_AFTER_IDD = 2
    TOO_SHORT_NSN = 3
    TOO_LONG = 4
    
    error_type: int
    _msg: str