Python: module phonenumbers.phonenumberutil

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'