0
# phonenumberslite
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: phonenumberslite
7
- **Language**: Python
8
- **Installation**: `pip install phonenumberslite`
9
- **Version**: 9.0.13
10
- **License**: Apache License 2.0
11

12
## Core Imports
13

14
```python
15
import phonenumbers
16
```
17

18
Import specific functions and classes:
19

20
```python
21
from phonenumbers import parse, format_number, PhoneNumber, PhoneNumberFormat
22
```
23

24
Import validation functions:
25

26
```python
27
from phonenumbers import is_valid_number, is_possible_number
28
```
29

30
## Basic Usage
31

32
```python
33
import phonenumbers
34
from phonenumbers import PhoneNumberFormat
35

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

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

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

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

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

54
# Validate numbers
55
is_valid = phonenumbers.is_valid_number(phone_number)
56
print(is_valid)  # True
57

58
is_possible = phonenumbers.is_possible_number(phone_number)
59
print(is_possible)  # True
60
```
61

62
## Architecture
63

64
phonenumberslite follows a clean architecture with well-separated concerns:
65

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

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

76
## Capabilities
77

78
### Core Parsing and Formatting
79

80
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.
81

82
```python { .api }
83
def parse(number: str, region: str = None, keep_raw_input: bool = False, 
84
          numobj: PhoneNumber = None, _check_region: bool = True) -> PhoneNumber: ...
85

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

88
def format_by_pattern(numobj: PhoneNumber, num_format: PhoneNumberFormat, 
89
                     user_defined_formats: list) -> str: ...
90
```
91

92
[Core Parsing and Formatting](./core-parsing-formatting.md)
93

94
### Number Validation
95

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

98
```python { .api }
99
def is_valid_number(numobj: PhoneNumber) -> bool: ...
100

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

103
def is_valid_number_for_region(numobj: PhoneNumber, region_code: str) -> bool: ...
104
```
105

106
[Number Validation](./number-validation.md)
107

108
### Utility Functions
109

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

112
```python { .api }
113
def normalize_digits_only(number: str) -> str: ...
114

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

117
def is_number_match(numobj1: PhoneNumber, numobj2: PhoneNumber) -> MatchType: ...
118
```
119

120
[Utility Functions](./utility-functions.md)
121

122
### Region and Metadata
123

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

126
```python { .api }
127
def country_code_for_region(region_code: str) -> int: ...
128

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

131
def supported_regions() -> set: ...
132
```
133

134
[Region and Metadata](./region-metadata.md)
135

136
### As-You-Type Formatting
137

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

140
```python { .api }
141
class AsYouTypeFormatter:
142
    def __init__(self, region_code: str): ...
143
    def input_digit(self, digit: str) -> str: ...
144
    def clear(self) -> AsYouTypeFormatter: ...
145
```
146

147
[As-You-Type Formatting](./as-you-type-formatting.md)
148

149
### Phone Number Matching
150

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

153
```python { .api }
154
class PhoneNumberMatcher:
155
    def __init__(self, text: str, region: str, leniency: Leniency = None, 
156
                 max_tries: int = 65536): ...
157

158
class PhoneNumberMatch:
159
    def start(self) -> int: ...
160
    def end(self) -> int: ...
161
    def number(self) -> PhoneNumber: ...
162
```
163

164
[Phone Number Matching](./phone-number-matching.md)
165

166
### Short Numbers
167

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

170
```python { .api }
171
def is_valid_short_number(numobj: PhoneNumber) -> bool: ...
172

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

175
def expected_cost(numobj: PhoneNumber) -> ShortNumberCost: ...
176
```
177

178
[Short Numbers](./short-numbers.md)
179

180
## Core Types
181

182
```python { .api }
183
class PhoneNumber:
184
    """Represents a parsed phone number with all associated metadata."""
185
    def __init__(self, country_code: int = None, national_number: int = None,
186
                 extension: str = None, italian_leading_zero: bool = None,
187
                 number_of_leading_zeros: int = None, raw_input: str = None,
188
                 country_code_source: CountryCodeSource = CountryCodeSource.UNSPECIFIED,
189
                 preferred_domestic_carrier_code: str = None): ...
190

191
class FrozenPhoneNumber(PhoneNumber):
192
    """Immutable version of PhoneNumber."""
193

194
class CountryCodeSource:
195
    """Source from which a country code is derived."""
196
    UNSPECIFIED = 0
197
    FROM_NUMBER_WITH_PLUS_SIGN = 1
198
    FROM_NUMBER_WITH_IDD = 5
199
    FROM_NUMBER_WITHOUT_PLUS_SIGN = 10
200
    FROM_DEFAULT_COUNTRY = 20
201

202
class PhoneNumberFormat:
203
    """Phone number formatting options."""
204
    E164 = 0          # +442083661177
205
    INTERNATIONAL = 1  # +44 20 8366 1177
206
    NATIONAL = 2      # 020 8366 1177
207
    RFC3966 = 3       # tel:+44-20-8366-1177
208

209
class PhoneNumberType:
210
    """Types of phone numbers."""
211
    FIXED_LINE = 0
212
    MOBILE = 1
213
    FIXED_LINE_OR_MOBILE = 2
214
    TOLL_FREE = 3
215
    PREMIUM_RATE = 4
216
    SHARED_COST = 5
217
    VOIP = 6
218
    PERSONAL_NUMBER = 7
219
    PAGER = 8
220
    UAN = 9
221
    VOICEMAIL = 10
222
    UNKNOWN = 99
223

224
class ValidationResult:
225
    """Validation outcomes for phone number possibility checks."""
226
    IS_POSSIBLE = 0
227
    IS_POSSIBLE_LOCAL_ONLY = 4
228
    INVALID_COUNTRY_CODE = 1
229
    TOO_SHORT = 2
230
    INVALID_LENGTH = 5
231
    TOO_LONG = 3
232

233
class MatchType:
234
    """Phone number match quality levels."""
235
    NOT_A_NUMBER = 0
236
    NO_MATCH = 1
237
    SHORT_NSN_MATCH = 2
238
    NSN_MATCH = 3
239
    EXACT_MATCH = 4
240
```
241

242
## Metadata Classes
243

244
```python { .api }
245
class NumberFormat:
246
    """Number formatting pattern definition for regional phone number formatting."""
247
    def __init__(self, pattern: str = None, format: str = None, 
248
                 leading_digits_pattern: list = None, national_prefix_formatting_rule: str = None,
249
                 national_prefix_optional_when_formatting: bool = False,
250
                 domestic_carrier_code_formatting_rule: str = None): ...
251

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

257
class PhoneMetadata:
258
    """Complete metadata for phone numbers in a geographic region."""
259
    def __init__(self, id: str = None, country_code: int = None, international_prefix: str = None,
260
                 national_prefix: str = None, preferred_extn_prefix: str = None,
261
                 national_prefix_for_parsing: str = None): ...
262
```
263

264
## Exception Types
265

266
```python { .api }
267
class NumberParseException(Exception):
268
    """Exception thrown when phone number parsing fails."""
269
    
270
    # Error types
271
    INVALID_COUNTRY_CODE = 0
272
    NOT_A_NUMBER = 1
273
    TOO_SHORT_NSN = 2
274
    TOO_SHORT_AFTER_IDD = 3
275
    TOO_LONG = 4
276
```
277

278
## Notable Differences from Full phonenumbers Package
279

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

282
- **Geocoder**: No `phonenumbers.geocoder` module for location information
283
- **Carrier**: No `phonenumbers.carrier` module for carrier identification  
284
- **Timezone**: No `phonenumbers.timezone` module for timezone data
285
- **Related data packages**: `geodata`, `carrierdata`, `tzdata` directories are excluded
286

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