PhoneNumber API

digitz.PhoneNumber dataclass

PhoneNumber(country_code: int, national_number: int, extension: Optional[str] = None, italian_leading_zero: bool = False, number_of_leading_zeros: Optional[int] = None, raw_input: Optional[str] = None, country_code_source: CountryCodeSource = CountryCodeSource.UNSPECIFIED, preferred_domestic_carrier_code: Optional[str] = None)

Bases: PhoneNumber

A dataclass representing a phone number.

Parameters:

Name	Type	Description	Default
country_code	int	The country code of the phone number.	required
national_number	int	The national number of the phone number.	required
extension	Optional[str]	The extension of the phone number.	None
italian_leading_zero	bool	Whether the phone number has an Italian leading zero.	False
number_of_leading_zeros	Optional[int]	The number of leading zeros in the phone number.	None
raw_input	Optional[str]	The raw input of the phone number.	None
country_code_source	CountryCodeSource	The source of the country code.	UNSPECIFIED
preferred_domestic_carrier_code	Optional[str]	The preferred domestic	None

Attributes

national_destination_code_length cached property

national_destination_code_length: int

Returns the length of the national destination code.

ndc_length property

ndc_length: int

An alias for the national_destination_code_length property.

national_significant_number cached property

national_significant_number: str

Returns the national significant number.

nsn property

nsn: str

An alias for the national_significant_number property.

national_destination_code property

national_destination_code: str

Returns the national destination code.

ndc property

ndc: str

An alias for the national_destination_code property.

subscriber_number property

subscriber_number: str

Returns the subscriber number.

region_code cached property

region_code: Optional[str]

Returns the region code of the phone number.

is_geographical cached property

is_geographical: bool

Returns True if the phone number has a geographical association.

is_nanpa_country cached property

is_nanpa_country: bool

Returns True if the phone number is from a NANPA country.

is_possible cached property

is_possible: bool

Returns True if the phone number is possible.

is_valid cached property

is_valid: bool

Returns True if the phone number is of a valid pattern.

number_type cached property

number_type: PhoneNumberType

Returns the type of a valid phone number.

is_fixed_line property

is_fixed_line: bool

Returns whether the phone number type is fixed line.

is_mobile property

is_mobile: bool

Returns whether the phone number type is mobile.

is_fixed_line_or_mobile property

is_fixed_line_or_mobile: bool

Returns whether the phone number type is fixed line or mobile.

is_toll_free property

is_toll_free: bool

Returns whether the phone number type is toll free.

is_premium_rate property

is_premium_rate: bool

Returns whether the phone number type is premium rate.

is_shared_cost property

is_shared_cost: bool

Returns whether the phone number type is shared cost.

is_voip property

is_voip: bool

Returns whether the phone number type is voip.

is_personal_number property

is_personal_number: bool

Returns whether the phone number type is personal number.

is_pager property

is_pager: bool

Returns whether the phone number type is pager.

is_uan property

is_uan: bool

Returns whether the phone number type is a universal access number.

is_voicemail property

is_voicemail: bool

Returns whether the phone number type is a voicemail access number.

timezones cached property

timezones: Tuple[ZoneInfo, ...]

Returns the timezones of the phone number.

Functions

parse classmethod

parse(number: str, /, *, region: Optional[str] = None, keep_raw_input: bool = False) -> Self

Attempts to parse a string and return a new PhoneNumber object.

Parameters:

Name	Type	Description	Default
number	str	The phone number to parse.	required
region	Optional[str]	The region code the phone number is expected to be from.	None
keep_raw_input	bool	Whether to keep the raw input of the phone number.	False

Raises:

Type	Description
NumberParseException	If the phone number cannot be parsed.

Returns:

Type	Description
Self	A new PhoneNumber object.

example_number classmethod

example_number(region: str, number_type: PhoneNumberType = PhoneNumberType.FIXED_LINE) -> Optional[Self]

Returns an example phone number for the specified region and number type.

Parameters:

Name	Type	Description	Default
region	str	The region code of the phone number.	required
number_type	PhoneNumberType	The type of phone number.	FIXED_LINE

Returns:

Type	Description
Optional[Self]	An example phone number for the specified region and number type.

__str__

__str__() -> str

Returns the E.164 representation of the phone number.

match

match(other: Union[str, pn.PhoneNumber]) -> MatchType

Returns the match type of the phone number.

Parameters:

Name	Type	Description	Default
other	Union[str, PhoneNumber]	The other phone number to compare.	required

Returns:

Type	Description
MatchType	The match type of the phone number.

is_short_nsn_match

is_short_nsn_match(other: Union[str, pn.PhoneNumber]) -> bool

Returns True if the other phone number is a short NSN match.

is_nsn_match

is_nsn_match(other: Union[str, pn.PhoneNumber]) -> bool

Returns True if the other phone number is a NSN match.

is_exact_match

is_exact_match(other: Union[str, pn.PhoneNumber]) -> bool

Returns True if the other phone number is an exact match.

is_any_nsn_match

is_any_nsn_match(other: Union[str, pn.PhoneNumber]) -> bool

Returns True if the other phone number is any NSN match.

is_any_match

is_any_match(other: Union[str, pn.PhoneNumber]) -> bool

Returns True if the other phone number is any match.

get_carrier_name cached

get_carrier_name(lang: str) -> str

Returns the carrier name of the phone number.

Parameters:

Name	Type	Description	Default
lang	str	The language to use.	required

Returns:

Type	Description
str	The carrier name of the phone number.

get_country_name cached

get_country_name(lang: str) -> str

Returns the country name of the phone number.

Parameters:

Name	Type	Description	Default
lang	str	The language to use.	required

Returns:

Type	Description
str	The country name of the phone number.

get_description cached

get_description(lang: str) -> str

Returns the description of the phone number.

Parameters:

Name	Type	Description	Default
lang	str	The language to use.	required

Returns:

Type	Description
str	The description of the phone number.

format cached

format(format: PhoneNumberFormat) -> str

Returns the string representation of the phone number in the specified format.

Parameters:

Name	Type	Description	Default
format	PhoneNumberFormat	The format to use.	required

Returns:

Type	Description
str	The string representation of the phone number.

to_e164

to_e164() -> str

Returns the E.164 representation of the phone number.

to_international

to_international() -> str

Returns the international representation of the phone number.

to_national

to_national() -> str

Returns the national representation of the phone number.

to_rfc3966

to_rfc3966() -> str

Returns the RFC3966 representation of the phone number.

to_dict

to_dict() -> Dict[str, Any]

Returns a dictionary representation of the phone number.

to_tuple

to_tuple() -> PhoneNumberTuple

Returns a tuple representation of the phone number.

replace

replace(*, country_code: Union[int, _MISSING_TYPE] = MISSING, national_number: Union[int, _MISSING_TYPE] = MISSING, extension: Union[Optional[str], _MISSING_TYPE] = MISSING, italian_leading_zero: Union[bool, _MISSING_TYPE] = MISSING, number_of_leading_zeros: Union[Optional[int], _MISSING_TYPE] = MISSING) -> Self

Returns a new phone number with the specified attributes replaced.

Parameters:

Name	Type	Description	Default
country_code	Union[int, _MISSING_TYPE]	The country code of the phone number.	MISSING
national_number	Union[int, _MISSING_TYPE]	The national number of the phone number.	MISSING
extension	Union[Optional[str], _MISSING_TYPE]	The extension of the phone number.	MISSING
italian_leading_zero	Union[bool, _MISSING_TYPE]	Whether the phone number has an Italian leading zero.	MISSING
number_of_leading_zeros	Union[Optional[int], _MISSING_TYPE]	The number of leading zeros in the phone number.	MISSING

Returns:

Type	Description
Self	A new PhoneNumber object