# -*- coding: utf-8 -*-

"""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

"""

# Based on original Java code:

# java/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java

# Copyright (C) 2009-2011 The Libphonenumber Authors

#

# Licensed under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

# http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an "AS IS" BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

import sys

import re

from .re_util import fullmatch # Extra regexp function; see README

from .util import UnicodeMixin, u, unicod, prnt, to_long

from .util import U_EMPTY_STRING, U_SPACE, U_DASH, U_TILDE, U_ZERO, U_SEMICOLON

from .unicode_util import digit as unicode_digit

# Data class definitions

from .phonenumber import PhoneNumber, CountryCodeSource

from .phonemetadata import NumberFormat, PhoneMetadata, REGION_CODE_FOR_NON_GEO_ENTITY

# Import auto-generated data structures

try:

from .data import _COUNTRY_CODE_TO_REGION_CODE

except ImportError: # pragma no cover

# Before the generated code exists, the data/ directory is empty.

# The generation process imports this module, creating a circular

# dependency. The hack below works around this.

import os

if (os.path.basename(sys.argv[0]) == "buildmetadatafromxml.py" or

os.path.basename(sys.argv[0]) == "buildprefixdata.py"):

prnt("Failed to import generated data (but OK as during autogeneration)", file=sys.stderr)

_COUNTRY_CODE_TO_REGION_CODE = {1: ("US",)}

else:

raise

# Set the master map from country code to region code. The

# extra level of indirection allows the unit test to replace

# the map with test data.

COUNTRY_CODE_TO_REGION_CODE = _COUNTRY_CODE_TO_REGION_CODE

# Naming convention for phone number arguments and variables:

# - string arguments are named 'number'

# - PhoneNumber objects are named 'numobj'

# Flags to use when compiling regular expressions for phone numbers.

_REGEX_FLAGS = re.UNICODE | re.IGNORECASE

# The minimum and maximum length of the national significant number.

_MIN_LENGTH_FOR_NSN = 2

# The ITU says the maximum length should be 15, but we have found longer

# numbers in Germany.

_MAX_LENGTH_FOR_NSN = 17

# The maximum length of the country calling code.

_MAX_LENGTH_COUNTRY_CODE = 3

# We don't allow input strings for parsing to be longer than 250 chars. This

# prevents malicious input from overflowing the regular-expression engine.

_MAX_INPUT_STRING_LENGTH = 250

# Region-code for the unknown region.

UNKNOWN_REGION = u("ZZ")

# The set of regions that share country calling code 1.

_NANPA_COUNTRY_CODE = 1

# The prefix that needs to be inserted in front of a Colombian landline number

# when dialed from a mobile phone in Colombia.

_COLOMBIA_MOBILE_TO_FIXED_LINE_PREFIX = unicod("3")

# Map of country calling codes that use a mobile token before the area

# code. One example of when this is relevant is when determining the length of

# the national destination code, which should be the length of the area code

# plus the length of the mobile token.

_MOBILE_TOKEN_MAPPINGS = {54: u('9')}

# Set of country codes that have geographically assigned mobile numbers (see

# GEO_MOBILE_COUNTRIES below) which are not based on *area codes*. For example,

# in China mobile numbers start with a carrier indicator, and beyond that are

# geographically assigned: this carrier indicator is not considered to be an

# area code.

_GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES = frozenset((

86,)) # China

# Set of country calling codes that have geographically assigned mobile

# numbers. This may not be complete; we add calling codes case by case, as we

# find geographical mobile numbers or hear from user reports. Note that

# countries like the US, where we can't distinguish between fixed-line or

# mobile numbers, are not listed here, since we consider FIXED_LINE_OR_MOBILE

# to be a possibly geographically-related type anyway (like FIXED_LINE).

_GEO_MOBILE_COUNTRIES = _GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES | set((

52, # Mexico

54, # Argentina

55, # Brazil

62)) # Indonesia: some prefixes only (fixed CMDA wireless)

# The PLUS_SIGN signifies the international prefix.

_PLUS_SIGN = u("+")

_STAR_SIGN = u('*')

_RFC3966_EXTN_PREFIX = u(";ext=")

_RFC3966_PREFIX = u("tel:")

_RFC3966_PHONE_CONTEXT = u(";phone-context=")

_RFC3966_ISDN_SUBADDRESS = u(";isub=")

# Simple ASCII digits map used to populate _ALPHA_PHONE_MAPPINGS and

# _ALL_PLUS_NUMBER_GROUPING_SYMBOLS.

_ASCII_DIGITS_MAP = {u("0"): u("0"), u("1"): u("1"),

u("2"): u("2"), u("3"): u("3"),

u("4"): u("4"), u("5"): u("5"),

u("6"): u("6"), u("7"): u("7"),

u("8"): u("8"), u("9"): u("9")}

# Only upper-case variants of alpha characters are stored.

_ALPHA_MAPPINGS = {u("A"): u("2"),

u("B"): u("2"),

u("C"): u("2"),

u("D"): u("3"),

u("E"): u("3"),

u("F"): u("3"),

u("G"): u("4"),

u("H"): u("4"),

u("I"): u("4"),

u("J"): u("5"),

u("K"): u("5"),

u("L"): u("5"),

u("M"): u("6"),

u("N"): u("6"),

u("O"): u("6"),

u("P"): u("7"),

u("Q"): u("7"),

u("R"): u("7"),

u("S"): u("7"),

u("T"): u("8"),

u("U"): u("8"),

u("V"): u("8"),

u("W"): u("9"),

u("X"): u("9"),

u("Y"): u("9"),

u("Z"): u("9"), }

# For performance reasons, amalgamate both into one map.

_ALPHA_PHONE_MAPPINGS = dict(_ALPHA_MAPPINGS, **_ASCII_DIGITS_MAP)

# A map that contains characters that are essential when dialling. That means

# any of the characters in this map must not be removed from a number when

# dialling, otherwise the call will not reach the intended destination.

_DIALLABLE_CHAR_MAPPINGS = dict({_PLUS_SIGN: _PLUS_SIGN,

u('*'): u('*'),

u('#'): u('#')},

**_ASCII_DIGITS_MAP)

# Separate map of all symbols that we wish to retain when formatting alpha

# numbers. This includes digits, ASCII letters and number grouping symbols

# such as "-" and " ".

_ALL_PLUS_NUMBER_GROUPING_SYMBOLS = dict({u("-"): u("-"), # Add grouping symbols.

u("\uFF0D"): u("-"),

u("\u2010"): u("-"),

u("\u2011"): u("-"),

u("\u2012"): u("-"),

u("\u2013"): u("-"),

u("\u2014"): u("-"),

u("\u2015"): u("-"),

u("\u2212"): u("-"),

u("/"): u("/"),

u("\uFF0F"): u("/"),

u(" "): u(" "),

u("\u3000"): u(" "),

u("\u2060"): u(" "),

u("."): u("."),

u("\uFF0E"): u(".")},

# Put (lower letter -> upper letter) and

# (upper letter -> upper letter) mappings.

**dict([(_c.lower(), _c) for _c in _ALPHA_MAPPINGS.keys()] +

[(_c, _c) for _c in _ALPHA_MAPPINGS.keys()],

**_ASCII_DIGITS_MAP))

# Pattern that makes it easy to distinguish whether a region has a single international dialing

# prefix or not. If a region has a single international prefix (e.g. 011 in USA), it will be

# represented as a string that contains a sequence of ASCII digits, and possibly a tilde, which

# signals waiting for the tone. If there are multiple available international prefixes in a

# region, they will be represented as a regex string that always contains one or more characters

# that are not ASCII digits or a tilde.

_SINGLE_INTERNATIONAL_PREFIX = re.compile(u("[\\d]+(?:[~\u2053\u223C\uFF5E][\\d]+)?"))

# Regular expression of acceptable punctuation found in phone numbers. This

# excludes punctuation found as a leading character only.

# Regular expression of acceptable punctuation found in phone numbers, used to find numbers in

# text and to decide what is a viable phone number. This excludes diallable characters.

# This consists of dash characters, white space characters, full stops, slashes, square brackets,

# parentheses and tildes. It also includes the letter 'x' as that is found as a placeholder for

# carrier information in some phone numbers. Full-width variants are also present.

_VALID_PUNCTUATION = (u("-x\u2010-\u2015\u2212\u30FC\uFF0D-\uFF0F ") +

u("\u00A0\u00AD\u200B\u2060\u3000()\uFF08\uFF09\uFF3B\uFF3D.\\[\\]/~\u2053\u223C\uFF5E"))

_DIGITS = unicod('\\d') # Java "\\p{Nd}", so need "(?u)" or re.UNICODE wherever this is used

# We accept alpha characters in phone numbers, ASCII only, upper and lower

# case.

_VALID_ALPHA = (U_EMPTY_STRING.join(_ALPHA_MAPPINGS.keys()) +

U_EMPTY_STRING.join([_k.lower() for _k in _ALPHA_MAPPINGS.keys()]))

_PLUS_CHARS = u("+\uFF0B")

_PLUS_CHARS_PATTERN = re.compile(u("[") + _PLUS_CHARS + u("]+"))

_SEPARATOR_PATTERN = re.compile(u("[") + _VALID_PUNCTUATION + u("]+"))

_CAPTURING_DIGIT_PATTERN = re.compile(u("(") + _DIGITS + u(")"), re.UNICODE)

# Regular expression of acceptable characters that may start a phone number

# for the purposes of parsing. This allows us to strip away meaningless

# prefixes to phone numbers that may be mistakenly given to us. This consists

# of digits, the plus symbol and arabic-indic digits. This does not contain

# alpha characters, although they may be used later in the number. It also

# does not include other punctuation, as this will be stripped later during

# parsing and is of no information value when parsing a number.

_VALID_START_CHAR = u("[") + _PLUS_CHARS + _DIGITS + u("]")

_VALID_START_CHAR_PATTERN = re.compile(_VALID_START_CHAR, re.UNICODE)

# Regular expression of characters typically used to start a second phone

# number for the purposes of parsing. This allows us to strip off parts of the

# number that are actually the start of another number, such as for: (530)

# 583-6985 x302/x2303 -> the second extension here makes this actually two

# phone numbers, (530) 583-6985 x302 and (530) 583-6985 x2303. We remove the

# second extension so that the first number is parsed correctly.

_SECOND_NUMBER_START = u("[\\\\/] *x")

_SECOND_NUMBER_START_PATTERN = re.compile(_SECOND_NUMBER_START)

# Regular expression of trailing characters that we want to remove. We remove

# all characters that are not alpha or numerical characters. The hash

# character is retained here, as it may signify the previous block was an

# extension.

#

# The original Java regexp is:

# [[\\P{N}&&\\P{L}]&&[^#]]+$

# which splits out as:

# [ ]+$ : >=1 of the following chars at end of string

# [ ]&&[ ] : intersection of these two sets of chars

# [ && ] : intersection of these two sets of chars

# \\P{N} : characters without the "Number" Unicode property

# \\P{L} : characters without the "Letter" Unicode property

# [^#] : character other than hash

# which nets down to: >=1 non-Number, non-Letter, non-# characters at string end

# In Python Unicode regexp mode '(?u)', the class '[^#\w]' will match anything

# that is not # and is not alphanumeric and is not underscore.

_UNWANTED_END_CHARS = u(r"(?u)(?:_|[^#\w])+$")

_UNWANTED_END_CHAR_PATTERN = re.compile(_UNWANTED_END_CHARS)

# We use this pattern to check if the phone number has at least three letters

# in it - if so, then we treat it as a number where some phone-number digits

# are represented by letters.

_VALID_ALPHA_PHONE_PATTERN = re.compile(u("(?:.*?[A-Za-z]){3}.*"))

# Regular expression of viable phone numbers. This is location

# independent. Checks we have at least three leading digits, and only valid

# punctuation, alpha characters and digits in the phone number. Does not

# include extension data. The symbol 'x' is allowed here as valid punctuation

# since it is often used as a placeholder for carrier codes, for example in

# Brazilian phone numbers. We also allow multiple "+" characters at the start.

# Corresponds to the following:

# [digits]{minLengthNsn}|

# plus_sign*(([punctuation]|[star])*[digits]){3,}([punctuation]|[star]|[digits]|[alpha])*

#

# The first reg-ex is to allow short numbers (two digits long) to be parsed if

# they are entered as "15" etc, but only if there is no punctuation in

# them. The second expression restricts the number of digits to three or more,

# but then allows them to be in international form, and to have

# alpha-characters and punctuation.

#

# Note VALID_PUNCTUATION starts with a -, so must be the first in the range.

_VALID_PHONE_NUMBER = (_DIGITS + (u("{%d}") % _MIN_LENGTH_FOR_NSN) + u("|") +

u("[") + _PLUS_CHARS + u("]*(?:[") + _VALID_PUNCTUATION + _STAR_SIGN + u("]*") + _DIGITS + u("){3,}[") +

_VALID_PUNCTUATION + _STAR_SIGN + _VALID_ALPHA + _DIGITS + u("]*"))

# Default extension prefix to use when formatting. This will be put in front

# of any extension component of the number, after the main national number is

# formatted. For example, if you wish the default extension formatting to be

# " extn: 3456", then you should specify " extn: " here as the default

# extension prefix. This can be overridden by region-specific preferences.

_DEFAULT_EXTN_PREFIX = u(" ext. ")

# Helper method for constructing regular expressions for parsing. Creates an expression that

# captures up to max_length digits.

def _extn_digits(max_length):

return u("(") + _DIGITS + (u("{1,%d})") % max_length)

# Helper initialiser method to create the regular-expression pattern to match extensions.

# Note that there are currently six capturing groups for the extension itself. If this number is

# changed, _maybe_strip_extension needs to be updated.

def _create_extn_pattern(for_parsing):

# We cap the maximum length of an extension based on the ambiguity of the way the extension is

# prefixed. As per ITU, the officially allowed length for extensions is actually 40, but we

# don't support this since we haven't seen real examples and this introduces many false

# interpretations as the extension labels are not standardized.

ext_limit_after_explicit_label = 20

ext_limit_after_likely_label = 15

ext_limit_after_ambiguous_char = 9

ext_limit_when_not_sure = 6

possible_separators_between_number_and_ext_label = u("[ \u00A0\\t,]*")

# Optional full stop (.) or colon, followed by zero or more spaces/tabs/commas.

possible_chars_after_ext_label = u("[:\\.\uFF0E]?[ \u00A0\\t,-]*")

optional_extn_suffix = u("#?")

# Here the extension is called out in more explicit way, i.e mentioning it obvious patterns

# like "ext.". Canonical-equivalence doesn't seem to be an option with Android java, so we

# allow two options for representing the accented o - the character itself, and one in the

# unicode decomposed form with the combining acute accent.

explicit_ext_labels = u("(?:e?xt(?:ensi(?:o\u0301?|\u00F3))?n?|\uFF45?\uFF58\uFF54\uFF4E?|\u0434\u043E\u0431|anexo)")

# One-character symbols that can be used to indicate an extension, and less commonly used

# or more ambiguous extension labels.

ambiguous_ext_labels = u("(?:[x\uFF58#\uFF03~\uFF5E]|int|\uFF49\uFF4E\uFF54)")

# When extension is not separated clearly.

ambiguous_separator = u("[- ]+")

rfc_extn = _RFC3966_EXTN_PREFIX + _extn_digits(ext_limit_after_explicit_label)

explicit_extn = (possible_separators_between_number_and_ext_label + explicit_ext_labels +

possible_chars_after_ext_label + _extn_digits(ext_limit_after_explicit_label) +

optional_extn_suffix)

ambiguous_extn = (possible_separators_between_number_and_ext_label + ambiguous_ext_labels +

possible_chars_after_ext_label + _extn_digits(ext_limit_after_ambiguous_char) + optional_extn_suffix)

american_style_extn_with_suffix = (ambiguous_separator + _extn_digits(ext_limit_when_not_sure) + u("#"))

# The first regular expression covers RFC 3966 format, where the extension is added using

# ";ext=". The second more generic where extension is mentioned with explicit labels like

# "ext:". In both the above cases we allow more numbers in extension than any other extension

# labels. The third one captures when single character extension labels or less commonly used

# labels are used. In such cases we capture fewer extension digits in order to reduce the

# chance of falsely interpreting two numbers beside each other as a number + extension. The

# fourth one covers the special case of American numbers where the extension is written with a

# hash at the end, such as "- 503#".

extension_pattern = (rfc_extn + u("|") +

explicit_extn + u("|") +

ambiguous_extn + u("|") +

american_style_extn_with_suffix)

# Additional pattern that is supported when parsing extensions, not when matching.

if for_parsing:

# This is same as possible_separators_between_number_and_ext_label, but not matching comma as

# extension label may have it.

possible_separators_number_ext_label_no_comma = u("[ \u00A0\\t]*")

# ",," is commonly used for auto dialling the extension when connected. First comma is matched

# through possible_separators_between_number_and_ext_label, so we do not repeat it here. Semi-colon

# works in Iphone and Android also to pop up a button with the extension number following.

auto_dialling_and_ext_labels_found = u("(?:,{2}|;)")

auto_dialling_extn = (possible_separators_number_ext_label_no_comma +

auto_dialling_and_ext_labels_found + possible_chars_after_ext_label +

_extn_digits(ext_limit_after_likely_label) + optional_extn_suffix)

only_commas_extn = (possible_separators_number_ext_label_no_comma +

u("(?:,)+") + possible_chars_after_ext_label + _extn_digits(ext_limit_after_ambiguous_char) +

optional_extn_suffix)

# Here the first pattern is exclusively for extension autodialling formats which are used

# when dialling and in this case we accept longer extensions. However, the second pattern

# is more liberal on the number of commas that acts as extension labels, so we have a strict

# cap on the number of digits in such extensions.

return (extension_pattern + u("|") +

auto_dialling_extn + u("|") +

only_commas_extn)

return extension_pattern

# Regexp of all possible ways to write extensions, for use when parsing. This

# will be run as a case-insensitive regexp match. Wide character versions are

# also provided after each ASCII version.

_EXTN_PATTERNS_FOR_PARSING = _create_extn_pattern(True)

_EXTN_PATTERNS_FOR_MATCHING = _create_extn_pattern(False)

# Regexp of all known extension prefixes used by different regions followed by

# 1 or more valid digits, for use when parsing.

_EXTN_PATTERN = re.compile(u("(?:") + _EXTN_PATTERNS_FOR_PARSING + u(")$"), _REGEX_FLAGS)

# We append optionally the extension pattern to the end here, as a valid phone

# number may have an extension prefix appended, followed by 1 or more digits.

_VALID_PHONE_NUMBER_PATTERN = re.compile(_VALID_PHONE_NUMBER + u("(?:") + _EXTN_PATTERNS_FOR_PARSING + u(")?"), _REGEX_FLAGS)

# We use a non-capturing group because Python's re.split() returns any capturing

# groups interspersed with the other results (unlike Java's Pattern.split()).

NON_DIGITS_PATTERN = re.compile(u("(?:\\D+)"))

# The FIRST_GROUP_PATTERN was originally set to \1 but there are some

# countries for which the first group is not used in the national pattern

# (e.g. Argentina) so the \1 group does not match correctly. Therefore, we

# use \d, so that the first group actually used in the pattern will be

# matched.

_FIRST_GROUP_PATTERN = re.compile(u(r"(\\\d)"))

# Constants used in the formatting rules to represent the national prefix, first group and

# carrier code respectively.

_NP_STRING = "$NP"

_FG_STRING = "$FG"

_CC_STRING = "$CC"

# A pattern that is used to determine if the national prefix formatting rule

# has the first group only, i.e., does not start with the national

# prefix. Note that the pattern explicitly allows for unbalanced parentheses.

_FIRST_GROUP_ONLY_PREFIX_PATTERN = re.compile("\\(?\\\\1\\)?")

class PhoneNumberFormat(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.

"""

E164 = 0

INTERNATIONAL = 1

NATIONAL = 2

RFC3966 = 3

class PhoneNumberType(object):

"""Type of phone numbers."""

FIXED_LINE = 0

MOBILE = 1

# In some regions (e.g. the USA), it is impossible to distinguish between

# fixed-line and mobile numbers by looking at the phone number itself.

FIXED_LINE_OR_MOBILE = 2

# Freephone lines

TOLL_FREE = 3

PREMIUM_RATE = 4

# The cost of this call is shared between the caller and the recipient,

# and is hence typically less than PREMIUM_RATE calls. See

# http://en.wikipedia.org/wiki/Shared_Cost_Service for more information.

SHARED_COST = 5

# Voice over IP numbers. This includes TSoIP (Telephony Service over IP).

VOIP = 6

# A personal number is associated with a particular person, and may be

# routed to either a MOBILE or FIXED_LINE number. Some more information

# can be found here: http://en.wikipedia.org/wiki/Personal_Numbers

PERSONAL_NUMBER = 7

PAGER = 8

# Used for "Universal Access Numbers" or "Company Numbers". They may be

# further routed to specific offices, but allow one number to be used for

# a company.

UAN = 9

# Used for "Voice Mail Access Numbers".

VOICEMAIL = 10

# A phone number is of type UNKNOWN when it does not fit any of the known

# patterns for a specific region.

UNKNOWN = 99

@classmethod

def values(cls):

return (PhoneNumberType.FIXED_LINE,

PhoneNumberType.MOBILE,

PhoneNumberType.FIXED_LINE_OR_MOBILE,

PhoneNumberType.TOLL_FREE,

PhoneNumberType.PREMIUM_RATE,

PhoneNumberType.SHARED_COST,

PhoneNumberType.VOIP,

PhoneNumberType.PERSONAL_NUMBER,

PhoneNumberType.PAGER,

PhoneNumberType.UAN,

PhoneNumberType.VOICEMAIL,

PhoneNumberType.UNKNOWN)

class MatchType(object):

"""Types of phone number matches."""

# Not a telephone number

NOT_A_NUMBER = 0

# None of the match types below apply

NO_MATCH = 1

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

SHORT_NSN_MATCH = 2

# Either or both has no region specified, and the NSNs and extensions are

# the same.

NSN_MATCH = 3

# The country_code, NSN, presence of a leading zero for Italian numbers

# and any extension present are the same.

EXACT_MATCH = 4

class ValidationResult(object):

"""Possible outcomes when testing if a PhoneNumber is a possible number."""

# The number length matches that of valid numbers for this region.

IS_POSSIBLE = 0

# The number length matches that of local numbers for this region only

# (i.e. numbers that may be able to be dialled within an area, but do not

# have all the information to be dialled from anywhere inside or outside

# the country).

IS_POSSIBLE_LOCAL_ONLY = 4

# The number has an invalid country calling code.

INVALID_COUNTRY_CODE = 1

# The number is shorter than all valid numbers for this region.

TOO_SHORT = 2

# The number is longer than the shortest valid numbers for this region,

# shorter than the longest valid numbers for this region, and does not

# itself have a number length that matches valid numbers for this region.

# This can also be returned in the case where

# is_possible_number_for_type_with_reason was called, and there are no

# numbers of this type at all for this region.

INVALID_LENGTH = 5

# The number is longer than all valid numbers for this region.

TOO_LONG = 3

# Derived data structures

SUPPORTED_REGIONS = set()

COUNTRY_CODES_FOR_NON_GEO_REGIONS = set()

_NANPA_REGIONS = set()

def _regenerate_derived_data():

global SUPPORTED_REGIONS, COUNTRY_CODES_FOR_NON_GEO_REGIONS, _NANPA_REGIONS

SUPPORTED_REGIONS.clear()

COUNTRY_CODES_FOR_NON_GEO_REGIONS.clear()

for cc, region_codes in COUNTRY_CODE_TO_REGION_CODE.items():

if (len(region_codes) == 1 and region_codes[0] == REGION_CODE_FOR_NON_GEO_ENTITY):

COUNTRY_CODES_FOR_NON_GEO_REGIONS.add(cc)

else:

SUPPORTED_REGIONS.update(region_codes)

if REGION_CODE_FOR_NON_GEO_ENTITY in SUPPORTED_REGIONS: # pragma no cover

SUPPORTED_REGIONS.remove(REGION_CODE_FOR_NON_GEO_ENTITY)

_NANPA_REGIONS.clear()

_NANPA_REGIONS.update(COUNTRY_CODE_TO_REGION_CODE[_NANPA_COUNTRY_CODE])

_regenerate_derived_data()

def _copy_number_format(other):

"""Return a mutable copy of the given NumberFormat object"""

copy = NumberFormat(pattern=other.pattern,

format=other.format,

leading_digits_pattern=list(other.leading_digits_pattern),

national_prefix_formatting_rule=other.national_prefix_formatting_rule,

national_prefix_optional_when_formatting=other.national_prefix_optional_when_formatting,

domestic_carrier_code_formatting_rule=other.domestic_carrier_code_formatting_rule)

copy._mutable = True

return copy

def _extract_possible_number(number):

"""Attempt to extract a possible number from the string passed in.

This currently strips all leading characters that cannot be used to

start a phone number. Characters that can be used to start a phone number

are defined in the VALID_START_CHAR_PATTERN. If none of these characters

are found in the number passed in, an empty string is returned. This

function also attempts to strip off any alternative extensions or endings

if two or more are present, such as in the case of: (530) 583-6985

x302/x2303. The second extension here makes this actually two phone

numbers, (530) 583-6985 x302 and (530) 583-6985 x2303. We remove the

second extension so that the first number is parsed correctly.

Arguments:

number -- The string that might contain a phone number.

Returns the number, stripped of any non-phone-number prefix (such

as "Tel:") or an empty string if no character used to start phone

numbers (such as + or any digit) is found in the number

"""

match = _VALID_START_CHAR_PATTERN.search(number)

if match:

number = number[match.start():]

# Remove trailing non-alpha non-numberical characters.

trailing_chars_match = _UNWANTED_END_CHAR_PATTERN.search(number)

if trailing_chars_match:

number = number[:trailing_chars_match.start()]

# Check for extra numbers at the end.

second_number_match = _SECOND_NUMBER_START_PATTERN.search(number)

if second_number_match:

number = number[:second_number_match.start()]

return number

else:

return U_EMPTY_STRING

def _is_viable_phone_number(number):

"""Checks to see if a string could possibly be a phone number.

At the moment, checks to see that the string begins with at least 2

digits, ignoring any punctuation commonly found in phone numbers. This

method does not require the number to be normalized in advance - but does

assume that leading non-number symbols have been removed, such as by the

method _extract_possible_number.

Arguments:

number -- string to be checked for viability as a phone number

Returns True if the number could be a phone number of some sort, otherwise

False

"""

if len(number) < _MIN_LENGTH_FOR_NSN:

return False

match = fullmatch(_VALID_PHONE_NUMBER_PATTERN, number)

return bool(match)

def _normalize(number):

"""Normalizes a string of characters representing a phone number.

This performs the following conversions:

- Punctuation is stripped.

- For ALPHA/VANITY numbers:

- Letters are converted to their numeric representation on a telephone

keypad. The keypad used here is the one defined in ITU

Recommendation E.161. This is only done if there are 3 or more

letters in the number, to lessen the risk that such letters are

typos.

- For other numbers:

- Wide-ascii digits are converted to normal ASCII (European) digits.

- Arabic-Indic numerals are converted to European numerals.

- Spurious alpha characters are stripped.

Arguments:

number -- string representing a phone number

Returns the normalized string version of the phone number.

"""

m = fullmatch(_VALID_ALPHA_PHONE_PATTERN, number)

if m:

return _normalize_helper(number, _ALPHA_PHONE_MAPPINGS, True)

else:

return normalize_digits_only(number)

def 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 = unicod(number)

number_length = len(number)

normalized_digits = U_EMPTY_STRING

for ii in range(number_length):

d = unicode_digit(number[ii], -1)

if d != -1:

normalized_digits += unicod(d)

elif keep_non_digits:

normalized_digits += number[ii]

return normalized_digits

def 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.

"""

return _normalize_helper(number, _DIALLABLE_CHAR_MAPPINGS, True)

def convert_alpha_characters_in_number(number):

"""Convert alpha chars in a number to their respective digits on a keypad,

but retains existing formatting."""

return _normalize_helper(number, _ALPHA_PHONE_MAPPINGS, False)

def 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.

"""

metadata = PhoneMetadata.metadata_for_region(region_code_for_number(numobj), None)

if metadata is None:

return 0

# If a country doesn't use a national prefix, and this number doesn't have

# an Italian leading zero, we assume it is a closed dialling plan with no

# area codes.

if metadata.national_prefix is None and not numobj.italian_leading_zero:

return 0

ntype = number_type(numobj)

country_code = numobj.country_code

if (ntype == PhoneNumberType.MOBILE and

(country_code in _GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES)):

# Note this is a rough heuristic; it doesn't cover Indonesia well, for

# example, where area codes are present for some mobile phones but not

# for others. We have no better way of representing this in the

# metadata at this point.

return 0

if not is_number_type_geographical(ntype, country_code):

return 0

return length_of_national_destination_code(numobj)

def 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.

"""

if numobj.extension is not None:

# We don't want to alter the object given to us, but we don't want to

# include the extension when we format it, so we copy it and clear the

# extension here.

copied_numobj = PhoneNumber()

copied_numobj.merge_from(numobj)

copied_numobj.extension = None

else:

copied_numobj = numobj

nsn = format_number(copied_numobj, PhoneNumberFormat.INTERNATIONAL)

number_groups = re.split(NON_DIGITS_PATTERN, nsn)

# The pattern will start with "+COUNTRY_CODE " so the first group will

# always be the empty string (before the + symbol) and the second group

# will be the country calling code. The third group will be area code if

# it is not the last group.

if len(number_groups) <= 3:

return 0

if number_type(numobj) == PhoneNumberType.MOBILE:

# For example Argentinian mobile numbers, when formatted in the

# international format, are in the form of +54 9 NDC XXXX... As a

# result, we take the length of the third group (NDC) and add the

# length of the second group (which is the mobile token), which also

# forms part of the national significant number. This assumes that

# the mobile token is always formatted separately from the rest of the

# phone number.

mobile_token = country_mobile_token(numobj.country_code)

if mobile_token != U_EMPTY_STRING:

return len(number_groups[2]) + len(number_groups[3])

return len(number_groups[2])

def 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.

"""

return _MOBILE_TOKEN_MAPPINGS.get(country_code, U_EMPTY_STRING)

def _normalize_helper(number, replacements, remove_non_matches):

"""Normalizes a string of characters representing a phone number by

replacing all characters found in the accompanying map with the values

therein, and stripping all other characters if remove_non_matches is true.

Arguments:

number -- a string representing a phone number

replacements -- a mapping of characters to what they should be replaced

by in the normalized version of the phone number

remove_non_matches -- indicates whether characters that are not able to be

replaced should be stripped from the number. If this is False,

they will be left unchanged in the number.

Returns the normalized string version of the phone number.

"""

normalized_number = []

for char in number:

new_digit = replacements.get(char.upper(), None)

if new_digit is not None:

normalized_number.append(new_digit)

elif not remove_non_matches:

normalized_number.append(char)

# If neither of the above are true, we remove this character

return U_EMPTY_STRING.join(normalized_number)

def 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.

"""

return set(COUNTRY_CODE_TO_REGION_CODE.keys())

def _desc_has_possible_number_data(desc):

"""Returns true if there is any possible number data set for a particular PhoneNumberDesc."""

# If this is empty, it means numbers of this type inherit from the "general desc" -> the value

# "-1" means that no numbers exist for this type.

if desc is None:

return False

return len(desc.possible_length) != 1 or desc.possible_length[0] != -1

# Note: desc_has_data must account for any of MetadataFilter's excludableChildFields potentially

# being absent from the metadata. It must check them all. For any changes in descHasData, ensure

# that all the excludableChildFields are still being checked. If your change is safe simply

# mention why during a review without needing to change MetadataFilter.

def _desc_has_data(desc):

"""Returns true if there is any data set for a particular PhoneNumberDesc."""

if desc is None:

return False

# Checking most properties since we don't know what's present, since a custom build may have

# stripped just one of them (e.g. liteBuild strips exampleNumber). We don't bother checking the

# possibleLengthsLocalOnly, since if this is the only thing that's present we don't really

# support the type at all: no type-specific methods will work with only this data.

return ((desc.example_number is not None) or

_desc_has_possible_number_data(desc) or

(desc.national_number_pattern is not None))

def _supported_types_for_metadata(metadata):

"""Returns the types we have metadata for based on the PhoneMetadata object passed in, which must be non-None."""

numtypes = set()

for numtype in PhoneNumberType.values():

if numtype in (PhoneNumberType.FIXED_LINE_OR_MOBILE, PhoneNumberType.UNKNOWN):

# Never return FIXED_LINE_OR_MOBILE (it is a convenience type, and represents that a

# particular number type can't be determined) or UNKNOWN (the non-type).

continue

if _desc_has_data(_number_desc_by_type(metadata, numtype)):

numtypes.add(numtype)

return numtypes

def 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.

"""

if not _is_valid_region_code(region_code):

return set()

metadata = PhoneMetadata.metadata_for_region(region_code.upper())

return _supported_types_for_metadata(metadata)

def 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.

"""

metadata = PhoneMetadata.metadata_for_nongeo_region(country_code, None)

if metadata is None:

return set()

return _supported_types_for_metadata(metadata)

def _formatting_rule_has_first_group_only(national_prefix_formatting_rule):

"""Helper function to check if the national prefix formatting rule has the

first group only, i.e., does not start with the national prefix.

"""

if national_prefix_formatting_rule is None:

return True

return bool(fullmatch(_FIRST_GROUP_ONLY_PREFIX_PATTERN,

national_prefix_formatting_rule))

def 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

"""

return is_number_type_geographical(number_type(numobj), numobj.country_code)

def 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.

"""

return (num_type == PhoneNumberType.FIXED_LINE or

num_type == PhoneNumberType.FIXED_LINE_OR_MOBILE or

((country_code in _GEO_MOBILE_COUNTRIES) and

num_type == PhoneNumberType.MOBILE))

def _is_valid_region_code(region_code):

"""Helper function to check region code is not unknown or None"""

if region_code is None:

return False

return (region_code in SUPPORTED_REGIONS)

def _has_valid_country_calling_code(country_calling_code):

return (country_calling_code in COUNTRY_CODE_TO_REGION_CODE)

def 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