Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/phonenumbers/phonenumberutil.py: 24%
1201 statements
« prev ^ index » next coverage.py v7.4.0, created at 2024-01-25 06:26 +0000
1# -*- coding: utf-8 -*-
2"""Python phone number parsing and formatting library
4If you use this library, and want to be notified about important changes,
5please sign up to the libphonenumber mailing list at
6https://groups.google.com/forum/#!aboutgroup/libphonenumber-discuss.
8NOTE: A lot of methods in this module require Region Code strings. These must
9be provided using CLDR two-letter region-code format. These should be in
10upper-case. The list of the codes can be found here:
11http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm
12"""
13# Based on original Java code:
14# java/src/com/google/i18n/phonenumbers/PhoneNumberUtil.java
15# Copyright (C) 2009-2011 The Libphonenumber Authors
16#
17# Licensed under the Apache License, Version 2.0 (the "License");
18# you may not use this file except in compliance with the License.
19# You may obtain a copy of the License at
20#
21# http://www.apache.org/licenses/LICENSE-2.0
22#
23# Unless required by applicable law or agreed to in writing, software
24# distributed under the License is distributed on an "AS IS" BASIS,
25# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
26# See the License for the specific language governing permissions and
27# limitations under the License.
28import sys
29import re
31from .re_util import fullmatch # Extra regexp function; see README
32from .util import UnicodeMixin, u, unicod, prnt, to_long
33from .util import U_EMPTY_STRING, U_SPACE, U_DASH, U_TILDE, U_ZERO, U_SEMICOLON
34from .unicode_util import digit as unicode_digit
36# Data class definitions
37from .phonenumber import PhoneNumber, CountryCodeSource
38from .phonemetadata import NumberFormat, PhoneMetadata, REGION_CODE_FOR_NON_GEO_ENTITY
40# Import auto-generated data structures
41try:
42 from .data import _COUNTRY_CODE_TO_REGION_CODE
43except ImportError: # pragma no cover
44 # Before the generated code exists, the data/ directory is empty.
45 # The generation process imports this module, creating a circular
46 # dependency. The hack below works around this.
47 import os
48 if (os.path.basename(sys.argv[0]) == "buildmetadatafromxml.py" or
49 os.path.basename(sys.argv[0]) == "buildprefixdata.py"):
50 prnt("Failed to import generated data (but OK as during autogeneration)", file=sys.stderr)
51 _COUNTRY_CODE_TO_REGION_CODE = {1: ("US",)}
52 else:
53 raise
55# Set the master map from country code to region code. The
56# extra level of indirection allows the unit test to replace
57# the map with test data.
58COUNTRY_CODE_TO_REGION_CODE = _COUNTRY_CODE_TO_REGION_CODE
60# Naming convention for phone number arguments and variables:
61# - string arguments are named 'number'
62# - PhoneNumber objects are named 'numobj'
64# Flags to use when compiling regular expressions for phone numbers.
65_REGEX_FLAGS = re.UNICODE | re.IGNORECASE
66# The minimum and maximum length of the national significant number.
67_MIN_LENGTH_FOR_NSN = 2
68# The ITU says the maximum length should be 15, but we have found longer
69# numbers in Germany.
70_MAX_LENGTH_FOR_NSN = 17
71# The maximum length of the country calling code.
72_MAX_LENGTH_COUNTRY_CODE = 3
73# We don't allow input strings for parsing to be longer than 250 chars. This
74# prevents malicious input from overflowing the regular-expression engine.
75_MAX_INPUT_STRING_LENGTH = 250
76# Region-code for the unknown region.
77UNKNOWN_REGION = u("ZZ")
78# The set of regions that share country calling code 1.
79_NANPA_COUNTRY_CODE = 1
80# Map of country calling codes that use a mobile token before the area
81# code. One example of when this is relevant is when determining the length of
82# the national destination code, which should be the length of the area code
83# plus the length of the mobile token.
84_MOBILE_TOKEN_MAPPINGS = {54: u('9')}
85# Set of country codes that have geographically assigned mobile numbers (see
86# GEO_MOBILE_COUNTRIES below) which are not based on *area codes*. For example,
87# in China mobile numbers start with a carrier indicator, and beyond that are
88# geographically assigned: this carrier indicator is not considered to be an
89# area code.
90_GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES = frozenset((
91 86,)) # China
92# Set of country calling codes that have geographically assigned mobile
93# numbers. This may not be complete; we add calling codes case by case, as we
94# find geographical mobile numbers or hear from user reports. Note that
95# countries like the US, where we can't distinguish between fixed-line or
96# mobile numbers, are not listed here, since we consider FIXED_LINE_OR_MOBILE
97# to be a possibly geographically-related type anyway (like FIXED_LINE).
98_GEO_MOBILE_COUNTRIES = _GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES | set((
99 52, # Mexico
100 54, # Argentina
101 55, # Brazil
102 62)) # Indonesia: some prefixes only (fixed CMDA wireless)
103# The PLUS_SIGN signifies the international prefix.
104_PLUS_SIGN = u("+")
105_STAR_SIGN = u('*')
106_RFC3966_EXTN_PREFIX = u(";ext=")
107_RFC3966_PREFIX = u("tel:")
108_RFC3966_PHONE_CONTEXT = u(";phone-context=")
109_RFC3966_ISDN_SUBADDRESS = u(";isub=")
111# Simple ASCII digits map used to populate _ALPHA_PHONE_MAPPINGS and
112# _ALL_PLUS_NUMBER_GROUPING_SYMBOLS.
113_ASCII_DIGITS_MAP = {u("0"): u("0"), u("1"): u("1"),
114 u("2"): u("2"), u("3"): u("3"),
115 u("4"): u("4"), u("5"): u("5"),
116 u("6"): u("6"), u("7"): u("7"),
117 u("8"): u("8"), u("9"): u("9")}
119# Only upper-case variants of alpha characters are stored.
120_ALPHA_MAPPINGS = {u("A"): u("2"),
121 u("B"): u("2"),
122 u("C"): u("2"),
123 u("D"): u("3"),
124 u("E"): u("3"),
125 u("F"): u("3"),
126 u("G"): u("4"),
127 u("H"): u("4"),
128 u("I"): u("4"),
129 u("J"): u("5"),
130 u("K"): u("5"),
131 u("L"): u("5"),
132 u("M"): u("6"),
133 u("N"): u("6"),
134 u("O"): u("6"),
135 u("P"): u("7"),
136 u("Q"): u("7"),
137 u("R"): u("7"),
138 u("S"): u("7"),
139 u("T"): u("8"),
140 u("U"): u("8"),
141 u("V"): u("8"),
142 u("W"): u("9"),
143 u("X"): u("9"),
144 u("Y"): u("9"),
145 u("Z"): u("9"), }
146# For performance reasons, amalgamate both into one map.
147_ALPHA_PHONE_MAPPINGS = dict(_ALPHA_MAPPINGS, **_ASCII_DIGITS_MAP)
149# A map that contains characters that are essential when dialling. That means
150# any of the characters in this map must not be removed from a number when
151# dialling, otherwise the call will not reach the intended destination.
152_DIALLABLE_CHAR_MAPPINGS = dict({_PLUS_SIGN: _PLUS_SIGN,
153 u('*'): u('*'),
154 u('#'): u('#')},
155 **_ASCII_DIGITS_MAP)
157# Separate map of all symbols that we wish to retain when formatting alpha
158# numbers. This includes digits, ASCII letters and number grouping symbols
159# such as "-" and " ".
160_ALL_PLUS_NUMBER_GROUPING_SYMBOLS = dict({u("-"): u("-"), # Add grouping symbols.
161 u("\uFF0D"): u("-"),
162 u("\u2010"): u("-"),
163 u("\u2011"): u("-"),
164 u("\u2012"): u("-"),
165 u("\u2013"): u("-"),
166 u("\u2014"): u("-"),
167 u("\u2015"): u("-"),
168 u("\u2212"): u("-"),
169 u("/"): u("/"),
170 u("\uFF0F"): u("/"),
171 u(" "): u(" "),
172 u("\u3000"): u(" "),
173 u("\u2060"): u(" "),
174 u("."): u("."),
175 u("\uFF0E"): u(".")},
176 # Put (lower letter -> upper letter) and
177 # (upper letter -> upper letter) mappings.
178 **dict([(_c.lower(), _c) for _c in _ALPHA_MAPPINGS.keys()] +
179 [(_c, _c) for _c in _ALPHA_MAPPINGS.keys()],
180 **_ASCII_DIGITS_MAP))
182# Pattern that makes it easy to distinguish whether a region has a single international dialing
183# prefix or not. If a region has a single international prefix (e.g. 011 in USA), it will be
184# represented as a string that contains a sequence of ASCII digits, and possibly a tilde, which
185# signals waiting for the tone. If there are multiple available international prefixes in a
186# region, they will be represented as a regex string that always contains one or more characters
187# that are not ASCII digits or a tilde.
188_SINGLE_INTERNATIONAL_PREFIX = re.compile(u("[\\d]+(?:[~\u2053\u223C\uFF5E][\\d]+)?"))
190# Regular expression of acceptable punctuation found in phone numbers. This
191# excludes punctuation found as a leading character only.
193# Regular expression of acceptable punctuation found in phone numbers, used to find numbers in
194# text and to decide what is a viable phone number. This excludes diallable characters.
195# This consists of dash characters, white space characters, full stops, slashes, square brackets,
196# parentheses and tildes. It also includes the letter 'x' as that is found as a placeholder for
197# carrier information in some phone numbers. Full-width variants are also present.
198_VALID_PUNCTUATION = (u("-x\u2010-\u2015\u2212\u30FC\uFF0D-\uFF0F ") +
199 u("\u00A0\u00AD\u200B\u2060\u3000()\uFF08\uFF09\uFF3B\uFF3D.\\[\\]/~\u2053\u223C\uFF5E"))
201_DIGITS = unicod('\\d') # Java "\\p{Nd}", so need "(?u)" or re.UNICODE wherever this is used
202# We accept alpha characters in phone numbers, ASCII only, upper and lower
203# case.
204_VALID_ALPHA = (U_EMPTY_STRING.join(_ALPHA_MAPPINGS.keys()) +
205 U_EMPTY_STRING.join([_k.lower() for _k in _ALPHA_MAPPINGS.keys()]))
206_PLUS_CHARS = u("+\uFF0B")
207_PLUS_CHARS_PATTERN = re.compile(u("[") + _PLUS_CHARS + u("]+"))
208_SEPARATOR_PATTERN = re.compile(u("[") + _VALID_PUNCTUATION + u("]+"))
209_CAPTURING_DIGIT_PATTERN = re.compile(u("(") + _DIGITS + u(")"), re.UNICODE)
211# Regular expression of acceptable characters that may start a phone number
212# for the purposes of parsing. This allows us to strip away meaningless
213# prefixes to phone numbers that may be mistakenly given to us. This consists
214# of digits, the plus symbol and arabic-indic digits. This does not contain
215# alpha characters, although they may be used later in the number. It also
216# does not include other punctuation, as this will be stripped later during
217# parsing and is of no information value when parsing a number.
218_VALID_START_CHAR = u("[") + _PLUS_CHARS + _DIGITS + u("]")
219_VALID_START_CHAR_PATTERN = re.compile(_VALID_START_CHAR, re.UNICODE)
221# Regular expression of characters typically used to start a second phone
222# number for the purposes of parsing. This allows us to strip off parts of the
223# number that are actually the start of another number, such as for: (530)
224# 583-6985 x302/x2303 -> the second extension here makes this actually two
225# phone numbers, (530) 583-6985 x302 and (530) 583-6985 x2303. We remove the
226# second extension so that the first number is parsed correctly.
227_SECOND_NUMBER_START = u("[\\\\/] *x")
228_SECOND_NUMBER_START_PATTERN = re.compile(_SECOND_NUMBER_START)
230# Regular expression of trailing characters that we want to remove. We remove
231# all characters that are not alpha or numerical characters. The hash
232# character is retained here, as it may signify the previous block was an
233# extension.
234#
235# The original Java regexp is:
236# [[\\P{N}&&\\P{L}]&&[^#]]+$
237# which splits out as:
238# [ ]+$ : >=1 of the following chars at end of string
239# [ ]&&[ ] : intersection of these two sets of chars
240# [ && ] : intersection of these two sets of chars
241# \\P{N} : characters without the "Number" Unicode property
242# \\P{L} : characters without the "Letter" Unicode property
243# [^#] : character other than hash
244# which nets down to: >=1 non-Number, non-Letter, non-# characters at string end
245# In Python Unicode regexp mode '(?u)', the class '[^#\w]' will match anything
246# that is not # and is not alphanumeric and is not underscore.
247_UNWANTED_END_CHARS = u(r"(?u)(?:_|[^#\w])+$")
248_UNWANTED_END_CHAR_PATTERN = re.compile(_UNWANTED_END_CHARS)
250# We use this pattern to check if the phone number has at least three letters
251# in it - if so, then we treat it as a number where some phone-number digits
252# are represented by letters.
253_VALID_ALPHA_PHONE_PATTERN = re.compile(u("(?:.*?[A-Za-z]){3}.*"))
255# Regular expression of viable phone numbers. This is location
256# independent. Checks we have at least three leading digits, and only valid
257# punctuation, alpha characters and digits in the phone number. Does not
258# include extension data. The symbol 'x' is allowed here as valid punctuation
259# since it is often used as a placeholder for carrier codes, for example in
260# Brazilian phone numbers. We also allow multiple "+" characters at the start.
261# Corresponds to the following:
262# [digits]{minLengthNsn}|
263# plus_sign*(([punctuation]|[star])*[digits]){3,}([punctuation]|[star]|[digits]|[alpha])*
264#
265# The first reg-ex is to allow short numbers (two digits long) to be parsed if
266# they are entered as "15" etc, but only if there is no punctuation in
267# them. The second expression restricts the number of digits to three or more,
268# but then allows them to be in international form, and to have
269# alpha-characters and punctuation.
270#
271# Note VALID_PUNCTUATION starts with a -, so must be the first in the range.
272_VALID_PHONE_NUMBER = (_DIGITS + (u("{%d}") % _MIN_LENGTH_FOR_NSN) + u("|") +
273 u("[") + _PLUS_CHARS + u("]*(?:[") + _VALID_PUNCTUATION + _STAR_SIGN + u("]*") + _DIGITS + u("){3,}[") +
274 _VALID_PUNCTUATION + _STAR_SIGN + _VALID_ALPHA + _DIGITS + u("]*"))
276# Default extension prefix to use when formatting. This will be put in front
277# of any extension component of the number, after the main national number is
278# formatted. For example, if you wish the default extension formatting to be
279# " extn: 3456", then you should specify " extn: " here as the default
280# extension prefix. This can be overridden by region-specific preferences.
281_DEFAULT_EXTN_PREFIX = u(" ext. ")
284# Helper method for constructing regular expressions for parsing. Creates an expression that
285# captures up to max_length digits.
286def _extn_digits(max_length):
287 return u("(") + _DIGITS + (u("{1,%d})") % max_length)
290# Helper initialiser method to create the regular-expression pattern to match extensions.
291# Note that there are currently six capturing groups for the extension itself. If this number is
292# changed, _maybe_strip_extension needs to be updated.
293def _create_extn_pattern(for_parsing):
294 # We cap the maximum length of an extension based on the ambiguity of the way the extension is
295 # prefixed. As per ITU, the officially allowed length for extensions is actually 40, but we
296 # don't support this since we haven't seen real examples and this introduces many false
297 # interpretations as the extension labels are not standardized.
298 ext_limit_after_explicit_label = 20
299 ext_limit_after_likely_label = 15
300 ext_limit_after_ambiguous_char = 9
301 ext_limit_when_not_sure = 6
303 possible_separators_between_number_and_ext_label = u("[ \u00A0\\t,]*")
304 # Optional full stop (.) or colon, followed by zero or more spaces/tabs/commas.
305 possible_chars_after_ext_label = u("[:\\.\uFF0E]?[ \u00A0\\t,-]*")
306 optional_extn_suffix = u("#?")
308 # Here the extension is called out in more explicit way, i.e mentioning it obvious patterns
309 # like "ext.". Canonical-equivalence doesn't seem to be an option with Android java, so we
310 # allow two options for representing the accented o - the character itself, and one in the
311 # unicode decomposed form with the combining acute accent.
312 explicit_ext_labels = u("(?:e?xt(?:ensi(?:o\u0301?|\u00F3))?n?|\uFF45?\uFF58\uFF54\uFF4E?|\u0434\u043E\u0431|anexo)")
313 # One-character symbols that can be used to indicate an extension, and less commonly used
314 # or more ambiguous extension labels.
315 ambiguous_ext_labels = u("(?:[x\uFF58#\uFF03~\uFF5E]|int|\uFF49\uFF4E\uFF54)")
316 # When extension is not separated clearly.
317 ambiguous_separator = u("[- ]+")
319 rfc_extn = _RFC3966_EXTN_PREFIX + _extn_digits(ext_limit_after_explicit_label)
320 explicit_extn = (possible_separators_between_number_and_ext_label + explicit_ext_labels +
321 possible_chars_after_ext_label + _extn_digits(ext_limit_after_explicit_label) +
322 optional_extn_suffix)
323 ambiguous_extn = (possible_separators_between_number_and_ext_label + ambiguous_ext_labels +
324 possible_chars_after_ext_label + _extn_digits(ext_limit_after_ambiguous_char) + optional_extn_suffix)
325 american_style_extn_with_suffix = (ambiguous_separator + _extn_digits(ext_limit_when_not_sure) + u("#"))
327 # The first regular expression covers RFC 3966 format, where the extension is added using
328 # ";ext=". The second more generic where extension is mentioned with explicit labels like
329 # "ext:". In both the above cases we allow more numbers in extension than any other extension
330 # labels. The third one captures when single character extension labels or less commonly used
331 # labels are used. In such cases we capture fewer extension digits in order to reduce the
332 # chance of falsely interpreting two numbers beside each other as a number + extension. The
333 # fourth one covers the special case of American numbers where the extension is written with a
334 # hash at the end, such as "- 503#".
335 extension_pattern = (rfc_extn + u("|") +
336 explicit_extn + u("|") +
337 ambiguous_extn + u("|") +
338 american_style_extn_with_suffix)
339 # Additional pattern that is supported when parsing extensions, not when matching.
340 if for_parsing:
341 # This is same as possible_separators_between_number_and_ext_label, but not matching comma as
342 # extension label may have it.
343 possible_separators_number_ext_label_no_comma = u("[ \u00A0\\t]*")
344 # ",," is commonly used for auto dialling the extension when connected. First comma is matched
345 # through possible_separators_between_number_and_ext_label, so we do not repeat it here. Semi-colon
346 # works in Iphone and Android also to pop up a button with the extension number following.
347 auto_dialling_and_ext_labels_found = u("(?:,{2}|;)")
349 auto_dialling_extn = (possible_separators_number_ext_label_no_comma +
350 auto_dialling_and_ext_labels_found + possible_chars_after_ext_label +
351 _extn_digits(ext_limit_after_likely_label) + optional_extn_suffix)
352 only_commas_extn = (possible_separators_number_ext_label_no_comma +
353 u("(?:,)+") + possible_chars_after_ext_label + _extn_digits(ext_limit_after_ambiguous_char) +
354 optional_extn_suffix)
355 # Here the first pattern is exclusively for extension autodialling formats which are used
356 # when dialling and in this case we accept longer extensions. However, the second pattern
357 # is more liberal on the number of commas that acts as extension labels, so we have a strict
358 # cap on the number of digits in such extensions.
359 return (extension_pattern + u("|") +
360 auto_dialling_extn + u("|") +
361 only_commas_extn)
362 return extension_pattern
365# Regexp of all possible ways to write extensions, for use when parsing. This
366# will be run as a case-insensitive regexp match. Wide character versions are
367# also provided after each ASCII version.
368_EXTN_PATTERNS_FOR_PARSING = _create_extn_pattern(True)
369_EXTN_PATTERNS_FOR_MATCHING = _create_extn_pattern(False)
371# Regular expression of valid global-number-digits for the phone-context
372# parameter, following the syntax defined in RFC3966.
373_RFC3966_VISUAL_SEPARATOR = "[\\-\\.\\(\\)]?"
374_RFC3966_PHONE_DIGIT = "(" + _DIGITS + "|" + _RFC3966_VISUAL_SEPARATOR + ")"
375_RFC3966_GLOBAL_NUMBER_DIGITS = "^\\" + _PLUS_SIGN + _RFC3966_PHONE_DIGIT + "*" + _DIGITS + _RFC3966_PHONE_DIGIT + "*$"
376_RFC3966_GLOBAL_NUMBER_DIGITS_PATTERN = re.compile(_RFC3966_GLOBAL_NUMBER_DIGITS)
378# Regular expression of valid domainname for the phone-context parameter,
379# following the syntax defined in RFC3966.
380_ALPHANUM = _VALID_ALPHA + _DIGITS
381_RFC3966_DOMAINLABEL = "[" + _ALPHANUM + "]+((\\-)*[" + _ALPHANUM + "])*"
382_RFC3966_TOPLABEL = "[" + _VALID_ALPHA + "]+((\\-)*[" + _ALPHANUM + "])*"
383_RFC3966_DOMAINNAME = "^(" + _RFC3966_DOMAINLABEL + "\\.)*" + _RFC3966_TOPLABEL + "\\.?$"
384_RFC3966_DOMAINNAME_PATTERN = re.compile(_RFC3966_DOMAINNAME)
386# Regexp of all known extension prefixes used by different regions followed by
387# 1 or more valid digits, for use when parsing.
388_EXTN_PATTERN = re.compile(u("(?:") + _EXTN_PATTERNS_FOR_PARSING + u(")$"), _REGEX_FLAGS)
390# We append optionally the extension pattern to the end here, as a valid phone
391# number may have an extension prefix appended, followed by 1 or more digits.
392_VALID_PHONE_NUMBER_PATTERN = re.compile(_VALID_PHONE_NUMBER + u("(?:") + _EXTN_PATTERNS_FOR_PARSING + u(")?"), _REGEX_FLAGS)
394# We use a non-capturing group because Python's re.split() returns any capturing
395# groups interspersed with the other results (unlike Java's Pattern.split()).
396NON_DIGITS_PATTERN = re.compile(u("(?:\\D+)"))
398# The FIRST_GROUP_PATTERN was originally set to \1 but there are some
399# countries for which the first group is not used in the national pattern
400# (e.g. Argentina) so the \1 group does not match correctly. Therefore, we
401# use \d, so that the first group actually used in the pattern will be
402# matched.
403_FIRST_GROUP_PATTERN = re.compile(u(r"(\\\d)"))
404# Constants used in the formatting rules to represent the national prefix, first group and
405# carrier code respectively.
406_NP_STRING = "$NP"
407_FG_STRING = "$FG"
408_CC_STRING = "$CC"
410# A pattern that is used to determine if the national prefix formatting rule
411# has the first group only, i.e., does not start with the national
412# prefix. Note that the pattern explicitly allows for unbalanced parentheses.
413_FIRST_GROUP_ONLY_PREFIX_PATTERN = re.compile("\\(?\\\\1\\)?")
416class PhoneNumberFormat(object):
417 """
418 Phone number format.
420 INTERNATIONAL and NATIONAL formats are consistent with the definition in
421 ITU-T Recommendation E123. However we follow local conventions such as using
422 '-' instead of whitespace as separators. For example, the number of the
423 Google Switzerland office will be written as "+41 44 668 1800" in
424 INTERNATIONAL format, and as "044 668 1800" in NATIONAL format. E164 format
425 is as per INTERNATIONAL format but with no formatting applied,
426 e.g. "+41446681800". RFC3966 is as per INTERNATIONAL format, but with all
427 spaces and other separating symbols replaced with a hyphen, and with any
428 phone number extension appended with ";ext=". It also will have a prefix of
429 "tel:" added, e.g. "tel:+41-44-668-1800".
431 Note: If you are considering storing the number in a neutral format, you
432 are highly advised to use the PhoneNumber class.
433 """
434 E164 = 0
435 INTERNATIONAL = 1
436 NATIONAL = 2
437 RFC3966 = 3
439 @classmethod
440 def to_string(cls, val):
441 """Return a string representation of a PhoneNumberFormat value"""
442 if val == PhoneNumberFormat.E164:
443 return u("E164")
444 elif val == PhoneNumberFormat.INTERNATIONAL:
445 return u("INTERNATIONAL")
446 elif val == PhoneNumberFormat.NATIONAL:
447 return u("NATIONAL")
448 elif val == PhoneNumberFormat.RFC3966:
449 return u("RFC3966")
450 else:
451 return u("INVALID (%d)" % val)
454class PhoneNumberType(object):
455 """Type of phone numbers."""
456 FIXED_LINE = 0
457 MOBILE = 1
458 # In some regions (e.g. the USA), it is impossible to distinguish between
459 # fixed-line and mobile numbers by looking at the phone number itself.
460 FIXED_LINE_OR_MOBILE = 2
461 # Freephone lines
462 TOLL_FREE = 3
463 PREMIUM_RATE = 4
464 # The cost of this call is shared between the caller and the recipient,
465 # and is hence typically less than PREMIUM_RATE calls. See
466 # http://en.wikipedia.org/wiki/Shared_Cost_Service for more information.
467 SHARED_COST = 5
468 # Voice over IP numbers. This includes TSoIP (Telephony Service over IP).
469 VOIP = 6
470 # A personal number is associated with a particular person, and may be
471 # routed to either a MOBILE or FIXED_LINE number. Some more information
472 # can be found here: http://en.wikipedia.org/wiki/Personal_Numbers
473 PERSONAL_NUMBER = 7
474 PAGER = 8
475 # Used for "Universal Access Numbers" or "Company Numbers". They may be
476 # further routed to specific offices, but allow one number to be used for
477 # a company.
478 UAN = 9
479 # Used for "Voice Mail Access Numbers".
480 VOICEMAIL = 10
481 # A phone number is of type UNKNOWN when it does not fit any of the known
482 # patterns for a specific region.
483 UNKNOWN = 99
485 @classmethod
486 def values(cls):
487 return (PhoneNumberType.FIXED_LINE,
488 PhoneNumberType.MOBILE,
489 PhoneNumberType.FIXED_LINE_OR_MOBILE,
490 PhoneNumberType.TOLL_FREE,
491 PhoneNumberType.PREMIUM_RATE,
492 PhoneNumberType.SHARED_COST,
493 PhoneNumberType.VOIP,
494 PhoneNumberType.PERSONAL_NUMBER,
495 PhoneNumberType.PAGER,
496 PhoneNumberType.UAN,
497 PhoneNumberType.VOICEMAIL,
498 PhoneNumberType.UNKNOWN)
500 @classmethod
501 def to_string(cls, val):
502 """Return a string representation of a PhoneNumberType value"""
503 if val == PhoneNumberType.FIXED_LINE:
504 return u("FIXED_LINE")
505 elif val == PhoneNumberType.MOBILE:
506 return u("MOBILE")
507 elif val == PhoneNumberType.FIXED_LINE_OR_MOBILE:
508 return u("FIXED_LINE_OR_MOBILE")
509 elif val == PhoneNumberType.TOLL_FREE:
510 return u("TOLL_FREE")
511 elif val == PhoneNumberType.PREMIUM_RATE:
512 return u("PREMIUM_RATE")
513 elif val == PhoneNumberType.SHARED_COST:
514 return u("SHARED_COST")
515 elif val == PhoneNumberType.VOIP:
516 return u("VOIP")
517 elif val == PhoneNumberType.PERSONAL_NUMBER:
518 return u("PERSONAL_NUMBER")
519 elif val == PhoneNumberType.PAGER:
520 return u("PAGER")
521 elif val == PhoneNumberType.UAN:
522 return u("UAN")
523 elif val == PhoneNumberType.VOICEMAIL:
524 return u("VOICEMAIL")
525 elif val == PhoneNumberType.UNKNOWN:
526 return u("UNKNOWN")
527 else:
528 return u("INVALID (%d)" % val)
531class MatchType(object):
532 """Types of phone number matches."""
533 # Not a telephone number
534 NOT_A_NUMBER = 0
535 # None of the match types below apply
536 NO_MATCH = 1
537 # Returns SHORT_NSN_MATCH if either or both has no region specified, or
538 # the region specified is the same, and one NSN could be a shorter version
539 # of the other number. This includes the case where one has an extension
540 # specified, and the other does not.
541 SHORT_NSN_MATCH = 2
542 # Either or both has no region specified, and the NSNs and extensions are
543 # the same.
544 NSN_MATCH = 3
545 # The country_code, NSN, presence of a leading zero for Italian numbers
546 # and any extension present are the same.
547 EXACT_MATCH = 4
549 @classmethod
550 def to_string(cls, val):
551 """Return a string representation of a MatchType value"""
552 if val == MatchType.NOT_A_NUMBER:
553 return u("NOT_A_NUMBER")
554 elif val == MatchType.NO_MATCH:
555 return u("NO_MATCH")
556 elif val == MatchType.SHORT_NSN_MATCH:
557 return u("SHORT_NSN_MATCH")
558 elif val == MatchType.NSN_MATCH:
559 return u("NSN_MATCH")
560 elif val == MatchType.EXACT_MATCH:
561 return u("EXACT_MATCH")
562 else:
563 return u("INVALID (%d)" % val)
566class ValidationResult(object):
567 """Possible outcomes when testing if a PhoneNumber is a possible number."""
568 # The number length matches that of valid numbers for this region.
569 IS_POSSIBLE = 0
570 # The number length matches that of local numbers for this region only
571 # (i.e. numbers that may be able to be dialled within an area, but do not
572 # have all the information to be dialled from anywhere inside or outside
573 # the country).
574 IS_POSSIBLE_LOCAL_ONLY = 4
575 # The number has an invalid country calling code.
576 INVALID_COUNTRY_CODE = 1
577 # The number is shorter than all valid numbers for this region.
578 TOO_SHORT = 2
579 # The number is longer than the shortest valid numbers for this region,
580 # shorter than the longest valid numbers for this region, and does not
581 # itself have a number length that matches valid numbers for this region.
582 # This can also be returned in the case where
583 # is_possible_number_for_type_with_reason was called, and there are no
584 # numbers of this type at all for this region.
585 INVALID_LENGTH = 5
586 # The number is longer than all valid numbers for this region.
587 TOO_LONG = 3
589 @classmethod
590 def to_string(cls, val):
591 """Return a string representation of a ValidationResult value"""
592 if val == ValidationResult.IS_POSSIBLE:
593 return u("IS_POSSIBLE")
594 elif val == ValidationResult.IS_POSSIBLE_LOCAL_ONLY:
595 return u("IS_POSSIBLE_LOCAL_ONLY")
596 elif val == ValidationResult.INVALID_COUNTRY_CODE:
597 return u("INVALID_COUNTRY_CODE")
598 elif val == ValidationResult.TOO_SHORT:
599 return u("TOO_SHORT")
600 elif val == ValidationResult.INVALID_LENGTH:
601 return u("INVALID_LENGTH")
602 elif val == ValidationResult.TOO_LONG:
603 return u("TOO_LONG")
604 else:
605 return u("INVALID (%d)" % val)
608# Derived data structures
609SUPPORTED_REGIONS = set()
610COUNTRY_CODES_FOR_NON_GEO_REGIONS = set()
611_NANPA_REGIONS = set()
614def _regenerate_derived_data():
615 global SUPPORTED_REGIONS, COUNTRY_CODES_FOR_NON_GEO_REGIONS, _NANPA_REGIONS
616 SUPPORTED_REGIONS.clear()
617 COUNTRY_CODES_FOR_NON_GEO_REGIONS.clear()
618 for cc, region_codes in COUNTRY_CODE_TO_REGION_CODE.items():
619 if (len(region_codes) == 1 and region_codes[0] == REGION_CODE_FOR_NON_GEO_ENTITY):
620 COUNTRY_CODES_FOR_NON_GEO_REGIONS.add(cc)
621 else:
622 SUPPORTED_REGIONS.update(region_codes)
623 if REGION_CODE_FOR_NON_GEO_ENTITY in SUPPORTED_REGIONS: # pragma no cover
624 SUPPORTED_REGIONS.remove(REGION_CODE_FOR_NON_GEO_ENTITY)
625 _NANPA_REGIONS.clear()
626 _NANPA_REGIONS.update(COUNTRY_CODE_TO_REGION_CODE[_NANPA_COUNTRY_CODE])
629_regenerate_derived_data()
632def _copy_number_format(other):
633 """Return a mutable copy of the given NumberFormat object"""
634 copy = NumberFormat(pattern=other.pattern,
635 format=other.format,
636 leading_digits_pattern=list(other.leading_digits_pattern),
637 national_prefix_formatting_rule=other.national_prefix_formatting_rule,
638 national_prefix_optional_when_formatting=other.national_prefix_optional_when_formatting,
639 domestic_carrier_code_formatting_rule=other.domestic_carrier_code_formatting_rule)
640 copy._mutable = True
641 return copy
644def _extract_possible_number(number):
645 """Attempt to extract a possible number from the string passed in.
647 This currently strips all leading characters that cannot be used to
648 start a phone number. Characters that can be used to start a phone number
649 are defined in the VALID_START_CHAR_PATTERN. If none of these characters
650 are found in the number passed in, an empty string is returned. This
651 function also attempts to strip off any alternative extensions or endings
652 if two or more are present, such as in the case of: (530) 583-6985
653 x302/x2303. The second extension here makes this actually two phone
654 numbers, (530) 583-6985 x302 and (530) 583-6985 x2303. We remove the
655 second extension so that the first number is parsed correctly.
657 Arguments:
658 number -- The string that might contain a phone number.
660 Returns the number, stripped of any non-phone-number prefix (such
661 as "Tel:") or an empty string if no character used to start phone
662 numbers (such as + or any digit) is found in the number
663 """
664 match = _VALID_START_CHAR_PATTERN.search(number)
665 if match:
666 number = number[match.start():]
667 # Remove trailing non-alpha non-numerical characters.
668 trailing_chars_match = _UNWANTED_END_CHAR_PATTERN.search(number)
669 if trailing_chars_match:
670 number = number[:trailing_chars_match.start()]
671 # Check for extra numbers at the end.
672 second_number_match = _SECOND_NUMBER_START_PATTERN.search(number)
673 if second_number_match:
674 number = number[:second_number_match.start()]
675 return number
676 else:
677 return U_EMPTY_STRING
680def _is_viable_phone_number(number):
681 """Checks to see if a string could possibly be a phone number.
683 At the moment, checks to see that the string begins with at least 2
684 digits, ignoring any punctuation commonly found in phone numbers. This
685 method does not require the number to be normalized in advance - but does
686 assume that leading non-number symbols have been removed, such as by the
687 method _extract_possible_number.
689 Arguments:
690 number -- string to be checked for viability as a phone number
692 Returns True if the number could be a phone number of some sort, otherwise
693 False
694 """
695 if len(number) < _MIN_LENGTH_FOR_NSN:
696 return False
697 match = fullmatch(_VALID_PHONE_NUMBER_PATTERN, number)
698 return bool(match)
701def _normalize(number):
702 """Normalizes a string of characters representing a phone number.
704 This performs the following conversions:
705 - Punctuation is stripped.
706 - For ALPHA/VANITY numbers:
707 - Letters are converted to their numeric representation on a telephone
708 keypad. The keypad used here is the one defined in ITU
709 Recommendation E.161. This is only done if there are 3 or more
710 letters in the number, to lessen the risk that such letters are
711 typos.
712 - For other numbers:
713 - Wide-ascii digits are converted to normal ASCII (European) digits.
714 - Arabic-Indic numerals are converted to European numerals.
715 - Spurious alpha characters are stripped.
717 Arguments:
718 number -- string representing a phone number
720 Returns the normalized string version of the phone number.
721 """
722 m = fullmatch(_VALID_ALPHA_PHONE_PATTERN, number)
723 if m:
724 return _normalize_helper(number, _ALPHA_PHONE_MAPPINGS, True)
725 else:
726 return normalize_digits_only(number)
729def normalize_digits_only(number, keep_non_digits=False):
730 """Normalizes a string of characters representing a phone number.
732 This converts wide-ascii and arabic-indic numerals to European numerals,
733 and strips punctuation and alpha characters (optional).
735 Arguments:
736 number -- a string representing a phone number
737 keep_non_digits -- whether to keep non-digits
739 Returns the normalized string version of the phone number.
740 """
741 number = unicod(number)
742 number_length = len(number)
743 normalized_digits = U_EMPTY_STRING
744 for ii in range(number_length):
745 d = unicode_digit(number[ii], -1)
746 if d != -1:
747 normalized_digits += unicod(d)
748 elif keep_non_digits:
749 normalized_digits += number[ii]
750 return normalized_digits
753def normalize_diallable_chars_only(number):
754 """Normalizes a string of characters representing a phone number.
756 This strips all characters which are not diallable on a mobile phone
757 keypad (including all non-ASCII digits).
759 Arguments:
760 number -- a string of characters representing a phone number
762 Returns the normalized string version of the phone number.
763 """
764 return _normalize_helper(number, _DIALLABLE_CHAR_MAPPINGS, True)
767def convert_alpha_characters_in_number(number):
768 """Convert alpha chars in a number to their respective digits on a keypad,
769 but retains existing formatting."""
770 return _normalize_helper(number, _ALPHA_PHONE_MAPPINGS, False)
773def length_of_geographical_area_code(numobj):
774 """Return length of the geographical area code for a number.
776 Gets the length of the geographical area code from the PhoneNumber object
777 passed in, so that clients could use it to split a national significant
778 number into geographical area code and subscriber number. It works in such
779 a way that the resultant subscriber number should be diallable, at least
780 on some devices. An example of how this could be used:
782 >>> import phonenumbers
783 >>> numobj = phonenumbers.parse("16502530000", "US")
784 >>> nsn = phonenumbers.national_significant_number(numobj)
785 >>> ac_len = phonenumbers.length_of_geographical_area_code(numobj)
786 >>> if ac_len > 0:
787 ... area_code = nsn[:ac_len]
788 ... subscriber_number = nsn[ac_len:]
789 ... else:
790 ... area_code = ""
791 ... subscriber_number = nsn
793 N.B.: area code is a very ambiguous concept, so the I18N team generally
794 recommends against using it for most purposes, but recommends using the
795 more general national_number instead. Read the following carefully before
796 deciding to use this method:
798 - geographical area codes change over time, and this method honors those
799 changes; therefore, it doesn't guarantee the stability of the result it
800 produces.
801 - subscriber numbers may not be diallable from all devices (notably
802 mobile devices, which typically require the full national_number to be
803 dialled in most countries).
804 - most non-geographical numbers have no area codes, including numbers
805 from non-geographical entities.
806 - some geographical numbers have no area codes.
808 Arguments:
809 numobj -- The PhoneNumber object to find the length of the area code form.
811 Returns the length of area code of the PhoneNumber object passed in.
812 """
813 metadata = PhoneMetadata.metadata_for_region(region_code_for_number(numobj), None)
814 if metadata is None:
815 return 0
817 # If a country doesn't use a national prefix, and this number doesn't have
818 # an Italian leading zero, we assume it is a closed dialling plan with no
819 # area codes.
820 if metadata.national_prefix is None and not numobj.italian_leading_zero:
821 return 0
823 ntype = number_type(numobj)
824 country_code = numobj.country_code
825 if (ntype == PhoneNumberType.MOBILE and
826 (country_code in _GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES)):
827 # Note this is a rough heuristic; it doesn't cover Indonesia well, for
828 # example, where area codes are present for some mobile phones but not
829 # for others. We have no better way of representing this in the
830 # metadata at this point.
831 return 0
833 if not is_number_type_geographical(ntype, country_code):
834 return 0
836 return length_of_national_destination_code(numobj)
839def length_of_national_destination_code(numobj):
840 """Return length of the national destination code code for a number.
842 Gets the length of the national destination code (NDC) from the
843 PhoneNumber object passed in, so that clients could use it to split a
844 national significant number into NDC and subscriber number. The NDC of a
845 phone number is normally the first group of digit(s) right after the
846 country calling code when the number is formatted in the international
847 format, if there is a subscriber number part that follows.
849 N.B.: similar to an area code, not all numbers have an NDC!
851 An example of how this could be used:
853 >>> import phonenumbers
854 >>> numobj = phonenumbers.parse("18002530000", "US")
855 >>> nsn = phonenumbers.national_significant_number(numobj)
856 >>> ndc_len = phonenumbers.length_of_national_destination_code(numobj)
857 >>> if ndc_len > 0:
858 ... national_destination_code = nsn[:ndc_len]
859 ... subscriber_number = nsn[ndc_len:]
860 ... else:
861 ... national_destination_code = ""
862 ... subscriber_number = nsn
864 Refer to the unittests to see the difference between this function and
865 length_of_geographical_area_code.
867 Arguments:
868 numobj -- The PhoneNumber object to find the length of the NDC from.
870 Returns the length of NDC of the PhoneNumber object passed in, which
871 could be zero.
872 """
873 if numobj.extension is not None:
874 # We don't want to alter the object given to us, but we don't want to
875 # include the extension when we format it, so we copy it and clear the
876 # extension here.
877 copied_numobj = PhoneNumber()
878 copied_numobj.merge_from(numobj)
879 copied_numobj.extension = None
880 else:
881 copied_numobj = numobj
883 nsn = format_number(copied_numobj, PhoneNumberFormat.INTERNATIONAL)
884 number_groups = re.split(NON_DIGITS_PATTERN, nsn)
886 # The pattern will start with "+COUNTRY_CODE " so the first group will
887 # always be the empty string (before the + symbol) and the second group
888 # will be the country calling code. The third group will be area code if
889 # it is not the last group.
890 if len(number_groups) <= 3:
891 return 0
893 if number_type(numobj) == PhoneNumberType.MOBILE:
894 # For example Argentinian mobile numbers, when formatted in the
895 # international format, are in the form of +54 9 NDC XXXX... As a
896 # result, we take the length of the third group (NDC) and add the
897 # length of the second group (which is the mobile token), which also
898 # forms part of the national significant number. This assumes that
899 # the mobile token is always formatted separately from the rest of the
900 # phone number.
901 mobile_token = country_mobile_token(numobj.country_code)
902 if mobile_token != U_EMPTY_STRING:
903 return len(number_groups[2]) + len(number_groups[3])
904 return len(number_groups[2])
907def country_mobile_token(country_code):
908 """Returns the mobile token for the provided country calling code if it has one, otherwise
909 returns an empty string. A mobile token is a number inserted before the area code when dialing
910 a mobile number from that country from abroad.
912 Arguments:
913 country_code -- the country calling code for which we want the mobile token
914 Returns the mobile token, as a string, for the given country calling code.
915 """
916 return _MOBILE_TOKEN_MAPPINGS.get(country_code, U_EMPTY_STRING)
919def _normalize_helper(number, replacements, remove_non_matches):
920 """Normalizes a string of characters representing a phone number by
921 replacing all characters found in the accompanying map with the values
922 therein, and stripping all other characters if remove_non_matches is true.
924 Arguments:
925 number -- a string representing a phone number
926 replacements -- a mapping of characters to what they should be replaced
927 by in the normalized version of the phone number
928 remove_non_matches -- indicates whether characters that are not able to be
929 replaced should be stripped from the number. If this is False,
930 they will be left unchanged in the number.
932 Returns the normalized string version of the phone number.
933 """
934 normalized_number = []
935 for char in number:
936 new_digit = replacements.get(char.upper(), None)
937 if new_digit is not None:
938 normalized_number.append(new_digit)
939 elif not remove_non_matches:
940 normalized_number.append(char)
941 # If neither of the above are true, we remove this character
942 return U_EMPTY_STRING.join(normalized_number)
945def supported_calling_codes():
946 """Returns all country calling codes the library has metadata for, covering
947 both non-geographical entities (global network calling codes) and those
948 used for geographical entities. This could be used to populate a drop-down
949 box of country calling codes for a phone-number widget, for instance.
951 Returns an unordered set of the country calling codes for every geographica
952 and non-geographical entity the library supports.
953 """
954 return set(COUNTRY_CODE_TO_REGION_CODE.keys())
957def _desc_has_possible_number_data(desc):
959 """Returns true if there is any possible number data set for a particular PhoneNumberDesc."""
960 # If this is empty, it means numbers of this type inherit from the "general desc" -> the value
961 # "-1" means that no numbers exist for this type.
962 if desc is None:
963 return False
964 return len(desc.possible_length) != 1 or desc.possible_length[0] != -1
967# Note: desc_has_data must account for any of MetadataFilter's excludableChildFields potentially
968# being absent from the metadata. It must check them all. For any changes in descHasData, ensure
969# that all the excludableChildFields are still being checked. If your change is safe simply
970# mention why during a review without needing to change MetadataFilter.
971def _desc_has_data(desc):
972 """Returns true if there is any data set for a particular PhoneNumberDesc."""
973 if desc is None:
974 return False
975 # Checking most properties since we don't know what's present, since a custom build may have
976 # stripped just one of them (e.g. liteBuild strips exampleNumber). We don't bother checking the
977 # possibleLengthsLocalOnly, since if this is the only thing that's present we don't really
978 # support the type at all: no type-specific methods will work with only this data.
979 return ((desc.example_number is not None) or
980 _desc_has_possible_number_data(desc) or
981 (desc.national_number_pattern is not None))
984def _supported_types_for_metadata(metadata):
985 """Returns the types we have metadata for based on the PhoneMetadata object passed in, which must be non-None."""
986 numtypes = set()
987 for numtype in PhoneNumberType.values():
988 if numtype in (PhoneNumberType.FIXED_LINE_OR_MOBILE, PhoneNumberType.UNKNOWN):
989 # Never return FIXED_LINE_OR_MOBILE (it is a convenience type, and represents that a
990 # particular number type can't be determined) or UNKNOWN (the non-type).
991 continue
992 if _desc_has_data(_number_desc_by_type(metadata, numtype)):
993 numtypes.add(numtype)
994 return numtypes
997def supported_types_for_region(region_code):
998 """Returns the types for a given region which the library has metadata for.
1000 Will not include FIXED_LINE_OR_MOBILE (if numbers in this region could
1001 be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would
1002 be present) and UNKNOWN.
1004 No types will be returned for invalid or unknown region codes.
1005 """
1006 if not _is_valid_region_code(region_code):
1007 return set()
1008 metadata = PhoneMetadata.metadata_for_region(region_code.upper())
1009 assert metadata is not None # due to _is_valid_region_code() check
1010 return _supported_types_for_metadata(metadata)
1013def supported_types_for_non_geo_entity(country_code):
1014 """Returns the types for a country-code belonging to a non-geographical entity
1015 which the library has metadata for. Will not include FIXED_LINE_OR_MOBILE
1016 (if numbers for this non-geographical entity could be classified as
1017 FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would be present) and
1018 UNKNOWN.
1020 No types will be returned for country calling codes that do not map to a
1021 known non-geographical entity.
1022 """
1023 metadata = PhoneMetadata.metadata_for_nongeo_region(country_code, None)
1024 if metadata is None:
1025 return set()
1026 return _supported_types_for_metadata(metadata)
1029def _formatting_rule_has_first_group_only(national_prefix_formatting_rule):
1030 """Helper function to check if the national prefix formatting rule has the
1031 first group only, i.e., does not start with the national prefix.
1032 """
1033 if national_prefix_formatting_rule is None:
1034 return True
1035 return bool(fullmatch(_FIRST_GROUP_ONLY_PREFIX_PATTERN,
1036 national_prefix_formatting_rule))
1039def is_number_geographical(numobj):
1040 """Tests whether a phone number has a geographical association.
1042 It checks if the number is associated with a certain region in the country
1043 to which it belongs. Note that this doesn't verify if the number is
1044 actually in use.
1045 country_code -- the country calling code for which we want the mobile token
1046 """
1047 return is_number_type_geographical(number_type(numobj), numobj.country_code)
1050def is_number_type_geographical(num_type, country_code):
1051 """Tests whether a phone number has a geographical association,
1052 as represented by its type and the country it belongs to.
1054 This version of isNumberGeographical exists since calculating the phone
1055 number type is expensive; if we have already done this, we don't want to
1056 do it again.
1057 """
1058 return (num_type == PhoneNumberType.FIXED_LINE or
1059 num_type == PhoneNumberType.FIXED_LINE_OR_MOBILE or
1060 ((country_code in _GEO_MOBILE_COUNTRIES) and
1061 num_type == PhoneNumberType.MOBILE))
1064def _is_valid_region_code(region_code):
1065 """Helper function to check region code is not unknown or None"""
1066 if region_code is None:
1067 return False
1068 return (region_code in SUPPORTED_REGIONS)
1071def _has_valid_country_calling_code(country_calling_code):
1072 return (country_calling_code in COUNTRY_CODE_TO_REGION_CODE)
1075def format_number(numobj, num_format):
1076 """Formats a phone number in the specified format using default rules.
1078 Note that this does not promise to produce a phone number that the user
1079 can dial from where they are - although we do format in either 'national'
1080 or 'international' format depending on what the client asks for, we do not
1081 currently support a more abbreviated format, such as for users in the same
1082 "area" who could potentially dial the number without area code. Note that
1083 if the phone number has a country calling code of 0 or an otherwise
1084 invalid country calling code, we cannot work out which formatting rules to
1085 apply so we return the national significant number with no formatting
1086 applied.
1088 Arguments:
1089 numobj -- The phone number to be formatted.
1090 num_format -- The format the phone number should be formatted into
1092 Returns the formatted phone number.
1093 """
1094 if numobj.national_number == 0:
1095 # Unparseable numbers that kept their raw input just use that. This
1096 # is the only case where a number can be formatted as E164 without a
1097 # leading '+' symbol (but the original number wasn't parseable
1098 # anyway).
1099 raw_input = numobj.raw_input or ""
1100 if len(raw_input) > 0 or numobj.country_code is None:
1101 return numobj.raw_input
1102 country_calling_code = numobj.country_code
1103 nsn = national_significant_number(numobj)
1104 if num_format == PhoneNumberFormat.E164:
1105 # Early exit for E164 case (even if the country calling code is
1106 # invalid) since no formatting of the national number needs to be
1107 # applied. Extensions are not formatted.
1108 return _prefix_number_with_country_calling_code(country_calling_code, num_format, nsn)
1109 if not _has_valid_country_calling_code(country_calling_code):
1110 return nsn
1111 # Note region_code_for_country_code() is used because formatting
1112 # information for regions which share a country calling code is contained
1113 # by only one region for performance reasons. For example, for NANPA
1114 # regions it will be contained in the metadata for US.
1115 region_code = region_code_for_country_code(country_calling_code)
1116 # Metadata cannot be None because the country calling code is valid (which
1117 # means that the region code cannot be ZZ and must be one of our supported
1118 # region codes).
1119 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_calling_code, region_code.upper())
1120 formatted_number = _format_nsn(nsn, metadata, num_format)
1121 formatted_number = _maybe_append_formatted_extension(numobj,
1122 metadata,
1123 num_format,
1124 formatted_number)
1125 return _prefix_number_with_country_calling_code(country_calling_code,
1126 num_format,
1127 formatted_number)
1130def format_by_pattern(numobj, number_format, user_defined_formats):
1131 """Formats a phone number using client-defined formatting rules.
1133 Note that if the phone number has a country calling code of zero or an
1134 otherwise invalid country calling code, we cannot work out things like
1135 whether there should be a national prefix applied, or how to format
1136 extensions, so we return the national significant number with no
1137 formatting applied.
1139 Arguments:
1140 numobj -- The phone number to be formatted
1141 number_format -- The format the phone number should be formatted into,
1142 as a PhoneNumberFormat value.
1143 user_defined_formats -- formatting rules specified by clients, as a list
1144 of NumberFormat objects.
1146 Returns the formatted phone number.
1147 """
1148 country_code = numobj.country_code
1149 nsn = national_significant_number(numobj)
1150 if not _has_valid_country_calling_code(country_code):
1151 return nsn
1152 # Note region_code_for_country_code() is used because formatting
1153 # information for regions which share a country calling code is contained
1154 # by only one region for performance reasons. For example, for NANPA
1155 # regions it will be contained in the metadata for US.
1156 region_code = region_code_for_country_code(country_code)
1157 # Metadata cannot be None because the country calling code is valid.
1158 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
1160 formatted_number = U_EMPTY_STRING
1161 formatting_pattern = _choose_formatting_pattern_for_number(user_defined_formats, nsn)
1162 if formatting_pattern is None:
1163 # If no pattern above is matched, we format the number as a whole.
1164 formatted_number = nsn
1165 else:
1166 num_format_copy = _copy_number_format(formatting_pattern)
1167 # Before we do a replacement of the national prefix pattern $NP with
1168 # the national prefix, we need to copy the rule so that subsequent
1169 # replacements for different numbers have the appropriate national
1170 # prefix.
1171 np_formatting_rule = formatting_pattern.national_prefix_formatting_rule
1172 if np_formatting_rule:
1173 national_prefix = metadata.national_prefix
1174 if national_prefix:
1175 # Replace $NP with national prefix and $FG with the first
1176 # group (\1) matcher.
1177 np_formatting_rule = np_formatting_rule.replace(_NP_STRING, national_prefix)
1178 np_formatting_rule = np_formatting_rule.replace(_FG_STRING, unicod("\\1"))
1179 num_format_copy.national_prefix_formatting_rule = np_formatting_rule
1180 else:
1181 # We don't want to have a rule for how to format the national
1182 # prefix if there isn't one.
1183 num_format_copy.national_prefix_formatting_rule = None
1184 formatted_number = _format_nsn_using_pattern(nsn, num_format_copy, number_format)
1185 formatted_number = _maybe_append_formatted_extension(numobj,
1186 metadata,
1187 number_format,
1188 formatted_number)
1189 formatted_number = _prefix_number_with_country_calling_code(country_code,
1190 number_format,
1191 formatted_number)
1192 return formatted_number
1195def format_national_number_with_carrier_code(numobj, carrier_code):
1196 """Format a number in national format for dialing using the specified carrier.
1198 The carrier-code will always be used regardless of whether the phone
1199 number already has a preferred domestic carrier code stored. If
1200 carrier_code contains an empty string, returns the number in national
1201 format without any carrier code.
1203 Arguments:
1204 numobj -- The phone number to be formatted
1205 carrier_code -- The carrier selection code to be used
1207 Returns the formatted phone number in national format for dialing using
1208 the carrier as specified in the carrier_code.
1209 """
1210 country_code = numobj.country_code
1211 nsn = national_significant_number(numobj)
1212 if not _has_valid_country_calling_code(country_code):
1213 return nsn
1214 # Note region_code_for_country_code() is used because formatting
1215 # information for regions which share a country calling code is contained
1216 # by only one region for performance reasons. For example, for NANPA
1217 # regions it will be contained in the metadata for US.
1218 region_code = region_code_for_country_code(country_code)
1219 # Metadata cannot be None because the country calling code is valid
1220 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
1221 formatted_number = _format_nsn(nsn,
1222 metadata,
1223 PhoneNumberFormat.NATIONAL,
1224 carrier_code)
1225 formatted_number = _maybe_append_formatted_extension(numobj,
1226 metadata,
1227 PhoneNumberFormat.NATIONAL,
1228 formatted_number)
1229 formatted_number = _prefix_number_with_country_calling_code(country_code,
1230 PhoneNumberFormat.NATIONAL,
1231 formatted_number)
1232 return formatted_number
1235def format_national_number_with_preferred_carrier_code(numobj, fallback_carrier_code):
1236 """Formats a phone number in national format for dialing using the carrier
1237 as specified in the preferred_domestic_carrier_code field of the
1238 PhoneNumber object passed in. If that is missing, use the
1239 fallback_carrier_code passed in instead. If there is no
1240 preferred_domestic_carrier_code, and the fallback_carrier_code contains an
1241 empty string, return the number in national format without any carrier
1242 code.
1244 Use format_national_number_with_carrier_code instead if the carrier code
1245 passed in should take precedence over the number's
1246 preferred_domestic_carrier_code when formatting.
1248 Arguments:
1249 numobj -- The phone number to be formatted
1250 carrier_code -- The carrier selection code to be used, if none is found in the
1251 phone number itself.
1253 Returns the formatted phone number in national format for dialing using
1254 the number's preferred_domestic_carrier_code, or the fallback_carrier_code
1255 pass in if none is found.
1256 """
1257 # Historically, we set this to an empty string when parsing with raw input
1258 # if none was found in the input string. However, this doesn't result in a
1259 # number we can dial. For this reason, we treat the empty string the same
1260 # as if it isn't set at all.
1261 if (numobj.preferred_domestic_carrier_code is not None and
1262 len(numobj.preferred_domestic_carrier_code) > 0):
1263 carrier_code = numobj.preferred_domestic_carrier_code
1264 else:
1265 carrier_code = fallback_carrier_code
1266 return format_national_number_with_carrier_code(numobj, carrier_code)
1269def format_number_for_mobile_dialing(numobj, region_calling_from, with_formatting):
1270 """Returns a number formatted in such a way that it can be dialed from a
1271 mobile phone in a specific region.
1273 If the number cannot be reached from the region (e.g. some countries block
1274 toll-free numbers from being called outside of the country), the method
1275 returns an empty string.
1277 Arguments:
1278 numobj -- The phone number to be formatted
1279 region_calling_from -- The region where the call is being placed.
1281 with_formatting -- whether the number should be returned with formatting
1282 symbols, such as spaces and dashes.
1284 Returns the formatted phone number.
1285 """
1286 country_calling_code = numobj.country_code
1287 if not _has_valid_country_calling_code(country_calling_code):
1288 if numobj.raw_input is None:
1289 return U_EMPTY_STRING
1290 else:
1291 return numobj.raw_input
1292 formatted_number = U_EMPTY_STRING
1293 # Clear the extension, as that part cannot normally be dialed together with the main number.
1294 numobj_no_ext = PhoneNumber()
1295 numobj_no_ext.merge_from(numobj)
1296 numobj_no_ext.extension = None
1297 region_code = region_code_for_country_code(country_calling_code)
1298 numobj_type = number_type(numobj_no_ext)
1299 is_valid_number = (numobj_type != PhoneNumberType.UNKNOWN)
1300 if region_calling_from == region_code:
1301 is_fixed_line_or_mobile = ((numobj_type == PhoneNumberType.FIXED_LINE) or
1302 (numobj_type == PhoneNumberType.MOBILE) or
1303 (numobj_type == PhoneNumberType.FIXED_LINE_OR_MOBILE))
1304 # Carrier codes may be needed in some countries. We handle this here.
1305 if region_code == "BR" and is_fixed_line_or_mobile:
1306 # Historically, we set this to an empty string when parsing with
1307 # raw input if none was found in the input string. However, this
1308 # doesn't result in a number we can dial. For this reason, we
1309 # treat the empty string the same as if it isn't set at all.
1310 if (numobj_no_ext.preferred_domestic_carrier_code is not None and
1311 len(numobj_no_ext.preferred_domestic_carrier_code) > 0):
1312 formatted_number = format_national_number_with_preferred_carrier_code(numobj_no_ext, "")
1313 else:
1314 # Brazilian fixed line and mobile numbers need to be dialed with a
1315 # carrier code when called within Brazil. Without that, most of
1316 # the carriers won't connect the call. Because of that, we return
1317 # an empty string here.
1318 formatted_number = U_EMPTY_STRING
1319 elif country_calling_code == _NANPA_COUNTRY_CODE:
1320 # For NANPA countries, we output international format for numbers
1321 # that can be dialed internationally, since that always works,
1322 # except for numbers which might potentially be short numbers,
1323 # which are always dialled in national format.
1324 metadata = PhoneMetadata.metadata_for_region(region_calling_from)
1325 assert metadata is not None # due to _has_valid_country_calling_code() check
1326 if (can_be_internationally_dialled(numobj_no_ext) and
1327 _test_number_length(national_significant_number(numobj_no_ext),
1328 metadata) != ValidationResult.TOO_SHORT):
1329 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL)
1330 else:
1331 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL)
1332 else:
1333 # For non-geographical countries, and Mexican, Chilean, and Uzbek
1334 # fixed line and mobile numbers, we output international format for
1335 # numbers that can be dialed internationally as that always works.
1336 if ((region_code == REGION_CODE_FOR_NON_GEO_ENTITY or
1337 ((region_code == unicod("MX") or region_code == unicod("CL") or
1338 region_code == unicod("UZ")) and
1339 is_fixed_line_or_mobile)) and
1340 can_be_internationally_dialled(numobj_no_ext)):
1341 # MX fixed line and mobile numbers should always be formatted
1342 # in international format, even when dialed within MX. For
1343 # national format to work, a carrier code needs to be used,
1344 # and the correct carrier code depends on if the caller and
1345 # callee are from the same local area. It is trickier to get
1346 # that to work correctly than using international format,
1347 # which is tested to work fine on all carriers.
1348 # CL fixed line numbers need the national prefix when dialing
1349 # in the national format, but don't have it when used for
1350 # display. The reverse is true for mobile numbers. As a
1351 # result, we output them in the international format to make
1352 # it work.
1353 # UZ mobile and fixed-line numbers have to be formatted in
1354 # international format or prefixed with special codes like 03,
1355 # 04 (for fixed-line) and 05 (for mobile) for dialling
1356 # successfully from mobile devices. As we do not have complete
1357 # information on special codes and to be consistent with
1358 # formatting across all phone types we return the number in
1359 # international format here.
1360 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL)
1361 else:
1362 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL)
1363 elif is_valid_number and can_be_internationally_dialled(numobj_no_ext):
1364 # We assume that short numbers are not diallable from outside their
1365 # region, so if a number is not a valid regular length phone number,
1366 # we treat it as if it cannot be internationally dialled.
1367 if with_formatting:
1368 return format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL)
1369 else:
1370 return format_number(numobj_no_ext, PhoneNumberFormat.E164)
1372 if with_formatting:
1373 return formatted_number
1374 else:
1375 return normalize_diallable_chars_only(formatted_number)
1378def format_out_of_country_calling_number(numobj, region_calling_from):
1379 """Formats a phone number for out-of-country dialing purposes.
1381 If no region_calling_from is supplied, we format the number in its
1382 INTERNATIONAL format. If the country calling code is the same as that of
1383 the region where the number is from, then NATIONAL formatting will be
1384 applied.
1386 If the number itself has a country calling code of zero or an otherwise
1387 invalid country calling code, then we return the number with no formatting
1388 applied.
1390 Note this function takes care of the case for calling inside of NANPA and
1391 between Russia and Kazakhstan (who share the same country calling
1392 code). In those cases, no international prefix is used. For regions which
1393 have multiple international prefixes, the number in its INTERNATIONAL
1394 format will be returned instead.
1396 Arguments:
1397 numobj -- The phone number to be formatted
1398 region_calling_from -- The region where the call is being placed
1400 Returns the formatted phone number
1401 """
1402 if not _is_valid_region_code(region_calling_from):
1403 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL)
1404 country_code = numobj.country_code
1405 nsn = national_significant_number(numobj)
1406 if not _has_valid_country_calling_code(country_code):
1407 return nsn
1408 if country_code == _NANPA_COUNTRY_CODE:
1409 if is_nanpa_country(region_calling_from):
1410 # For NANPA regions, return the national format for these regions
1411 # but prefix it with the country calling code.
1412 return (unicod(country_code) + U_SPACE +
1413 format_number(numobj, PhoneNumberFormat.NATIONAL))
1414 elif country_code == country_code_for_valid_region(region_calling_from):
1415 # If regions share a country calling code, the country calling code
1416 # need not be dialled. This also applies when dialling within a
1417 # region, so this if clause covers both these cases. Technically this
1418 # is the case for dialling from La Reunion to other overseas
1419 # departments of France (French Guiana, Martinique, Guadeloupe), but
1420 # not vice versa - so we don't cover this edge case for now and for
1421 # those cases return the version including country calling code.
1422 # Details here:
1423 # http://www.petitfute.com/voyage/225-info-pratiques-reunion
1424 return format_number(numobj, PhoneNumberFormat.NATIONAL)
1426 # Metadata cannot be None because we checked '_is_valid_region_code()' above.
1427 metadata_for_region_calling_from = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_calling_from.upper())
1428 international_prefix = metadata_for_region_calling_from.international_prefix
1430 # In general, if there is a preferred international prefix, use that. Otherwise, for regions
1431 # that have multiple international prefixes, the international format of the number is
1432 # returned since we would not know which one to use.
1433 i18n_prefix_for_formatting = U_EMPTY_STRING
1434 if metadata_for_region_calling_from.preferred_international_prefix is not None:
1435 i18n_prefix_for_formatting = metadata_for_region_calling_from.preferred_international_prefix
1436 elif fullmatch(_SINGLE_INTERNATIONAL_PREFIX, international_prefix):
1437 i18n_prefix_for_formatting = international_prefix
1439 region_code = region_code_for_country_code(country_code)
1440 # Metadata cannot be None because the country calling code is valid.
1441 metadata_for_region = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code.upper())
1442 formatted_national_number = _format_nsn(nsn,
1443 metadata_for_region,
1444 PhoneNumberFormat.INTERNATIONAL)
1445 formatted_number = _maybe_append_formatted_extension(numobj,
1446 metadata_for_region,
1447 PhoneNumberFormat.INTERNATIONAL,
1448 formatted_national_number)
1449 if len(i18n_prefix_for_formatting) > 0:
1450 formatted_number = (i18n_prefix_for_formatting + U_SPACE +
1451 unicod(country_code) + U_SPACE + formatted_number)
1452 else:
1453 formatted_number = _prefix_number_with_country_calling_code(country_code,
1454 PhoneNumberFormat.INTERNATIONAL,
1455 formatted_number)
1456 return formatted_number
1459def format_in_original_format(numobj, region_calling_from):
1460 """Formats a phone number using the original phone number format
1461 (e.g. INTERNATIONAL or NATIONAL) that the number is parsed from, provided
1462 that the number has been parsed with parse(.., keep_raw_input=True).
1463 Otherwise the number will be formatted in NATIONAL format.
1465 The original format is embedded in the country_code_source field of the
1466 PhoneNumber object passed in, which is only set when parsing keeps the raw
1467 input. When we don't have a formatting pattern for the number, the method
1468 falls back to returning the raw input.
1470 Note this method guarantees no digit will be inserted, removed or modified
1471 as a result of formatting.
1473 Arguments:
1474 number -- The phone number that needs to be formatted in its original
1475 number format
1476 region_calling_from -- The region whose IDD needs to be prefixed if the
1477 original number has one.
1479 Returns the formatted phone number in its original number format.
1480 """
1481 if (numobj.raw_input is not None and not _has_formatting_pattern_for_number(numobj)):
1482 # We check if we have the formatting pattern because without that, we
1483 # might format the number as a group without national prefix.
1484 return numobj.raw_input
1485 if numobj.country_code_source is CountryCodeSource.UNSPECIFIED:
1486 return format_number(numobj, PhoneNumberFormat.NATIONAL)
1488 formatted_number = _format_original_allow_mods(numobj, region_calling_from)
1489 num_raw_input = numobj.raw_input
1490 # If no digit is inserted/removed/modified as a result of our formatting,
1491 # we return the formatted phone number; otherwise we return the raw input
1492 # the user entered.
1493 if (formatted_number is not None and num_raw_input):
1494 normalized_formatted_number = normalize_diallable_chars_only(formatted_number)
1495 normalized_raw_input = normalize_diallable_chars_only(num_raw_input)
1496 if normalized_formatted_number != normalized_raw_input:
1497 formatted_number = num_raw_input
1498 return formatted_number
1501def _format_original_allow_mods(numobj, region_calling_from):
1502 if (numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN):
1503 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL)
1504 elif numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITH_IDD:
1505 return format_out_of_country_calling_number(numobj, region_calling_from)
1506 elif (numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITHOUT_PLUS_SIGN):
1507 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL)[1:]
1508 else:
1509 region_code = region_code_for_country_code(numobj.country_code)
1510 # We strip non-digits from the NDD here, and from the raw input later, so that we can
1511 # compare them easily.
1512 national_prefix = ndd_prefix_for_region(region_code, True) # strip non-digits
1513 national_format = format_number(numobj, PhoneNumberFormat.NATIONAL)
1514 if (national_prefix is None or len(national_prefix) == 0):
1515 # If the region doesn't have a national prefix at all, we can
1516 # safely return the national format without worrying about a
1517 # national prefix being added.
1518 return national_format
1519 # Otherwise, we check if the original number was entered with a national prefix.
1520 if (_raw_input_contains_national_prefix(numobj.raw_input, national_prefix, region_code)):
1521 # If so, we can safely return the national format.
1522 return national_format
1523 # Metadata cannot be None here because ndd_prefix_for_region() (above) returns None if
1524 # there is no metadata for the region.
1525 metadata = PhoneMetadata.metadata_for_region(region_code)
1526 assert metadata is not None
1527 national_number = national_significant_number(numobj)
1528 format_rule = _choose_formatting_pattern_for_number(metadata.number_format, national_number)
1529 # The format rule could still be null here if the national number was
1530 # 0 and there was no raw input (this should not be possible for
1531 # numbers generated by the phonenumber library as they would also not
1532 # have a country calling code and we would have exited earlier).
1533 if format_rule is None:
1534 return national_format
1535 # When the format we apply to this number doesn't contain national
1536 # prefix, we can just return the national format.
1537 # TODO: Refactor the code below with the code in isNationalPrefixPresentIfRequired.
1538 candidate_national_prefix_rule = format_rule.national_prefix_formatting_rule
1539 # We assume that the first-group symbol will never be _before_ the national prefix.
1540 if candidate_national_prefix_rule is None:
1541 return national_format
1542 index_of_first_group = candidate_national_prefix_rule.find("\\1")
1543 if (index_of_first_group <= 0):
1544 return national_format
1545 candidate_national_prefix_rule = candidate_national_prefix_rule[:index_of_first_group]
1546 candidate_national_prefix_rule = normalize_digits_only(candidate_national_prefix_rule)
1547 if len(candidate_national_prefix_rule) == 0:
1548 # National prefix not used when formatting this number.
1549 return national_format
1550 # Otherwise, we need to remove the national prefix from our output.
1551 new_format_rule = _copy_number_format(format_rule)
1552 new_format_rule.national_prefix_formatting_rule = None
1553 return format_by_pattern(numobj, PhoneNumberFormat.NATIONAL, [new_format_rule])
1556def _raw_input_contains_national_prefix(raw_input, national_prefix, region_code):
1557 """Check if raw_input, which is assumed to be in the national format, has a
1558 national prefix. The national prefix is assumed to be in digits-only
1559 form."""
1560 nnn = normalize_digits_only(raw_input)
1561 if nnn.startswith(national_prefix):
1562 try:
1563 # Some Japanese numbers (e.g. 00777123) might be mistaken to
1564 # contain the national prefix when written without it
1565 # (e.g. 0777123) if we just do prefix matching. To tackle that, we
1566 # check the validity of the number if the assumed national prefix
1567 # is removed (777123 won't be valid in Japan).
1568 return is_valid_number(parse(nnn[len(national_prefix):], region_code))
1569 except NumberParseException:
1570 return False
1571 return False
1574def _has_formatting_pattern_for_number(numobj):
1575 country_code = numobj.country_code
1576 phone_number_region = region_code_for_country_code(country_code)
1577 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, phone_number_region)
1578 if metadata is None:
1579 return False
1580 national_number = national_significant_number(numobj)
1581 format_rule = _choose_formatting_pattern_for_number(metadata.number_format, national_number)
1582 return format_rule is not None
1585def format_out_of_country_keeping_alpha_chars(numobj, region_calling_from):
1586 """Formats a phone number for out-of-country dialing purposes.
1588 Note that in this version, if the number was entered originally using
1589 alpha characters and this version of the number is stored in raw_input,
1590 this representation of the number will be used rather than the digit
1591 representation. Grouping information, as specified by characters such as
1592 "-" and " ", will be retained.
1594 Caveats:
1596 - This will not produce good results if the country calling code is both
1597 present in the raw input _and_ is the start of the national
1598 number. This is not a problem in the regions which typically use alpha
1599 numbers.
1601 - This will also not produce good results if the raw input has any
1602 grouping information within the first three digits of the national
1603 number, and if the function needs to strip preceding digits/words in
1604 the raw input before these digits. Normally people group the first
1605 three digits together so this is not a huge problem - and will be fixed
1606 if it proves to be so.
1608 Arguments:
1609 numobj -- The phone number that needs to be formatted.
1610 region_calling_from -- The region where the call is being placed.
1612 Returns the formatted phone number
1613 """
1614 num_raw_input = numobj.raw_input
1615 # If there is no raw input, then we can't keep alpha characters because there aren't any.
1616 # In this case, we return format_out_of_country_calling_number.
1617 if num_raw_input is None or len(num_raw_input) == 0:
1618 return format_out_of_country_calling_number(numobj, region_calling_from)
1619 country_code = numobj.country_code
1620 if not _has_valid_country_calling_code(country_code):
1621 return num_raw_input
1622 # Strip any prefix such as country calling code, IDD, that was present. We
1623 # do this by comparing the number in raw_input with the parsed number. To
1624 # do this, first we normalize punctuation. We retain number grouping
1625 # symbols such as " " only.
1626 num_raw_input = _normalize_helper(num_raw_input,
1627 _ALL_PLUS_NUMBER_GROUPING_SYMBOLS,
1628 True)
1629 # Now we trim everything before the first three digits in the parsed
1630 # number. We choose three because all valid alpha numbers have 3 digits at
1631 # the start - if it does not, then we don't trim anything at
1632 # all. Similarly, if the national number was less than three digits, we
1633 # don't trim anything at all.
1634 national_number = national_significant_number(numobj)
1635 if len(national_number) > 3:
1636 first_national_number_digit = num_raw_input.find(national_number[:3])
1637 if first_national_number_digit != -1:
1638 num_raw_input = num_raw_input[first_national_number_digit:]
1640 metadata_for_region_calling_from = PhoneMetadata.metadata_for_region(region_calling_from.upper(), None)
1641 if country_code == _NANPA_COUNTRY_CODE:
1642 if is_nanpa_country(region_calling_from):
1643 return unicod(country_code) + U_SPACE + num_raw_input
1644 elif (metadata_for_region_calling_from is not None and
1645 country_code == country_code_for_region(region_calling_from)):
1646 formatting_pattern = _choose_formatting_pattern_for_number(metadata_for_region_calling_from.number_format,
1647 national_number)
1648 if formatting_pattern is None:
1649 # If no pattern above is matched, we format the original input
1650 return num_raw_input
1651 new_format = _copy_number_format(formatting_pattern)
1652 # The first group is the first group of digits that the user
1653 # wrote together.
1654 new_format.pattern = u("(\\d+)(.*)")
1655 # Here we just concatenate them back together after the national
1656 # prefix has been fixed.
1657 new_format.format = u(r"\1\2")
1658 # Now we format using this pattern instead of the default pattern,
1659 # but with the national prefix prefixed if necessary.
1660 # This will not work in the cases where the pattern (and not the
1661 # leading digits) decide whether a national prefix needs to be used,
1662 # since we have overridden the pattern to match anything, but that is
1663 # not the case in the metadata to date.
1664 return _format_nsn_using_pattern(num_raw_input,
1665 new_format,
1666 PhoneNumberFormat.NATIONAL)
1667 i18n_prefix_for_formatting = U_EMPTY_STRING
1668 # If an unsupported region-calling-from is entered, or a country with
1669 # multiple international prefixes, the international format of the number
1670 # is returned, unless there is a preferred international prefix.
1671 if metadata_for_region_calling_from is not None:
1672 international_prefix = metadata_for_region_calling_from.international_prefix
1673 i18n_match = fullmatch(_SINGLE_INTERNATIONAL_PREFIX, international_prefix)
1674 if i18n_match:
1675 i18n_prefix_for_formatting = international_prefix
1676 else:
1677 i18n_prefix_for_formatting = metadata_for_region_calling_from.preferred_international_prefix
1679 region_code = region_code_for_country_code(country_code)
1680 # Metadata cannot be None because the country calling code is valid.
1681 metadata_for_region = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
1682 formatted_number = _maybe_append_formatted_extension(numobj,
1683 metadata_for_region,
1684 PhoneNumberFormat.INTERNATIONAL,
1685 num_raw_input)
1686 if i18n_prefix_for_formatting:
1687 formatted_number = (i18n_prefix_for_formatting + U_SPACE +
1688 unicod(country_code) + U_SPACE + formatted_number)
1689 else:
1690 # Invalid region entered as country-calling-from (so no metadata was
1691 # found for it) or the region chosen has multiple international
1692 # dialling prefixes.
1693 formatted_number = _prefix_number_with_country_calling_code(country_code,
1694 PhoneNumberFormat.INTERNATIONAL,
1695 formatted_number)
1696 return formatted_number
1699def national_significant_number(numobj):
1700 """Gets the national significant number of a phone number.
1702 Note that a national significant number doesn't contain a national prefix
1703 or any formatting.
1705 Arguments:
1706 numobj -- The PhoneNumber object for which the national significant number
1707 is needed.
1709 Returns the national significant number of the PhoneNumber object passed
1710 in.
1711 """
1712 # If leading zero(s) have been set, we prefix this now. Note this is not a
1713 # national prefix.
1714 national_number = U_EMPTY_STRING
1715 if numobj.italian_leading_zero:
1716 num_zeros = numobj.number_of_leading_zeros
1717 if num_zeros is None:
1718 num_zeros = 1
1719 if num_zeros > 0:
1720 national_number = U_ZERO * num_zeros
1721 national_number += str(numobj.national_number)
1722 return national_number
1725def _prefix_number_with_country_calling_code(country_code, num_format, formatted_number):
1726 """A helper function that is used by format_number and format_by_pattern."""
1727 if num_format == PhoneNumberFormat.E164:
1728 return _PLUS_SIGN + unicod(country_code) + formatted_number
1729 elif num_format == PhoneNumberFormat.INTERNATIONAL:
1730 return _PLUS_SIGN + unicod(country_code) + U_SPACE + formatted_number
1731 elif num_format == PhoneNumberFormat.RFC3966:
1732 return _RFC3966_PREFIX + _PLUS_SIGN + unicod(country_code) + U_DASH + formatted_number
1733 else:
1734 return formatted_number
1737def _format_nsn(number, metadata, num_format, carrier_code=None):
1738 """Format a national number."""
1739 # Note in some regions, the national number can be written in two
1740 # completely different ways depending on whether it forms part of the
1741 # NATIONAL format or INTERNATIONAL format. The num_format parameter here
1742 # is used to specify which format to use for those cases. If a carrier_code
1743 # is specified, this will be inserted into the formatted string to replace
1744 # $CC.
1745 intl_number_formats = metadata.intl_number_format
1747 # When the intl_number_formats exists, we use that to format national
1748 # number for the INTERNATIONAL format instead of using the
1749 # number_desc.number_formats.
1750 if (len(intl_number_formats) == 0 or
1751 num_format == PhoneNumberFormat.NATIONAL):
1752 available_formats = metadata.number_format
1753 else:
1754 available_formats = metadata.intl_number_format
1755 formatting_pattern = _choose_formatting_pattern_for_number(available_formats, number)
1756 if formatting_pattern is None:
1757 return number
1758 else:
1759 return _format_nsn_using_pattern(number, formatting_pattern, num_format, carrier_code)
1762def _choose_formatting_pattern_for_number(available_formats, national_number):
1763 for num_format in available_formats:
1764 size = len(num_format.leading_digits_pattern)
1765 # We always use the last leading_digits_pattern, as it is the most detailed.
1766 if size > 0:
1767 ld_pattern = re.compile(num_format.leading_digits_pattern[-1])
1768 ld_match = ld_pattern.match(national_number)
1769 if size == 0 or ld_match:
1770 format_pattern = re.compile(num_format.pattern)
1771 if fullmatch(format_pattern, national_number):
1772 return num_format
1773 return None
1776def _format_nsn_using_pattern(national_number, formatting_pattern, number_format,
1777 carrier_code=None):
1778 # Note that carrier_code is optional - if None or an empty string, no
1779 # carrier code replacement will take place.
1780 number_format_rule = formatting_pattern.format
1781 m_re = re.compile(formatting_pattern.pattern)
1782 formatted_national_number = U_EMPTY_STRING
1784 if (number_format == PhoneNumberFormat.NATIONAL and carrier_code and
1785 formatting_pattern.domestic_carrier_code_formatting_rule):
1786 # Replace the $CC in the formatting rule with the desired
1787 # carrier code.
1788 cc_format_rule = formatting_pattern.domestic_carrier_code_formatting_rule
1789 cc_format_rule = cc_format_rule.replace(_CC_STRING, carrier_code)
1791 # Now replace the $FG in the formatting rule with the
1792 # first group and the carrier code combined in the
1793 # appropriate way.
1794 number_format_rule = re.sub(_FIRST_GROUP_PATTERN,
1795 cc_format_rule,
1796 number_format_rule,
1797 count=1)
1798 formatted_national_number = re.sub(m_re, number_format_rule, national_number)
1799 else:
1800 # Use the national prefix formatting rule instead.
1801 national_prefix_formatting_rule = formatting_pattern.national_prefix_formatting_rule
1802 if (number_format == PhoneNumberFormat.NATIONAL and
1803 national_prefix_formatting_rule):
1804 first_group_rule = re.sub(_FIRST_GROUP_PATTERN,
1805 national_prefix_formatting_rule,
1806 number_format_rule,
1807 count=1)
1808 formatted_national_number = re.sub(m_re, first_group_rule, national_number)
1809 else:
1810 formatted_national_number = re.sub(m_re, number_format_rule, national_number)
1812 if number_format == PhoneNumberFormat.RFC3966:
1813 # Strip any leading punctuation.
1814 m = _SEPARATOR_PATTERN.match(formatted_national_number)
1815 if m:
1816 formatted_national_number = re.sub(_SEPARATOR_PATTERN, U_EMPTY_STRING, formatted_national_number, count=1)
1817 # Replace the rest with a dash between each number group
1818 formatted_national_number = re.sub(_SEPARATOR_PATTERN, U_DASH, formatted_national_number)
1820 return formatted_national_number
1823def example_number(region_code):
1824 """Gets a valid number for the specified region.
1826 Arguments:
1827 region_code -- The region for which an example number is needed.
1829 Returns a valid fixed-line number for the specified region. Returns None
1830 when the metadata does not contain such information, or the region 001 is
1831 passed in. For 001 (representing non-geographical numbers), call
1832 example_number_for_non_geo_entity instead.
1833 """
1834 return example_number_for_type(region_code, PhoneNumberType.FIXED_LINE)
1837def invalid_example_number(region_code):
1838 """Gets an invalid number for the specified region.
1840 This is useful for unit-testing purposes, where you want to test what
1841 will happen with an invalid number. Note that the number that is
1842 returned will always be able to be parsed and will have the correct
1843 country code. It may also be a valid *short* number/code for this
1844 region. Validity checking such numbers is handled with shortnumberinfo.
1846 Arguments:
1847 region_code -- The region for which an example number is needed.
1850 Returns an invalid number for the specified region. Returns None when an
1851 unsupported region or the region 001 (Earth) is passed in.
1852 """
1853 if not _is_valid_region_code(region_code):
1854 return None
1855 # We start off with a valid fixed-line number since every country
1856 # supports this. Alternatively we could start with a different number
1857 # type, since fixed-line numbers typically have a wide breadth of valid
1858 # number lengths and we may have to make it very short before we get an
1859 # invalid number.
1860 metadata = PhoneMetadata.metadata_for_region(region_code.upper())
1861 assert metadata is not None # due to _is_valid_region_code() check
1862 desc = _number_desc_by_type(metadata, PhoneNumberType.FIXED_LINE)
1863 if desc is None or desc.example_number is None:
1864 # This shouldn't happen; we have a test for this.
1865 return None # pragma no cover
1866 example_number = desc.example_number
1867 # Try and make the number invalid. We do this by changing the length. We
1868 # try reducing the length of the number, since currently no region has a
1869 # number that is the same length as MIN_LENGTH_FOR_NSN. This is probably
1870 # quicker than making the number longer, which is another
1871 # alternative. We could also use the possible number pattern to extract
1872 # the possible lengths of the number to make this faster, but this
1873 # method is only for unit-testing so simplicity is preferred to
1874 # performance. We don't want to return a number that can't be parsed,
1875 # so we check the number is long enough. We try all possible lengths
1876 # because phone number plans often have overlapping prefixes so the
1877 # number 123456 might be valid as a fixed-line number, and 12345 as a
1878 # mobile number. It would be faster to loop in a different order, but we
1879 # prefer numbers that look closer to real numbers (and it gives us a
1880 # variety of different lengths for the resulting phone numbers -
1881 # otherwise they would all be MIN_LENGTH_FOR_NSN digits long.)
1882 phone_number_length = len(example_number) - 1
1883 while phone_number_length >= _MIN_LENGTH_FOR_NSN:
1884 number_to_try = example_number[:phone_number_length]
1885 try:
1886 possibly_valid_number = parse(number_to_try, region_code)
1887 if not is_valid_number(possibly_valid_number):
1888 return possibly_valid_number
1889 except NumberParseException: # pragma no cover
1890 # Shouldn't happen: we have already checked the length, we know
1891 # example numbers have only valid digits, and we know the region
1892 # code is fine.
1893 pass
1894 phone_number_length -= 1
1896 # We have a test to check that this doesn't happen for any of our
1897 # supported regions.
1898 return None # pragma no cover
1901def example_number_for_type(region_code, num_type):
1902 """Gets a valid number for the specified region and number type.
1904 If None is given as the region_code, then the returned number object
1905 may belong to any country.
1907 Arguments:
1908 region_code -- The region for which an example number is needed, or None.
1909 num_type -- The type of number that is needed.
1911 Returns a valid number for the specified region and type. Returns None
1912 when the metadata does not contain such information or if an invalid
1913 region or region 001 was specified. For 001 (representing
1914 non-geographical numbers), call example_number_for_non_geo_entity instead.
1915 """
1916 if region_code is None:
1917 return _example_number_anywhere_for_type(num_type)
1918 # Check the region code is valid.
1919 if not _is_valid_region_code(region_code):
1920 return None
1921 metadata = PhoneMetadata.metadata_for_region(region_code.upper())
1922 assert metadata is not None # due to _is_valid_region_code() check
1923 desc = _number_desc_by_type(metadata, num_type)
1924 if desc is not None and desc.example_number is not None:
1925 try:
1926 return parse(desc.example_number, region_code)
1927 except NumberParseException: # pragma no cover
1928 pass
1929 return None
1932def _example_number_anywhere_for_type(num_type):
1933 """Gets a valid number for the specified number type (it may belong to any country).
1935 Arguments:
1936 num_type -- The type of number that is needed.
1938 Returns a valid number for the specified type. Returns None when the
1939 metadata does not contain such information. This should only happen when
1940 no numbers of this type are allocated anywhere in the world anymore.
1941 """
1942 for region_code in SUPPORTED_REGIONS:
1943 example_numobj = example_number_for_type(region_code, num_type)
1944 if example_numobj is not None:
1945 return example_numobj
1946 # If there wasn't an example number for a region, try the non-geographical entities.
1947 for country_calling_code in COUNTRY_CODES_FOR_NON_GEO_REGIONS:
1948 metadata = PhoneMetadata.metadata_for_nongeo_region(country_calling_code, None)
1949 desc = _number_desc_by_type(metadata, num_type)
1950 if desc is not None and desc.example_number is not None:
1951 try:
1952 return parse(_PLUS_SIGN + unicod(country_calling_code) + desc.example_number, UNKNOWN_REGION)
1953 except NumberParseException: # pragma no cover
1954 pass
1956 # There are no example numbers of this type for any country in the library.
1957 return None # pragma no cover
1960def example_number_for_non_geo_entity(country_calling_code):
1961 """Gets a valid number for the specified country calling code for a non-geographical entity.
1963 Arguments:
1964 country_calling_code -- The country calling code for a non-geographical entity.
1966 Returns a valid number for the non-geographical entity. Returns None when
1967 the metadata does not contain such information, or the country calling
1968 code passed in does not belong to a non-geographical entity.
1969 """
1970 metadata = PhoneMetadata.metadata_for_nongeo_region(country_calling_code, None)
1971 if metadata is not None:
1972 # For geographical entities, fixed-line data is always present. However, for non-geographical
1973 # entities, this is not the case, so we have to go through different types to find the
1974 # example number. We don't check fixed-line or personal number since they aren't used by
1975 # non-geographical entities (if this changes, a unit-test will catch this.)
1976 for desc in (metadata.mobile, metadata.toll_free, metadata.shared_cost, metadata.voip,
1977 metadata.voicemail, metadata.uan, metadata.premium_rate):
1978 try:
1979 if (desc is not None and desc.example_number is not None):
1980 return parse(_PLUS_SIGN + unicod(country_calling_code) + desc.example_number, UNKNOWN_REGION)
1981 except NumberParseException:
1982 pass
1983 return None
1986def _maybe_append_formatted_extension(numobj, metadata, num_format, number):
1987 """Appends the formatted extension of a phone number to formatted number,
1988 if the phone number had an extension specified.
1989 """
1990 if numobj.extension:
1991 if num_format == PhoneNumberFormat.RFC3966:
1992 return number + _RFC3966_EXTN_PREFIX + numobj.extension
1993 else:
1994 if metadata.preferred_extn_prefix is not None:
1995 return number + metadata.preferred_extn_prefix + numobj.extension
1996 else:
1997 return number + _DEFAULT_EXTN_PREFIX + numobj.extension
1998 return number
2001def _number_desc_by_type(metadata, num_type):
2002 """Return the PhoneNumberDesc of the metadata for the given number type"""
2003 if num_type == PhoneNumberType.PREMIUM_RATE:
2004 return metadata.premium_rate
2005 elif num_type == PhoneNumberType.TOLL_FREE:
2006 return metadata.toll_free
2007 elif num_type == PhoneNumberType.MOBILE:
2008 return metadata.mobile
2009 elif (num_type == PhoneNumberType.FIXED_LINE or
2010 num_type == PhoneNumberType.FIXED_LINE_OR_MOBILE):
2011 return metadata.fixed_line
2012 elif num_type == PhoneNumberType.SHARED_COST:
2013 return metadata.shared_cost
2014 elif num_type == PhoneNumberType.VOIP:
2015 return metadata.voip
2016 elif num_type == PhoneNumberType.PERSONAL_NUMBER:
2017 return metadata.personal_number
2018 elif num_type == PhoneNumberType.PAGER:
2019 return metadata.pager
2020 elif num_type == PhoneNumberType.UAN:
2021 return metadata.uan
2022 elif num_type == PhoneNumberType.VOICEMAIL:
2023 return metadata.voicemail
2024 else:
2025 return metadata.general_desc
2028def number_type(numobj):
2029 """Gets the type of a valid phone number.
2031 Arguments:
2032 numobj -- The PhoneNumber object that we want to know the type of.
2034 Returns the type of the phone number, as a PhoneNumberType value;
2035 returns PhoneNumberType.UNKNOWN if it is invalid.
2036 """
2037 region_code = region_code_for_number(numobj)
2038 metadata = PhoneMetadata.metadata_for_region_or_calling_code(numobj.country_code, region_code)
2039 if metadata is None:
2040 return PhoneNumberType.UNKNOWN
2041 national_number = national_significant_number(numobj)
2042 return _number_type_helper(national_number, metadata)
2045def _number_type_helper(national_number, metadata):
2046 """Return the type of the given number against the metadata"""
2047 if not _is_number_matching_desc(national_number, metadata.general_desc):
2048 return PhoneNumberType.UNKNOWN
2049 if _is_number_matching_desc(national_number, metadata.premium_rate):
2050 return PhoneNumberType.PREMIUM_RATE
2051 if _is_number_matching_desc(national_number, metadata.toll_free):
2052 return PhoneNumberType.TOLL_FREE
2053 if _is_number_matching_desc(national_number, metadata.shared_cost):
2054 return PhoneNumberType.SHARED_COST
2055 if _is_number_matching_desc(national_number, metadata.voip):
2056 return PhoneNumberType.VOIP
2057 if _is_number_matching_desc(national_number, metadata.personal_number):
2058 return PhoneNumberType.PERSONAL_NUMBER
2059 if _is_number_matching_desc(national_number, metadata.pager):
2060 return PhoneNumberType.PAGER
2061 if _is_number_matching_desc(national_number, metadata.uan):
2062 return PhoneNumberType.UAN
2063 if _is_number_matching_desc(national_number, metadata.voicemail):
2064 return PhoneNumberType.VOICEMAIL
2066 if _is_number_matching_desc(national_number, metadata.fixed_line):
2067 if metadata.same_mobile_and_fixed_line_pattern:
2068 return PhoneNumberType.FIXED_LINE_OR_MOBILE
2069 elif _is_number_matching_desc(national_number, metadata.mobile):
2070 return PhoneNumberType.FIXED_LINE_OR_MOBILE
2071 return PhoneNumberType.FIXED_LINE
2073 # Otherwise, test to see if the number is mobile. Only do this if certain
2074 # that the patterns for mobile and fixed line aren't the same.
2075 if (not metadata.same_mobile_and_fixed_line_pattern and
2076 _is_number_matching_desc(national_number, metadata.mobile)):
2077 return PhoneNumberType.MOBILE
2078 return PhoneNumberType.UNKNOWN
2081def _is_number_matching_desc(national_number, number_desc):
2082 """Determine if the number matches the given PhoneNumberDesc"""
2083 # Check if any possible number lengths are present; if so, we use them to avoid checking the
2084 # validation pattern if they don't match. If they are absent, this means they match the general
2085 # description, which we have already checked before checking a specific number type.
2086 if number_desc is None:
2087 return False
2088 actual_length = len(national_number)
2089 possible_lengths = number_desc.possible_length
2090 if len(possible_lengths) > 0 and actual_length not in possible_lengths:
2091 return False
2092 return _match_national_number(national_number, number_desc, False)
2095def is_valid_number(numobj):
2096 """Tests whether a phone number matches a valid pattern.
2098 Note this doesn't verify the number is actually in use, which is
2099 impossible to tell by just looking at a number itself. It only verifies
2100 whether the parsed, canonicalised number is valid: not whether a
2101 particular series of digits entered by the user is diallable from the
2102 region provided when parsing. For example, the number +41 (0) 78 927 2696
2103 can be parsed into a number with country code "41" and national
2104 significant number "789272696". This is valid, while the original string
2105 is not diallable.
2107 Arguments:
2108 numobj -- The phone number object that we want to validate
2110 Returns a boolean that indicates whether the number is of a valid pattern.
2111 """
2112 region_code = region_code_for_number(numobj)
2113 return is_valid_number_for_region(numobj, region_code)
2116def is_valid_number_for_region(numobj, region_code):
2117 """Tests whether a phone number is valid for a certain region.
2119 Note this doesn't verify the number is actually in use, which is
2120 impossible to tell by just looking at a number itself. If the country
2121 calling code is not the same as the country calling code for the region,
2122 this immediately exits with false. After this, the specific number pattern
2123 rules for the region are examined. This is useful for determining for
2124 example whether a particular number is valid for Canada, rather than just
2125 a valid NANPA number.
2127 Warning: In most cases, you want to use is_valid_number instead. For
2128 example, this method will mark numbers from British Crown dependencies
2129 such as the Isle of Man as invalid for the region "GB" (United Kingdom),
2130 since it has its own region code, "IM", which may be undesirable.
2132 Arguments:
2133 numobj -- The phone number object that we want to validate.
2134 region_code -- The region that we want to validate the phone number for.
2136 Returns a boolean that indicates whether the number is of a valid pattern.
2137 """
2138 country_code = numobj.country_code
2139 if region_code is None:
2140 return False
2141 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code.upper())
2142 if (metadata is None or
2143 (region_code != REGION_CODE_FOR_NON_GEO_ENTITY and
2144 country_code != country_code_for_valid_region(region_code))):
2145 # Either the region code was invalid, or the country calling code for
2146 # this number does not match that of the region code.
2147 return False
2148 nsn = national_significant_number(numobj)
2149 return (_number_type_helper(nsn, metadata) != PhoneNumberType.UNKNOWN)
2152def region_code_for_number(numobj):
2153 """Returns the region where a phone number is from.
2155 This could be used for geocoding at the region level. Only guarantees
2156 correct results for valid, full numbers (not short-codes, or invalid
2157 numbers).
2159 Arguments:
2160 numobj -- The phone number object whose origin we want to know
2162 Returns the region where the phone number is from, or None if no region
2163 matches this calling code.
2165 """
2166 country_code = numobj.country_code
2167 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None)
2168 if regions is None:
2169 return None
2171 if len(regions) == 1:
2172 return regions[0]
2173 else:
2174 return _region_code_for_number_from_list(numobj, regions)
2177def _region_code_for_number_from_list(numobj, regions):
2178 """Find the region in a list that matches a number"""
2179 national_number = national_significant_number(numobj)
2180 for region_code in regions:
2181 # If leading_digits is present, use this. Otherwise, do full
2182 # validation.
2183 # Metadata cannot be None because the region codes come from
2184 # the country calling code map.
2185 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None)
2186 if metadata is None:
2187 continue
2188 if metadata.leading_digits is not None:
2189 leading_digit_re = re.compile(metadata.leading_digits)
2190 match = leading_digit_re.match(national_number)
2191 if match:
2192 return region_code
2193 elif _number_type_helper(national_number, metadata) != PhoneNumberType.UNKNOWN:
2194 return region_code
2195 return None
2198def region_code_for_country_code(country_code):
2199 """Returns the region code that matches a specific country calling code.
2201 In the case of no region code being found, UNKNOWN_REGION ('ZZ') will be
2202 returned. In the case of multiple regions, the one designated in the
2203 metadata as the "main" region for this calling code will be returned. If
2204 the country_code entered is valid but doesn't match a specific region
2205 (such as in the case of non-geographical calling codes like 800) the value
2206 "001" will be returned (corresponding to the value for World in the UN
2207 M.49 schema).
2208 """
2209 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None)
2210 if regions is None:
2211 return UNKNOWN_REGION
2212 else:
2213 return regions[0]
2216def region_codes_for_country_code(country_code):
2217 """Returns a list with the region codes that match the specific country calling code.
2219 For non-geographical country calling codes, the region code 001 is
2220 returned. Also, in the case of no region code being found, an empty
2221 list is returned.
2222 """
2223 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None)
2224 if regions is None:
2225 return ()
2226 else:
2227 return regions
2230def country_code_for_region(region_code):
2231 """Returns the country calling code for a specific region.
2233 For example, this would be 1 for the United States, and 64 for New
2234 Zealand.
2236 Arguments:
2237 region_code -- The region that we want to get the country calling code for.
2239 Returns the country calling code for the region denoted by region_code.
2240 """
2241 if not _is_valid_region_code(region_code):
2242 return 0
2243 return country_code_for_valid_region(region_code)
2246def country_code_for_valid_region(region_code):
2247 """Returns the country calling code for a specific region.
2249 For example, this would be 1 for the United States, and 64 for New
2250 Zealand. Assumes the region is already valid.
2252 Arguments:
2253 region_code -- The region that we want to get the country calling code for.
2255 Returns the country calling code for the region denoted by region_code.
2256 """
2257 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None)
2258 if metadata is None:
2259 raise Exception("Invalid region code %s" % region_code)
2260 return metadata.country_code
2263def ndd_prefix_for_region(region_code, strip_non_digits):
2264 """Returns the national dialling prefix for a specific region.
2266 For example, this would be 1 for the United States, and 0 for New
2267 Zealand. Set strip_non_digits to True to strip symbols like "~" (which
2268 indicates a wait for a dialling tone) from the prefix returned. If no
2269 national prefix is present, we return None.
2271 Warning: Do not use this method for do-your-own formatting - for some
2272 regions, the national dialling prefix is used only for certain types of
2273 numbers. Use the library's formatting functions to prefix the national
2274 prefix when required.
2276 Arguments:
2277 region_code -- The region that we want to get the dialling prefix for.
2278 strip_non_digits -- whether to strip non-digits from the national
2279 dialling prefix.
2281 Returns the dialling prefix for the region denoted by region_code.
2282 """
2283 if region_code is None:
2284 return None
2285 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None)
2286 if metadata is None:
2287 return None
2288 national_prefix = metadata.national_prefix
2289 if national_prefix is None or len(national_prefix) == 0:
2290 return None
2291 if strip_non_digits:
2292 # Note: if any other non-numeric symbols are ever used in national
2293 # prefixes, these would have to be removed here as well.
2294 national_prefix = re.sub(U_TILDE, U_EMPTY_STRING, national_prefix)
2295 return national_prefix
2298def is_nanpa_country(region_code):
2299 """Checks if this region is a NANPA region.
2301 Returns True if region_code is one of the regions under the North American
2302 Numbering Plan Administration (NANPA).
2303 """
2304 return region_code in _NANPA_REGIONS
2307def is_alpha_number(number):
2308 """Checks if the number is a valid vanity (alpha) number such as 800
2309 MICROSOFT. A valid vanity number will start with at least 3 digits and
2310 will have three or more alpha characters. This does not do region-specific
2311 checks - to work out if this number is actually valid for a region, it
2312 should be parsed and methods such as is_possible_number_with_reason() and
2313 is_valid_number() should be used.
2315 Arguments:
2316 number -- the number that needs to be checked
2318 Returns True if the number is a valid vanity number
2319 """
2320 if not _is_viable_phone_number(number):
2321 # Number is too short, or doesn't match the basic phone number pattern.
2322 return False
2323 extension, stripped_number = _maybe_strip_extension(number)
2324 return bool(fullmatch(_VALID_ALPHA_PHONE_PATTERN, stripped_number))
2327def is_possible_number(numobj):
2328 """Convenience wrapper around is_possible_number_with_reason.
2330 Instead of returning the reason for failure, this method returns true if
2331 the number is either a possible fully-qualified number (containing the area
2332 code and country code), or if the number could be a possible local number
2333 (with a country code, but missing an area code). Local numbers are
2334 considered possible if they could be possibly dialled in this format: if
2335 the area code is needed for a call to connect, the number is not considered
2336 possible without it.
2338 Arguments:
2339 numobj -- the number object that needs to be checked
2341 Returns True if the number is possible
2343 """
2344 result = is_possible_number_with_reason(numobj)
2345 return (result == ValidationResult.IS_POSSIBLE or
2346 result == ValidationResult.IS_POSSIBLE_LOCAL_ONLY)
2349def is_possible_number_for_type(numobj, numtype):
2350 """Convenience wrapper around is_possible_number_for_type_with_reason.
2352 Instead of returning the reason for failure, this method returns true if
2353 the number is either a possible fully-qualified number (containing the area
2354 code and country code), or if the number could be a possible local number
2355 (with a country code, but missing an area code). Local numbers are
2356 considered possible if they could be possibly dialled in this format: if
2357 the area code is needed for a call to connect, the number is not considered
2358 possible without it.
2360 Arguments:
2361 numobj -- the number object that needs to be checked
2362 numtype -- the type we are interested in
2364 Returns True if the number is possible
2366 """
2367 result = is_possible_number_for_type_with_reason(numobj, numtype)
2368 return (result == ValidationResult.IS_POSSIBLE or
2369 result == ValidationResult.IS_POSSIBLE_LOCAL_ONLY)
2372def _test_number_length(national_number, metadata, numtype=PhoneNumberType.UNKNOWN):
2373 """Helper method to check a number against possible lengths for this number,
2374 and determine whether it matches, or is too short or too long.
2375 """
2376 desc_for_type = _number_desc_by_type(metadata, numtype)
2377 if desc_for_type is None:
2378 possible_lengths = metadata.general_desc.possible_length
2379 local_lengths = ()
2380 else:
2381 # There should always be "possibleLengths" set for every element. This is declared in the XML
2382 # schema which is verified by PhoneNumberMetadataSchemaTest.
2383 # For size efficiency, where a sub-description (e.g. fixed-line) has the same possibleLengths
2384 # as the parent, this is missing, so we fall back to the general desc (where no numbers of the
2385 # type exist at all, there is one possible length (-1) which is guaranteed not to match the
2386 # length of any real phone number).
2387 possible_lengths = desc_for_type.possible_length
2388 if len(possible_lengths) == 0: # pragma no cover: Python sub-descs all have possible_length
2389 possible_lengths = metadata.general_desc.possible_length
2390 local_lengths = desc_for_type.possible_length_local_only
2392 if numtype == PhoneNumberType.FIXED_LINE_OR_MOBILE:
2393 if not _desc_has_possible_number_data(_number_desc_by_type(metadata, PhoneNumberType.FIXED_LINE)):
2394 # The rare case has been encountered where no fixedLine data is available (true for some
2395 # non-geographical entities), so we just check mobile.
2396 return _test_number_length(national_number, metadata, PhoneNumberType.MOBILE)
2397 else:
2398 mobile_desc = _number_desc_by_type(metadata, PhoneNumberType.MOBILE)
2399 if _desc_has_possible_number_data(mobile_desc):
2400 # Merge the mobile data in if there was any. We have to make a copy to do this.
2401 possible_lengths = list(possible_lengths)
2402 # Note that when adding the possible lengths from mobile, we have to again check they
2403 # aren't empty since if they are this indicates they are the same as the general desc and
2404 # should be obtained from there.
2405 if len(mobile_desc.possible_length) == 0: # pragma no cover: Python sub-descs all have possible_length
2406 possible_lengths += metadata.general_desc.possible_length
2407 else:
2408 possible_lengths += mobile_desc.possible_length
2409 # The current list is sorted; we need to merge in the new list and re-sort (duplicates
2410 # are okay). Sorting isn't so expensive because the lists are very small.
2411 list.sort(possible_lengths)
2413 if len(local_lengths) == 0:
2414 local_lengths = mobile_desc.possible_length_local_only
2415 else:
2416 local_lengths = list(local_lengths)
2417 local_lengths += mobile_desc.possible_length_local_only
2418 list.sort(local_lengths)
2420 # If the type is not supported at all (indicated by a missing PhoneNumberDesc) we return invalid length.
2421 if desc_for_type is None:
2422 return ValidationResult.INVALID_LENGTH
2424 actual_length = len(national_number)
2425 # This is safe because there is never an overlap between the possible lengths and the local-only
2426 # lengths; this is checked at build time.
2427 if actual_length in local_lengths:
2428 return ValidationResult.IS_POSSIBLE_LOCAL_ONLY
2430 minimum_length = possible_lengths[0]
2431 if minimum_length == actual_length:
2432 return ValidationResult.IS_POSSIBLE
2433 elif minimum_length > actual_length:
2434 return ValidationResult.TOO_SHORT
2435 elif possible_lengths[-1] < actual_length:
2436 return ValidationResult.TOO_LONG
2437 # We skip the first element; we've already checked it.
2438 if actual_length in possible_lengths[1:]:
2439 return ValidationResult.IS_POSSIBLE
2440 else:
2441 return ValidationResult.INVALID_LENGTH
2444def is_possible_number_with_reason(numobj):
2445 return is_possible_number_for_type_with_reason(numobj, PhoneNumberType.UNKNOWN)
2448def is_possible_number_for_type_with_reason(numobj, numtype):
2449 """Check whether a phone number is a possible number of a particular type.
2451 For types that don't exist in a particular region, this will return a result
2452 that isn't so useful; it is recommended that you use
2453 supported_types_for_region or supported_types_for_non_geo_entity
2454 respectively before calling this method to determine whether you should call
2455 it for this number at all.
2457 This provides a more lenient check than is_valid_number in the following sense:
2459 - It only checks the length of phone numbers. In particular, it doesn't
2460 check starting digits of the number.
2462 - For some numbers (particularly fixed-line), many regions have the
2463 concept of area code, which together with subscriber number constitute
2464 the national significant number. It is sometimes okay to dial only the
2465 subscriber number when dialing in the same area. This function will
2466 return IS_POSSIBLE_LOCAL_ONLY if the subscriber-number-only version is
2467 passed in. On the other hand, because is_valid_number validates using
2468 information on both starting digits (for fixed line numbers, that would
2469 most likely be area codes) and length (obviously includes the length of
2470 area codes for fixed line numbers), it will return false for the
2471 subscriber-number-only version.
2473 Arguments:
2474 numobj -- The number object that needs to be checked
2475 numtype -- The type we are interested in
2477 Returns a value from ValidationResult which indicates whether the number
2478 is possible
2479 """
2480 national_number = national_significant_number(numobj)
2481 country_code = numobj.country_code
2482 # Note: For regions that share a country calling code, like NANPA numbers,
2483 # we just use the rules from the default region (US in this case) since the
2484 # region_code_for_number will not work if the number is possible but not
2485 # valid. There is in fact one country calling code (290) where the possible
2486 # number pattern differs between various regions (Saint Helena and Tristan
2487 # da Cuñha), but this is handled by putting all possible lengths for any
2488 # country with this country calling code in the metadata for the default
2489 # region in this case.
2490 if not _has_valid_country_calling_code(country_code):
2491 return ValidationResult.INVALID_COUNTRY_CODE
2492 region_code = region_code_for_country_code(country_code)
2493 # Metadata cannot be None because the country calling code is valid.
2494 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
2495 return _test_number_length(national_number, metadata, numtype)
2498def is_possible_number_string(number, region_dialing_from):
2499 """Check whether a phone number string is a possible number.
2501 Takes a number in the form of a string, and the region where the number
2502 could be dialed from. It provides a more lenient check than
2503 is_valid_number; see is_possible_number_with_reason() for details.
2505 This method first parses the number, then invokes is_possible_number with
2506 the resultant PhoneNumber object.
2508 Arguments:
2509 number -- The number that needs to be checked, in the form of a string.
2510 region_dialling_from -- The region that we are expecting the number to be
2511 dialed from. Note this is different from the region where the
2512 number belongs. For example, the number +1 650 253 0000 is a
2513 number that belongs to US. When written in this form, it can be
2514 dialed from any region. When it is written as 00 1 650 253 0000,
2515 it can be dialed from any region which uses an international
2516 dialling prefix of 00. When it is written as 650 253 0000, it
2517 can only be dialed from within the US, and when written as 253
2518 0000, it can only be dialed from within a smaller area in the US
2519 (Mountain View, CA, to be more specific).
2521 Returns True if the number is possible
2522 """
2523 try:
2524 return is_possible_number(parse(number, region_dialing_from))
2525 except NumberParseException:
2526 return False
2529def truncate_too_long_number(numobj):
2530 """Truncate a number object that is too long.
2532 Attempts to extract a valid number from a phone number that is too long
2533 to be valid, and resets the PhoneNumber object passed in to that valid
2534 version. If no valid number could be extracted, the PhoneNumber object
2535 passed in will not be modified.
2537 Arguments:
2538 numobj -- A PhoneNumber object which contains a number that is too long to
2539 be valid.
2541 Returns True if a valid phone number can be successfully extracted.
2542 """
2543 if is_valid_number(numobj):
2544 return True
2545 numobj_copy = PhoneNumber()
2546 numobj_copy.merge_from(numobj)
2547 national_number = numobj.national_number
2549 while not is_valid_number(numobj_copy):
2550 # Strip a digit off the RHS
2551 national_number = national_number // 10
2552 numobj_copy.national_number = national_number
2553 validation_result = is_possible_number_with_reason(numobj_copy)
2554 if (validation_result == ValidationResult.TOO_SHORT or
2555 national_number == 0):
2556 return False
2557 # To reach here, numobj_copy is a valid number. Modify the original object
2558 numobj.national_number = national_number
2559 return True
2562def _extract_country_code(number):
2563 """Extracts country calling code from number.
2565 Returns a 2-tuple of (country_calling_code, rest_of_number). It assumes
2566 that the leading plus sign or IDD has already been removed. Returns (0,
2567 number) if number doesn't start with a valid country calling code.
2568 """
2570 if len(number) == 0 or number[0] == U_ZERO:
2571 # Country codes do not begin with a '0'.
2572 return (0, number)
2573 for ii in range(1, min(len(number), _MAX_LENGTH_COUNTRY_CODE) + 1):
2574 try:
2575 country_code = int(number[:ii])
2576 if country_code in COUNTRY_CODE_TO_REGION_CODE:
2577 return (country_code, number[ii:])
2578 except Exception:
2579 pass
2580 return (0, number)
2583def _maybe_extract_country_code(number, metadata, keep_raw_input, numobj):
2584 """Tries to extract a country calling code from a number.
2586 This method will return zero if no country calling code is considered to
2587 be present. Country calling codes are extracted in the following ways:
2589 - by stripping the international dialing prefix of the region the person
2590 is dialing from, if this is present in the number, and looking at the
2591 next digits
2593 - by stripping the '+' sign if present and then looking at the next
2594 digits
2596 - by comparing the start of the number and the country calling code of
2597 the default region. If the number is not considered possible for the
2598 numbering plan of the default region initially, but starts with the
2599 country calling code of this region, validation will be reattempted
2600 after stripping this country calling code. If this number is considered
2601 a possible number, then the first digits will be considered the country
2602 calling code and removed as such.
2604 It will raise a NumberParseException if the number starts with a '+' but
2605 the country calling code supplied after this does not match that of any
2606 known region.
2608 Arguments:
2609 number -- non-normalized telephone number that we wish to extract a
2610 country calling code from; may begin with '+'
2611 metadata -- metadata about the region this number may be from, or None
2612 keep_raw_input -- True if the country_code_source and
2613 preferred_carrier_code fields of numobj should be populated.
2614 numobj -- The PhoneNumber object where the country_code and
2615 country_code_source need to be populated. Note the country_code
2616 is always populated, whereas country_code_source is only
2617 populated when keep_raw_input is True.
2619 Returns a 2-tuple containing:
2620 - the country calling code extracted or 0 if none could be extracted
2621 - a string holding the national significant number, in the case
2622 that a country calling code was extracted. If no country calling code
2623 was extracted, this will be empty.
2624 """
2625 if len(number) == 0:
2626 return (0, U_EMPTY_STRING)
2627 full_number = number
2628 # Set the default prefix to be something that will never match.
2629 possible_country_idd_prefix = unicod("NonMatch")
2630 if metadata is not None and metadata.international_prefix is not None:
2631 possible_country_idd_prefix = metadata.international_prefix
2633 country_code_source, full_number = _maybe_strip_i18n_prefix_and_normalize(full_number,
2634 possible_country_idd_prefix)
2635 if keep_raw_input:
2636 numobj.country_code_source = country_code_source
2638 if country_code_source != CountryCodeSource.FROM_DEFAULT_COUNTRY:
2639 if len(full_number) <= _MIN_LENGTH_FOR_NSN:
2640 raise NumberParseException(NumberParseException.TOO_SHORT_AFTER_IDD,
2641 "Phone number had an IDD, but after this was not " +
2642 "long enough to be a viable phone number.")
2643 potential_country_code, rest_of_number = _extract_country_code(full_number)
2644 if potential_country_code != 0:
2645 numobj.country_code = potential_country_code
2646 return (potential_country_code, rest_of_number)
2648 # If this fails, they must be using a strange country calling code
2649 # that we don't recognize, or that doesn't exist.
2650 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE,
2651 "Country calling code supplied was not recognised.")
2652 elif metadata is not None:
2653 # Check to see if the number starts with the country calling code for
2654 # the default region. If so, we remove the country calling code, and
2655 # do some checks on the validity of the number before and after.
2656 default_country_code = metadata.country_code
2657 default_country_code_str = str(metadata.country_code)
2658 normalized_number = full_number
2659 if normalized_number.startswith(default_country_code_str):
2660 potential_national_number = full_number[len(default_country_code_str):]
2661 general_desc = metadata.general_desc
2662 _, potential_national_number, _ = _maybe_strip_national_prefix_carrier_code(potential_national_number,
2663 metadata)
2665 # If the number was not valid before but is valid now, or if it
2666 # was too long before, we consider the number with the country
2667 # calling code stripped to be a better result and keep that
2668 # instead.
2669 if ((not _match_national_number(full_number, general_desc, False) and
2670 _match_national_number(potential_national_number, general_desc, False)) or
2671 (_test_number_length(full_number, metadata) == ValidationResult.TOO_LONG)):
2672 if keep_raw_input:
2673 numobj.country_code_source = CountryCodeSource.FROM_NUMBER_WITHOUT_PLUS_SIGN
2674 numobj.country_code = default_country_code
2675 return (default_country_code, potential_national_number)
2677 # No country calling code present.
2678 numobj.country_code = 0
2679 return (0, U_EMPTY_STRING)
2682def _parse_prefix_as_idd(idd_pattern, number):
2683 """Strips the IDD from the start of the number if present.
2685 Helper function used by _maybe_strip_i18n_prefix_and_normalize().
2687 Returns a 2-tuple:
2688 - Boolean indicating if IDD was stripped
2689 - Number with IDD stripped
2690 """
2691 match = idd_pattern.match(number)
2692 if match:
2693 match_end = match.end()
2694 # Only strip this if the first digit after the match is not a 0, since
2695 # country calling codes cannot begin with 0.
2696 digit_match = _CAPTURING_DIGIT_PATTERN.search(number[match_end:])
2697 if digit_match:
2698 normalized_group = normalize_digits_only(digit_match.group(1))
2699 if normalized_group == U_ZERO:
2700 return (False, number)
2701 return (True, number[match_end:])
2702 return (False, number)
2705def _maybe_strip_i18n_prefix_and_normalize(number, possible_idd_prefix):
2706 """Strips any international prefix (such as +, 00, 011) present in the
2707 number provided, normalizes the resulting number, and indicates if an
2708 international prefix was present.
2710 Arguments:
2711 number -- The non-normalized telephone number that we wish to strip any international
2712 dialing prefix from.
2713 possible_idd_prefix -- The international direct dialing prefix from the region we
2714 think this number may be dialed in.
2716 Returns a 2-tuple containing:
2717 - The corresponding CountryCodeSource if an international dialing prefix
2718 could be removed from the number, otherwise
2719 CountryCodeSource.FROM_DEFAULT_COUNTRY if the number did not seem to
2720 be in international format.
2721 - The number with the prefix stripped.
2722 """
2723 if len(number) == 0:
2724 return (CountryCodeSource.FROM_DEFAULT_COUNTRY, number)
2725 # Check to see if the number begins with one or more plus signs.
2726 m = _PLUS_CHARS_PATTERN.match(number)
2727 if m:
2728 number = number[m.end():]
2729 # Can now normalize the rest of the number since we've consumed the
2730 # "+" sign at the start.
2731 return (CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN,
2732 _normalize(number))
2734 # Attempt to parse the first digits as an international prefix.
2735 idd_pattern = re.compile(possible_idd_prefix)
2736 number = _normalize(number)
2737 stripped, number = _parse_prefix_as_idd(idd_pattern, number)
2738 if stripped:
2739 return (CountryCodeSource.FROM_NUMBER_WITH_IDD, number)
2740 else:
2741 return (CountryCodeSource.FROM_DEFAULT_COUNTRY, number)
2744def _maybe_strip_national_prefix_carrier_code(number, metadata):
2745 """Strips any national prefix (such as 0, 1) present in a number.
2747 Arguments:
2748 number -- The normalized telephone number that we wish to strip any
2749 national dialing prefix from
2750 metadata -- The metadata for the region that we think this number
2751 is from.
2753 Returns a 3-tuple of
2754 - The carrier code extracted if it is present, otherwise an empty string.
2755 - The number with the prefix stripped.
2756 - Boolean indicating if a national prefix or carrier code (or both) could be extracted.
2757 """
2758 carrier_code = U_EMPTY_STRING
2759 possible_national_prefix = metadata.national_prefix_for_parsing
2760 if (len(number) == 0 or
2761 possible_national_prefix is None or
2762 len(possible_national_prefix) == 0):
2763 # Early return for numbers of zero length.
2764 return (U_EMPTY_STRING, number, False)
2766 # Attempt to parse the first digits as a national prefix.
2767 prefix_pattern = re.compile(possible_national_prefix)
2768 prefix_match = prefix_pattern.match(number)
2769 if prefix_match:
2770 general_desc = metadata.general_desc
2771 # Check if the original number is viable.
2772 is_viable_original_number = _match_national_number(number, general_desc, False)
2773 # prefix_match.groups() == () implies nothing was captured by the
2774 # capturing groups in possible_national_prefix; therefore, no
2775 # transformation is necessary, and we just remove the national prefix.
2776 num_groups = len(prefix_match.groups())
2777 transform_rule = metadata.national_prefix_transform_rule
2778 if (transform_rule is None or
2779 len(transform_rule) == 0 or
2780 prefix_match.groups()[num_groups - 1] is None):
2781 # If the original number was viable, and the resultant number is not, we return.
2782 # Check that the resultant number is viable. If not, return.
2783 national_number_match = _match_national_number(number[prefix_match.end():], general_desc, False)
2784 if (is_viable_original_number and not national_number_match):
2785 return (U_EMPTY_STRING, number, False)
2787 if (num_groups > 0 and
2788 prefix_match.groups(num_groups) is not None):
2789 carrier_code = prefix_match.group(1)
2790 return (carrier_code, number[prefix_match.end():], True)
2791 else:
2792 # Check that the resultant number is still viable. If not,
2793 # return. Check this by copying the number and making the
2794 # transformation on the copy first.
2795 transformed_number = re.sub(prefix_pattern, transform_rule, number, count=1)
2796 national_number_match = _match_national_number(transformed_number, general_desc, False)
2797 if (is_viable_original_number and not national_number_match):
2798 return ("", number, False)
2799 if num_groups > 1:
2800 carrier_code = prefix_match.group(1)
2801 return (carrier_code, transformed_number, True)
2802 else:
2803 return (carrier_code, number, False)
2806def _maybe_strip_extension(number):
2807 """Strip extension from the end of a number string.
2809 Strips any extension (as in, the part of the number dialled after the
2810 call is connected, usually indicated with extn, ext, x or similar) from
2811 the end of the number, and returns it.
2813 Arguments:
2814 number -- the non-normalized telephone number that we wish to strip the extension from.
2816 Returns a 2-tuple of:
2817 - the phone extension (or "" or not present)
2818 - the number before the extension.
2819 """
2820 match = _EXTN_PATTERN.search(number)
2821 # If we find a potential extension, and the number preceding this is a
2822 # viable number, we assume it is an extension.
2823 if match and _is_viable_phone_number(number[:match.start()]):
2824 # The numbers are captured into groups in the regular expression.
2825 for group in match.groups():
2826 # We go through the capturing groups until we find one that
2827 # captured some digits. If none did, then we will return the empty
2828 # string.
2829 if group is not None:
2830 return (group, number[:match.start()])
2831 return ("", number)
2834def _check_region_for_parsing(number, default_region):
2835 """Checks to see that the region code used is valid, or if it is not
2836 valid, that the number to parse starts with a + symbol so that we can
2837 attempt to infer the region from the number. Returns False if it cannot
2838 use the region provided and the region cannot be inferred.
2839 """
2840 if not _is_valid_region_code(default_region):
2841 # If the number is None or empty, we can't infer the region.
2842 if number is None or len(number) == 0:
2843 return False
2844 match = _PLUS_CHARS_PATTERN.match(number)
2845 if match is None:
2846 return False
2847 return True
2850def _set_italian_leading_zeros_for_phone_number(national_number, numobj):
2851 """A helper function to set the values related to leading zeros in a
2852 PhoneNumber."""
2853 if len(national_number) > 1 and national_number[0] == U_ZERO:
2854 numobj.italian_leading_zero = True
2855 number_of_leading_zeros = 1
2856 # Note that if the number is all "0"s, the last "0" is not counted as
2857 # a leading zero.
2858 while (number_of_leading_zeros < len(national_number) - 1 and
2859 national_number[number_of_leading_zeros] == U_ZERO):
2860 number_of_leading_zeros += 1
2861 if number_of_leading_zeros != 1:
2862 numobj.number_of_leading_zeros = number_of_leading_zeros
2865def parse(number, region=None, keep_raw_input=False,
2866 numobj=None, _check_region=True):
2867 """Parse a string and return a corresponding PhoneNumber object.
2869 The method is quite lenient and looks for a number in the input text
2870 (raw input) and does not check whether the string is definitely only a
2871 phone number. To do this, it ignores punctuation and white-space, as
2872 well as any text before the number (e.g. a leading "Tel: ") and trims
2873 the non-number bits. It will accept a number in any format (E164,
2874 national, international etc), assuming it can be interpreted with the
2875 defaultRegion supplied. It also attempts to convert any alpha characters
2876 into digits if it thinks this is a vanity number of the type "1800
2877 MICROSOFT".
2879 This method will throw a NumberParseException if the number is not
2880 considered to be a possible number. Note that validation of whether the
2881 number is actually a valid number for a particular region is not
2882 performed. This can be done separately with is_valid_number.
2884 Note this method canonicalizes the phone number such that different
2885 representations can be easily compared, no matter what form it was
2886 originally entered in (e.g. national, international). If you want to
2887 record context about the number being parsed, such as the raw input that
2888 was entered, how the country code was derived etc. then ensure
2889 keep_raw_input is set.
2891 Note if any new field is added to this method that should always be filled
2892 in, even when keep_raw_input is False, it should also be handled in the
2893 _copy_core_fields_only() function.
2895 Arguments:
2896 number -- The number that we are attempting to parse. This can
2897 contain formatting such as +, ( and -, as well as a phone
2898 number extension. It can also be provided in RFC3966 format.
2899 region -- The region that we are expecting the number to be from. This
2900 is only used if the number being parsed is not written in
2901 international format. The country_code for the number in
2902 this case would be stored as that of the default region
2903 supplied. If the number is guaranteed to start with a '+'
2904 followed by the country calling code, then None or
2905 UNKNOWN_REGION can be supplied.
2906 keep_raw_input -- Whether to populate the raw_input field of the
2907 PhoneNumber object with number (as well as the
2908 country_code_source field).
2909 numobj -- An optional existing PhoneNumber object to receive the
2910 parsing results
2911 _check_region -- Whether to check the supplied region parameter;
2912 should always be True for external callers.
2914 Returns a PhoneNumber object filled with the parse number.
2916 Raises:
2917 NumberParseException if the string is not considered to be a viable
2918 phone number (e.g. too few or too many digits) or if no default
2919 region was supplied and the number is not in international format
2920 (does not start with +).
2922 """
2923 if numobj is None:
2924 numobj = PhoneNumber()
2925 if number is None:
2926 raise NumberParseException(NumberParseException.NOT_A_NUMBER,
2927 "The phone number supplied was None.")
2928 elif len(number) > _MAX_INPUT_STRING_LENGTH:
2929 raise NumberParseException(NumberParseException.TOO_LONG,
2930 "The string supplied was too long to parse.")
2932 national_number = _build_national_number_for_parsing(number)
2934 if not _is_viable_phone_number(national_number):
2935 raise NumberParseException(NumberParseException.NOT_A_NUMBER,
2936 "The string supplied did not seem to be a phone number.")
2938 # Check the region supplied is valid, or that the extracted number starts
2939 # with some sort of + sign so the number's region can be determined.
2940 if _check_region and not _check_region_for_parsing(national_number, region):
2941 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE,
2942 "Missing or invalid default region.")
2943 if keep_raw_input:
2944 numobj.raw_input = number
2946 # Attempt to parse extension first, since it doesn't require
2947 # region-specific data and we want to have the non-normalised number here.
2948 extension, national_number = _maybe_strip_extension(national_number)
2949 if len(extension) > 0:
2950 numobj.extension = extension
2951 if region is None:
2952 metadata = None
2953 else:
2954 metadata = PhoneMetadata.metadata_for_region(region.upper(), None)
2956 country_code = 0
2957 try:
2958 country_code, normalized_national_number = _maybe_extract_country_code(national_number,
2959 metadata,
2960 keep_raw_input,
2961 numobj)
2962 except NumberParseException:
2963 _, e, _ = sys.exc_info()
2964 matchobj = _PLUS_CHARS_PATTERN.match(national_number)
2965 if (e.error_type == NumberParseException.INVALID_COUNTRY_CODE and
2966 matchobj is not None):
2967 # Strip the plus-char, and try again.
2968 country_code, normalized_national_number = _maybe_extract_country_code(national_number[matchobj.end():],
2969 metadata,
2970 keep_raw_input,
2971 numobj)
2972 if country_code == 0:
2973 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE,
2974 "Could not interpret numbers after plus-sign.")
2975 else:
2976 raise
2978 if country_code != 0:
2979 number_region = region_code_for_country_code(country_code)
2980 if number_region != region:
2981 # Metadata cannot be None because the country calling code is valid.
2982 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, number_region)
2983 assert metadata is not None
2984 else:
2985 # If no extracted country calling code, use the region supplied
2986 # instead. The national number is just the normalized version of the
2987 # number we were given to parse.
2988 normalized_national_number += _normalize(national_number)
2989 if region is not None:
2990 country_code = metadata.country_code
2991 numobj.country_code = country_code
2992 elif keep_raw_input:
2993 numobj.country_code_source = CountryCodeSource.UNSPECIFIED
2995 if len(normalized_national_number) < _MIN_LENGTH_FOR_NSN:
2996 raise NumberParseException(NumberParseException.TOO_SHORT_NSN,
2997 "The string supplied is too short to be a phone number.")
2998 if metadata is not None:
2999 potential_national_number = normalized_national_number
3000 carrier_code, potential_national_number, _ = _maybe_strip_national_prefix_carrier_code(potential_national_number,
3001 metadata)
3002 # We require that the NSN remaining after stripping the national
3003 # prefix and carrier code be long enough to be a possible length for
3004 # the region. Otherwise, we don't do the stripping, since the original
3005 # number could be a valid short number.
3006 validation_result = _test_number_length(potential_national_number, metadata)
3007 if validation_result not in (ValidationResult.TOO_SHORT,
3008 ValidationResult.IS_POSSIBLE_LOCAL_ONLY,
3009 ValidationResult.INVALID_LENGTH):
3010 normalized_national_number = potential_national_number
3011 if keep_raw_input and carrier_code is not None and len(carrier_code) > 0:
3012 numobj.preferred_domestic_carrier_code = carrier_code
3013 len_national_number = len(normalized_national_number)
3014 if len_national_number < _MIN_LENGTH_FOR_NSN: # pragma no cover
3015 # Check of _is_viable_phone_number() at the top of this function makes
3016 # this effectively unhittable.
3017 raise NumberParseException(NumberParseException.TOO_SHORT_NSN,
3018 "The string supplied is too short to be a phone number.")
3019 if len_national_number > _MAX_LENGTH_FOR_NSN:
3020 raise NumberParseException(NumberParseException.TOO_LONG,
3021 "The string supplied is too long to be a phone number.")
3022 _set_italian_leading_zeros_for_phone_number(normalized_national_number, numobj)
3023 numobj.national_number = to_long(normalized_national_number)
3024 return numobj
3027def _extract_phone_context(number_to_extract_from, index_of_phone_context):
3028 """Extracts the value of the phone-context parameter of number_to_extract_from where the index of
3029 ";phone-context=" is the parameter index_of_phone_context, following the syntax defined in
3030 RFC3966.
3032 Returns the extracted string (possibly empty), or None if no phone-context parameter is found."""
3033 # If no phone-context parameter is present
3034 if index_of_phone_context == -1:
3035 return None
3037 phone_context_start = index_of_phone_context + len(_RFC3966_PHONE_CONTEXT)
3038 # If phone-context parameter is empty
3039 if phone_context_start >= len(number_to_extract_from):
3040 return U_EMPTY_STRING
3042 phone_context_end = number_to_extract_from.find(';', phone_context_start)
3043 # If phone-context is not the last parameter
3044 if phone_context_end != -1:
3045 return number_to_extract_from[phone_context_start:phone_context_end]
3046 else:
3047 return number_to_extract_from[phone_context_start:]
3050def _is_phone_context_valid(phone_context):
3051 """"Returns whether the value of phoneContext follows the syntax defined in RFC3966."""
3052 if phone_context is None:
3053 return True
3054 if len(phone_context) == 0:
3055 return False
3057 # Does phone-context value match pattern of global-number-digits or domainname
3058 return (fullmatch(_RFC3966_GLOBAL_NUMBER_DIGITS_PATTERN, phone_context) or
3059 fullmatch(_RFC3966_DOMAINNAME_PATTERN, phone_context))
3062def _build_national_number_for_parsing(number):
3063 """Converts number to a form that we can parse and return it if it is
3064 written in RFC3966; otherwise extract a possible number out of it and return it."""
3065 index_of_phone_context = number.find(_RFC3966_PHONE_CONTEXT)
3067 phone_context = _extract_phone_context(number, index_of_phone_context)
3068 if not _is_phone_context_valid(phone_context):
3069 raise NumberParseException(NumberParseException.NOT_A_NUMBER, "The phone-context value is invalid")
3070 if phone_context is not None:
3071 # If the phone context contains a phone number prefix, we need to
3072 # capture it, whereas domains will be ignored.
3073 if phone_context[0] == _PLUS_SIGN:
3074 # Additional parameters might follow the phone context. If so, we
3075 # will remove them here because the parameters after phone context
3076 # are not important for parsing the phone number.
3077 national_number = phone_context
3078 else:
3079 national_number = U_EMPTY_STRING
3081 # Now append everything between the "tel:" prefix and the
3082 # phone-context. This should include the national number, an optional
3083 # extension or isdn-subaddress component. Note we also handle the case
3084 # when "tel:" is missing, as we have seen in some of the phone number
3085 # inputs. In that case we append everything from the beginning.
3086 index_of_rfc3996_prefix = number.find(_RFC3966_PREFIX)
3087 index_of_national_number = ((index_of_rfc3996_prefix + len(_RFC3966_PREFIX))
3088 if (index_of_rfc3996_prefix >= 0) else 0)
3089 national_number += number[index_of_national_number:index_of_phone_context]
3090 else:
3091 # Extract a possible number from the string passed in (this strips leading characters that
3092 # could not be the start of a phone number.)
3093 national_number = _extract_possible_number(number)
3095 # Delete the isdn-subaddress and everything after it if it is
3096 # present. Note extension won't appear at the same time with
3097 # isdn-subaddress according to paragraph 5.3 of the RFC3966 spec,
3098 index_of_isdn = national_number.find(_RFC3966_ISDN_SUBADDRESS)
3099 if index_of_isdn > 0:
3100 national_number = national_number[:index_of_isdn]
3101 # If both phone context and isdn-subaddress are absent but other
3102 # parameters are present, the parameters are left in national_number. This
3103 # is because we are concerned about deleting content from a potential
3104 # number string when there is no strong evidence that the number is
3105 # actually written in RFC3966.
3106 return national_number
3109def _copy_core_fields_only(inobj):
3110 """Returns a new phone number containing only the fields needed to uniquely
3111 identify a phone number, rather than any fields that capture the context in
3112 which the phone number was created.
3113 """
3114 numobj = PhoneNumber()
3115 numobj.country_code = inobj.country_code
3116 numobj.national_number = inobj.national_number
3117 if inobj.extension is not None and len(inobj.extension) > 0:
3118 numobj.extension = inobj.extension
3119 if inobj.italian_leading_zero:
3120 numobj.italian_leading_zero = True
3121 # This field is only relevant if there are leading zeros at all.
3122 numobj.number_of_leading_zeros = inobj.number_of_leading_zeros
3123 if numobj.number_of_leading_zeros is None:
3124 # No number set is implicitly a count of 1; make it explicit.
3125 numobj.number_of_leading_zeros = 1
3126 return numobj
3129def _is_number_match_OO(numobj1_in, numobj2_in):
3130 """Takes two phone number objects and compares them for equality."""
3131 # We only care about the fields that uniquely define a number, so we copy these across explicitly.
3132 numobj1 = _copy_core_fields_only(numobj1_in)
3133 numobj2 = _copy_core_fields_only(numobj2_in)
3135 # Early exit if both had extensions and these are different.
3136 if (numobj1.extension is not None and
3137 numobj2.extension is not None and
3138 numobj1.extension != numobj2.extension):
3139 return MatchType.NO_MATCH
3141 country_code1 = numobj1.country_code
3142 country_code2 = numobj2.country_code
3143 # Both had country_code specified.
3144 if country_code1 != 0 and country_code2 != 0:
3145 if numobj1 == numobj2:
3146 return MatchType.EXACT_MATCH
3147 elif (country_code1 == country_code2 and
3148 _is_national_number_suffix_of_other(numobj1, numobj2)):
3149 # A SHORT_NSN_MATCH occurs if there is a difference because of the
3150 # presence or absence of an 'Italian leading zero', the presence
3151 # or absence of an extension, or one NSN being a shorter variant
3152 # of the other.
3153 return MatchType.SHORT_NSN_MATCH
3154 # This is not a match.
3155 return MatchType.NO_MATCH
3157 # Checks cases where one or both country_code fields were not
3158 # specified. To make equality checks easier, we first set the country_code
3159 # fields to be equal.
3160 numobj1.country_code = country_code2
3161 # If all else was the same, then this is an NSN_MATCH.
3162 if numobj1 == numobj2:
3163 return MatchType.NSN_MATCH
3164 if _is_national_number_suffix_of_other(numobj1, numobj2):
3165 return MatchType.SHORT_NSN_MATCH
3166 return MatchType.NO_MATCH
3169def _is_national_number_suffix_of_other(numobj1, numobj2):
3170 """Returns true when one national number is the suffix of the other or both
3171 are the same.
3172 """
3173 nn1 = str(numobj1.national_number)
3174 nn2 = str(numobj2.national_number)
3175 # Note that endswith returns True if the numbers are equal.
3176 return nn1.endswith(nn2) or nn2.endswith(nn1)
3179def _is_number_match_SS(number1, number2):
3180 """Takes two phone numbers as strings and compares them for equality.
3182 This is a convenience wrapper for _is_number_match_OO/_is_number_match_OS.
3183 No default region is known.
3184 """
3185 try:
3186 numobj1 = parse(number1, UNKNOWN_REGION)
3187 return _is_number_match_OS(numobj1, number2)
3188 except NumberParseException:
3189 _, exc, _ = sys.exc_info()
3190 if exc.error_type == NumberParseException.INVALID_COUNTRY_CODE:
3191 try:
3192 numobj2 = parse(number2, UNKNOWN_REGION)
3193 return _is_number_match_OS(numobj2, number1)
3194 except NumberParseException:
3195 _, exc2, _ = sys.exc_info()
3196 if exc2.error_type == NumberParseException.INVALID_COUNTRY_CODE:
3197 try:
3198 numobj1 = parse(number1, None, keep_raw_input=False,
3199 _check_region=False, numobj=None)
3200 numobj2 = parse(number2, None, keep_raw_input=False,
3201 _check_region=False, numobj=None)
3202 return _is_number_match_OO(numobj1, numobj2)
3203 except NumberParseException:
3204 return MatchType.NOT_A_NUMBER
3206 # One or more of the phone numbers we are trying to match is not a viable
3207 # phone number.
3208 return MatchType.NOT_A_NUMBER
3211def _is_number_match_OS(numobj1, number2):
3212 """Wrapper variant of _is_number_match_OO that copes with one
3213 PhoneNumber object and one string."""
3214 # First see if the second number has an implicit country calling code, by
3215 # attempting to parse it.
3216 try:
3217 numobj2 = parse(number2, UNKNOWN_REGION)
3218 return _is_number_match_OO(numobj1, numobj2)
3219 except NumberParseException:
3220 _, exc, _ = sys.exc_info()
3221 if exc.error_type == NumberParseException.INVALID_COUNTRY_CODE:
3222 # The second number has no country calling code. EXACT_MATCH is no
3223 # longer possible. We parse it as if the region was the same as
3224 # that for the first number, and if EXACT_MATCH is returned, we
3225 # replace this with NSN_MATCH.
3226 region1 = region_code_for_country_code(numobj1.country_code)
3227 try:
3228 if region1 != UNKNOWN_REGION:
3229 numobj2 = parse(number2, region1)
3230 match = _is_number_match_OO(numobj1, numobj2)
3231 if match == MatchType.EXACT_MATCH:
3232 return MatchType.NSN_MATCH
3233 else:
3234 return match
3235 else:
3236 # If the first number didn't have a valid country calling
3237 # code, then we parse the second number without one as
3238 # well.
3239 numobj2 = parse(number2, None, keep_raw_input=False,
3240 _check_region=False, numobj=None)
3241 return _is_number_match_OO(numobj1, numobj2)
3242 except NumberParseException:
3243 return MatchType.NOT_A_NUMBER
3244 # One or more of the phone numbers we are trying to match is not a viable
3245 # phone number.
3246 return MatchType.NOT_A_NUMBER
3249def is_number_match(num1, num2):
3250 """Takes two phone numbers and compares them for equality.
3252 For example, the numbers +1 345 657 1234 and 657 1234 are a SHORT_NSN_MATCH.
3253 The numbers +1 345 657 1234 and 345 657 are a NO_MATCH.
3255 Arguments
3256 num1 -- First number object or string to compare. Can contain formatting,
3257 and can have country calling code specified with + at the start.
3258 num2 -- Second number object or string to compare. Can contain formatting,
3259 and can have country calling code specified with + at the start.
3261 Returns:
3262 - EXACT_MATCH if the country_code, NSN, presence of a leading zero for
3263 Italian numbers and any extension present are the same.
3264 - NSN_MATCH if either or both has no region specified, and the NSNs and
3265 extensions are the same.
3266 - SHORT_NSN_MATCH if either or both has no region specified, or the
3267 region specified is the same, and one NSN could be a shorter version of
3268 the other number. This includes the case where one has an extension
3269 specified, and the other does not.
3270 - NO_MATCH otherwise.
3271 """
3272 if isinstance(num1, PhoneNumber) and isinstance(num2, PhoneNumber):
3273 return _is_number_match_OO(num1, num2)
3274 elif isinstance(num1, PhoneNumber):
3275 return _is_number_match_OS(num1, num2)
3276 elif isinstance(num2, PhoneNumber):
3277 return _is_number_match_OS(num2, num1)
3278 else:
3279 return _is_number_match_SS(num1, num2)
3282def can_be_internationally_dialled(numobj):
3283 """Returns True if the number can only be dialled from outside the region,
3284 or unknown.
3286 If the number can only be dialled from within the region
3287 as well, returns False. Does not check the number is a valid number.
3288 Note that, at the moment, this method does not handle short numbers (which
3289 are currently all presumed to not be diallable from outside their country).
3291 Arguments:
3292 numobj -- the phone number objectfor which we want to know whether it is
3293 diallable from outside the region.
3294 """
3295 metadata = PhoneMetadata.metadata_for_region(region_code_for_number(numobj), None)
3296 if metadata is None:
3297 # Note numbers belonging to non-geographical entities (e.g. +800
3298 # numbers) are always internationally diallable, and will be caught
3299 # here.
3300 return True
3301 nsn = national_significant_number(numobj)
3302 return not _is_number_matching_desc(nsn, metadata.no_international_dialling)
3305def is_mobile_number_portable_region(region_code):
3306 """Returns true if the supplied region supports mobile number portability.
3307 Returns false for invalid, unknown or regions that don't support mobile
3308 number portability.
3310 Arguments:
3311 region_code -- the region for which we want to know whether it supports mobile number
3312 portability or not.
3313 """
3314 metadata = PhoneMetadata.metadata_for_region(region_code, None)
3315 if metadata is None:
3316 return False
3317 return metadata.mobile_number_portable_region
3320class NumberParseException(UnicodeMixin, Exception):
3321 """Exception when attempting to parse a putative phone number"""
3323 # The reason a string could not be interpreted as a phone number.
3325 # The country code supplied did not belong to a supported country or
3326 # non-geographical entity.
3327 INVALID_COUNTRY_CODE = 0
3329 # This generally indicates the string passed in had fewer than 3 digits in
3330 # it. The number failed to match the regular expression
3331 # _VALID_PHONE_NUMBER in phonenumberutil.py.
3333 # This indicates the string passed is not a valid number. Either the string
3334 # had less than 3 digits in it or had an invalid phone-context
3335 # parameter. More specifically, the number failed to match the regular
3336 # expression _VALID_PHONE_NUMBER, )RFC3966_GLOBAL_NUMBER_DIGITS, or
3337 # _RFC3966_DOMAINNAME in phonenumberutil.py.
3338 NOT_A_NUMBER = 1
3340 # This indicates the string started with an international dialing prefix,
3341 # but after this was removed, it had fewer digits than any valid phone
3342 # number (including country code) could have.
3343 TOO_SHORT_AFTER_IDD = 2
3345 # This indicates the string, after any country code has been stripped,
3346 # had fewer digits than any valid phone number could have.
3347 TOO_SHORT_NSN = 3
3349 # This indicates the string had more digits than any valid phone number
3350 # could have
3351 TOO_LONG = 4
3353 def __init__(self, error_type, msg):
3354 Exception.__init__(self, msg)
3355 self.error_type = error_type
3356 self._msg = msg
3358 def __reduce__(self):
3359 return (type(self), (self.error_type, self._msg))
3361 def __unicode__(self):
3362 return unicod("(%s) %s") % (self.error_type, self._msg)
3365def _match_national_number(number, number_desc, allow_prefix_match):
3366 """Returns whether the given national number (a string containing only decimal digits) matches
3367 the national number pattern defined in the given PhoneNumberDesc object.
3368 """
3369 # We don't want to consider it a prefix match when matching non-empty input against an empty
3370 # pattern.
3371 if number_desc is None or number_desc.national_number_pattern is None or len(number_desc.national_number_pattern) == 0:
3372 return False
3373 return _match(number, re.compile(number_desc.national_number_pattern), allow_prefix_match)
3376def _match(number, pattern, allow_prefix_match):
3377 if not pattern.match(number):
3378 return False
3379 else:
3380 if fullmatch(pattern, number):
3381 return True
3382 else:
3383 return allow_prefix_match