tessl/pypi-phonenumbers

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

—

Pending

Overview

Eval results

Files

Geographic Services

Name: tessl/pypi-phonenumbers
Author: tessl

Location-based services that provide geographic context for phone numbers, including geocoding to determine physical locations, carrier identification for mobile network operators, and timezone detection for scheduling and localization purposes.

Capabilities

Region and Country Code Services

Functions for mapping between phone numbers, country codes, and region identifiers.

def region_code_for_number(numobj: PhoneNumber) -> str | None:
    """
    Get region code for a phone number.
    
    Parameters:
    - numobj: PhoneNumber to get region for
    
    Returns:
    Region code (e.g., "US", "GB") or None if not determinable
    """

def region_code_for_country_code(country_code: int) -> str:
    """
    Get main region code for a country calling code.
    
    Parameters:
    - country_code: Country calling code (e.g., 1, 44, 33)
    
    Returns:
    Primary region code for the country code
    """

def region_codes_for_country_code(country_code: int) -> tuple[str, ...]:
    """
    Get all region codes that use the specified country code.
    
    Parameters:
    - country_code: Country calling code
    
    Returns:
    Tuple of all region codes using this country code
    """

def country_code_for_region(region_code: str) -> int:
    """
    Get country calling code for a region.
    
    Parameters:
    - region_code: Region identifier (e.g., "US", "GB")
    
    Returns:
    Country calling code for the region, 0 if invalid region
    """

def country_code_for_valid_region(region_code: str) -> int:
    """
    Get country code for region, assuming region is valid.
    
    Parameters:
    - region_code: Valid region identifier
    
    Returns:
    Country calling code for the region
    """

Usage Examples:

phone = phonenumbers.parse("+442083661177")

# Get region for a number
region = phonenumbers.region_code_for_number(phone)  # "GB"

# Map country codes to regions
main_region = phonenumbers.region_code_for_country_code(44)  # "GB"
all_regions = phonenumbers.region_codes_for_country_code(1)  # ("US", "CA", "PR", ...)

# Map regions to country codes
country_code = phonenumbers.country_code_for_region("GB")  # 44
us_code = phonenumbers.country_code_for_region("US")  # 1

# Handle multiple regions with same country code
phone_us = phonenumbers.parse("+12125551234")  # New York number
region_us = phonenumbers.region_code_for_number(phone_us)  # "US"

phone_ca = phonenumbers.parse("+14161234567")  # Toronto number  
region_ca = phonenumbers.region_code_for_number(phone_ca)  # "CA"

Geographic Classification

Functions to determine if phone numbers are tied to specific geographic locations.

def is_number_geographical(numobj: PhoneNumber) -> bool:
    """
    Check if number represents a geographical location.
    
    Parameters:
    - numobj: PhoneNumber to check
    
    Returns:
    True if the number is tied to a specific geographic area
    """

def is_number_type_geographical(num_type: int, country_code: int) -> bool:
    """
    Check if number type represents geographical numbers in given country.
    
    Parameters:
    - num_type: PhoneNumberType value
    - country_code: Country calling code
    
    Returns:
    True if the number type is geographical in the specified country
    """

Usage Examples:

landline = phonenumbers.parse("+442083661177")  # UK landline
mobile = phonenumbers.parse("+447700123456")    # UK mobile
toll_free = phonenumbers.parse("+18001234567")  # US toll-free

# Check if numbers are geographical
is_geo_landline = phonenumbers.is_number_geographical(landline)  # True
is_geo_mobile = phonenumbers.is_number_geographical(mobile)      # False (in UK)
is_geo_toll_free = phonenumbers.is_number_geographical(toll_free) # False

# Check if number types are geographical in specific countries
is_fixed_geo_uk = phonenumbers.is_number_type_geographical(
    phonenumbers.PhoneNumberType.FIXED_LINE, 44
)  # True

is_mobile_geo_uk = phonenumbers.is_number_type_geographical(
    phonenumbers.PhoneNumberType.MOBILE, 44
)  # False

Geocoding Services

Functions to get human-readable geographic descriptions for phone numbers.

def description_for_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
    """
    Get geographic description (city/region) for phone number.
    
    Parameters:
    - numobj: PhoneNumber to get description for
    - lang: Language code for description (e.g., "en", "fr", "de")
    - script: Script code for language variants (optional)
    - region: Region code for localization (optional)
    
    Returns:
    Geographic description string, empty if unavailable
    """

def description_for_valid_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
    """
    Get description for number, assuming it's already validated.
    
    Parameters:
    - numobj: Valid PhoneNumber to get description for
    - lang: Language code for description
    - script: Script code for language variants (optional)
    - region: Region code for localization (optional)
    
    Returns:
    Geographic description string
    """

def country_name_for_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
    """
    Get country name for phone number in specified language.
    
    Parameters:
    - numobj: PhoneNumber to get country for
    - lang: Language code for country name
    - script: Script code for language variants (optional)
    - region: Region code for localization (optional)
    
    Returns:
    Country name string in requested language
    """

Usage Examples:

# Import geocoder functions
from phonenumbers import geocoder

# Get geographic descriptions
uk_phone = phonenumbers.parse("+442083661177")
description_en = geocoder.description_for_number(uk_phone, "en")  # "London"
description_fr = geocoder.description_for_number(uk_phone, "fr")  # "Londres"

# Get country names
country_en = geocoder.country_name_for_number(uk_phone, "en")  # "United Kingdom"
country_de = geocoder.country_name_for_number(uk_phone, "de")  # "Vereinigtes Königreich"

# US number with area code
us_phone = phonenumbers.parse("+12125551234")  # New York area code
ny_description = geocoder.description_for_number(us_phone, "en")  # "New York, NY"

# For performance with pre-validated numbers
description = geocoder.description_for_valid_number(uk_phone, "en")

Carrier Information Services

Functions to identify mobile network operators and carrier information.

def name_for_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
    """
    Get carrier name for phone number in specified language.
    
    Parameters:
    - numobj: PhoneNumber to get carrier for
    - lang: Language code for carrier name
    - script: Script code for language variants (optional)
    - region: Region code for localization (optional)
    
    Returns:
    Carrier name string, empty if unavailable or not applicable
    """

def name_for_valid_number(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
    """
    Get carrier name, assuming number is already validated.
    
    Parameters:
    - numobj: Valid PhoneNumber to get carrier for
    - lang: Language code for carrier name
    - script: Script code for language variants (optional)
    - region: Region code for localization (optional)
    
    Returns:
    Carrier name string
    """

def safe_display_name(numobj: PhoneNumber, lang: str, script: str | None = None, region: str | None = None) -> str:
    """
    Get carrier name safe for display (empty string if unavailable).
    
    Parameters:
    - numobj: PhoneNumber to get carrier for
    - lang: Language code for carrier name
    - script: Script code for language variants (optional)
    - region: Region code for localization (optional)
    
    Returns:
    Carrier name string or empty string if not available
    """

Usage Examples:

# Import carrier functions
from phonenumbers import carrier

# Get carrier information for mobile numbers
mobile_phone = phonenumbers.parse("+447700123456")  # UK mobile
carrier_name = carrier.name_for_number(mobile_phone, "en")  # "Vodafone" (example)

# Different languages
carrier_fr = carrier.name_for_number(mobile_phone, "fr")

# Safe display (won't raise exceptions)
display_name = carrier.safe_display_name(mobile_phone, "en")

# For landlines, carrier info is typically empty
landline = phonenumbers.parse("+442083661177")
landline_carrier = carrier.name_for_number(landline, "en")  # ""

# US mobile example
us_mobile = phonenumbers.parse("+15551234567")
us_carrier = carrier.name_for_number(us_mobile, "en")  # "Verizon" (example)

Timezone Services

Functions to determine possible timezones for phone numbers.

def time_zones_for_number(numobj: PhoneNumber) -> tuple[str, ...]:
    """
    Get possible time zones for a phone number.
    
    Parameters:
    - numobj: PhoneNumber to get timezones for
    
    Returns:
    Tuple of timezone identifiers (e.g., "America/New_York", "Europe/London")
    """

def time_zones_for_geographical_number(numobj: PhoneNumber) -> tuple[str, ...]:
    """
    Get time zones for geographical numbers only.
    
    Parameters:
    - numobj: Geographical PhoneNumber
    
    Returns:
    Tuple of timezone identifiers for geographical numbers
    """

Timezone Constants:

UNKNOWN_TIMEZONE: str  # Constant for unknown timezone

Usage Examples:

# Import timezone functions
from phonenumbers import timezone

# Get timezones for numbers
uk_phone = phonenumbers.parse("+442083661177")
uk_timezones = timezone.time_zones_for_number(uk_phone)  # ("Europe/London",)

us_phone = phonenumbers.parse("+12125551234")  # New York
us_timezones = timezone.time_zones_for_number(us_phone)  # ("America/New_York",)

# Some regions may have multiple timezones
russia_phone = phonenumbers.parse("+74951234567")  # Moscow area
russia_timezones = timezone.time_zones_for_number(russia_phone)

# For geographical numbers only
geo_timezones = timezone.time_zones_for_geographical_number(uk_phone)

# Handle unknown timezones
if not uk_timezones or uk_timezones[0] == timezone.UNKNOWN_TIMEZONE:
    print("Timezone information not available")
else:
    print(f"Timezone: {uk_timezones[0]}")

# Working with timezone information
import datetime
import pytz

if uk_timezones:
    tz = pytz.timezone(uk_timezones[0])
    local_time = datetime.datetime.now(tz)
    print(f"Local time in {uk_timezones[0]}: {local_time}")

Regional Information and Capabilities

Functions to get information about supported regions and their capabilities.

def supported_calling_codes() -> set[int]:
    """
    Get set of all supported country calling codes.
    
    Returns:
    Set of supported country calling codes
    """

def supported_types_for_region(region_code: str) -> set[int]:
    """
    Get supported phone number types for region.
    
    Parameters:
    - region_code: Region identifier
    
    Returns:
    Set of PhoneNumberType values supported in the region
    """

def supported_types_for_non_geo_entity(country_code: int) -> set[int]:
    """
    Get supported types for non-geographical entities.
    
    Parameters:
    - country_code: Non-geographical country code
    
    Returns:
    Set of supported PhoneNumberType values
    """

def is_nanpa_country(region_code: str) -> bool:
    """
    Check if region is part of North American Numbering Plan (NANPA).
    
    Parameters:
    - region_code: Region identifier
    
    Returns:
    True if region uses NANPA numbering
    """

def is_mobile_number_portable_region(region_code: str) -> bool:
    """
    Check if mobile number portability is supported in region.
    
    Parameters:
    - region_code: Region identifier
    
    Returns:
    True if mobile numbers can be ported between carriers
    """

Usage Examples:

# Get all supported country codes
all_codes = phonenumbers.supported_calling_codes()  # {1, 7, 20, 27, 30, ...}

# Check what number types are supported in a region
uk_types = phonenumbers.supported_types_for_region("GB")
# {PhoneNumberType.FIXED_LINE, PhoneNumberType.MOBILE, PhoneNumberType.TOLL_FREE, ...}

us_types = phonenumbers.supported_types_for_region("US")

# Check NANPA membership
is_us_nanpa = phonenumbers.is_nanpa_country("US")  # True
is_uk_nanpa = phonenumbers.is_nanpa_country("GB")  # False

# Check mobile number portability
us_portable = phonenumbers.is_mobile_number_portable_region("US")  # True
some_portable = phonenumbers.is_mobile_number_portable_region("XX")  # False

# Working with supported types
if phonenumbers.PhoneNumberType.MOBILE in uk_types:
    print("UK supports mobile numbers")

if phonenumbers.PhoneNumberType.PREMIUM_RATE in us_types:
    print("US supports premium rate numbers")

International Services

Functions for international dialing and cross-border calling.

def can_be_internationally_dialled(numobj: PhoneNumber) -> bool:
    """
    Check if number can be dialed internationally.
    
    Parameters:
    - numobj: PhoneNumber to check
    
    Returns:
    True if the number can be called from other countries
    """

def ndd_prefix_for_region(region_code: str, strip_non_digits: bool) -> str | None:
    """
    Get national direct dialing prefix for region.
    
    Parameters:
    - region_code: Region identifier
    - strip_non_digits: Whether to remove non-digit characters
    
    Returns:
    National dialing prefix (e.g., "0" for UK) or None
    """

def country_mobile_token(country_code: int) -> str:
    """
    Get mobile token for country (used in some countries when calling mobiles).
    
    Parameters:
    - country_code: Country calling code
    
    Returns:
    Mobile token string, empty if not applicable
    """

Usage Examples:

# Check international dialing capability
uk_phone = phonenumbers.parse("+442083661177")
can_dial_intl = phonenumbers.can_be_internationally_dialled(uk_phone)  # True

# Some numbers may not be internationally dialable (e.g., emergency, short codes)
emergency = phonenumbers.parse("911", "US")
can_dial_911 = phonenumbers.can_be_internationally_dialled(emergency)  # False

# Get national dialing prefixes
uk_prefix = phonenumbers.ndd_prefix_for_region("GB", True)  # "0"
us_prefix = phonenumbers.ndd_prefix_for_region("US", True)  # "1"

# Mobile tokens (used in some countries)
mobile_token = phonenumbers.country_mobile_token(39)  # Italy example

# Practical usage for international calling
def format_for_international_call(phone, calling_from_region):
    if phonenumbers.can_be_internationally_dialled(phone):
        return phonenumbers.format_out_of_country_calling_number(phone, calling_from_region)
    else:
        return "Cannot be dialed internationally"

intl_format = format_for_international_call(uk_phone, "US")
# "011 44 20 8366 1177"

Install with Tessl CLI