### Example usage of expected_cost_for_region

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.shortnumberinfo.html

Demonstrates how to check the validity of a short number for a region and then get its expected cost. This example uses '110' in France.

```python
short_number = "110"
region_code = "FR"
if phonenumbers.is_valid_short_number_for_region(short_number, region_code):
    cost = phonenumbers.expected_cost(short_number, region_code) # ShortNumberCost

```

--------------------------------

### example_number

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Retrieves a valid example phone number for a given region.

```APIDOC
## example_number(region_code)

### Description
Gets a valid number for the specified region.

### Parameters
#### Arguments
- **region_code** (string) - Required - The region for which an example number is needed.

### Response
- **PhoneNumber** - A valid fixed-line number for the specified region, or None if not available.
```

--------------------------------

### Get Time Zones for a Phone Number

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.timezone.html

Demonstrates how to get a list of time zones associated with a given phone number. This example shows mapping a Romanian number to a single time zone and a Mongolian number to multiple time zones.

```python
import phonenumbers
from phonenumbers.timezone import time_zones_for_number

ro_number = phonenumbers.parse("+40721234567", "RO")
tzlist = time_zones_for_number(ro_number)
print(len(tzlist))
print(str(tzlist[0]))

dual_number = phonenumbers.parse("+976136234567", "US")
tzlist = time_zones_for_number(dual_number)
print(len(tzlist))
print(str(tzlist[0]))
print(str(tzlist[1]))
```

--------------------------------

### Accessing PhoneNumberMatch properties

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Example usage of accessing start and end indices of a matched phone number and verifying the match object.

```python
>>> (m.start, m.end) # define the range of the matched subsequence.  
(11, 26)  
>>> text[m.start, m.end]  
"+1 425 882-8080"  
>>> phonenumberutil.parse("+1 425 882-8080", "US") == m.number  
True
```

--------------------------------

### GET /supported_calling_codes

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Retrieves all country calling codes supported by the library.

```APIDOC
## GET /supported_calling_codes

### Description
Returns an unordered set of all country calling codes the library has metadata for, including both geographical and non-geographical entities.
```

--------------------------------

### example_number

Source: https://daviddrysdale.github.io/python-phonenumbers

Gets a valid fixed-line phone number for a specified region. Returns None if the region code is invalid, does not contain such information, or if '001' (non-geographical numbers) is passed.

```APIDOC
## example_number

### Description
Gets a valid number for the specified region.

### Arguments
- **region_code** (string) - The region for which an example number is needed.

### Returns
(PhoneNumber object or None) - A valid fixed-line number for the specified region. Returns None when the metadata does not contain such information, or the region '001' is passed in. For '001' (representing non-geographical numbers), call `example_number_for_non_geo_entity` instead.
```

--------------------------------

### Invalid Example Number

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Retrieves an invalid phone number for a specified region, useful for unit testing.

```APIDOC
## invalid_example_number

### Description
Gets an invalid number for the specified region.

This is useful for unit-testing purposes, where you want to test what will happen with an invalid number. Note that the number that is returned will always be able to be parsed and will have the correct country code. It may also be a valid *short* number/code for this region. Validity checking such numbers is handled with shortnumberinfo.

### Arguments
- **region_code** (string) - The region for which an example number is needed.

### Returns
(string or None) An invalid number for the specified region. Returns None when an unsupported region or the region 001 (Earth) is passed in.
```

--------------------------------

### Map Phone Number to Carrier Name

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.carrier.html

Example usage of name_for_number to retrieve the carrier name for a parsed phone number in a specified language.

```python
>>> import phonenumbers
>>> from phonenumbers.carrier import name_for_number
>>> ro_number = phonenumbers.parse("+40721234567", "RO")
>>> str(name_for_number(ro_number, "en"))
'Vodafone'
>>> str(name_for_number(ro_number, "fr")) # fall back to English
'Vodafone'
```

--------------------------------

### GET /number_type

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Determines the type of a valid phone number.

```APIDOC
## GET /number_type

### Description
Gets the type of a valid phone number (e.g., mobile, fixed line).

### Method
GET

### Endpoint
/number_type

### Parameters
#### Query Parameters
- **numobj** (object) - Required - The PhoneNumber object.
```

--------------------------------

### example_number_for_type

Source: https://daviddrysdale.github.io/python-phonenumbers

Gets a valid phone number for a specified region and number type. If `region_code` is None, the number may belong to any country. Returns None if the metadata does not contain the information or if an invalid region is specified. For non-geographical numbers ('001'), use `example_number_for_non_geo_entity`.

```APIDOC
## example_number_for_type

### Description
Gets a valid number for the specified region and number type.

If None is given as the region_code, then the returned number object may belong to any country.

### Arguments
- **region_code** (string or None) - The region for which an example number is needed, or None.
- **num_type** (NumberType enum) - The type of number that is needed.

### Returns
(PhoneNumber object or None) - A valid number for the specified region and type. Returns None when the metadata does not contain such information or if an invalid region or region '001' was specified. For '001' (representing non-geographical numbers), call `example_number_for_non_geo_entity` instead.
```

--------------------------------

### GET /ndd_prefix_for_region

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Returns the national dialling prefix for a specific region.

```APIDOC
## GET /ndd_prefix_for_region

### Description
Returns the national dialling prefix for a specific region code.

### Method
GET

### Endpoint
/ndd_prefix_for_region

### Parameters
#### Query Parameters
- **region_code** (string) - Required - The region code.
- **strip_non_digits** (boolean) - Required - Whether to strip non-digits from the prefix.
```

--------------------------------

### GET /parse

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Parses a string into a PhoneNumber object, handling various formats and vanity numbers.

```APIDOC
## GET /parse

### Description
Parses a string and returns a corresponding PhoneNumber object. It is lenient, ignores punctuation/whitespace, and attempts to convert alpha characters to digits.

### Method
GET

### Endpoint
/parse

### Parameters
#### Query Parameters
- **number** (string) - Required - The number to parse.
- **region** (string) - Optional - The region expected if not in international format.
- **keep_raw_input** (boolean) - Optional - Whether to populate the raw_input field.
- **numobj** (object) - Optional - Existing PhoneNumber object to receive results.

### Response
#### Success Response (200)
- **PhoneNumber** (object) - The parsed phone number object.
```

--------------------------------

### expected_cost

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.shortnumberinfo.html

Gets the expected cost category of a short number based on its country calling code.

```APIDOC
## expected_cost(numobj)

### Description
Gets the expected cost category of a short number. If the country calling code is shared by multiple regions, it returns the highest cost in the sequence PREMIUM_RATE, UNKNOWN_COST, STANDARD_RATE, TOLL_FREE.

### Parameters
#### Arguments
- **numobj** (object) - The short number for which we want to know the expected cost category.

### Response
- **Returns** (ShortNumberCost) - The highest expected cost category of the short number.
```

--------------------------------

### Example of using national_significant_number with length_of_national_destination_code

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Illustrates how to split a national significant number into its national destination code (NDC) and subscriber number. Note that not all numbers have an NDC.

```python
>>> import phonenumbers
>>> numobj = phonenumbers.parse("18002530000", "US")
>>> nsn = phonenumbers.national_significant_number(numobj)
>>> ndc_len = phonenumbers.length_of_national_destination_code(numobj)
>>> if ndc_len > 0:
... national_destination_code = nsn[:ndc_len]
... subscriber_number = nsn[ndc_len:]
... else:
... national_destination_code = ""
... subscriber_number = nsn
```

--------------------------------

### GET /is_number_match

Source: https://daviddrysdale.github.io/python-phonenumbers

Compares two phone numbers for equality based on various matching criteria.

```APIDOC
## GET /is_number_match

### Description
Takes two phone numbers and compares them for equality.

### Method
GET

### Endpoint
/is_number_match

### Parameters
#### Query Parameters
- **num1** (string) - Required - First number object or string to compare.
- **num2** (string) - Required - Second number object or string to compare.

### Response
#### Success Response (200)
- **match_type** (string) - Returns one of: EXACT_MATCH, NSN_MATCH, SHORT_NSN_MATCH, or NO_MATCH.
```

--------------------------------

### expected_cost_for_region

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.shortnumberinfo.html

Gets the expected cost category of a short number when dialed from a specific region.

```APIDOC
## expected_cost_for_region(short_numobj, region_dialing_from)

### Description
Gets the expected cost category of a short number when dialed from a specific region. Emergency numbers are always considered toll-free.

### Parameters
#### Arguments
- **short_numobj** (object) - The short number object.
- **region_dialing_from** (string) - The region from which the number is dialed.

### Response
- **Returns** (ShortNumberCost) - The expected cost category.
```

--------------------------------

### Example of using national_significant_number with length_of_geographical_area_code

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Demonstrates how to extract the geographical area code and subscriber number from a parsed phone number object. This method should be used with caution as area codes can change and may not be universally diallable.

```python
>>> import phonenumbers
>>> numobj = phonenumbers.parse("16502530000", "US")
>>> nsn = phonenumbers.national_significant_number(numobj)
>>> ac_len = phonenumbers.length_of_geographical_area_code(numobj)
>>> if ac_len > 0:
... area_code = nsn[:ac_len]
... subscriber_number = nsn[ac_len:]
... else:
... area_code = ""
... subscriber_number = nsn
```

--------------------------------

### example_number_for_non_geo_entity

Source: https://daviddrysdale.github.io/python-phonenumbers

Gets a valid phone number for a non-geographical entity associated with a given country calling code. Returns None if the country calling code does not belong to a non-geographical entity or if the metadata does not contain such information.

```APIDOC
## example_number_for_non_geo_entity

### Description
Gets a valid number for the specified country calling code for a non-geographical entity.

### Arguments
- **country_calling_code** (integer) - The country calling code for a non-geographical entity.

### Returns
(PhoneNumber object or None) - A valid number for the non-geographical entity. Returns None when the metadata does not contain such information, or the country calling code passed in does not belong to a non-geographical entity.
```

--------------------------------

### expected_cost

Source: https://daviddrysdale.github.io/python-phonenumbers

Gets the expected cost category of a short number. If the country calling code is unique to a region, it behaves like `expected_cost_for_region`. If the code is shared, it returns the highest cost category among the regions (PREMIUM_RATE > UNKNOWN_COST > STANDARD_RATE > TOLL_FREE). It's preferable to use `expected_cost_for_region` if the dialing region is known.

```APIDOC
## expected_cost

### Description
Gets the expected cost category of a short number (however, nothing is implied about its validity). If the country calling code is unique to a region, this method behaves exactly the same as `expected_cost_for_region`. However, if the country calling code is shared by multiple regions, then it returns the highest cost in the sequence PREMIUM_RATE, UNKNOWN_COST, STANDARD_RATE, TOLL_FREE. The reason for the position of UNKNOWN_COST in this order is that if a number is UNKNOWN_COST in one region but STANDARD_RATE or TOLL_FREE in another, its expected cost cannot be estimated as one of the latter since it might be a PREMIUM_RATE number.

For example, if a number is STANDARD_RATE in the US, but TOLL_FREE in Canada, the expected cost returned by this method will be STANDARD_RATE, since the NANPA countries share the same country calling code.

Note: If the region from which the number is dialed is known, it is highly preferable to call `expected_cost_for_region` instead.

### Arguments
- **numobj** (PhoneNumber object) - The short number for which we want to know the expected cost category.

### Returns
(CostCategory enum) - The highest expected cost category of the short number in the region(s) with the given country calling code.
```

--------------------------------

### Match phone numbers in text with PhoneNumberMatcher

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumbermatcher.html

Demonstrates how to initialize a PhoneNumberMatcher, iterate through matches, and verify match details like offsets and the parsed number.

```python
>>> text = "Call me at +1 425 882-8080 for details."
>>> country = "US"
>>> import phonenumbers
>>> matcher = phonenumbers.PhoneNumberMatcher(text, country)
>>> matcher.has_next()
True
>>> m = matcher.next() # Find the first phone number match
>>> m.raw_string # contains the phone number as it appears in the text.
"+1 425 882-8080"
>>> (m.start, m.end) # define the range of the matched subsequence.
(11, 26)
>>> text[m.start, m.end]
"+1 425 882-8080"
>>> phonenumberutil.parse("+1 425 882-8080", "US") == m.number
True
```

--------------------------------

### Geocode Phone Numbers with Python

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.geocoder.html

Demonstrates how to parse phone numbers and retrieve their geographical descriptions in different languages and regions.

```python
>>> import phonenumbers
>>> from phonenumbers.geocoder import description_for_number
>>> from phonenumbers.util import u
>>> gb_number = phonenumbers.parse("+442083612345", "GB")
>>> de_number = phonenumbers.parse("0891234567", "DE")
>>> ch_number = phonenumbers.parse("0431234567", "CH")
>>> str(description_for_number(gb_number, "en"))
'London'
>>> str(description_for_number(gb_number, "fr")) # fall back to English
'London'
>>> str(description_for_number(gb_number, "en", region="GB"))
'London'
>>> str(description_for_number(gb_number, "en", region="US")) # fall back to country
'United Kingdom'
>>> str(description_for_number(de_number, "en"))
'Munich'
>>> u('München') == description_for_number(de_number, "de")
True
>>> u('Zürich') == description_for_number(ch_number, "de")
True
>>> str(description_for_number(ch_number, "en"))
'Zurich'
>>> str(description_for_number(ch_number, "fr"))
'Zurich'
>>> str(description_for_number(ch_number, "it"))
'Zurigo'
```

--------------------------------

### number_type

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Gets the type of a valid phone number.

```APIDOC
## number_type(numobj)

### Description
Gets the type of a valid phone number.

### Arguments
- **numobj** (PhoneNumber) - The PhoneNumber object that we want to know the type of.

### Returns
- (PhoneNumberType) The type of the phone number, as a PhoneNumberType value; returns PhoneNumberType.UNKNOWN if it is invalid.
```

--------------------------------

### Use AsYouTypeFormatter in Python

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Illustrates how to use the AsYouTypeFormatter to format phone numbers as digits are entered, providing real-time formatting for a US number.

```python
formatter = phonenumbers.AsYouTypeFormatter("US")
prnt(formatter.input_digit("6"))
prnt(formatter.input_digit("5"))
prnt(formatter.input_digit("0"))
prnt(formatter.input_digit("2"))
prnt(formatter.input_digit("5"))
prnt(formatter.input_digit("3"))
prnt(formatter.input_digit("2"))
prnt(formatter.input_digit("2"))
prnt(formatter.input_digit("2"))
prnt(formatter.input_digit("2"))
```

--------------------------------

### Initializing PhoneNumberMatcher

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Constructor signature for the PhoneNumberMatcher class, which is used to extract phone numbers from text.

```python
PhoneNumberMatcher(text, region, leniency=1, max_tries=65535)
```

--------------------------------

### Utility Functions

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.util.html

Functions for handling cross-version string compatibility, printing, and object representation.

```APIDOC
## Utility Functions

### Description
Collection of functions to ensure consistent behavior across Python 2.x and 3.x environments.

### Functions
- **prnt(*args, **kwargs)**: Prints arguments to a file with specified separator and ending.
- **to_long(val)**: Creates a long integer object from the input.
- **u(s)**: Allows string literals with non-ASCII characters to be used in both Python 2 and 3.
- **unicod(s)**: Forces the argument to a Unicode string.
- **rpr(s)**: Generates a string representation compatible with both Python 2 and 3.
- **force_unicode(s)**: Forces the argument to be a Unicode string, preserving None.
- **mutating_method(func)**: Decorator for methods allowed to modify immutable objects.
```

--------------------------------

### Parse and Format Phone Numbers in Python

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Demonstrates parsing a phone number with a country code and formatting it into NATIONAL, INTERNATIONAL, and E164 formats. Also shows parsing a local number with a region code.

```python
import phonenumbers
from phonenumbers.util import prnt # equivalent to Py3k print()
x = phonenumbers.parse("+442083661177", None)
prnt(x)

str(phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.NATIONAL))
str(phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.INTERNATIONAL))
str(phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.E164))

y = phonenumbers.parse("020 8366 1177", "GB")
prnt(y)
x == y
```

--------------------------------

### GET /national_significant_number

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Retrieves the national significant number from a PhoneNumber object.

```APIDOC
## GET /national_significant_number

### Description
Gets the national significant number of a phone number, excluding national prefixes or formatting.

### Method
GET

### Endpoint
/national_significant_number

### Parameters
#### Query Parameters
- **numobj** (object) - Required - The PhoneNumber object.
```

--------------------------------

### Finding Phone Numbers in Text

Source: https://daviddrysdale.github.io/python-phonenumbers

Demonstrates how to find and extract phone numbers from a given text using `PhoneNumberMatcher`.

```APIDOC
## Finding Phone Numbers in Text

### Description
This section illustrates how to use `PhoneNumberMatcher` to iterate over all phone numbers found within a piece of text, specifying the default region for parsing.

### Usage

```python
import phonenumbers
from phonenumbers.util import prnt

text = "Call me at 510-748-8230 if it\'s before 9:30, or on 703-4800500 after 10am."

# Iterate over found phone numbers and print match details
for match in phonenumbers.PhoneNumberMatcher(text, "US"):
    prnt(match)
# Output:
# PhoneNumberMatch [11,23) 510-748-8230
# PhoneNumberMatch [51,62) 703-4800500

# Iterate again and format the found numbers to E.164 format
for match in phonenumbers.PhoneNumberMatcher(text, "US"):
    prnt(phonenumbers.format_number(match.number, phonenumbers.PhoneNumberFormat.E164))
# Output:
# +15107488230
# +17034800500
```
```

--------------------------------

### Using fullmatch for String Matching

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.re_util.html

Demonstrates the `fullmatch` function from `phonenumbers.re_util`. It returns a match object if the entire string matches the pattern, otherwise returns None. Requires importing `re` and `fullmatch`.

```python
import re
from .re_util import fullmatch
from .util import u
string = 'abcd'
r1 = re.compile('abcd')
r2 = re.compile('bc')
r3 = re.compile('abc')
fullmatch(r1, string) # doctest: +ELLIPSIS
fullmatch(r2, string)
fullmatch(r3, string)
```

```python
r = re.compile(r'\d{8}|\d{10,11}')
m = fullmatch(r, '1234567890')
m.end()
```

```python
r = re.compile(u(r'[+＋\d]'), re.UNICODE)
m = fullmatch(r, u('０'))
m.end()
```

--------------------------------

### safe_display_name

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.carrier.html

Gets the carrier name only when it is considered 'safe' to display to users.

```APIDOC
## safe_display_name(numobj, lang, script=None, region=None)

### Description
Gets the name of the carrier for the given PhoneNumber object only when it is 'safe' to display to users. A carrier name is considered safe if the number is valid and for a region that doesn't support mobile number portability.

### Parameters
- **numobj** (PhoneNumber) - Required - The PhoneNumber object for which we want to get a carrier name.
- **lang** (string) - Required - A 2-letter lowercase ISO 639-1 language code.
- **script** (string) - Optional - A 4-letter titlecase ISO 15924 script code.
- **region** (string) - Optional - A 2-letter uppercase ISO 3166-1 country code.

### Response
- **string** - The carrier name if safe to display, otherwise an empty string.
```

--------------------------------

### Identify Phone Number Matches in Text

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Demonstrates how to use PhoneNumberMatcher to find and extract phone number matches from a string.

```python
>>> text = "Call me at +1 425 882-8080 for details."
>>> country = "US"
>>> import phonenumbers
>>> matcher = phonenumbers.PhoneNumberMatcher(text, country)
>>> matcher.has_next()
True
>>> m = matcher.next() # Find the first phone number match
>>> m.raw_string # contains the phone number as it appears in the text.
"+1 425 882-8080"
```

--------------------------------

### GET /is_mobile_number_portable_region

Source: https://daviddrysdale.github.io/python-phonenumbers

Determines if a specific region supports mobile number portability.

```APIDOC
## GET /is_mobile_number_portable_region

### Description
Returns true if the supplied region supports mobile number portability.

### Method
GET

### Endpoint
/is_mobile_number_portable_region

### Parameters
#### Query Parameters
- **region_code** (string) - Required - The region to check for mobile number portability support.

### Response
#### Success Response (200)
- **result** (boolean) - Returns true if the region supports portability, false otherwise.
```

--------------------------------

### Basic Phone Number Parsing and Formatting

Source: https://daviddrysdale.github.io/python-phonenumbers

Demonstrates how to parse phone numbers from various formats and format them into different international standards.

```APIDOC
## Phone Number Parsing and Formatting

### Description
This section shows how to parse phone numbers with and without a default region, and then format them into NATIONAL, INTERNATIONAL, and E164 formats.

### Usage

```python
import phonenumbers
from phonenumbers.util import prnt

# Parse a number with a country code
x = phonenumbers.parse("+442083661177", None)
prnt(x)
# Output: Country Code: 44 National Number: 2083661177
print(type(x))
# Output: <class 'phonenumbers.phonenumber.PhoneNumber'>

# Format the number
print(str(phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.NATIONAL)))
# Output: 020 8366 1177
print(str(phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.INTERNATIONAL)))
# Output: +44 20 8366 1177
print(str(phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.E164)))
# Output: +442083661177

# Parse a number with a default region
y = phonenumbers.parse("020 8366 1177", "GB")
prnt(y)
# Output: Country Code: 44 National Number: 2083661177

# Check for equality
print(x == y)
# Output: True
```
```

--------------------------------

### GET /supported_types_for_region

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Retrieves the supported phone number types for a specific region.

```APIDOC
## GET /supported_types_for_region

### Description
Returns the types (e.g., FIXED_LINE, MOBILE) for a given region code. Excludes UNKNOWN and FIXED_LINE_OR_MOBILE types.

### Method
GET

### Parameters
#### Query Parameters
- **region_code** (string) - Required - The region code to query.
```

--------------------------------

### GET /region_code_for_number

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Determines the region origin for a given phone number object.

```APIDOC
## GET /region_code_for_number

### Description
Returns the region where a phone number is from. Only guarantees correct results for valid, full numbers.

### Method
GET

### Parameters
#### Request Body
- **numobj** (PhoneNumber) - Required - The phone number object to analyze.
```

--------------------------------

### Find Phone Numbers in Text using Python

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Shows how to use PhoneNumberMatcher to find all phone numbers within a given text string for a specific region, and then format the found numbers.

```python
text = "Call me at 510-748-8230 if it\'s before 9:30, or on 703-4800500 after 10am."
for match in phonenumbers.PhoneNumberMatcher(text, "US"):
  prnt(match)

for match in phonenumbers.PhoneNumberMatcher(text, "US"):
  prnt(phonenumbers.format_number(match.number, phonenumbers.PhoneNumberFormat.E164))
```

--------------------------------

### GET /is_nanpa_country

Source: https://daviddrysdale.github.io/python-phonenumbers

Checks if a region is part of the North American Numbering Plan Administration (NANPA).

```APIDOC
## GET /is_nanpa_country

### Description
Checks if this region is a NANPA region.

### Method
GET

### Endpoint
/is_nanpa_country

### Parameters
#### Query Parameters
- **region_code** (string) - Required - The region code to check.

### Response
#### Success Response (200)
- **result** (boolean) - Returns true if the region is under NANPA.
```

--------------------------------

### Parse and Format Phone Numbers

Source: https://daviddrysdale.github.io/python-phonenumbers

Demonstrates parsing a phone number with an international prefix and formatting it into NATIONAL, INTERNATIONAL, and E164 formats. Also shows parsing a local number with a country code.

```python
import phonenumbers
from phonenumbers.util import prnt # equivalent to Py3k print()
x = phonenumbers.parse("+442083661177", None)
prnt(x)
print(type(x))
str(phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.NATIONAL))
str(phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.INTERNATIONAL))
str(phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.E164))
```

```python
y = phonenumbers.parse("020 8366 1177", "GB")
prnt(y)
x == y
```

--------------------------------

### national_significant_number

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Gets the national significant number of a phone number. This does not include the national prefix or any formatting.

```APIDOC
## national_significant_number(numobj)

### Description
Gets the national significant number of a phone number. Note that a national significant number doesn't contain a national prefix or any formatting.

### Arguments
- **numobj** (PhoneNumber) - The PhoneNumber object for which the national significant number is needed.

### Returns
- (string) The national significant number of the PhoneNumber object passed in.
```

--------------------------------

### GET /region_code_for_country_code

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Retrieves the primary region code associated with a specific country calling code.

```APIDOC
## GET /region_code_for_country_code

### Description
Returns the region code that matches a specific country calling code. If multiple regions exist, the 'main' region is returned. Returns 'ZZ' for unknown regions and '001' for non-geographical codes.

### Method
GET

### Parameters
#### Query Parameters
- **country_code** (int) - Required - The country calling code to look up.
```

--------------------------------

### invalid_example_number

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Retrieves an invalid number for a specified region for testing purposes.

```APIDOC
## invalid_example_number

### Description
Gets an invalid number for the specified region, useful for unit-testing. The returned number is parsable and has the correct country code.

### Parameters
#### Arguments
- **region_code** (string) - Required - The region for which an example number is needed

### Response
- **number** (string/None) - An invalid number for the region, or None if unsupported.
```

--------------------------------

### Define Module Exports

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.carrier.html

The __all__ list defines the public interface of the carrier module.

```python
__all__ = ['name_for_valid_number', 'name_for_number', 'safe_display_name']
```

--------------------------------

### GET /normalize_digits_only

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Normalizes a phone number string by converting numerals and stripping non-numeric characters.

```APIDOC
## GET /normalize_digits_only

### Description
Converts wide-ascii and arabic-indic numerals to European numerals and strips punctuation/alpha characters.

### Method
GET

### Endpoint
/normalize_digits_only

### Parameters
#### Query Parameters
- **number** (string) - Required - The phone number string.
- **keep_non_digits** (boolean) - Optional - Whether to keep non-digits.
```

--------------------------------

### expected_cost

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Determines the expected cost category for a short number.

```APIDOC
## expected_cost(numobj)

### Description
Gets the expected cost category of a short number. If the country calling code is shared by multiple regions, it returns the highest cost in the sequence PREMIUM_RATE, UNKNOWN_COST, STANDARD_RATE, TOLL_FREE.

### Parameters
#### Arguments
- **numobj** (object) - Required - The short number for which we want to know the expected cost category.

### Response
- **string** - The highest expected cost category of the short number.
```

--------------------------------

### GET /is_emergency_number

Source: https://daviddrysdale.github.io/python-phonenumbers

Checks if a given phone number matches an emergency service number in a specific region.

```APIDOC
## GET /is_emergency_number

### Description
Returns true if the given number exactly matches an emergency service number in the given region.

### Method
GET

### Endpoint
/is_emergency_number

### Parameters
#### Query Parameters
- **number** (string) - Required - The phone number to test.
- **region_code** (string) - Required - The region where the phone number is being dialed.

### Response
#### Success Response (200)
- **result** (boolean) - Returns true if the number matches an emergency services number.
```

--------------------------------

### expected_cost_for_region

Source: https://daviddrysdale.github.io/python-phonenumbers

Gets the expected cost category of a short number when dialled from a region. Note that emergency numbers are always considered toll-free.

```APIDOC
## expected_cost_for_region

### Description
Gets the expected cost category of a short number when dialled from a region (however, nothing is implied about its validity). If it is important that the number is valid, then its validity must first be checked using is_valid_short_number_for_region. Note that emergency numbers are always considered toll-free.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "short_numobj": "example_short_number_object",
  "region_dialing_from": "example_region_code"
}
```

### Response
#### Success Response (200)
- **ShortNumberCost** (enum) - The expected cost category of the short number.

#### Response Example
```json
{
  "cost": "TOLL_FREE"
}
```

### Example Usage:
```python
import phonenumbers

short_number = "110"
region_code = "FR"

if phonenumbers.is_valid_short_number_for_region(short_number, region_code):
    cost = phonenumbers.expected_cost(short_number, region_code) # ShortNumberCost
    print(f"The expected cost for dialing {short_number} from {region_code} is: {cost}")
else:
    print(f"{short_number} is not a valid short number for region {region_code}")
```
```

--------------------------------

### Category.get

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.unicode_util.html

Retrieves the general category code for a given Unicode character.

```APIDOC
## Category.get

### Description
Returns the general category code (as a Unicode string) for the given Unicode character based on Unicode standards.

### Method
Class Method

### Parameters
#### Path Parameters
- **uni_char** (Unicode character) - Required - The character to retrieve the category for.

### Response
#### Success Response (200)
- **category_code** (string) - The Unicode general category code (e.g., 'Lu' for Uppercase Letter).
```

--------------------------------

### format_by_pattern

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Formats a phone number using client-defined formatting rules.

```APIDOC
## format_by_pattern

### Description
Formats a phone number using client-defined formatting rules.

### Parameters
- **numobj** (PhoneNumber) - Required - The phone number to be formatted
- **number_format** (PhoneNumberFormat) - Required - The format the phone number should be formatted into
- **user_defined_formats** (list) - Required - Formatting rules specified by clients, as a list of NumberFormat objects.

### Response
- **string** - The formatted phone number.
```

--------------------------------

### Is Alpha Number

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Checks if a given number is a valid vanity (alpha) number, starting with at least 3 digits and containing three or more alpha characters.

```APIDOC
## is_alpha_number

### Description
Checks if the number is a valid vanity (alpha) number such as 800 MICROSOFT. A valid vanity number will start with at least 3 digits and will have three or more alpha characters. This does not do region-specific checks - to work out if this number is actually valid for a region, it should be parsed and methods such as is_possible_number_with_reason() and is_valid_number() should be used.

### Arguments
- **number** (string) - The number that needs to be checked.

### Returns
(boolean) True if the number is a valid vanity number.
```

--------------------------------

### is_possible_number_with_reason

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Checks if a phone number is possible and returns the reason.

```APIDOC
## is_possible_number_with_reason

### Description
Returns True if the number is possible.

### Method
(Not specified, likely a function call)

### Endpoint
(Not applicable, this is a library function)

### Parameters
#### Path Parameters
(None)

#### Query Parameters
(None)

#### Request Body
- **numobj** (PhoneNumber) - The phone number object to check.

### Request Example
(Not applicable for this function)

### Response
#### Success Response (boolean)
- **True/False**: Indicates if the number is possible.

#### Response Example
(Not applicable for this function)
```

--------------------------------

### fullmatch Function

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.re_util.html

The `fullmatch` function attempts to match a regular expression pattern against the entire input string. It returns a match object if the whole string conforms to the pattern, otherwise it returns None.

```APIDOC
## fullmatch(pattern, string, flags=0)

### Description
Try to apply the pattern at the start of the string, returning a match object if the whole string matches, or None if no match was found.

### Method
N/A (Function within a module)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import re
from phonenumbers.re_util import fullmatch
from phonenumbers.util import u

string = 'abcd'
r1 = re.compile('abcd')
print(fullmatch(r1, string))

r = re.compile(r'\d{8}|\d{10,11}')
m = fullmatch(r, '1234567890')
if m:
    print(m.end())
```

### Response
#### Success Response (Match Object or None)
- **Match Object**: Returned if the entire string matches the pattern.
- **None**: Returned if no match is found for the entire string.

#### Response Example
```json
<re.Match object; span=(0, 4), match='abcd'>
```

```json
None
```

```json
10
```
```

--------------------------------

### Metadata and Support Utilities

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Functions to retrieve supported calling codes and types for regions or non-geographical entities.

```APIDOC
## GET /supported_calling_codes

### Description
Returns all country calling codes the library has metadata for.

### Response
#### Success Response (200)
- **codes** (set) - An unordered set of supported country calling codes.

## GET /supported_types_for_region

### Description
Returns the types (e.g., FIXED_LINE, MOBILE) for a given region.

### Parameters
#### Query Parameters
- **region_code** (string) - Required - The region code to query.

### Response
#### Success Response (200)
- **types** (list) - A list of supported number types for the region.
```

--------------------------------

### Prefix Utilities

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.prefix.html

Provides constants and utilities for handling phone number prefixes.

```APIDOC
## Prefix Utilities

### Description
Utilities for handling prefix dictionaries, including constants for empty strings and the plus sign.

### Data Constants

- **U_EMPTY_STRING** (string) - Represents an empty string.
- **U_PLUS** (string) - Represents the '+' character, commonly used as a prefix for international phone numbers.
```

--------------------------------

### Get Length of National Destination Code

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Returns the length of the national destination code (NDC) for a phone number. This helps in splitting a national significant number into NDC and subscriber number. Not all numbers have an NDC.

```python
>>> import phonenumbers
>>> numobj = phonenumbers.parse("18002530000", "US")
>>> nsn = phonenumbers.national_significant_number(numobj)
>>> ndc_len = phonenumbers.length_of_national_destination_code(numobj)
>>> if ndc_len > 0:
...     national_destination_code = nsn[:ndc_len]
```

--------------------------------

### UnicodeMixin class

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.util.html

Mixin class to define a __str__ method in terms of the __unicode__ method. Ensures string representation compatibility.

```python
class UnicodeMixin(builtins.object):
    """Mixin class to define a __str__ method in terms of __unicode__ method"""

    def __str__(self):
        """Return str(self)."""

    __dict__
    __weakref__
```

--------------------------------

### Library Constants

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.shortnumberinfo.html

Information about important constants used within the python-phonenumbers library.

```APIDOC
## Constants

### SUPPORTED_SHORT_REGIONS
- **Type**: List of strings
- **Description**: A list of region codes for which short numbers are supported. Example: `['AC', 'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', ...]`

### U_EMPTY_STRING
- **Type**: String
- **Description**: Represents an empty string. Value: `''`
```

--------------------------------

### Get expected cost of a short number

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.shortnumberinfo.html

Retrieves the expected cost category for a short number. If the country calling code is shared, it returns the highest cost category across all associated regions, prioritizing PREMIUM_RATE over UNKNOWN_COST, STANDARD_RATE, or TOLL_FREE.

```python
phonenumbers.expected_cost(numobj)
```

--------------------------------

### Module: unicode_util Functions

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.unicode_util.html

Utility functions for checking character properties and digit values.

```APIDOC
## Module: unicode_util

### Functions
- **is_letter(char)**: Returns True if the character is a letter, False otherwise.
- **digit(char, default)**: Returns the numeric value of the character if it is a digit; otherwise returns the provided default value.
```

--------------------------------

### Get Expected Cost for Region

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Retrieves the expected cost category of a short number when dialed from a specified region. Note that this does not validate the number's existence; validity should be checked separately using `is_valid_short_number_for_region`. Emergency numbers are always considered toll-free.

```APIDOC
## GET /expected_cost_for_region

### Description
Gets the expected cost category of a short number when dialled from a region. Note that nothing is implied about its validity. If it is important that the number is valid, then its validity must first be checked using `is_valid_short_number_for_region`. Emergency numbers are always considered toll-free.

### Method
GET

### Endpoint
`/expected_cost_for_region(short_numobj, region_dialing_from)`

### Parameters
#### Path Parameters
- **short_numobj** (object) - Required - The short number object to check.
- **region_dialing_from** (string) - Required - The region code (e.g., 'FR') from which the number is dialed.

### Request Example
```python
import phonenumbers

short_number = "110"
region_code = "FR"

# First, check validity if necessary
if phonenumbers.is_valid_short_number_for_region(short_number, region_code):
    cost = phonenumbers.expected_cost_for_region(short_number, region_code) # Returns ShortNumberCost enum
    print(f"The expected cost for {short_number} from {region_code} is: {cost}")
else:
    print(f"The number {short_number} is not valid for region {region_code}.")
```

### Response
#### Success Response (200)
- **ShortNumberCost** (enum) - The expected cost category (e.g., PREMIUM_RATE, STANDARD_RATE, TOLL_FREE, UNKNOWN_COST).

#### Response Example
```json
{
  "cost": "TOLL_FREE"
}
```
```

--------------------------------

### Unicode Utility Functions Usage

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.unicode_util.html

Demonstrates how to use Category and Block classes to inspect Unicode characters. Note that behavior for non-BMP characters depends on whether the Python build is UCS2 or UCS4.

```python
>>> from .import unicode_util
>>> from .util import u
>>> u1 = '1' # DIGIT ONE
>>> u2 = u('a') # LATIN SMALL LETTER A
>>> u3 = u('２') # FULLWIDTH DIGIT TWO
>>> u4 = u('Ā') # LATIN CAPITAL LETTER A WITH MACRON
>>> unicode_util.Category.get(u1) == u('Nd')
True
>>> unicode_util.Category.get(u2) == u('Ll')
True
>>> unicode_util.Category.get(u3) == u('Nd')
True
>>> unicode_util.Category.get(u4) == u('Lu')
True
>>> unicode_util.Category.get(u2) == unicode_util.Category.LOWERCASE_LETTER
True
>>> try:
... beyond_bmp = u('𐄀') # AEGEAN WORD SEPARATOR LINE
... except Exception:
... beyond_bmp = u('')
>>> if len(beyond_bmp) == 1: # We have a UCS4 build of Python
... cat_po = unicode_util.Category.get(beyond_bmp)
... else: # UCS2 build of Python; no non-BMP chars available
... cat_po = unicode_util.Category.OTHER_PUNCTUATION
>>> cat_po == u('Po')
True
>>> unicode_util.is_letter(u1)
False
>>> unicode_util.is_letter(u2)
True
>>> unicode_util.is_letter(u3)
False
>>> unicode_util.is_letter(u4)
True
>>> b1 = unicode_util.Block.get(u1)
>>> str(b1)
'Block[0000, 007f]'
>>> b1 == unicode_util.Block.BASIC_LATIN
True
>>> b1 == [0x0000, 0x0075]
False
>>> b2 = unicode_util.Block.get(u2)
>>> b2 == unicode_util.Block.BASIC_LATIN
True
>>> b3 = unicode_util.Block.get(u3)
>>> b3 != unicode_util.Block.BASIC_LATIN
True
>>> b3 == unicode_util.Block.HALFWIDTH_AND_FULLWIDTH_FORMS
True
>>> b4 = unicode_util.Block.get(u4)
>>> b4 == unicode_util.Block.LATIN_EXTENDED_A
True
>>> unicode_util.Block.get(u('ࡠ')) == unicode_util.Block.UNKNOWN
True
>>> try:
... unknown_block = u('𓐰')
... except Exception:
... unknown_block = u('')
>>> if len(unknown_block) == 1: # We have a UCS4 build of Python
... unicode_util.Block.get(u('𓐰')) == unicode_util.Block.UNKNOWN
... else: # UCS2 build of Python; no unknown characters available
... True
True
>>> unicode_util.digit(u1)
1
>>> unicode_util.digit(u2, -1)
-1
>>> unicode_util.digit(u3, -1)
2
>>> str(hash(b3)) # doctest: +ELLIPSIS
'...'
```

--------------------------------

### Get Length of Geographical Area Code

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.html

Returns the length of the geographical area code for a given phone number object. This can be used to split a national significant number into an area code and subscriber number. Note that area codes are ambiguous and change over time.

```python
>>> import phonenumbers
>>> numobj = phonenumbers.parse("16502530000", "US")
>>> nsn = phonenumbers.national_significant_number(numobj)
>>> ac_len = phonenumbers.length_of_geographical_area_code(numobj)
>>> if ac_len > 0:
...     area_code = nsn[:ac_len]
...     subscriber_number = nsn[ac_len:]
... else:
...     area_code = ""
...     subscriber_number = nsn
```

--------------------------------

### is_possible_number_for_type_with_reason

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.phonenumberutil.html

Performs a lenient length-based check to see if a number is possible for a specific type.

```APIDOC
## is_possible_number_for_type_with_reason

### Description
Checks whether a phone number is a possible number of a particular type, providing a more lenient check than is_valid_number.

### Parameters
#### Arguments
- **numobj** (object) - Required - The number object that needs to be checked.
- **numtype** (object) - Required - The type we are interested in.

### Response
- **Returns** (ValidationResult) - Indicates whether the number is possible.
```

--------------------------------

### Get expected cost of a short number for a specific region

Source: https://daviddrysdale.github.io/python-phonenumbers/phonenumbers.shortnumberinfo.html

Determines the expected cost category of a short number when dialed from a particular region. Note that emergency numbers are always considered toll-free. It's recommended to check validity first using `is_valid_short_number_for_region`.

```python
phonenumbers.expected_cost_for_region(short_numobj, region_dialing_from)
```