phonenumbers.phonenumberutil
index
phonenumbers/phonenumberutil.py

Python phone number parsing and formatting library
 
If you use this library, and want to be notified about important changes,
please sign up to the libphonenumber mailing list at
https://groups.google.com/forum/#!aboutgroup/libphonenumber-discuss.
 
NOTE: A lot of methods in this module require Region Code strings. These must
be provided using CLDR two-letter region-code format. These should be in
upper-case. The list of the codes can be found here:
http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm

 
Modules
       
re
sys

 
Classes
       
builtins.Exception(builtins.BaseException)
NumberParseException(phonenumbers.util.UnicodeMixin, builtins.Exception)
builtins.object
MatchType
PhoneNumberFormat
PhoneNumberType
ValidationResult
phonenumbers.util.UnicodeMixin(builtins.object)
NumberParseException(phonenumbers.util.UnicodeMixin, builtins.Exception)

 
class MatchType(builtins.object)
    Types of phone number matches.
 
  Class methods defined here:
to_string(val) from builtins.type
Return a string representation of a MatchType value

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
EXACT_MATCH = 4
NOT_A_NUMBER = 0
NO_MATCH = 1
NSN_MATCH = 3
SHORT_NSN_MATCH = 2

 
class NumberParseException(phonenumbers.util.UnicodeMixin, builtins.Exception)
    NumberParseException(error_type, msg)
 
Exception when attempting to parse a putative phone number
 
 
Method resolution order:
NumberParseException
phonenumbers.util.UnicodeMixin
builtins.Exception
builtins.BaseException
builtins.object

Methods defined here:
__init__(self, error_type, msg)
Initialize self.  See help(type(self)) for accurate signature.
__reduce__(self)
Helper for pickle.
__unicode__(self)

Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
INVALID_COUNTRY_CODE = 0
NOT_A_NUMBER = 1
TOO_LONG = 4
TOO_SHORT_AFTER_IDD = 2
TOO_SHORT_NSN = 3

Methods inherited from phonenumbers.util.UnicodeMixin:
__str__(self)
Return str(self).

Data descriptors inherited from phonenumbers.util.UnicodeMixin:
__dict__
dictionary for instance variables (if defined)

Static methods inherited from builtins.Exception:
__new__(*args, **kwargs) from builtins.type
Create and return a new object.  See help(type) for accurate signature.

Methods inherited from builtins.BaseException:
__delattr__(self, name, /)
Implement delattr(self, name).
__getattribute__(self, name, /)
Return getattr(self, name).
__repr__(self, /)
Return repr(self).
__setattr__(self, name, value, /)
Implement setattr(self, name, value).
__setstate__(...)
with_traceback(...)
Exception.with_traceback(tb) --
set self.__traceback__ to tb and return self.

Data descriptors inherited from builtins.BaseException:
__cause__
exception cause
__context__
exception context
__suppress_context__
__traceback__
args

 
class PhoneNumberFormat(builtins.object)
    Phone number format.
 
INTERNATIONAL and NATIONAL formats are consistent with the definition in
ITU-T Recommendation E123. However we follow local conventions such as using
'-' instead of whitespace as separators. For example, the number of the
Google Switzerland office will be written as "+41 44 668 1800" in
INTERNATIONAL format, and as "044 668 1800" in NATIONAL format. E164 format
is as per INTERNATIONAL format but with no formatting applied,
e.g. "+41446681800". RFC3966 is as per INTERNATIONAL format, but with all
spaces and other separating symbols replaced with a hyphen, and with any
phone number extension appended with ";ext=". It also will have a prefix of
"tel:" added, e.g. "tel:+41-44-668-1800".
 
Note: If you are considering storing the number in a neutral format, you
are highly advised to use the PhoneNumber class.
 
  Class methods defined here:
to_string(val) from builtins.type
Return a string representation of a PhoneNumberFormat value

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
E164 = 0
INTERNATIONAL = 1
NATIONAL = 2
RFC3966 = 3

 
class PhoneNumberType(builtins.object)
    Type of phone numbers.
 
  Class methods defined here:
to_string(val) from builtins.type
Return a string representation of a PhoneNumberType value
values() from builtins.type

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
FIXED_LINE = 0
FIXED_LINE_OR_MOBILE = 2
MOBILE = 1
PAGER = 8
PERSONAL_NUMBER = 7
PREMIUM_RATE = 4
SHARED_COST = 5
TOLL_FREE = 3
UAN = 9
UNKNOWN = 99
VOICEMAIL = 10
VOIP = 6

 
class ValidationResult(builtins.object)
    Possible outcomes when testing if a PhoneNumber is a possible number.
 
  Class methods defined here:
to_string(val) from builtins.type
Return a string representation of a ValidationResult value

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

Data and other attributes defined here:
INVALID_COUNTRY_CODE = 1
INVALID_LENGTH = 5
IS_POSSIBLE = 0
IS_POSSIBLE_LOCAL_ONLY = 4
TOO_LONG = 3
TOO_SHORT = 2

 
Functions
       
can_be_internationally_dialled(numobj)
Returns True if the number can only be dialled from outside the region,
or unknown.
 
If the number can only be dialled from within the region
as well, returns False. Does not check the number is a valid number.
Note that, at the moment, this method does not handle short numbers (which
are currently all presumed to not be diallable from outside their country).
 
Arguments:
numobj -- the phone number objectfor which we want to know whether it is
          diallable from outside the region.
convert_alpha_characters_in_number(number)
Convert alpha chars in a number to their respective digits on a keypad,
but retains existing formatting.
country_code_for_region(region_code)
Returns the country calling code for a specific region.
 
For example, this would be 1 for the United States, and 64 for New
Zealand.
 
Arguments:
region_code -- The region that we want to get the country calling code for.
 
Returns the country calling code for the region denoted by region_code.
country_code_for_valid_region(region_code)
Returns the country calling code for a specific region.
 
For example, this would be 1 for the United States, and 64 for New
Zealand.  Assumes the region is already valid.
 
Arguments:
region_code -- The region that we want to get the country calling code for.
 
Returns the country calling code for the region denoted by region_code.
country_mobile_token(country_code)
Returns the mobile token for the provided country calling code if it has one, otherwise
returns an empty string. A mobile token is a number inserted before the area code when dialing
a mobile number from that country from abroad.
 
Arguments:
country_code -- the country calling code for which we want the mobile token
Returns the mobile token, as a string, for the given country calling code.
example_number(region_code)
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.
example_number_for_non_geo_entity(country_calling_code)
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.
example_number_for_type(region_code, num_type)
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, or None.
num_type -- The type of number that is needed.
 
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.
format_by_pattern(numobj, number_format, user_defined_formats)
Formats a phone number using client-defined formatting rules.
 
Note that if the phone number has a country calling code of zero or an
otherwise invalid country calling code, we cannot work out things like
whether there should be a national prefix applied, or how to format
extensions, so we return the national significant number with no
formatting applied.
 
Arguments:
numobj -- The phone number to be formatted
number_format -- The format the phone number should be formatted into,
          as a PhoneNumberFormat value.
user_defined_formats -- formatting rules specified by clients, as a list
          of NumberFormat objects.
 
Returns the formatted phone number.
format_in_original_format(numobj, region_calling_from)
Formats a phone number using the original phone number format
(e.g. INTERNATIONAL or NATIONAL) that the number is parsed from, provided
that the number has been parsed with parse(.., keep_raw_input=True).
Otherwise the number will be formatted in NATIONAL format.
 
The original format is embedded in the country_code_source field of the
PhoneNumber object passed in, which is only set when parsing keeps the raw
input. When we don't have a formatting pattern for the number, the method
falls back to returning the raw input.
 
Note this method guarantees no digit will be inserted, removed or modified
as a result of formatting.
 
Arguments:
number -- The phone number that needs to be formatted in its original
          number format
region_calling_from -- The region whose IDD needs to be prefixed if the
          original number has one.
 
Returns the formatted phone number in its original number format.
format_national_number_with_carrier_code(numobj, carrier_code)
Format a number in national format for dialing using the specified carrier.
 
The carrier-code will always be used regardless of whether the phone
number already has a preferred domestic carrier code stored. If
carrier_code contains an empty string, returns the number in national
format without any carrier code.
 
Arguments:
numobj -- The phone number to be formatted
carrier_code -- The carrier selection code to be used
 
Returns the formatted phone number in national format for dialing using
the carrier as specified in the carrier_code.
format_national_number_with_preferred_carrier_code(numobj, fallback_carrier_code)
Formats a phone number in national format for dialing using the carrier
as specified in the preferred_domestic_carrier_code field of the
PhoneNumber object passed in. If that is missing, use the
fallback_carrier_code passed in instead. If there is no
preferred_domestic_carrier_code, and the fallback_carrier_code contains an
empty string, return the number in national format without any carrier
code.
 
Use format_national_number_with_carrier_code instead if the carrier code
passed in should take precedence over the number's
preferred_domestic_carrier_code when formatting.
 
Arguments:
numobj -- The phone number to be formatted
carrier_code -- The carrier selection code to be used, if none is found in the
          phone number itself.
 
Returns the formatted phone number in national format for dialing using
the number's preferred_domestic_carrier_code, or the fallback_carrier_code
pass in if none is found.
format_number(numobj, num_format)
Formats a phone number in the specified format using default rules.
 
Note that this does not promise to produce a phone number that the user
can dial from where they are - although we do format in either 'national'
or 'international' format depending on what the client asks for, we do not
currently support a more abbreviated format, such as for users in the same
"area" who could potentially dial the number without area code. Note that
if the phone number has a country calling code of 0 or an otherwise
invalid country calling code, we cannot work out which formatting rules to
apply so we return the national significant number with no formatting
applied.
 
Arguments:
numobj -- The phone number to be formatted.
num_format -- The format the phone number should be formatted into
 
Returns the formatted phone number.
format_number_for_mobile_dialing(numobj, region_calling_from, with_formatting)
Returns a number formatted in such a way that it can be dialed from a
 mobile phone in a specific region.
 
If the number cannot be reached from the region (e.g. some countries block
toll-free numbers from being called outside of the country), the method
returns an empty string.
 
Arguments:
numobj -- The phone number to be formatted
region_calling_from -- The region where the call is being placed.
 
with_formatting -- whether the number should be returned with formatting
          symbols, such as spaces and dashes.
 
Returns the formatted phone number.
format_out_of_country_calling_number(numobj, region_calling_from)
Formats a phone number for out-of-country dialing purposes.
 
If no region_calling_from is supplied, we format the number in its
INTERNATIONAL format. If the country calling code is the same as that of
the region where the number is from, then NATIONAL formatting will be
applied.
 
If the number itself has a country calling code of zero or an otherwise
invalid country calling code, then we return the number with no formatting
applied.
 
Note this function takes care of the case for calling inside of NANPA and
between Russia and Kazakhstan (who share the same country calling
code). In those cases, no international prefix is used. For regions which
have multiple international prefixes, the number in its INTERNATIONAL
format will be returned instead.
 
Arguments:
numobj -- The phone number to be formatted
region_calling_from -- The region where the call is being placed
 
Returns the formatted phone number
format_out_of_country_keeping_alpha_chars(numobj, region_calling_from)
Formats a phone number for out-of-country dialing purposes.
 
Note that in this version, if the number was entered originally using
alpha characters and this version of the number is stored in raw_input,
this representation of the number will be used rather than the digit
representation. Grouping information, as specified by characters such as
"-" and " ", will be retained.
 
Caveats:
 
 - This will not produce good results if the country calling code is both
   present in the raw input _and_ is the start of the national
   number. This is not a problem in the regions which typically use alpha
   numbers.
 
 - This will also not produce good results if the raw input has any
   grouping information within the first three digits of the national
   number, and if the function needs to strip preceding digits/words in
   the raw input before these digits. Normally people group the first
   three digits together so this is not a huge problem - and will be fixed
   if it proves to be so.
 
Arguments:
numobj -- The phone number that needs to be formatted.
region_calling_from -- The region where the call is being placed.
 
Returns the formatted phone number
invalid_example_number(region_code)
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 -- 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.
is_alpha_number(number)
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 -- the number that needs to be checked
 
Returns True if the number is a valid vanity number
is_mobile_number_portable_region(region_code)
Returns true if the supplied region supports mobile number portability.
Returns false for invalid, unknown or regions that don't support mobile
number portability.
 
Arguments:
region_code -- the region for which we want to know whether it supports mobile number
               portability or not.
is_nanpa_country(region_code)
Checks if this region is a NANPA region.
 
Returns True if region_code is one of the regions under the North American
Numbering Plan Administration (NANPA).
is_number_geographical(numobj)
Tests whether a phone number has a geographical association.
 
It checks if the number is associated with a certain region in the country
to which it belongs. Note that this doesn't verify if the number is
actually in use.
country_code -- the country calling code for which we want the mobile token
is_number_match(num1, num2)
Takes two phone numbers and compares them for equality.
 
For example, the numbers +1 345 657 1234 and 657 1234 are a SHORT_NSN_MATCH.
The numbers +1 345 657 1234 and 345 657 are a NO_MATCH.
 
Arguments
num1 -- First number object or string to compare. Can contain formatting,
          and can have country calling code specified with + at the start.
num2 -- Second number object or string to compare. Can contain formatting,
          and can have country calling code specified with + at the start.
 
Returns:
 - EXACT_MATCH if the country_code, NSN, presence of a leading zero for
   Italian numbers and any extension present are the same.
 - NSN_MATCH if either or both has no region specified, and the NSNs and
   extensions are the same.
 - SHORT_NSN_MATCH if either or both has no region specified, or the
   region specified is the same, and one NSN could be a shorter version of
   the other number. This includes the case where one has an extension
   specified, and the other does not.
 - NO_MATCH otherwise.
is_number_type_geographical(num_type, country_code)
Tests whether a phone number has a geographical association,
as represented by its type and the country it belongs to.
 
This version of isNumberGeographical exists since calculating the phone
number type is expensive; if we have already done this, we don't want to
do it again.
is_possible_number(numobj)
Convenience wrapper around is_possible_number_with_reason.
 
Instead of returning the reason for failure, this method returns true if
the number is either a possible fully-qualified number (containing the area
code and country code), or if the number could be a possible local number
(with a country code, but missing an area code). Local numbers are
considered possible if they could be possibly dialled in this format: if
the area code is needed for a call to connect, the number is not considered
possible without it.
 
Arguments:
numobj -- the number object that needs to be checked
 
Returns True if the number is possible
is_possible_number_for_type(numobj, numtype)
Convenience wrapper around is_possible_number_for_type_with_reason.
 
Instead of returning the reason for failure, this method returns true if
the number is either a possible fully-qualified number (containing the area
code and country code), or if the number could be a possible local number
(with a country code, but missing an area code). Local numbers are
considered possible if they could be possibly dialled in this format: if
the area code is needed for a call to connect, the number is not considered
possible without it.
 
Arguments:
numobj -- the number object that needs to be checked
numtype -- the type we are interested in
 
Returns True if the number is possible
is_possible_number_for_type_with_reason(numobj, numtype)
Check whether a phone number is a possible number of a particular type.
 
For types that don't exist in a particular region, this will return a result
that isn't so useful; it is recommended that you use
supported_types_for_region or supported_types_for_non_geo_entity
respectively before calling this method to determine whether you should call
it for this number at all.
 
This provides a more lenient check than is_valid_number in the following sense:
 
 - It only checks the length of phone numbers. In particular, it doesn't
   check starting digits of the number.
 
 - For some numbers (particularly fixed-line), many regions have the
   concept of area code, which together with subscriber number constitute
   the national significant number. It is sometimes okay to dial only the
   subscriber number when dialing in the same area. This function will
   return IS_POSSIBLE_LOCAL_ONLY if the subscriber-number-only version is
   passed in. On the other hand, because is_valid_number validates using
   information on both starting digits (for fixed line numbers, that would
   most likely be area codes) and length (obviously includes the length of
   area codes for fixed line numbers), it will return false for the
   subscriber-number-only version.
 
Arguments:
numobj -- The number object that needs to be checked
numtype -- The type we are interested in
 
Returns a value from ValidationResult which indicates whether the number
is possible
is_possible_number_string(number, region_dialing_from)
Check whether a phone number string is a possible number.
 
Takes a number in the form of a string, and the region where the number
could be dialed from. It provides a more lenient check than
is_valid_number; see is_possible_number_with_reason() for details.
 
This method first parses the number, then invokes is_possible_number with
the resultant PhoneNumber object.
 
Arguments:
number -- The number that needs to be checked, in the form of a string.
region_dialling_from -- The region that we are expecting the number to be
          dialed from.  Note this is different from the region where the
          number belongs.  For example, the number +1 650 253 0000 is a
          number that belongs to US. When written in this form, it can be
          dialed from any region. When it is written as 00 1 650 253 0000,
          it can be dialed from any region which uses an international
          dialling prefix of 00. When it is written as 650 253 0000, it
          can only be dialed from within the US, and when written as 253
          0000, it can only be dialed from within a smaller area in the US
          (Mountain View, CA, to be more specific).
 
Returns True if the number is possible
is_possible_number_with_reason(numobj)
is_valid_number(numobj)
Tests whether a phone number matches a valid pattern.
 
Note this doesn't verify the number is actually in use, which is
impossible to tell by just looking at a number itself.  It only verifies
whether the parsed, canonicalised number is valid: not whether a
particular series of digits entered by the user is diallable from the
region provided when parsing. For example, the number +41 (0) 78 927 2696
can be parsed into a number with country code "41" and national
significant number "789272696". This is valid, while the original string
is not diallable.
 
Arguments:
numobj -- The phone number object that we want to validate
 
Returns a boolean that indicates whether the number is of a valid pattern.
is_valid_number_for_region(numobj, region_code)
Tests whether a phone number is valid for a certain region.
 
Note this doesn't verify the number is actually in use, which is
impossible to tell by just looking at a number itself. If the country
calling code is not the same as the country calling code for the region,
this immediately exits with false. After this, the specific number pattern
rules for the region are examined. This is useful for determining for
example whether a particular number is valid for Canada, rather than just
a valid NANPA number.
 
Warning: In most cases, you want to use is_valid_number instead. For
example, this method will mark numbers from British Crown dependencies
such as the Isle of Man as invalid for the region "GB" (United Kingdom),
since it has its own region code, "IM", which may be undesirable.
 
Arguments:
numobj -- The phone number object that we want to validate.
region_code -- The region that we want to validate the phone number for.
 
Returns a boolean that indicates whether the number is of a valid pattern.
length_of_geographical_area_code(numobj)
Return length of the geographical area code for a number.
 
Gets the length of the geographical area code from the PhoneNumber object
passed in, so that clients could use it to split a national significant
number into geographical area code and subscriber number. It works in such
a way that the resultant subscriber number should be diallable, at least
on some devices. An example of how this could be used:
 
>>> 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
 
N.B.: area code is a very ambiguous concept, so the I18N team generally
recommends against using it for most purposes, but recommends using the
more general national_number instead. Read the following carefully before
deciding to use this method:
 
 - geographical area codes change over time, and this method honors those
   changes; therefore, it doesn't guarantee the stability of the result it
   produces.
 - subscriber numbers may not be diallable from all devices (notably
   mobile devices, which typically require the full national_number to be
   dialled in most countries).
 - most non-geographical numbers have no area codes, including numbers
   from non-geographical entities.
 - some geographical numbers have no area codes.
 
Arguments:
numobj -- The PhoneNumber object to find the length of the area code form.
 
Returns the length of area code of the PhoneNumber object passed in.
length_of_national_destination_code(numobj)
Return length of the national destination code code for a number.
 
Gets the length of the national destination code (NDC) from the
PhoneNumber object passed in, so that clients could use it to split a
national significant number into NDC and subscriber number. The NDC of a
phone number is normally the first group of digit(s) right after the
country calling code when the number is formatted in the international
format, if there is a subscriber number part that follows.
 
N.B.: similar to an area code, not all numbers have an NDC!
 
An example of how this could be used:
 
>>> 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
 
Refer to the unittests to see the difference between this function and
length_of_geographical_area_code.
 
Arguments:
numobj -- The PhoneNumber object to find the length of the NDC from.
 
Returns the length of NDC of the PhoneNumber object passed in, which
could be zero.
national_significant_number(numobj)
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 -- The PhoneNumber object for which the national significant number
          is needed.
 
Returns the national significant number of the PhoneNumber object passed
in.
ndd_prefix_for_region(region_code, strip_non_digits)
Returns the national dialling prefix for a specific region.
 
For example, this would be 1 for the United States, and 0 for New
Zealand. Set strip_non_digits to True to strip symbols like "~" (which
indicates a wait for a dialling tone) from the prefix returned. If no
national prefix is present, we return None.
 
Warning: Do not use this method for do-your-own formatting - for some
regions, the national dialling prefix is used only for certain types of
numbers. Use the library's formatting functions to prefix the national
prefix when required.
 
Arguments:
region_code -- The region that we want to get the dialling prefix for.
strip_non_digits -- whether to strip non-digits from the national
           dialling prefix.
 
Returns the dialling prefix for the region denoted by region_code.
normalize_diallable_chars_only(number)
Normalizes a string of characters representing a phone number.
 
This strips all characters which are not diallable on a mobile phone
keypad (including all non-ASCII digits).
 
Arguments:
number -- a string of characters representing a phone number
 
Returns the normalized string version of the phone number.
normalize_digits_only(number, keep_non_digits=False)
Normalizes a string of characters representing a phone number.
 
This converts wide-ascii and arabic-indic numerals to European numerals,
and strips punctuation and alpha characters (optional).
 
Arguments:
number -- a string representing a phone number
keep_non_digits -- whether to keep non-digits
 
Returns the normalized string version of the phone number.
number_type(numobj)
Gets the type of a valid phone number.
 
Arguments:
numobj -- The PhoneNumber object that we want to know the type of.
 
Returns the type of the phone number, as a PhoneNumberType value;
returns PhoneNumberType.UNKNOWN if it is invalid.
parse(number, region=None, keep_raw_input=False, numobj=None, _check_region=True)
Parse a string and return a corresponding PhoneNumber object.
 
The method is quite lenient and looks for a number in the input text
(raw input) and does not check whether the string is definitely only a
phone number. To do this, it ignores punctuation and white-space, as
well as any text before the number (e.g. a leading "Tel: ") and trims
the non-number bits.  It will accept a number in any format (E164,
national, international etc), assuming it can be interpreted with the
defaultRegion supplied. It also attempts to convert any alpha characters
into digits if it thinks this is a vanity number of the type "1800
MICROSOFT".
 
This method will throw a NumberParseException if the number is not
considered to be a possible number. Note that validation of whether the
number is actually a valid number for a particular region is not
performed. This can be done separately with is_valid_number.
 
Note this method canonicalizes the phone number such that different
representations can be easily compared, no matter what form it was
originally entered in (e.g. national, international). If you want to
record context about the number being parsed, such as the raw input that
was entered, how the country code was derived etc. then ensure
keep_raw_input is set.
 
Note if any new field is added to this method that should always be filled
in, even when keep_raw_input is False, it should also be handled in the
_copy_core_fields_only() function.
 
Arguments:
number -- The number that we are attempting to parse. This can
          contain formatting such as +, ( and -, as well as a phone
          number extension. It can also be provided in RFC3966 format.
region -- The region that we are expecting the number to be from. This
          is only used if the number being parsed is not written in
          international format. The country_code for the number in
          this case would be stored as that of the default region
          supplied. If the number is guaranteed to start with a '+'
          followed by the country calling code, then None or
          UNKNOWN_REGION can be supplied.
keep_raw_input -- Whether to populate the raw_input field of the
          PhoneNumber object with number (as well as the
          country_code_source field).
numobj -- An optional existing PhoneNumber object to receive the
          parsing results
_check_region -- Whether to check the supplied region parameter;
          should always be True for external callers.
 
Returns a PhoneNumber object filled with the parse number.
 
Raises:
NumberParseException if the string is not considered to be a viable
phone number (e.g.  too few or too many digits) or if no default
region was supplied and the number is not in international format
(does not start with +).
region_code_for_country_code(country_code)
Returns the region code that matches a specific country calling code.
 
In the case of no region code being found, UNKNOWN_REGION ('ZZ') will be
returned. In the case of multiple regions, the one designated in the
metadata as the "main" region for this calling code will be returned.  If
the country_code entered is valid but doesn't match a specific region
(such as in the case of non-geographical calling codes like 800) the value
"001" will be returned (corresponding to the value for World in the UN
M.49 schema).
region_code_for_number(numobj)
Returns the region where a phone number is from.
 
This could be used for geocoding at the region level. Only guarantees
correct results for valid, full numbers (not short-codes, or invalid
numbers).
 
Arguments:
numobj -- The phone number object whose origin we want to know
 
Returns the region where the phone number is from, or None if no region
matches this calling code.
region_codes_for_country_code(country_code)
Returns a list with the region codes that match the specific country calling code.
 
For non-geographical country calling codes, the region code 001 is
returned. Also, in the case of no region code being found, an empty
list is returned.
supported_calling_codes()
Returns all country calling codes the library has metadata for, covering
both non-geographical entities (global network calling codes) and those
used for geographical entities. This could be used to populate a drop-down
box of country calling codes for a phone-number widget, for instance.
 
Returns an unordered set of the country calling codes for every geographica
and non-geographical entity the library supports.
supported_types_for_non_geo_entity(country_code)
Returns the types for a country-code belonging to a non-geographical entity
which the library has metadata for. Will not include FIXED_LINE_OR_MOBILE
(if numbers for this non-geographical entity could be classified as
FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would be present) and
UNKNOWN.
 
No types will be returned for country calling codes that do not map to a
known non-geographical entity.
supported_types_for_region(region_code)
Returns the types for a given region which the library has metadata for.
 
Will not include FIXED_LINE_OR_MOBILE (if numbers in this region could
be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would
be present) and UNKNOWN.
 
No types will be returned for invalid or unknown region codes.
truncate_too_long_number(numobj)
Truncate a number object that is too long.
 
Attempts to extract a valid number from a phone number that is too long
to be valid, and resets the PhoneNumber object passed in to that valid
version. If no valid number could be extracted, the PhoneNumber object
passed in will not be modified.
 
Arguments:
numobj -- A PhoneNumber object which contains a number that is too long to
          be valid.
 
Returns True if a valid phone number can be successfully extracted.

 
Data
        COUNTRY_CODES_FOR_NON_GEO_REGIONS = {800, 808, 870, 878, 881, 882, ...}
COUNTRY_CODE_TO_REGION_CODE = {1: ('US', 'AG', 'AI', 'AS', 'BB', 'BM', 'BS', 'CA', 'DM', 'DO', 'GD', 'GU', 'JM', 'KN', 'KY', 'LC', 'MP', 'MS', 'PR', 'SX', ...), 7: ('RU', 'KZ'), 20: ('EG',), 27: ('ZA',), 30: ('GR',), 31: ('NL',), 32: ('BE',), 33: ('FR',), 34: ('ES',), 36: ('HU',), ...}
NON_DIGITS_PATTERN = re.compile('(?:\\D+)')
REGION_CODE_FOR_NON_GEO_ENTITY = '001'
SUPPORTED_REGIONS = {'AC', 'AD', 'AE', 'AF', 'AG', 'AI', ...}
UNKNOWN_REGION = 'ZZ'
U_DASH = '-'
U_EMPTY_STRING = ''
U_SEMICOLON = ';'
U_SPACE = ' '
U_TILDE = '~'
U_ZERO = '0'