or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

as-you-type-formatting.md core-parsing-formatting.md index.md number-validation.md phone-number-matching.md region-metadata.md short-numbers.md utility-functions.md

tile.json

tessl/pypi-phonenumberslite

Python library for parsing, formatting, storing and validating international phone numbers with reduced memory footprint

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:pypi/phonenumberslite@9.0.x

To install, run

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

phonenumberslite

A memory-optimized Python library for parsing, formatting, storing and validating international phone numbers. This is the "lite" version of Google's libphonenumber library that excludes geocoder, carrier, and timezone metadata to reduce memory footprint while maintaining all core phone number processing functionality.

Package Information

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

Core Imports

import phonenumbers

Import specific functions and classes:

from phonenumbers import parse, format_number, PhoneNumber, PhoneNumberFormat

Import validation functions:

from phonenumbers import is_valid_number, is_possible_number

Basic Usage

import phonenumbers
from phonenumbers import PhoneNumberFormat

# Parse a phone number
phone_number = phonenumbers.parse("+442083661177", None)
print(phone_number)  # Country Code: 44 National Number: 2083661177

# Format in different ways
national = phonenumbers.format_number(phone_number, PhoneNumberFormat.NATIONAL)
print(national)  # 020 8366 1177

international = phonenumbers.format_number(phone_number, PhoneNumberFormat.INTERNATIONAL)
print(international)  # +44 20 8366 1177

e164 = phonenumbers.format_number(phone_number, PhoneNumberFormat.E164)
print(e164)  # +442083661177

# Parse with region context
uk_number = phonenumbers.parse("020 8366 1177", "GB")
print(uk_number == phone_number)  # True

# Validate numbers
is_valid = phonenumbers.is_valid_number(phone_number)
print(is_valid)  # True

is_possible = phonenumbers.is_possible_number(phone_number)
print(is_possible)  # True

Architecture

phonenumberslite follows a clean architecture with well-separated concerns:

Core Data Models: PhoneNumber and FrozenPhoneNumber classes represent parsed phone numbers with metadata
Parser Engine: Functions like parse() handle various input formats and regional contexts
Formatters: Multiple formatting options (E164, international, national, RFC3966) for different use cases
Validators: Comprehensive validation system checking number possibility, validity, and type classification
Regional Metadata: Built-in metadata for country codes, dialing patterns, and numbering plans
As-You-Type Formatting: Interactive formatting for user input interfaces
Pattern Matching: Advanced text processing to find phone numbers in unstructured text

The library is designed for high performance and accuracy, based on Google's authoritative libphonenumber data and algorithms.

Capabilities

Core Parsing and Formatting

Essential functions for parsing phone number strings into structured objects and formatting them for display or storage. Supports multiple input formats and international/national output formats.

def parse(number: str, region: str = None, keep_raw_input: bool = False, 
          numobj: PhoneNumber = None, _check_region: bool = True) -> PhoneNumber: ...

def format_number(numobj: PhoneNumber, num_format: PhoneNumberFormat) -> str: ...

def format_by_pattern(numobj: PhoneNumber, num_format: PhoneNumberFormat, 
                     user_defined_formats: list) -> str: ...

Core Parsing and Formatting

Number Validation

Comprehensive validation functions to check if phone numbers are valid, possible, or match specific criteria. Includes detailed validation reasons and type checking.

def is_valid_number(numobj: PhoneNumber) -> bool: ...

def is_possible_number(numobj: PhoneNumber) -> bool: ...

def is_valid_number_for_region(numobj: PhoneNumber, region_code: str) -> bool: ...

Number Validation

Utility Functions

Helper functions for normalizing, converting, and analyzing phone numbers. Includes string manipulation, character conversion, and number comparison utilities.

def normalize_digits_only(number: str) -> str: ...

def convert_alpha_characters_in_number(number: str) -> str: ...

def is_number_match(numobj1: PhoneNumber, numobj2: PhoneNumber) -> MatchType: ...

Utility Functions

Region and Metadata

Functions for working with country codes, region codes, and geographical information. Provides access to supported regions, calling codes, and number type information.

def country_code_for_region(region_code: str) -> int: ...

def region_code_for_number(numobj: PhoneNumber) -> str: ...

def supported_regions() -> set: ...

Region and Metadata

As-You-Type Formatting

Interactive phone number formatting for user interfaces, providing real-time formatting as users type phone numbers.

class AsYouTypeFormatter:
    def __init__(self, region_code: str): ...
    def input_digit(self, digit: str) -> str: ...
    def clear(self) -> AsYouTypeFormatter: ...

As-You-Type Formatting

Phone Number Matching

Advanced pattern matching to find and extract phone numbers from text, with configurable leniency levels and comprehensive match information.

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

class PhoneNumberMatch:
    def start(self) -> int: ...
    def end(self) -> int: ...
    def number(self) -> PhoneNumber: ...

Phone Number Matching

Short Numbers

Support for emergency numbers, short codes, and special service numbers with cost information and regional validation.

def is_valid_short_number(numobj: PhoneNumber) -> bool: ...

def is_emergency_number(number: str, region_code: str) -> bool: ...

def expected_cost(numobj: PhoneNumber) -> ShortNumberCost: ...

Short Numbers

Core Types

class PhoneNumber:
    """Represents a parsed phone number with all associated metadata."""
    def __init__(self, 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: CountryCodeSource = CountryCodeSource.UNSPECIFIED,
                 preferred_domestic_carrier_code: str = None): ...

class FrozenPhoneNumber(PhoneNumber):
    """Immutable version of PhoneNumber."""

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 PhoneNumberFormat:
    """Phone number formatting options."""
    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 ValidationResult:
    """Validation outcomes for phone number possibility checks."""
    IS_POSSIBLE = 0
    IS_POSSIBLE_LOCAL_ONLY = 4
    INVALID_COUNTRY_CODE = 1
    TOO_SHORT = 2
    INVALID_LENGTH = 5
    TOO_LONG = 3

class MatchType:
    """Phone number match quality levels."""
    NOT_A_NUMBER = 0
    NO_MATCH = 1
    SHORT_NSN_MATCH = 2
    NSN_MATCH = 3
    EXACT_MATCH = 4

Metadata Classes

class NumberFormat:
    """Number formatting pattern definition for regional phone number formatting."""
    def __init__(self, pattern: str = None, format: str = None, 
                 leading_digits_pattern: list = None, national_prefix_formatting_rule: str = None,
                 national_prefix_optional_when_formatting: bool = False,
                 domestic_carrier_code_formatting_rule: str = None): ...

class PhoneNumberDesc:
    """Phone number description with validation patterns and example numbers."""
    def __init__(self, national_number_pattern: str = None, possible_number_pattern: str = None,
                 example_number: str = None): ...

class PhoneMetadata:
    """Complete metadata for phone numbers in a geographic region."""
    def __init__(self, id: str = None, country_code: int = None, international_prefix: str = None,
                 national_prefix: str = None, preferred_extn_prefix: str = None,
                 national_prefix_for_parsing: str = None): ...

Exception Types

class NumberParseException(Exception):
    """Exception thrown when phone number parsing fails."""
    
    # Error types
    INVALID_COUNTRY_CODE = 0
    NOT_A_NUMBER = 1
    TOO_SHORT_NSN = 2
    TOO_SHORT_AFTER_IDD = 3
    TOO_LONG = 4

Notable Differences from Full phonenumbers Package

The phonenumberslite package excludes the following modules to reduce memory footprint:

Geocoder: No phonenumbers.geocoder module for location information
Carrier: No phonenumbers.carrier module for carrier identification
Timezone: No phonenumbers.timezone module for timezone data
Related data packages: geodata, carrierdata, tzdata directories are excluded

All core parsing, formatting, validation, and utility functions remain fully available.

Version

Tile

Files

tessl/pypi-phonenumberslite

To install, run

index.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

phonenumberslite

Package Information

Core Imports

Basic Usage

Architecture

Capabilities

Core Parsing and Formatting

Number Validation

Utility Functions

Region and Metadata

As-You-Type Formatting

Phone Number Matching

Short Numbers

Core Types

Metadata Classes

Exception Types

Notable Differences from Full phonenumbers Package

index.mddocs/