### Install phonenumbers using setup.py

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/tools/python/README.md

Install the phonenumbers library by downloading the source archive, navigating to the directory, and running the pip install command. Ensure you have the necessary permissions.

```console
tar xfz phonenumbers-<version>.tar.gz
cd phonenumbers-<version>
sudo python -m pip install .  # or su first
```

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

### Example Usage of PhoneNumberMatcher

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.phonenumbermatcher.html

This example demonstrates how to use the PhoneNumberMatcher to find a phone number in a text. It shows how to initialize the matcher, check for the next match, retrieve the match object, and access its properties like raw_string, start, end, and the parsed number. It also verifies the match against a 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"
phonenumbers.phonenumberutil.parse("+1 425 882-8080", "US") == m.number
True
```

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

### example_number(region_code)

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.phonenumberutil.html

Gets a valid example phone number for the specified region. Returns None if metadata is unavailable or if region_code is '001'. For non-geographical numbers, use example_number_for_non_geo_entity.

```APIDOC
## example_number(region_code)

### Description
Gets a valid fixed-line number for the specified region.

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

### Returns
A valid fixed-line number for the specified region, or None if metadata is unavailable or region_code is '001'. For non-geographical numbers, call `example_number_for_non_geo_entity` instead.
```

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

### Install phonenumbers with pip

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/README.md

Install the library using pip. This is the standard method for adding Python packages to your project.

```bash
pip install phonenumbers
```

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

### Find Phone Numbers in Text

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.html

This example demonstrates how to find the first phone number match within a given text using the PhoneNumberMatcher. It shows how to access the raw matched string, its start and end positions in the text, and the parsed phone number object.

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

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

### example_number_for_type(region_code, num_type)

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.phonenumberutil.html

Gets a valid example phone number for the specified region and number type. If region_code is None, the number may belong to any country. Returns None if metadata is unavailable, or if an invalid region or '001' was specified. For non-geographical numbers, use example_number_for_non_geo_entity.

```APIDOC
## example_number_for_type(region_code, num_type)

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

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

### Returns
A valid number for the specified region and type, or None if metadata is unavailable, or if an invalid region or '001' was specified. For non-geographical numbers, call `example_number_for_non_geo_entity` instead.
```

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

### Force Load All Metadata

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/README.md

Ensures all core library metadata is loaded into memory at the start of the application.

```python
phonenumbers.PhoneMetadata.load_all()
```

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

### Build and Upload Full Package to PyPI

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/tools/python/README.md

Build the full package and upload it to PyPI. Ensure you have 'build' and 'twine' installed. Navigate to the python directory first.

```bash
cd python && rm -rf build dist phonenumbers.egg-info && python -m build
twine check dist/*
twine upload dist/*
cd -
```

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

### invalid_example_number(region_code)

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.html

Gets an invalid number for the specified region. Useful for unit-testing purposes.

```APIDOC
## invalid_example_number(region_code)

### 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
An invalid number for the specified region. Returns None when an unsupported region or the region 001 (Earth) is passed in.
```

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

### example_number

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/index.html

Gets a valid fixed-line phone number for a specified region. Returns None if no such information is available or if the region is '001'.

```APIDOC
## example_number(region_code)

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

### Arguments
* `region_code` -- The region for which an example number is needed.

### Returns
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.
```

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

### Get Phone Number Descriptions

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.geocoder.html

Demonstrates how to get geographical descriptions for phone numbers in different languages and regions. Imports are required for phonenumbers, geocoder, and util.

```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"))
str(description_for_number(gb_number, "fr")) # fall back to English
str(description_for_number(gb_number, "en", region="GB"))
str(description_for_number(gb_number, "en", region="US")) # fall back to country
str(description_for_number(de_number, "en"))
u('München') == description_for_number(de_number, "de")
u('Zürich') == description_for_number(ch_number, "de")
str(description_for_number(ch_number, "en"))
str(description_for_number(ch_number, "fr"))
str(description_for_number(ch_number, "it"))
```

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

### Build and Upload Lite Package to PyPI

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/tools/python/README.md

Build the lite package and upload it to PyPI. Ensure you have 'build' and 'twine' installed. Navigate to the python/phonenumberslite directory first.

```bash
cd python/phonenumberslite && rm -rf build dist phonenumberslite.egg-info && python -m build
twine check dist/*
twine upload dist/*
cd -
```

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

### Run phonenumbers tests

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/tools/python/README.md

After installing the phonenumbers library and ensuring it's on the Python path, execute the tests using the provided testwrapper script.

```console
python -m testwrapper
```

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

### Build Timezone Data

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/resources/timezones/README.md

Builds the timezone data for the library. This command should be run from the root of the repository and requires 'ant' to be installed.

```bash
ant -f java/build.xml build-timezones-data
```

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

### example_number_for_type

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/index.html

Gets a valid phone number for a specified region and number type. If region_code is None, the number may belong to any country.

```APIDOC
## example_number_for_type(region_code, num_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` -- The region for which an example number is needed. Can be None.
* `num_type` -- The type of number to retrieve (e.g., fixed-line, mobile).
```

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

### example_number_for_non_geo_entity(country_calling_code)

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.phonenumberutil.html

Gets a valid example phone number for a non-geographical entity given its country calling code. Returns None if metadata is unavailable or the country calling code does not belong to a non-geographical entity.

```APIDOC
## example_number_for_non_geo_entity(country_calling_code)

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

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

### Returns
A valid number for the non-geographical entity, or None if metadata is unavailable or the country calling code does not belong to a non-geographical entity.
```

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

### Run Unit Tests

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/tools/python/README.md

Execute the unit tests for the library. Navigate to the tools/python directory first.

```bash
cd tools/python && make test
```

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

### Run Unit Tests (Python 2.5)

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/tools/python/README.md

Ensure compatibility by running tests with Python 2.5. Navigate to the tools/python directory first.

```bash
cd tools/python && make PYTHON=python2.5 test
```

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

### Run Unit Tests (Python 3)

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/tools/python/README.md

Execute unit tests using Python 3. Navigate to the tools/python directory first.

```bash
cd tools/python && make PYTHON=python3 test
```

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

### Create and Push Git Tag

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/tools/python/README.md

Create a version tag and push it to the remote repository.

```bash
git tag vX.Y.Z
git push <github-remote> vX.Y.Z
```

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

### Get Time Zones for a Phone Number (with validation)

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.timezone.html

Use this function to get a list of time zones for a phone number. It explicitly checks the validity of the number and returns a list of corresponding time zones or a default unknown time zone if no other is found or the number is invalid.

```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]))
```

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

### number_type

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.phonenumberutil.html

Gets the type of a valid phone number object. Returns UNKNOWN if the number is invalid.

```APIDOC
## number_type(numobj)

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

### Method
`number_type`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **numobj** (PhoneNumber object) - The PhoneNumber object to determine the type of.

### Returns
The type of the phone number as a PhoneNumberType value. Returns PhoneNumberType.UNKNOWN if the number is invalid.
```

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

### example_number

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.html

Retrieves an example phone number for a specified region and number type. It returns None if the metadata does not contain the requested information or if an invalid region is provided. For non-geographical numbers, a separate function should be used.

```APIDOC
## example_number

### Description
Returns 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.

### Arguments
* `region_code` -- The region for which an example number is needed, or None.
* `num_type` -- The type of number that is needed.
```

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

### Using fullmatch with Compiled Regex

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.re_util.html

Demonstrates how to use the fullmatch function with pre-compiled regular expression objects. It shows cases where the entire string matches the pattern and where it does not.

```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](#-fullmatch)(r1, string)  # doctest: +ELLIPSIS
<...Match object...>
[fullmatch](#-fullmatch)(r2, string)
[fullmatch](#-fullmatch)(r3, string)
```

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

### Get National Significant Number

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/phonenumbers.phonenumberutil.html

Retrieves the national significant number from a PhoneNumber object, excluding national prefixes or formatting.

```python
import phonenumbers
numobj = phonenumbers.parse("16502530000", "US")
nsn = phonenumbers.national_significant_number(numobj)
```

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

### Find Phone Numbers in Text

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/index.html

Demonstrates how to find all phone numbers within a given text using PhoneNumberMatcher. It shows how to retrieve the match objects and then format the matched 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)
# PhoneNumberMatch [11,23) 510-748-8230
# PhoneNumberMatch [51,62) 703-4800500

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

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

### As-You-Type Formatting

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/index.html

Shows how to use the AsYouTypeFormatter to format a phone number as the user types it. This is ideal for real-time input fields in user interfaces.

```python
formatter = phonenumbers.AsYouTypeFormatter("US")
prnt(formatter.input_digit("6"))
# 6
prnt(formatter.input_digit("5"))
# 65
prnt(formatter.input_digit("0"))
# 650
prnt(formatter.input_digit("2"))
# 650-2
prnt(formatter.input_digit("5"))
# 650-25
prnt(formatter.input_digit("3"))
# 650-253
prnt(formatter.input_digit("2"))
# 650-2532
prnt(formatter.input_digit("2"))
# (650) 253-22
prnt(formatter.input_digit("2"))
# (650) 253-222
prnt(formatter.input_digit("2"))
# (650) 253-2222
```

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

### Get Geocoding Description for Phone Number

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/README.md

Retrieves a localized description for a given phone number. Requires the geocoder metadata to be loaded.

```python
from phonenumbers import geocoder
ch_number = phonenumbers.parse("0431234567", "CH")
geocoder.description_for_number(ch_number, "de")
```

```python
from phonenumbers import geocoder
ch_number = phonenumbers.parse("0431234567", "CH")
geocoder.description_for_number(ch_number, "en")
```

```python
from phonenumbers import geocoder
ch_number = phonenumbers.parse("0431234567", "CH")
geocoder.description_for_number(ch_number, "fr")
```

```python
from phonenumbers import geocoder
ch_number = phonenumbers.parse("0431234567", "CH")
geocoder.description_for_number(ch_number, "it")
```

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

### example_number_for_non_geo_entity

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/docs/index.html

Gets a valid phone number for a non-geographical entity associated with a given country calling code. Returns None if the information is not available.

```APIDOC
## example_number_for_non_geo_entity(country_calling_code)

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

### Arguments
* `country_calling_code` -- The country calling code for a non-geographical entity.

### Returns
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.
```

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

### Force Metadata Regeneration (Python 3)

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/tools/python/README.md

Regenerate metadata using Python 3. Navigate to the tools/python directory first.

```bash
cd tools/python && make PYTHON=python3 metaclean alldata
```

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

### Get Geocoding Description for a Number

Source: https://github.com/daviddrysdale/python-phonenumbers/blob/dev/python/phonenumberslite/README.md

Retrieve the geographical description for a parsed phone number in a specified language. Requires the geocoder metadata to be loaded.

```python
>>> from phonenumbers import geocoder
>>> ch_number = phonenumbers.parse("0431234567", "CH")
>>> geocoder.description_for_number(ch_number, "de")
'Zürich'
>>> geocoder.description_for_number(ch_number, "en")
'Zurich'
>>> geocoder.description_for_number(ch_number, "fr")
'Zurich'
>>> geocoder.description_for_number(ch_number, "it")
'Zurigo'
```