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

http://groups.google.com/group/libphonenumber-discuss/about.

NOTE: A lot of methods in this module require Region Code strings. These must

be provided using ISO 3166-1 two-letter country-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

author: Shaopeng Jia (original Java version)

author: Lara Rennie (original Java Version)

author: David Drysdale (Python version)

"""

# 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 re

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

from .util import UnicodeMixin

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

import sys

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

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

print >> sys.stderr, "Failed to import generated data (but OK as during autogeneration)"

_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 = 16

# 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 = "3"

# 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'*'},

**_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'-', # Put 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 unique

# international dialing prefix or not. If a region has a unique international

# prefix (e.g. 011 in USA), it will be represented as a string that contains a

# sequence of ASCII digits. If there are multiple available international

# prefixes in a region, they will be represented as a regex string that always

# contains character(s) other than ASCII digits. Note this regex also

# includes tilde, which signals waiting for the tone.

_UNIQUE_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. 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 = '\\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 = (''.join(_ALPHA_MAPPINGS.keys()) +

''.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)(?:_|[^#\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. "

# Pattern to capture digits used in an extension. Places a maximum length of

# "7" for an extension.

_CAPTURING_EXTN_DIGITS = u"(" + _DIGITS + u"{1,7})"

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

# One-character symbols that can be used to indicate an extension.

_SINGLE_EXTN_SYMBOLS_FOR_MATCHING = u"x\uFF58#\uFF03~\uFF5E"

# For parsing, we are slightly more lenient in our interpretation than for

# matching. Here we allow a "comma" as a possible extension indicator. When

# matching, this is hardly ever used to indicate this.

_SINGLE_EXTN_SYMBOLS_FOR_PARSING = "," + _SINGLE_EXTN_SYMBOLS_FOR_MATCHING

def _create_extn_pattern(single_extn_symbols):

"""Helper initialiser method to create the regular-expression pattern to

match extensions, allowing the one-char extension symbols provided by

single_extn_symbols."""

# There are three regular expressions here. The first covers RFC 3966

# format, where the extension is added using ";ext=". The second more

# generic one starts with optional white space and ends with an optional

# full stop (.), followed by zero or more spaces/tabs and then the numbers

# themselves. The other one covers the special case of American numbers

# where the extension is written with a hash at the end, such as "- 503#".

# Note that the only capturing groups should be around the digits that you

# want to capture as part of the extension, or else parsing will fail!

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

return (_RFC3966_EXTN_PREFIX + _CAPTURING_EXTN_DIGITS + u"|" +

u"[ \u00A0\\t,]*(?:e?xt(?:ensi(?:o\u0301?|\u00F3))?n?|" +

u"\uFF45?\uFF58\uFF54\uFF4E?|" +

u"[" + single_extn_symbols + u"]|int|anexo|\uFF49\uFF4E\uFF54)" +

u"[:\\.\uFF0E]?[ \u00A0\\t,-]*" + _CAPTURING_EXTN_DIGITS + u"#?|" +

u"[- ]+(" + _DIGITS + u"{1,5})#")

_EXTN_PATTERNS_FOR_PARSING = _create_extn_pattern(_SINGLE_EXTN_SYMBOLS_FOR_PARSING)

_EXTN_PATTERNS_FOR_MATCHING = _create_extn_pattern(_SINGLE_EXTN_SYMBOLS_FOR_MATCHING)

# 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("(?:\\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(r"(\\\d)")

_NP_PATTERN = re.compile("\\$NP")

_FG_PATTERN = re.compile("\\$FG")

_CC_PATTERN = re.compile("\\$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. 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

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

IS_POSSIBLE = 0

INVALID_COUNTRY_CODE = 1

TOO_SHORT = 2

TOO_LONG = 3

# Derived data structures

SUPPORTED_REGIONS = set([_item for _sublist in COUNTRY_CODE_TO_REGION_CODE.values() for _item in _sublist])

if REGION_CODE_FOR_NON_GEO_ENTITY in SUPPORTED_REGIONS:

SUPPORTED_REGIONS.remove(REGION_CODE_FOR_NON_GEO_ENTITY)

_NANPA_REGIONS = set(COUNTRY_CODE_TO_REGION_CODE[_NANPA_COUNTRY_CODE])

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

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 - otherwise alpha characters are stripped.

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

number_length = len(number)

normalized_digits = u""

for ii in xrange(number_length):

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

if d != -1:

normalized_digits += unicode(d)

elif keep_non_digits:

normalized_digits += number[ii]

return normalized_digits

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 national_number

field of 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.region_metadata.get(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

if not _is_number_geographical(numobj):

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

"""

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 (region_code_for_country_code(numobj.country_code) == "AR" and

number_type(numobj) == PhoneNumberType.MOBILE):

# 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 1 for the digit 9, which also

# forms part of the national significant number.

#

# TODO: Investigate the possibility of better modeling the metadata to

# make it easier to obtain the NDC.

return len(number_groups[3]) + 1

return len(number_groups[2])

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''.join(normalized_number)

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: # pragma no cover

return False

return bool(fullmatch(_FIRST_GROUP_ONLY_PREFIX_PATTERN,

national_prefix_formatting_rule))

def _is_number_geographical(numobj):

num_type = number_type(numobj)

# TODO: Include mobile phone numbers from countries like Indonesia, which

# has some mobile numbers that are geographical.

return (num_type == PhoneNumberType.FIXED_LINE or

num_type == PhoneNumberType.FIXED_LINE_OR_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

Returns the formatted phone number.

"""

if numobj.national_number == 0 and numobj.raw_input is not None:

# Unparseable numbers that kept their raw input just use that. This

# is the only case where a number can be formatted as E164 without a

# leading '+' symbol (but the original number wasn't parseable

# anyway).

# TODO: Consider removing the 'if' above so that unparseable strings

# without raw input format to the empty string instead of "+00"

if len(numobj.raw_input) > 0:

return numobj.raw_input

country_calling_code = numobj.country_code

nsn = national_significant_number(numobj)

if num_format == PhoneNumberFormat.E164:

# Early exit for E164 case (even if the country calling code is

# invalid) since no formatting of the national number needs to be

# applied. Extensions are not formatted.

return _prefix_number_with_country_calling_code(country_calling_code, num_format, nsn)

if not _has_valid_country_calling_code(country_calling_code):

return nsn

# Note region_code_for_country_code() is used because formatting

# information for regions which share a country calling code is contained

# by only one region for performance reasons. For example, for NANPA

# regions it will be contained in the metadata for US.

region_code = region_code_for_country_code(country_calling_code)

# Metadata cannot be None because the country calling code is valid (which

# means that the region code cannot be ZZ and must be one of our supported

# region codes).

metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_calling_code, region_code.upper())

formatted_number = _format_nsn(nsn, metadata, num_format)

formatted_number = _maybe_append_formatted_extension(numobj,

metadata,

num_format,

formatted_number)

return _prefix_number_with_country_calling_code(country_calling_code,

num_format,

formatted_number)

def 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

num_format -- The format the phone number should be formatted into

user_defined_formats -- formatting rules specified by clients

Returns the formatted phone number.

"""

country_code = numobj.country_code

nsn = national_significant_number(numobj)

if not _has_valid_country_calling_code(country_code):

return nsn

# Note region_code_for_country_code() is used because formatting

# information for regions which share a country calling code is contained

# by only one region for performance reasons. For example, for NANPA

# regions it will be contained in the metadata for US.

region_code = region_code_for_country_code(country_code)

# Metadata cannot be None because the country calling code is valid

metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)

formatted_number = ""

formatting_pattern = choose_formatting_pattern_for_number(user_defined_formats, nsn)

if formatting_pattern is None:

# If no pattern above is matched, we format the number as a whole.

formatted_number = nsn

else:

num_format_copy = NumberFormat()

num_format_copy._mutable = True

# Before we do a replacement of the national prefix pattern $NP with

# the national prefix, we need to copy the rule so that subsequent

# replacements for different numbers have the appropriate national

# prefix.

num_format_copy.merge_from(formatting_pattern)

np_formatting_rule = formatting_pattern.national_prefix_formatting_rule

if (np_formatting_rule is not None and len(np_formatting_rule) > 0):

national_prefix = metadata.national_prefix

if (national_prefix is not None and len(national_prefix) > 0):

# Replace $NP with national prefix and $FG with the first

# group (\1) matcher.

np_formatting_rule = re.sub(_NP_PATTERN,

national_prefix,

np_formatting_rule,

count=1)

np_formatting_rule = re.sub(_FG_PATTERN,

u"\\\\1",

np_formatting_rule,

count=1)

num_format_copy.national_prefix_formatting_rule = np_formatting_rule

else:

# We don't want to have a rule for how to format the national

# prefix if there isn't one.

num_format_copy.national_prefix_formatting_rule = None

formatted_number = format_nsn_using_pattern(nsn, num_format_copy, number_format)

formatted_number = _maybe_append_formatted_extension(numobj,

metadata,

number_format,

formatted_number)

formatted_number = _prefix_number_with_country_calling_code(country_code,

number_format,

formatted_number)

return formatted_number

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

"""

country_code = numobj.country_code

nsn = national_significant_number(numobj)

if not _has_valid_country_calling_code(country_code):

return nsn

# Note region_code_for_country_code() is used because formatting

# information for regions which share a country calling code is contained

# by only one region for performance reasons. For example, for NANPA

# regions it will be contained in the metadata for US.

region_code = region_code_for_country_code(country_code)

# Metadata cannot be None because the country calling code is valid

metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)

formatted_number = _format_nsn(nsn,

metadata,

PhoneNumberFormat.NATIONAL,

carrier_code)

formatted_number = _maybe_append_formatted_extension(numobj,

metadata,

PhoneNumberFormat.NATIONAL,

formatted_number)

formatted_number = _prefix_number_with_country_calling_code(country_code,

PhoneNumberFormat.NATIONAL,

formatted_number)

return formatted_number

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

"""

if numobj.preferred_domestic_carrier_code is not None:

carrier_code = numobj.preferred_domestic_carrier_code

else:

carrier_code = fallback_carrier_code

return format_national_number_with_carrier_code(numobj, carrier_code)

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

"""

country_calling_code = numobj.country_code

if not _has_valid_country_calling_code(country_calling_code):

if numobj.raw_input is None:

return ""

else:

return numobj.raw_input

# Clear the extension, as that part cannot normally be dialed together with the main number.

numobj_no_ext = PhoneNumber()

numobj_no_ext.merge_from(numobj)

numobj_no_ext.extension = None

numobj_type = number_type(numobj_no_ext)

region_code = region_code_for_country_code(country_calling_code)

if region_code == "CO" and region_calling_from == "CO":

if numobj_type == PhoneNumberType.FIXED_LINE:

formatted_number = format_national_number_with_carrier_code(numobj_no_ext,

_COLOMBIA_MOBILE_TO_FIXED_LINE_PREFIX)

else:

# E164 doesn't work at all when dialling within Colombia

formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL)

elif region_code == "PE" and region_calling_from == "PE":

# In Peru, numbers cannot be dialled using E164 format from a mobile

# phone for Movistar. Instead they must be dialled in national

# format.

formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL)

elif (region_code == "BR" and region_calling_from == "BR" and

((numobj_type == PhoneNumberType.FIXED_LINE) or

(numobj_type == PhoneNumberType.MOBILE) or

(numobj_type == PhoneNumberType.FIXED_LINE_OR_MOBILE))):

if numobj_no_ext.preferred_domestic_carrier_code is not None:

formatted_number = format_national_number_with_preferred_carrier_code(numobj_no_ext, "")

else:

# Brazilian fixed line and mobile numbers need to be dialed with a

# carrier code when called within Brazil. Without that, most of

# the carriers won't connect the call. Because of that, we return

# an empty string here.

formatted_number = ""

elif _can_be_internationally_dialled(numobj_no_ext):

if with_formatting:

return format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL)

else:

return format_number(numobj_no_ext, PhoneNumberFormat.E164)

else:

if region_calling_from == region_code:

formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL)

else:

formatted_number = ""

if with_formatting:

return formatted_number

else:

return _normalize_helper(formatted_number, _DIALLABLE_CHAR_MAPPINGS,

True) # remove non matches

def 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