Python-phonenumbers

Common errors

• ModuleNotFoundError: No module named 'phonenumbers'

  cause The `phonenumbers` library is not installed in the Python environment being used, or there is a mismatch between the installed package name and the import statement.
  fix Ensure the library is correctly installed using pip: `pip install phonenumbers`. If using a virtual environment, ensure it's activated before installation. Verify the import statement is `import phonenumbers`.

• phonenumbers.phonenumberutil.NumberParseException: (0) Missing or invalid default region.

  cause The `parse()` function was called with a national phone number string but without specifying a valid default region code, or with an invalid region code, making it impossible for the library to interpret the number's format.
  fix When parsing a national number (without an international dialing code), provide the two-letter ISO 3166-1 alpha-2 country code as the second argument to `phonenumbers.parse()`. For international numbers (starting with '+'), the region code can often be `None`. Example: `phonenumbers.parse('0721234567', 'RO')` or `phonenumbers.parse('+40721234567', None)`.

• phonenumbers.phonenumberutil.NumberParseException: (1) The string supplied did not seem to be a phone number.

  cause The input string provided to the `parse()` function does not resemble a valid phone number, contains too few digits, or includes unexpected characters, preventing the library from recognizing it as a parseable number.
  fix Ensure the input string is a plausible phone number. This error indicates fundamental parsing failure, often requiring pre-validation of user input or a robust `try-except` block to handle malformed strings gracefully. Example: `try: number = phonenumbers.parse(input_string, 'US') except phonenumbers.phonenumberutil.NumberParseException: print('Invalid number format')`.

• AttributeError: 'str' object has no attribute 'italian_leading_zero'

  cause A function that expects a `PhoneNumber` object (returned by `phonenumbers.parse()`) was instead passed a string. This often happens after `phonenumbers.format_number()` is called, as `format_number` returns a string, not a `PhoneNumber` object.
  fix Ensure that subsequent operations requiring a `PhoneNumber` object receive the parsed object, not the formatted string. If you need to re-validate or operate on a formatted number, parse it again into a `PhoneNumber` object. Example: `parsed_number = phonenumbers.parse('+15551234567', 'US'); formatted_string = phonenumbers.format_number(parsed_number, phonenumbers.PhoneNumberFormat.E164); # If you need to validate formatted_string, you must re-parse it: re_parsed_number = phonenumbers.parse(formatted_string, None); is_valid = phonenumbers.is_valid_number(re_parsed_number)`.

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}")