DOCSEARCHbyAlgolia
Submit Docs

phonenumbers

repository·dev·Indexed 25 days ago

https://github.com/daviddrysdale/python-phonenumbers

A Python port of Google's libphonenumber library used for parsing, formatting, storing, and validating international phone numbers. It provides utilities for checking number validity, extracting numbers from text via PhoneNumberMatcher, and retrieving metadata such as geocoding, carrier names, and timezones. The library offers a full version and a reduced 'phonenumberslite' version for smaller package sizes.

Tokens
10.1K
Snippets
23
Records
90
Agent score
86%

What's inside phonenumbers

  1. Understand the difference between phonenumbers and phonenumberslite

    dev

    The library provides two versions of the package:

    • phonenumbers: The full version containing all metadata.
    • phonenumberslite: A reduced version designed for smaller package size. It excludes prefix-based metadata, meaning phonenumbers.geodata, phonenumbers.carrierdata, and phonenumbers.tzdata are unavailable in this version.

  3. Manage memory usage and metadata loading

    dev

    The library loads metadata on-demand. To prevent memory spikes or pauses during runtime, you can force-load metadata at application startup:

    • Core metadata: Call phonenumbers.PhoneMetadata.load_all().
    • Geocoding metadata: import phonenumbers.geocoder.
    • Carrier metadata: import phonenumbers.carrier.
    • Timezone metadata: import phonenumbers.timezone.

    If you have strict memory/space constraints, use the phonenumberslite package, which excludes geocoder, carrier, and timezone metadata.

  4. Map phone numbers to timezones using Timezone Mapper

    dev

    The timezone mapper provides the canonical CLDR (Unicode Common Locale Data Repository) timezone ID for a given phone number.

    Key Behaviors:

    • Returns the canonical ID (e.g., Asia/Calcutta), not a localized name.
    • For mobile phones, it returns the timezone associated with the specific area code.
    • It does not track user location; it only maps the number's area code to a likely timezone.
    • This is useful for determining if it is a suitable time to contact a user based on their phone number.
    PhoneNumberToTimeZonesMapper timeZonesMapper = PhoneNumberToTimeZonesMapper.getInstance();

List<String> timezones = timeZonesMapper.getTimeZonesForNumber(phoneNumber);

  10. Extract phone numbers from text with PhoneNumberMatcher

    dev
    Use phonenumbers.PhoneNumberMatcher(text, region) to find phone numbers within a larger block of text. It returns an iterable of PhoneNumberMatch objects. Each match contains a .number (the PhoneNumber object) and the span of the match in the original string.

  11. Validate phone numbers

    dev

    After parsing, use these functions to check the quality of the number:

    • phonenumbers.is_possible_number(phone_number): Checks if the number has the correct number of digits for the region.
    • phonenumbers.is_valid_number(phone_number): Checks if the number is actually assigned to an exchange.

  12. Parse phone numbers with parse()

    dev

    Use phonenumbers.parse(string, region) to create a PhoneNumber object.

    • If the string is in E.164 format (e.g., +44...), the region can be None.
    • If the string is a local format, you must provide a region (e.g., "GB") to uniquely identify the number.

    Note: parse() raises phonenumbers.phonenumberutil.NumberParseException if the input cannot be uniquely parsed or is not a valid phone number format.

    import phonenumbers
# From E.164 format
x = phonenumbers.parse("+442083661177", None)
# From local format
y = phonenumbers.parse("020 8366 1177", "GB")