Python-phonenumbers

Warnings

• gotcha Calling `phonenumbers.parse()` with a non-E.164 number and `None` as the default region will raise a `NumberParseException`.
  Fix: Always provide a valid default region code (e.g., 'US', 'GB') when parsing numbers that are not in E.164 international format (starting with '+') or wrap parsing calls in a `try-except phonenumbers.NumberParseException` block.
• breaking In version 8.0.0, methods like `_for_region` in `shortnumberinfo.py` no longer accept strings; they now require a `PhoneNumber` object.
  Fix: If migrating from versions prior to 8.0.0, ensure that you call `phonenumbers.parse()` first to create a `PhoneNumber` object and pass that object to these methods.
• gotcha The `PhoneNumberMatcher` class, used for extracting phone numbers from text, is explicitly stated as not being thread-safe.
  Fix: Do not share `PhoneNumberMatcher` instances across multiple threads. Create a new instance for each thread or use appropriate locking mechanisms if sharing is unavoidable.
• gotcha The full `phonenumbers` library includes substantial metadata (e.g., geocoder, carrier, timezone data) which can impact memory footprint, especially in resource-constrained environments.
  Fix: If memory usage is a critical concern, consider using the `phonenumberslite` variant (`pip install phonenumberslite`), which omits some of the larger metadata packages. Alternatively, be aware of the memory implications and manage them for your application.

Install

• pip install phonenumbers Install stable version

Imports

• phonenumbers

  import phonenumbers

• parse

  import phonenumbers
  parsed_number = phonenumbers.parse("+12133734253", "US")

• format_number

  from phonenumbers import PhoneNumberFormat
  formatted_number = phonenumbers.format_number(number_obj, PhoneNumberFormat.INTERNATIONAL)

• is_valid_number

  is_valid = phonenumbers.is_valid_number(number_obj)

• carrier

  from phonenumbers import carrier

  For carrier lookup, import the 'carrier' submodule.
• geocoder

  from phonenumbers import geocoder

  For geographical lookup, import the 'geocoder' submodule.
• timezone

  from phonenumbers import timezone

  For timezone lookup, import the 'timezone' submodule.

Quickstart

This quickstart demonstrates how to parse, validate, format, and retrieve auxiliary information (carrier, region, timezone) for a phone number. It handles potential parsing errors using a try-except block.

import phonenumbers
from phonenumbers import geocoder, carrier, timezone, PhoneNumberFormat

# 1. Parse a phone number
#   - The second argument ('GB') provides a default region if the number is not in E.164 format.
#   - If the number is E.164 (e.g., '+44...'), None can be used as the default region.
phone_number_str = "+442083661177"
country_code = "GB" # Default region for parsing, if number is not in international format

try:
    parsed_number = phonenumbers.parse(phone_number_str, country_code)
    print(f"Parsed Number: {parsed_number}")

    # 2. Validate the phone number
    is_valid = phonenumbers.is_valid_number(parsed_number)
    is_possible = phonenumbers.is_possible_number(parsed_number)
    print(f"Is Valid: {is_valid}, Is Possible: {is_possible}")

    if is_valid:
        # 3. Format the phone number in various ways
        national_format = phonenumbers.format_number(parsed_number, PhoneNumberFormat.NATIONAL)
        international_format = phonenumbers.format_number(parsed_number, PhoneNumberFormat.INTERNATIONAL)
        e164_format = phonenumbers.format_number(parsed_number, PhoneNumberFormat.E164)

        print(f"National Format: {national_format}")
        print(f"International Format: {international_format}")
        print(f"E.164 Format: {e164_format}")

        # 4. Get carrier, region, and timezone information
        #    Note: These lookups depend on the data included in the phonenumbers library.
        carrier_name = carrier.name_for_number(parsed_number, "en")
        region_description = geocoder.description_for_number(parsed_number, "en")
        timezones = timezone.time_zones_for_number(parsed_number)

        print(f"Carrier: {carrier_name}")
        print(f"Region: {region_description}")
        print(f"Timezones: {timezones}")

except phonenumbers.NumberParseException as e:
    print(f"Error parsing number: {e}")