0
# Core Operations
1

2
Essential phone number operations that form the foundation of all phone number processing. These functions handle parsing phone numbers from various string formats, formatting them for different output contexts, and validating their correctness.
3

4
## Capabilities
5

6
### Phone Number Parsing
7

8
Converts phone number strings into structured PhoneNumber objects, handling various input formats and regional contexts.
9

10
```python { .api }
11
def parse(number: str, region: str | None = None, keep_raw_input: bool = False, numobj: PhoneNumber | None = None) -> PhoneNumber:
12
    """
13
    Parse a phone number string and return a PhoneNumber object.
14
    
15
    Parameters:
16
    - number: Phone number string to parse
17
    - region: Default region code (e.g., "US", "GB") for parsing numbers without country codes
18
    - keep_raw_input: Whether to store raw input for reformatting (enables format_in_original_format)
19
    - numobj: Existing PhoneNumber to populate (optional)
20
    
21
    Returns:
22
    PhoneNumber object representing the parsed number
23
    
24
    Raises:
25
    NumberParseException: If the number cannot be parsed
26
    """
27
```
28

29
**Usage Examples:**
30

31
```python
32
# Parse international number with country code
33
phone = phonenumbers.parse("+442083661177")
34

35
# Parse national number with region context  
36
phone = phonenumbers.parse("020 8366 1177", "GB")
37

38
# Parse with raw input retention for original formatting
39
phone = phonenumbers.parse("(650) 253-2222", "US", keep_raw_input=True)
40

41
# Handle parsing errors
42
try:
43
    phone = phonenumbers.parse("invalid", "US")
44
except phonenumbers.NumberParseException as e:
45
    print(f"Parsing failed: {e}")
46
```
47

48
### Phone Number Formatting
49

50
Converts PhoneNumber objects to formatted strings in various standard formats.
51

52
```python { .api }
53
def format_number(numobj: PhoneNumber, num_format: int) -> str:
54
    """
55
    Format a phone number using the specified format.
56
    
57
    Parameters:
58
    - numobj: PhoneNumber object to format
59
    - num_format: Format type (PhoneNumberFormat.E164, INTERNATIONAL, NATIONAL, RFC3966)
60
    
61
    Returns:
62
    Formatted phone number string
63
    """
64

65
def format_by_pattern(numobj: PhoneNumber, number_format: int, user_defined_formats: list[NumberFormat]) -> str:
66
    """
67
    Format using custom user-defined formatting patterns.
68
    
69
    Parameters:
70
    - numobj: PhoneNumber object to format
71
    - number_format: Base format type
72
    - user_defined_formats: List of custom NumberFormat patterns
73
    
74
    Returns:
75
    Formatted phone number string using custom patterns
76
    """
77

78
def format_in_original_format(numobj: PhoneNumber, region_calling_from: str) -> str:
79
    """
80
    Format in the same style as the original input (requires keep_raw_input=True during parsing).
81
    
82
    Parameters:
83
    - numobj: PhoneNumber object (must have raw_input preserved)
84
    - region_calling_from: Region code for formatting context
85
    
86
    Returns:
87
    Phone number formatted to match original input style
88
    """
89
```
90

91
**Usage Examples:**
92

93
```python
94
phone = phonenumbers.parse("+442083661177")
95

96
# Different format types
97
e164 = phonenumbers.format_number(phone, phonenumbers.PhoneNumberFormat.E164)
98
# "+442083661177"
99

100
international = phonenumbers.format_number(phone, phonenumbers.PhoneNumberFormat.INTERNATIONAL)  
101
# "+44 20 8366 1177"
102

103
national = phonenumbers.format_number(phone, phonenumbers.PhoneNumberFormat.NATIONAL)
104
# "020 8366 1177"
105

106
rfc3966 = phonenumbers.format_number(phone, phonenumbers.PhoneNumberFormat.RFC3966)
107
# "tel:+44-20-8366-1177"
108

109
# Original format preservation
110
phone = phonenumbers.parse("(650) 253-2222", "US", keep_raw_input=True)
111
original = phonenumbers.format_in_original_format(phone, "US")  
112
# "(650) 253-2222"
113
```
114

115
### International and Mobile Formatting
116

117
Specialized formatting for international dialing and mobile contexts.
118

119
```python { .api }
120
def format_out_of_country_calling_number(numobj: PhoneNumber, region_calling_from: str) -> str:
121
    """
122
    Format for calling from one country to another.
123
    
124
    Parameters:
125
    - numobj: PhoneNumber to format
126
    - region_calling_from: Region code where the call originates
127
    
128
    Returns:
129
    Number formatted for international dialing from the specified region
130
    """
131

132
def format_number_for_mobile_dialing(numobj: PhoneNumber, region_calling_from: str, with_formatting: bool) -> str:
133
    """
134
    Format for mobile dialing from specified region.
135
    
136
    Parameters:
137
    - numobj: PhoneNumber to format
138
    - region_calling_from: Region code for mobile dialing context
139
    - with_formatting: Whether to include spacing and punctuation
140
    
141
    Returns:
142
    Number formatted for mobile dialing
143
    """
144

145
def format_out_of_country_keeping_alpha_chars(numobj: PhoneNumber, region_calling_from: str) -> str:
146
    """
147
    Format for international calling while preserving alphabetic characters.
148
    
149
    Parameters:
150
    - numobj: PhoneNumber with potential alpha characters
151
    - region_calling_from: Region code for calling context
152
    
153
    Returns:
154
    Formatted number preserving letters (e.g., 1-800-FLOWERS)
155
    """
156
```
157

158
### Carrier Code Formatting
159

160
National formatting with carrier-specific prefixes.
161

162
```python { .api }
163
def format_national_number_with_carrier_code(numobj: PhoneNumber, carrier_code: str) -> str:
164
    """
165
    Format in national format with specified carrier code.
166
    
167
    Parameters:
168
    - numobj: PhoneNumber to format
169
    - carrier_code: Carrier access code to include
170
    
171
    Returns:
172
    National format with carrier code prefix
173
    """
174

175
def format_national_number_with_preferred_carrier_code(numobj: PhoneNumber, fallback_carrier_code: str) -> str:
176
    """
177
    Format in national format using preferred carrier code or fallback.
178
    
179
    Parameters:
180
    - numobj: PhoneNumber (may have preferred_domestic_carrier_code set)
181
    - fallback_carrier_code: Carrier code to use if none preferred
182
    
183
    Returns:
184
    National format with preferred or fallback carrier code
185
    """
186
```
187

188
### Phone Number Validation
189

190
Comprehensive validation functions for checking phone number correctness and possibility.
191

192
```python { .api }
193
def is_valid_number(numobj: PhoneNumber) -> bool:
194
    """
195
    Check if number is valid and can be used for connecting calls.
196
    
197
    Parameters:
198
    - numobj: PhoneNumber to validate
199
    
200
    Returns:
201
    True if the number is valid for calling
202
    """
203

204
def is_valid_number_for_region(numobj: PhoneNumber, region_code: str) -> bool:
205
    """
206
    Check if number is valid for the specified region.
207
    
208
    Parameters:
209
    - numobj: PhoneNumber to validate  
210
    - region_code: Region code to validate against
211
    
212
    Returns:
213
    True if the number is valid in the specified region
214
    """
215

216
def is_possible_number(numobj: PhoneNumber) -> bool:
217
    """
218
    Check if number could be a valid phone number (length-based check).
219
    
220
    Parameters:
221
    - numobj: PhoneNumber to check
222
    
223
    Returns:
224
    True if the number has valid length characteristics
225
    """
226

227
def is_possible_number_for_type(numobj: PhoneNumber, numtype: int) -> bool:
228
    """
229
    Check if number is possible for the specified type.
230
    
231
    Parameters:
232
    - numobj: PhoneNumber to check
233
    - numtype: PhoneNumberType value to check against
234
    
235
    Returns:
236
    True if the number could be valid for the specified type
237
    """
238

239
def is_possible_number_with_reason(numobj: PhoneNumber) -> int:
240
    """
241
    Check possibility and return detailed reason.
242
    
243
    Parameters:
244
    - numobj: PhoneNumber to validate
245
    
246
    Returns:
247
    ValidationResult value indicating why number may not be possible
248
    """
249

250
def is_possible_number_for_type_with_reason(numobj: PhoneNumber, numtype: int) -> int:
251
    """
252
    Check possibility for specific type and return detailed reason.
253
    
254
    Parameters:
255
    - numobj: PhoneNumber to validate
256
    - numtype: PhoneNumberType value to check against
257
    
258
    Returns:
259
    ValidationResult value for the specific number type
260
    """
261

262
def is_possible_number_string(number: str, region_dialing_from: str) -> bool:
263
    """
264
    Check if number string could be possible from given region without full parsing.
265
    
266
    Parameters:
267
    - number: Phone number string
268
    - region_dialing_from: Region code for parsing context
269
    
270
    Returns:
271
    True if the string could represent a valid phone number
272
    """
273
```
274

275
**Usage Examples:**
276

277
```python
278
phone = phonenumbers.parse("+442083661177")
279

280
# Basic validation
281
is_valid = phonenumbers.is_valid_number(phone)  # True
282
is_possible = phonenumbers.is_possible_number(phone)  # True
283

284
# Regional validation
285
is_valid_uk = phonenumbers.is_valid_number_for_region(phone, "GB")  # True
286
is_valid_us = phonenumbers.is_valid_number_for_region(phone, "US")  # False
287

288
# Type-specific validation
289
is_possible_mobile = phonenumbers.is_possible_number_for_type(
290
    phone, phonenumbers.PhoneNumberType.MOBILE
291
)
292

293
# Detailed validation reasons
294
reason = phonenumbers.is_possible_number_with_reason(phone)
295
if reason == phonenumbers.ValidationResult.IS_POSSIBLE:
296
    print("Number is possible")
297
elif reason == phonenumbers.ValidationResult.TOO_SHORT:
298
    print("Number is too short")
299

300
# Quick string validation
301
is_possible_str = phonenumbers.is_possible_number_string("020 8366 1177", "GB")
302
```
303

304
### Number Type Detection
305

306
Determine the type and classification of phone numbers.
307

308
```python { .api }
309
def number_type(numobj: PhoneNumber) -> int:
310
    """
311
    Determine the type of phone number.
312
    
313
    Parameters:
314
    - numobj: PhoneNumber to classify
315
    
316
    Returns:
317
    PhoneNumberType value (FIXED_LINE, MOBILE, TOLL_FREE, etc.)
318
    """
319
```
320

321
**Usage Examples:**
322

323
```python
324
phone = phonenumbers.parse("+442083661177")
325
num_type = phonenumbers.number_type(phone)
326

327
if num_type == phonenumbers.PhoneNumberType.FIXED_LINE:
328
    print("This is a landline number")
329
elif num_type == phonenumbers.PhoneNumberType.MOBILE:
330
    print("This is a mobile number")
331
elif num_type == phonenumbers.PhoneNumberType.TOLL_FREE:
332
    print("This is a toll-free number")
333

334
# Check for specific types
335
mobile_phone = phonenumbers.parse("+447700123456")
336
is_mobile = phonenumbers.number_type(mobile_phone) == phonenumbers.PhoneNumberType.MOBILE
337
```
338

339
### Number Comparison and Matching
340

341
Compare phone numbers to determine if they represent the same number.
342

343
```python { .api }
344
def is_number_match(num1: PhoneNumber | str, num2: PhoneNumber | str) -> int:
345
    """
346
    Compare two numbers and return MatchType indicating similarity level.
347
    
348
    Parameters:
349
    - num1: First number (PhoneNumber object or string)
350
    - num2: Second number (PhoneNumber object or string)
351
    
352
    Returns:
353
    MatchType value indicating the level of match
354
    """
355
```
356

357
**Usage Examples:**
358

359
```python
360
phone1 = phonenumbers.parse("+442083661177")
361
phone2 = phonenumbers.parse("020 8366 1177", "GB")
362

363
match_result = phonenumbers.is_number_match(phone1, phone2)
364

365
if match_result == phonenumbers.MatchType.EXACT_MATCH:
366
    print("Numbers are exactly the same")
367
elif match_result == phonenumbers.MatchType.NSN_MATCH:
368
    print("National significant numbers match")
369
elif match_result == phonenumbers.MatchType.NO_MATCH:
370
    print("Numbers don't match")
371

372
# Can also compare strings directly
373
match_result = phonenumbers.is_number_match("+442083661177", "020 8366 1177")
374
```
375

376
### Number Manipulation
377

378
Utility functions for extracting and modifying phone number components.
379

380
```python { .api }
381
def national_significant_number(numobj: PhoneNumber) -> str:
382
    """
383
    Extract national significant number as string.
384
    
385
    Parameters:
386
    - numobj: PhoneNumber to extract from
387
    
388
    Returns:
389
    National significant number without country code
390
    """
391

392
def truncate_too_long_number(numobj: PhoneNumber) -> bool:
393
    """
394
    Truncate number that's too long to make it valid.
395
    
396
    Parameters:
397
    - numobj: PhoneNumber to potentially truncate (modified in place)
398
    
399
    Returns:
400
    True if the number was modified, False otherwise
401
    """
402

403
def length_of_geographical_area_code(numobj: PhoneNumber) -> int:
404
    """
405
    Get length of geographical area code.
406
    
407
    Parameters:
408
    - numobj: PhoneNumber to analyze
409
    
410
    Returns:
411
    Length of area code in digits, 0 if no area code
412
    """
413

414
def length_of_national_destination_code(numobj: PhoneNumber) -> int:
415
    """
416
    Get length of national destination code.
417
    
418
    Parameters:
419
    - numobj: PhoneNumber to analyze
420
    
421
    Returns:
422
    Length of national destination code in digits
423
    """
424
```