Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/phonenumbers/phonenumberutil.py: 64%
1200 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-07 06:30 +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 and numobj.raw_input is not None:
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 # TODO: Consider removing the 'if' above so that unparseable strings
1100 # without raw input format to the empty string instead of "+00".
1101 if len(numobj.raw_input) > 0:
1102 return numobj.raw_input
1103 country_calling_code = numobj.country_code
1104 nsn = national_significant_number(numobj)
1105 if num_format == PhoneNumberFormat.E164:
1106 # Early exit for E164 case (even if the country calling code is
1107 # invalid) since no formatting of the national number needs to be
1108 # applied. Extensions are not formatted.
1109 return _prefix_number_with_country_calling_code(country_calling_code, num_format, nsn)
1110 if not _has_valid_country_calling_code(country_calling_code):
1111 return nsn
1112 # Note region_code_for_country_code() is used because formatting
1113 # information for regions which share a country calling code is contained
1114 # by only one region for performance reasons. For example, for NANPA
1115 # regions it will be contained in the metadata for US.
1116 region_code = region_code_for_country_code(country_calling_code)
1117 # Metadata cannot be None because the country calling code is valid (which
1118 # means that the region code cannot be ZZ and must be one of our supported
1119 # region codes).
1120 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_calling_code, region_code.upper())
1121 formatted_number = _format_nsn(nsn, metadata, num_format)
1122 formatted_number = _maybe_append_formatted_extension(numobj,
1123 metadata,
1124 num_format,
1125 formatted_number)
1126 return _prefix_number_with_country_calling_code(country_calling_code,
1127 num_format,
1128 formatted_number)
1131def format_by_pattern(numobj, number_format, user_defined_formats):
1132 """Formats a phone number using client-defined formatting rules.
1134 Note that if the phone number has a country calling code of zero or an
1135 otherwise invalid country calling code, we cannot work out things like
1136 whether there should be a national prefix applied, or how to format
1137 extensions, so we return the national significant number with no
1138 formatting applied.
1140 Arguments:
1141 numobj -- The phone number to be formatted
1142 number_format -- The format the phone number should be formatted into,
1143 as a PhoneNumberFormat value.
1144 user_defined_formats -- formatting rules specified by clients, as a list
1145 of NumberFormat objects.
1147 Returns the formatted phone number.
1148 """
1149 country_code = numobj.country_code
1150 nsn = national_significant_number(numobj)
1151 if not _has_valid_country_calling_code(country_code):
1152 return nsn
1153 # Note region_code_for_country_code() is used because formatting
1154 # information for regions which share a country calling code is contained
1155 # by only one region for performance reasons. For example, for NANPA
1156 # regions it will be contained in the metadata for US.
1157 region_code = region_code_for_country_code(country_code)
1158 # Metadata cannot be None because the country calling code is valid.
1159 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
1161 formatted_number = U_EMPTY_STRING
1162 formatting_pattern = _choose_formatting_pattern_for_number(user_defined_formats, nsn)
1163 if formatting_pattern is None:
1164 # If no pattern above is matched, we format the number as a whole.
1165 formatted_number = nsn
1166 else:
1167 num_format_copy = _copy_number_format(formatting_pattern)
1168 # Before we do a replacement of the national prefix pattern $NP with
1169 # the national prefix, we need to copy the rule so that subsequent
1170 # replacements for different numbers have the appropriate national
1171 # prefix.
1172 np_formatting_rule = formatting_pattern.national_prefix_formatting_rule
1173 if np_formatting_rule:
1174 national_prefix = metadata.national_prefix
1175 if national_prefix:
1176 # Replace $NP with national prefix and $FG with the first
1177 # group (\1) matcher.
1178 np_formatting_rule = np_formatting_rule.replace(_NP_STRING, national_prefix)
1179 np_formatting_rule = np_formatting_rule.replace(_FG_STRING, unicod("\\1"))
1180 num_format_copy.national_prefix_formatting_rule = np_formatting_rule
1181 else:
1182 # We don't want to have a rule for how to format the national
1183 # prefix if there isn't one.
1184 num_format_copy.national_prefix_formatting_rule = None
1185 formatted_number = _format_nsn_using_pattern(nsn, num_format_copy, number_format)
1186 formatted_number = _maybe_append_formatted_extension(numobj,
1187 metadata,
1188 number_format,
1189 formatted_number)
1190 formatted_number = _prefix_number_with_country_calling_code(country_code,
1191 number_format,
1192 formatted_number)
1193 return formatted_number
1196def format_national_number_with_carrier_code(numobj, carrier_code):
1197 """Format a number in national format for dialing using the specified carrier.
1199 The carrier-code will always be used regardless of whether the phone
1200 number already has a preferred domestic carrier code stored. If
1201 carrier_code contains an empty string, returns the number in national
1202 format without any carrier code.
1204 Arguments:
1205 numobj -- The phone number to be formatted
1206 carrier_code -- The carrier selection code to be used
1208 Returns the formatted phone number in national format for dialing using
1209 the carrier as specified in the carrier_code.
1210 """
1211 country_code = numobj.country_code
1212 nsn = national_significant_number(numobj)
1213 if not _has_valid_country_calling_code(country_code):
1214 return nsn
1215 # Note region_code_for_country_code() is used because formatting
1216 # information for regions which share a country calling code is contained
1217 # by only one region for performance reasons. For example, for NANPA
1218 # regions it will be contained in the metadata for US.
1219 region_code = region_code_for_country_code(country_code)
1220 # Metadata cannot be None because the country calling code is valid
1221 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
1222 formatted_number = _format_nsn(nsn,
1223 metadata,
1224 PhoneNumberFormat.NATIONAL,
1225 carrier_code)
1226 formatted_number = _maybe_append_formatted_extension(numobj,
1227 metadata,
1228 PhoneNumberFormat.NATIONAL,
1229 formatted_number)
1230 formatted_number = _prefix_number_with_country_calling_code(country_code,
1231 PhoneNumberFormat.NATIONAL,
1232 formatted_number)
1233 return formatted_number
1236def format_national_number_with_preferred_carrier_code(numobj, fallback_carrier_code):
1237 """Formats a phone number in national format for dialing using the carrier
1238 as specified in the preferred_domestic_carrier_code field of the
1239 PhoneNumber object passed in. If that is missing, use the
1240 fallback_carrier_code passed in instead. If there is no
1241 preferred_domestic_carrier_code, and the fallback_carrier_code contains an
1242 empty string, return the number in national format without any carrier
1243 code.
1245 Use format_national_number_with_carrier_code instead if the carrier code
1246 passed in should take precedence over the number's
1247 preferred_domestic_carrier_code when formatting.
1249 Arguments:
1250 numobj -- The phone number to be formatted
1251 carrier_code -- The carrier selection code to be used, if none is found in the
1252 phone number itself.
1254 Returns the formatted phone number in national format for dialing using
1255 the number's preferred_domestic_carrier_code, or the fallback_carrier_code
1256 pass in if none is found.
1257 """
1258 # Historically, we set this to an empty string when parsing with raw input
1259 # if none was found in the input string. However, this doesn't result in a
1260 # number we can dial. For this reason, we treat the empty string the same
1261 # as if it isn't set at all.
1262 if (numobj.preferred_domestic_carrier_code is not None and
1263 len(numobj.preferred_domestic_carrier_code) > 0):
1264 carrier_code = numobj.preferred_domestic_carrier_code
1265 else:
1266 carrier_code = fallback_carrier_code
1267 return format_national_number_with_carrier_code(numobj, carrier_code)
1270def format_number_for_mobile_dialing(numobj, region_calling_from, with_formatting):
1271 """Returns a number formatted in such a way that it can be dialed from a
1272 mobile phone in a specific region.
1274 If the number cannot be reached from the region (e.g. some countries block
1275 toll-free numbers from being called outside of the country), the method
1276 returns an empty string.
1278 Arguments:
1279 numobj -- The phone number to be formatted
1280 region_calling_from -- The region where the call is being placed.
1282 with_formatting -- whether the number should be returned with formatting
1283 symbols, such as spaces and dashes.
1285 Returns the formatted phone number.
1286 """
1287 country_calling_code = numobj.country_code
1288 if not _has_valid_country_calling_code(country_calling_code):
1289 if numobj.raw_input is None:
1290 return U_EMPTY_STRING
1291 else:
1292 return numobj.raw_input
1293 formatted_number = U_EMPTY_STRING
1294 # Clear the extension, as that part cannot normally be dialed together with the main number.
1295 numobj_no_ext = PhoneNumber()
1296 numobj_no_ext.merge_from(numobj)
1297 numobj_no_ext.extension = None
1298 region_code = region_code_for_country_code(country_calling_code)
1299 numobj_type = number_type(numobj_no_ext)
1300 is_valid_number = (numobj_type != PhoneNumberType.UNKNOWN)
1301 if region_calling_from == region_code:
1302 is_fixed_line_or_mobile = ((numobj_type == PhoneNumberType.FIXED_LINE) or
1303 (numobj_type == PhoneNumberType.MOBILE) or
1304 (numobj_type == PhoneNumberType.FIXED_LINE_OR_MOBILE))
1305 # Carrier codes may be needed in some countries. We handle this here.
1306 if region_code == "BR" and is_fixed_line_or_mobile:
1307 # Historically, we set this to an empty string when parsing with
1308 # raw input if none was found in the input string. However, this
1309 # doesn't result in a number we can dial. For this reason, we
1310 # treat the empty string the same as if it isn't set at all.
1311 if (numobj_no_ext.preferred_domestic_carrier_code is not None and
1312 len(numobj_no_ext.preferred_domestic_carrier_code) > 0):
1313 formatted_number = format_national_number_with_preferred_carrier_code(numobj_no_ext, "")
1314 else:
1315 # Brazilian fixed line and mobile numbers need to be dialed with a
1316 # carrier code when called within Brazil. Without that, most of
1317 # the carriers won't connect the call. Because of that, we return
1318 # an empty string here.
1319 formatted_number = U_EMPTY_STRING
1320 elif country_calling_code == _NANPA_COUNTRY_CODE:
1321 # For NANPA countries, we output international format for numbers
1322 # that can be dialed internationally, since that always works,
1323 # except for numbers which might potentially be short numbers,
1324 # which are always dialled in national format.
1325 metadata = PhoneMetadata.metadata_for_region(region_calling_from)
1326 assert metadata is not None # due to _has_valid_country_calling_code() check
1327 if (can_be_internationally_dialled(numobj_no_ext) and
1328 _test_number_length(national_significant_number(numobj_no_ext),
1329 metadata) != ValidationResult.TOO_SHORT):
1330 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL)
1331 else:
1332 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL)
1333 else:
1334 # For non-geographical countries, and Mexican, Chilean, and Uzbek
1335 # fixed line and mobile numbers, we output international format for
1336 # numbers that can be dialed internationally as that always works.
1337 if ((region_code == REGION_CODE_FOR_NON_GEO_ENTITY or
1338 ((region_code == unicod("MX") or region_code == unicod("CL") or
1339 region_code == unicod("UZ")) and
1340 is_fixed_line_or_mobile)) and
1341 can_be_internationally_dialled(numobj_no_ext)):
1342 # MX fixed line and mobile numbers should always be formatted
1343 # in international format, even when dialed within MX. For
1344 # national format to work, a carrier code needs to be used,
1345 # and the correct carrier code depends on if the caller and
1346 # callee are from the same local area. It is trickier to get
1347 # that to work correctly than using international format,
1348 # which is tested to work fine on all carriers.
1349 # CL fixed line numbers need the national prefix when dialing
1350 # in the national format, but don't have it when used for
1351 # display. The reverse is true for mobile numbers. As a
1352 # result, we output them in the international format to make
1353 # it work.
1354 # UZ mobile and fixed-line numbers have to be formatted in
1355 # international format or prefixed with special codes like 03,
1356 # 04 (for fixed-line) and 05 (for mobile) for dialling
1357 # successfully from mobile devices. As we do not have complete
1358 # information on special codes and to be consistent with
1359 # formatting across all phone types we return the number in
1360 # international format here.
1361 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL)
1362 else:
1363 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL)
1364 elif is_valid_number and can_be_internationally_dialled(numobj_no_ext):
1365 # We assume that short numbers are not diallable from outside their
1366 # region, so if a number is not a valid regular length phone number,
1367 # we treat it as if it cannot be internationally dialled.
1368 if with_formatting:
1369 return format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL)
1370 else:
1371 return format_number(numobj_no_ext, PhoneNumberFormat.E164)
1373 if with_formatting:
1374 return formatted_number
1375 else:
1376 return normalize_diallable_chars_only(formatted_number)
1379def format_out_of_country_calling_number(numobj, region_calling_from):
1380 """Formats a phone number for out-of-country dialing purposes.
1382 If no region_calling_from is supplied, we format the number in its
1383 INTERNATIONAL format. If the country calling code is the same as that of
1384 the region where the number is from, then NATIONAL formatting will be
1385 applied.
1387 If the number itself has a country calling code of zero or an otherwise
1388 invalid country calling code, then we return the number with no formatting
1389 applied.
1391 Note this function takes care of the case for calling inside of NANPA and
1392 between Russia and Kazakhstan (who share the same country calling
1393 code). In those cases, no international prefix is used. For regions which
1394 have multiple international prefixes, the number in its INTERNATIONAL
1395 format will be returned instead.
1397 Arguments:
1398 numobj -- The phone number to be formatted
1399 region_calling_from -- The region where the call is being placed
1401 Returns the formatted phone number
1402 """
1403 if not _is_valid_region_code(region_calling_from):
1404 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL)
1405 country_code = numobj.country_code
1406 nsn = national_significant_number(numobj)
1407 if not _has_valid_country_calling_code(country_code):
1408 return nsn
1409 if country_code == _NANPA_COUNTRY_CODE:
1410 if is_nanpa_country(region_calling_from):
1411 # For NANPA regions, return the national format for these regions
1412 # but prefix it with the country calling code.
1413 return (unicod(country_code) + U_SPACE +
1414 format_number(numobj, PhoneNumberFormat.NATIONAL))
1415 elif country_code == country_code_for_valid_region(region_calling_from):
1416 # If regions share a country calling code, the country calling code
1417 # need not be dialled. This also applies when dialling within a
1418 # region, so this if clause covers both these cases. Technically this
1419 # is the case for dialling from La Reunion to other overseas
1420 # departments of France (French Guiana, Martinique, Guadeloupe), but
1421 # not vice versa - so we don't cover this edge case for now and for
1422 # those cases return the version including country calling code.
1423 # Details here:
1424 # http://www.petitfute.com/voyage/225-info-pratiques-reunion
1425 return format_number(numobj, PhoneNumberFormat.NATIONAL)
1427 # Metadata cannot be None because we checked '_is_valid_region_code()' above.
1428 metadata_for_region_calling_from = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_calling_from.upper())
1429 international_prefix = metadata_for_region_calling_from.international_prefix
1431 # In general, if there is a preferred international prefix, use that. Otherwise, for regions
1432 # that have multiple international prefixes, the international format of the number is
1433 # returned since we would not know which one to use.
1434 i18n_prefix_for_formatting = U_EMPTY_STRING
1435 if metadata_for_region_calling_from.preferred_international_prefix is not None:
1436 i18n_prefix_for_formatting = metadata_for_region_calling_from.preferred_international_prefix
1437 elif fullmatch(_SINGLE_INTERNATIONAL_PREFIX, international_prefix):
1438 i18n_prefix_for_formatting = international_prefix
1440 region_code = region_code_for_country_code(country_code)
1441 # Metadata cannot be None because the country calling code is valid.
1442 metadata_for_region = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code.upper())
1443 formatted_national_number = _format_nsn(nsn,
1444 metadata_for_region,
1445 PhoneNumberFormat.INTERNATIONAL)
1446 formatted_number = _maybe_append_formatted_extension(numobj,
1447 metadata_for_region,
1448 PhoneNumberFormat.INTERNATIONAL,
1449 formatted_national_number)
1450 if len(i18n_prefix_for_formatting) > 0:
1451 formatted_number = (i18n_prefix_for_formatting + U_SPACE +
1452 unicod(country_code) + U_SPACE + formatted_number)
1453 else:
1454 formatted_number = _prefix_number_with_country_calling_code(country_code,
1455 PhoneNumberFormat.INTERNATIONAL,
1456 formatted_number)
1457 return formatted_number
1460def format_in_original_format(numobj, region_calling_from):
1461 """Formats a phone number using the original phone number format
1462 (e.g. INTERNATIONAL or NATIONAL) that the number is parsed from, provided
1463 that the number has been parsed with parse(.., keep_raw_input=True).
1464 Otherwise the number will be formatted in NATIONAL format.
1466 The original format is embedded in the country_code_source field of the
1467 PhoneNumber object passed in, which is only set when parsing keeps the raw
1468 input. When we don't have a formatting pattern for the number, the method
1469 falls back to returning the raw input.
1471 Note this method guarantees no digit will be inserted, removed or modified
1472 as a result of formatting.
1474 Arguments:
1475 number -- The phone number that needs to be formatted in its original
1476 number format
1477 region_calling_from -- The region whose IDD needs to be prefixed if the
1478 original number has one.
1480 Returns the formatted phone number in its original number format.
1481 """
1482 if (numobj.raw_input is not None and not _has_formatting_pattern_for_number(numobj)):
1483 # We check if we have the formatting pattern because without that, we
1484 # might format the number as a group without national prefix.
1485 return numobj.raw_input
1486 if numobj.country_code_source is CountryCodeSource.UNSPECIFIED:
1487 return format_number(numobj, PhoneNumberFormat.NATIONAL)
1489 formatted_number = _format_original_allow_mods(numobj, region_calling_from)
1490 num_raw_input = numobj.raw_input
1491 # If no digit is inserted/removed/modified as a result of our formatting,
1492 # we return the formatted phone number; otherwise we return the raw input
1493 # the user entered.
1494 if (formatted_number is not None and num_raw_input):
1495 normalized_formatted_number = normalize_diallable_chars_only(formatted_number)
1496 normalized_raw_input = normalize_diallable_chars_only(num_raw_input)
1497 if normalized_formatted_number != normalized_raw_input:
1498 formatted_number = num_raw_input
1499 return formatted_number
1502def _format_original_allow_mods(numobj, region_calling_from):
1503 if (numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN):
1504 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL)
1505 elif numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITH_IDD:
1506 return format_out_of_country_calling_number(numobj, region_calling_from)
1507 elif (numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITHOUT_PLUS_SIGN):
1508 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL)[1:]
1509 else:
1510 region_code = region_code_for_country_code(numobj.country_code)
1511 # We strip non-digits from the NDD here, and from the raw input later, so that we can
1512 # compare them easily.
1513 national_prefix = ndd_prefix_for_region(region_code, True) # strip non-digits
1514 national_format = format_number(numobj, PhoneNumberFormat.NATIONAL)
1515 if (national_prefix is None or len(national_prefix) == 0):
1516 # If the region doesn't have a national prefix at all, we can
1517 # safely return the national format without worrying about a
1518 # national prefix being added.
1519 return national_format
1520 # Otherwise, we check if the original number was entered with a national prefix.
1521 if (_raw_input_contains_national_prefix(numobj.raw_input, national_prefix, region_code)):
1522 # If so, we can safely return the national format.
1523 return national_format
1524 # Metadata cannot be None here because ndd_prefix_for_region() (above) returns None if
1525 # there is no metadata for the region.
1526 metadata = PhoneMetadata.metadata_for_region(region_code)
1527 assert metadata is not None
1528 national_number = national_significant_number(numobj)
1529 format_rule = _choose_formatting_pattern_for_number(metadata.number_format, national_number)
1530 # The format rule could still be null here if the national number was
1531 # 0 and there was no raw input (this should not be possible for
1532 # numbers generated by the phonenumber library as they would also not
1533 # have a country calling code and we would have exited earlier).
1534 if format_rule is None:
1535 return national_format
1536 # When the format we apply to this number doesn't contain national
1537 # prefix, we can just return the national format.
1538 # TODO: Refactor the code below with the code in isNationalPrefixPresentIfRequired.
1539 candidate_national_prefix_rule = format_rule.national_prefix_formatting_rule
1540 # We assume that the first-group symbol will never be _before_ the national prefix.
1541 if candidate_national_prefix_rule is None:
1542 return national_format
1543 index_of_first_group = candidate_national_prefix_rule.find("\\1")
1544 if (index_of_first_group <= 0):
1545 return national_format
1546 candidate_national_prefix_rule = candidate_national_prefix_rule[:index_of_first_group]
1547 candidate_national_prefix_rule = normalize_digits_only(candidate_national_prefix_rule)
1548 if len(candidate_national_prefix_rule) == 0:
1549 # National prefix not used when formatting this number.
1550 return national_format
1551 # Otherwise, we need to remove the national prefix from our output.
1552 new_format_rule = _copy_number_format(format_rule)
1553 new_format_rule.national_prefix_formatting_rule = None
1554 return format_by_pattern(numobj, PhoneNumberFormat.NATIONAL, [new_format_rule])
1557def _raw_input_contains_national_prefix(raw_input, national_prefix, region_code):
1558 """Check if raw_input, which is assumed to be in the national format, has a
1559 national prefix. The national prefix is assumed to be in digits-only
1560 form."""
1561 nnn = normalize_digits_only(raw_input)
1562 if nnn.startswith(national_prefix):
1563 try:
1564 # Some Japanese numbers (e.g. 00777123) might be mistaken to
1565 # contain the national prefix when written without it
1566 # (e.g. 0777123) if we just do prefix matching. To tackle that, we
1567 # check the validity of the number if the assumed national prefix
1568 # is removed (777123 won't be valid in Japan).
1569 return is_valid_number(parse(nnn[len(national_prefix):], region_code))
1570 except NumberParseException:
1571 return False
1572 return False
1575def _has_formatting_pattern_for_number(numobj):
1576 country_code = numobj.country_code
1577 phone_number_region = region_code_for_country_code(country_code)
1578 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, phone_number_region)
1579 if metadata is None:
1580 return False
1581 national_number = national_significant_number(numobj)
1582 format_rule = _choose_formatting_pattern_for_number(metadata.number_format, national_number)
1583 return format_rule is not None
1586def format_out_of_country_keeping_alpha_chars(numobj, region_calling_from):
1587 """Formats a phone number for out-of-country dialing purposes.
1589 Note that in this version, if the number was entered originally using
1590 alpha characters and this version of the number is stored in raw_input,
1591 this representation of the number will be used rather than the digit
1592 representation. Grouping information, as specified by characters such as
1593 "-" and " ", will be retained.
1595 Caveats:
1597 - This will not produce good results if the country calling code is both
1598 present in the raw input _and_ is the start of the national
1599 number. This is not a problem in the regions which typically use alpha
1600 numbers.
1602 - This will also not produce good results if the raw input has any
1603 grouping information within the first three digits of the national
1604 number, and if the function needs to strip preceding digits/words in
1605 the raw input before these digits. Normally people group the first
1606 three digits together so this is not a huge problem - and will be fixed
1607 if it proves to be so.
1609 Arguments:
1610 numobj -- The phone number that needs to be formatted.
1611 region_calling_from -- The region where the call is being placed.
1613 Returns the formatted phone number
1614 """
1615 num_raw_input = numobj.raw_input
1616 # If there is no raw input, then we can't keep alpha characters because there aren't any.
1617 # In this case, we return format_out_of_country_calling_number.
1618 if num_raw_input is None or len(num_raw_input) == 0:
1619 return format_out_of_country_calling_number(numobj, region_calling_from)
1620 country_code = numobj.country_code
1621 if not _has_valid_country_calling_code(country_code):
1622 return num_raw_input
1623 # Strip any prefix such as country calling code, IDD, that was present. We
1624 # do this by comparing the number in raw_input with the parsed number. To
1625 # do this, first we normalize punctuation. We retain number grouping
1626 # symbols such as " " only.
1627 num_raw_input = _normalize_helper(num_raw_input,
1628 _ALL_PLUS_NUMBER_GROUPING_SYMBOLS,
1629 True)
1630 # Now we trim everything before the first three digits in the parsed
1631 # number. We choose three because all valid alpha numbers have 3 digits at
1632 # the start - if it does not, then we don't trim anything at
1633 # all. Similarly, if the national number was less than three digits, we
1634 # don't trim anything at all.
1635 national_number = national_significant_number(numobj)
1636 if len(national_number) > 3:
1637 first_national_number_digit = num_raw_input.find(national_number[:3])
1638 if first_national_number_digit != -1:
1639 num_raw_input = num_raw_input[first_national_number_digit:]
1641 metadata_for_region_calling_from = PhoneMetadata.metadata_for_region(region_calling_from.upper(), None)
1642 if country_code == _NANPA_COUNTRY_CODE:
1643 if is_nanpa_country(region_calling_from):
1644 return unicod(country_code) + U_SPACE + num_raw_input
1645 elif (metadata_for_region_calling_from is not None and
1646 country_code == country_code_for_region(region_calling_from)):
1647 formatting_pattern = _choose_formatting_pattern_for_number(metadata_for_region_calling_from.number_format,
1648 national_number)
1649 if formatting_pattern is None:
1650 # If no pattern above is matched, we format the original input
1651 return num_raw_input
1652 new_format = _copy_number_format(formatting_pattern)
1653 # The first group is the first group of digits that the user
1654 # wrote together.
1655 new_format.pattern = u("(\\d+)(.*)")
1656 # Here we just concatenate them back together after the national
1657 # prefix has been fixed.
1658 new_format.format = u(r"\1\2")
1659 # Now we format using this pattern instead of the default pattern,
1660 # but with the national prefix prefixed if necessary.
1661 # This will not work in the cases where the pattern (and not the
1662 # leading digits) decide whether a national prefix needs to be used,
1663 # since we have overridden the pattern to match anything, but that is
1664 # not the case in the metadata to date.
1665 return _format_nsn_using_pattern(num_raw_input,
1666 new_format,
1667 PhoneNumberFormat.NATIONAL)
1668 i18n_prefix_for_formatting = U_EMPTY_STRING
1669 # If an unsupported region-calling-from is entered, or a country with
1670 # multiple international prefixes, the international format of the number
1671 # is returned, unless there is a preferred international prefix.
1672 if metadata_for_region_calling_from is not None:
1673 international_prefix = metadata_for_region_calling_from.international_prefix
1674 i18n_match = fullmatch(_SINGLE_INTERNATIONAL_PREFIX, international_prefix)
1675 if i18n_match:
1676 i18n_prefix_for_formatting = international_prefix
1677 else:
1678 i18n_prefix_for_formatting = metadata_for_region_calling_from.preferred_international_prefix
1680 region_code = region_code_for_country_code(country_code)
1681 # Metadata cannot be None because the country calling code is valid.
1682 metadata_for_region = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
1683 formatted_number = _maybe_append_formatted_extension(numobj,
1684 metadata_for_region,
1685 PhoneNumberFormat.INTERNATIONAL,
1686 num_raw_input)
1687 if i18n_prefix_for_formatting:
1688 formatted_number = (i18n_prefix_for_formatting + U_SPACE +
1689 unicod(country_code) + U_SPACE + formatted_number)
1690 else:
1691 # Invalid region entered as country-calling-from (so no metadata was
1692 # found for it) or the region chosen has multiple international
1693 # dialling prefixes.
1694 formatted_number = _prefix_number_with_country_calling_code(country_code,
1695 PhoneNumberFormat.INTERNATIONAL,
1696 formatted_number)
1697 return formatted_number
1700def national_significant_number(numobj):
1701 """Gets the national significant number of a phone number.
1703 Note that a national significant number doesn't contain a national prefix
1704 or any formatting.
1706 Arguments:
1707 numobj -- The PhoneNumber object for which the national significant number
1708 is needed.
1710 Returns the national significant number of the PhoneNumber object passed
1711 in.
1712 """
1713 # If leading zero(s) have been set, we prefix this now. Note this is not a
1714 # national prefix.
1715 national_number = U_EMPTY_STRING
1716 if numobj.italian_leading_zero:
1717 num_zeros = numobj.number_of_leading_zeros
1718 if num_zeros is None:
1719 num_zeros = 1
1720 if num_zeros > 0:
1721 national_number = U_ZERO * num_zeros
1722 national_number += str(numobj.national_number)
1723 return national_number
1726def _prefix_number_with_country_calling_code(country_code, num_format, formatted_number):
1727 """A helper function that is used by format_number and format_by_pattern."""
1728 if num_format == PhoneNumberFormat.E164:
1729 return _PLUS_SIGN + unicod(country_code) + formatted_number
1730 elif num_format == PhoneNumberFormat.INTERNATIONAL:
1731 return _PLUS_SIGN + unicod(country_code) + U_SPACE + formatted_number
1732 elif num_format == PhoneNumberFormat.RFC3966:
1733 return _RFC3966_PREFIX + _PLUS_SIGN + unicod(country_code) + U_DASH + formatted_number
1734 else:
1735 return formatted_number
1738def _format_nsn(number, metadata, num_format, carrier_code=None):
1739 """Format a national number."""
1740 # Note in some regions, the national number can be written in two
1741 # completely different ways depending on whether it forms part of the
1742 # NATIONAL format or INTERNATIONAL format. The num_format parameter here
1743 # is used to specify which format to use for those cases. If a carrier_code
1744 # is specified, this will be inserted into the formatted string to replace
1745 # $CC.
1746 intl_number_formats = metadata.intl_number_format
1748 # When the intl_number_formats exists, we use that to format national
1749 # number for the INTERNATIONAL format instead of using the
1750 # number_desc.number_formats.
1751 if (len(intl_number_formats) == 0 or
1752 num_format == PhoneNumberFormat.NATIONAL):
1753 available_formats = metadata.number_format
1754 else:
1755 available_formats = metadata.intl_number_format
1756 formatting_pattern = _choose_formatting_pattern_for_number(available_formats, number)
1757 if formatting_pattern is None:
1758 return number
1759 else:
1760 return _format_nsn_using_pattern(number, formatting_pattern, num_format, carrier_code)
1763def _choose_formatting_pattern_for_number(available_formats, national_number):
1764 for num_format in available_formats:
1765 size = len(num_format.leading_digits_pattern)
1766 # We always use the last leading_digits_pattern, as it is the most detailed.
1767 if size > 0:
1768 ld_pattern = re.compile(num_format.leading_digits_pattern[-1])
1769 ld_match = ld_pattern.match(national_number)
1770 if size == 0 or ld_match:
1771 format_pattern = re.compile(num_format.pattern)
1772 if fullmatch(format_pattern, national_number):
1773 return num_format
1774 return None
1777def _format_nsn_using_pattern(national_number, formatting_pattern, number_format,
1778 carrier_code=None):
1779 # Note that carrier_code is optional - if None or an empty string, no
1780 # carrier code replacement will take place.
1781 number_format_rule = formatting_pattern.format
1782 m_re = re.compile(formatting_pattern.pattern)
1783 formatted_national_number = U_EMPTY_STRING
1785 if (number_format == PhoneNumberFormat.NATIONAL and carrier_code and
1786 formatting_pattern.domestic_carrier_code_formatting_rule):
1787 # Replace the $CC in the formatting rule with the desired
1788 # carrier code.
1789 cc_format_rule = formatting_pattern.domestic_carrier_code_formatting_rule
1790 cc_format_rule = cc_format_rule.replace(_CC_STRING, carrier_code)
1792 # Now replace the $FG in the formatting rule with the
1793 # first group and the carrier code combined in the
1794 # appropriate way.
1795 number_format_rule = re.sub(_FIRST_GROUP_PATTERN,
1796 cc_format_rule,
1797 number_format_rule,
1798 count=1)
1799 formatted_national_number = re.sub(m_re, number_format_rule, national_number)
1800 else:
1801 # Use the national prefix formatting rule instead.
1802 national_prefix_formatting_rule = formatting_pattern.national_prefix_formatting_rule
1803 if (number_format == PhoneNumberFormat.NATIONAL and
1804 national_prefix_formatting_rule):
1805 first_group_rule = re.sub(_FIRST_GROUP_PATTERN,
1806 national_prefix_formatting_rule,
1807 number_format_rule,
1808 count=1)
1809 formatted_national_number = re.sub(m_re, first_group_rule, national_number)
1810 else:
1811 formatted_national_number = re.sub(m_re, number_format_rule, national_number)
1813 if number_format == PhoneNumberFormat.RFC3966:
1814 # Strip any leading punctuation.
1815 m = _SEPARATOR_PATTERN.match(formatted_national_number)
1816 if m:
1817 formatted_national_number = re.sub(_SEPARATOR_PATTERN, U_EMPTY_STRING, formatted_national_number, count=1)
1818 # Replace the rest with a dash between each number group
1819 formatted_national_number = re.sub(_SEPARATOR_PATTERN, U_DASH, formatted_national_number)
1821 return formatted_national_number
1824def example_number(region_code):
1825 """Gets a valid number for the specified region.
1827 Arguments:
1828 region_code -- The region for which an example number is needed.
1830 Returns a valid fixed-line number for the specified region. Returns None
1831 when the metadata does not contain such information, or the region 001 is
1832 passed in. For 001 (representing non-geographical numbers), call
1833 example_number_for_non_geo_entity instead.
1834 """
1835 return example_number_for_type(region_code, PhoneNumberType.FIXED_LINE)
1838def invalid_example_number(region_code):
1839 """Gets an invalid number for the specified region.
1841 This is useful for unit-testing purposes, where you want to test what
1842 will happen with an invalid number. Note that the number that is
1843 returned will always be able to be parsed and will have the correct
1844 country code. It may also be a valid *short* number/code for this
1845 region. Validity checking such numbers is handled with shortnumberinfo.
1847 Arguments:
1848 region_code -- The region for which an example number is needed.
1851 Returns an invalid number for the specified region. Returns None when an
1852 unsupported region or the region 001 (Earth) is passed in.
1853 """
1854 if not _is_valid_region_code(region_code):
1855 return None
1856 # We start off with a valid fixed-line number since every country
1857 # supports this. Alternatively we could start with a different number
1858 # type, since fixed-line numbers typically have a wide breadth of valid
1859 # number lengths and we may have to make it very short before we get an
1860 # invalid number.
1861 metadata = PhoneMetadata.metadata_for_region(region_code.upper())
1862 assert metadata is not None # due to _is_valid_region_code() check
1863 desc = _number_desc_by_type(metadata, PhoneNumberType.FIXED_LINE)
1864 if desc is None or desc.example_number is None:
1865 # This shouldn't happen; we have a test for this.
1866 return None # pragma no cover
1867 example_number = desc.example_number
1868 # Try and make the number invalid. We do this by changing the length. We
1869 # try reducing the length of the number, since currently no region has a
1870 # number that is the same length as MIN_LENGTH_FOR_NSN. This is probably
1871 # quicker than making the number longer, which is another
1872 # alternative. We could also use the possible number pattern to extract
1873 # the possible lengths of the number to make this faster, but this
1874 # method is only for unit-testing so simplicity is preferred to
1875 # performance. We don't want to return a number that can't be parsed,
1876 # so we check the number is long enough. We try all possible lengths
1877 # because phone number plans often have overlapping prefixes so the
1878 # number 123456 might be valid as a fixed-line number, and 12345 as a
1879 # mobile number. It would be faster to loop in a different order, but we
1880 # prefer numbers that look closer to real numbers (and it gives us a
1881 # variety of different lengths for the resulting phone numbers -
1882 # otherwise they would all be MIN_LENGTH_FOR_NSN digits long.)
1883 phone_number_length = len(example_number) - 1
1884 while phone_number_length >= _MIN_LENGTH_FOR_NSN:
1885 number_to_try = example_number[:phone_number_length]
1886 try:
1887 possibly_valid_number = parse(number_to_try, region_code)
1888 if not is_valid_number(possibly_valid_number):
1889 return possibly_valid_number
1890 except NumberParseException: # pragma no cover
1891 # Shouldn't happen: we have already checked the length, we know
1892 # example numbers have only valid digits, and we know the region
1893 # code is fine.
1894 pass
1895 phone_number_length -= 1
1897 # We have a test to check that this doesn't happen for any of our
1898 # supported regions.
1899 return None # pragma no cover
1902def example_number_for_type(region_code, num_type):
1903 """Gets a valid number for the specified region and number type.
1905 If None is given as the region_code, then the returned number object
1906 may belong to any country.
1908 Arguments:
1909 region_code -- The region for which an example number is needed, or None.
1910 num_type -- The type of number that is needed.
1912 Returns a valid number for the specified region and type. Returns None
1913 when the metadata does not contain such information or if an invalid
1914 region or region 001 was specified. For 001 (representing
1915 non-geographical numbers), call example_number_for_non_geo_entity instead.
1916 """
1917 if region_code is None:
1918 return _example_number_anywhere_for_type(num_type)
1919 # Check the region code is valid.
1920 if not _is_valid_region_code(region_code):
1921 return None
1922 metadata = PhoneMetadata.metadata_for_region(region_code.upper())
1923 assert metadata is not None # due to _is_valid_region_code() check
1924 desc = _number_desc_by_type(metadata, num_type)
1925 if desc is not None and desc.example_number is not None:
1926 try:
1927 return parse(desc.example_number, region_code)
1928 except NumberParseException: # pragma no cover
1929 pass
1930 return None
1933def _example_number_anywhere_for_type(num_type):
1934 """Gets a valid number for the specified number type (it may belong to any country).
1936 Arguments:
1937 num_type -- The type of number that is needed.
1939 Returns a valid number for the specified type. Returns None when the
1940 metadata does not contain such information. This should only happen when
1941 no numbers of this type are allocated anywhere in the world anymore.
1942 """
1943 for region_code in SUPPORTED_REGIONS:
1944 example_numobj = example_number_for_type(region_code, num_type)
1945 if example_numobj is not None:
1946 return example_numobj
1947 # If there wasn't an example number for a region, try the non-geographical entities.
1948 for country_calling_code in COUNTRY_CODES_FOR_NON_GEO_REGIONS:
1949 metadata = PhoneMetadata.metadata_for_nongeo_region(country_calling_code, None)
1950 desc = _number_desc_by_type(metadata, num_type)
1951 if desc is not None and desc.example_number is not None:
1952 try:
1953 return parse(_PLUS_SIGN + unicod(country_calling_code) + desc.example_number, UNKNOWN_REGION)
1954 except NumberParseException: # pragma no cover
1955 pass
1957 # There are no example numbers of this type for any country in the library.
1958 return None # pragma no cover
1961def example_number_for_non_geo_entity(country_calling_code):
1962 """Gets a valid number for the specified country calling code for a non-geographical entity.
1964 Arguments:
1965 country_calling_code -- The country calling code for a non-geographical entity.
1967 Returns a valid number for the non-geographical entity. Returns None when
1968 the metadata does not contain such information, or the country calling
1969 code passed in does not belong to a non-geographical entity.
1970 """
1971 metadata = PhoneMetadata.metadata_for_nongeo_region(country_calling_code, None)
1972 if metadata is not None:
1973 # For geographical entities, fixed-line data is always present. However, for non-geographical
1974 # entities, this is not the case, so we have to go through different types to find the
1975 # example number. We don't check fixed-line or personal number since they aren't used by
1976 # non-geographical entities (if this changes, a unit-test will catch this.)
1977 for desc in (metadata.mobile, metadata.toll_free, metadata.shared_cost, metadata.voip,
1978 metadata.voicemail, metadata.uan, metadata.premium_rate):
1979 try:
1980 if (desc is not None and desc.example_number is not None):
1981 return parse(_PLUS_SIGN + unicod(country_calling_code) + desc.example_number, UNKNOWN_REGION)
1982 except NumberParseException:
1983 pass
1984 return None
1987def _maybe_append_formatted_extension(numobj, metadata, num_format, number):
1988 """Appends the formatted extension of a phone number to formatted number,
1989 if the phone number had an extension specified.
1990 """
1991 if numobj.extension:
1992 if num_format == PhoneNumberFormat.RFC3966:
1993 return number + _RFC3966_EXTN_PREFIX + numobj.extension
1994 else:
1995 if metadata.preferred_extn_prefix is not None:
1996 return number + metadata.preferred_extn_prefix + numobj.extension
1997 else:
1998 return number + _DEFAULT_EXTN_PREFIX + numobj.extension
1999 return number
2002def _number_desc_by_type(metadata, num_type):
2003 """Return the PhoneNumberDesc of the metadata for the given number type"""
2004 if num_type == PhoneNumberType.PREMIUM_RATE:
2005 return metadata.premium_rate
2006 elif num_type == PhoneNumberType.TOLL_FREE:
2007 return metadata.toll_free
2008 elif num_type == PhoneNumberType.MOBILE:
2009 return metadata.mobile
2010 elif (num_type == PhoneNumberType.FIXED_LINE or
2011 num_type == PhoneNumberType.FIXED_LINE_OR_MOBILE):
2012 return metadata.fixed_line
2013 elif num_type == PhoneNumberType.SHARED_COST:
2014 return metadata.shared_cost
2015 elif num_type == PhoneNumberType.VOIP:
2016 return metadata.voip
2017 elif num_type == PhoneNumberType.PERSONAL_NUMBER:
2018 return metadata.personal_number
2019 elif num_type == PhoneNumberType.PAGER:
2020 return metadata.pager
2021 elif num_type == PhoneNumberType.UAN:
2022 return metadata.uan
2023 elif num_type == PhoneNumberType.VOICEMAIL:
2024 return metadata.voicemail
2025 else:
2026 return metadata.general_desc
2029def number_type(numobj):
2030 """Gets the type of a valid phone number.
2032 Arguments:
2033 numobj -- The PhoneNumber object that we want to know the type of.
2035 Returns the type of the phone number, as a PhoneNumberType value;
2036 returns PhoneNumberType.UNKNOWN if it is invalid.
2037 """
2038 region_code = region_code_for_number(numobj)
2039 metadata = PhoneMetadata.metadata_for_region_or_calling_code(numobj.country_code, region_code)
2040 if metadata is None:
2041 return PhoneNumberType.UNKNOWN
2042 national_number = national_significant_number(numobj)
2043 return _number_type_helper(national_number, metadata)
2046def _number_type_helper(national_number, metadata):
2047 """Return the type of the given number against the metadata"""
2048 if not _is_number_matching_desc(national_number, metadata.general_desc):
2049 return PhoneNumberType.UNKNOWN
2050 if _is_number_matching_desc(national_number, metadata.premium_rate):
2051 return PhoneNumberType.PREMIUM_RATE
2052 if _is_number_matching_desc(national_number, metadata.toll_free):
2053 return PhoneNumberType.TOLL_FREE
2054 if _is_number_matching_desc(national_number, metadata.shared_cost):
2055 return PhoneNumberType.SHARED_COST
2056 if _is_number_matching_desc(national_number, metadata.voip):
2057 return PhoneNumberType.VOIP
2058 if _is_number_matching_desc(national_number, metadata.personal_number):
2059 return PhoneNumberType.PERSONAL_NUMBER
2060 if _is_number_matching_desc(national_number, metadata.pager):
2061 return PhoneNumberType.PAGER
2062 if _is_number_matching_desc(national_number, metadata.uan):
2063 return PhoneNumberType.UAN
2064 if _is_number_matching_desc(national_number, metadata.voicemail):
2065 return PhoneNumberType.VOICEMAIL
2067 if _is_number_matching_desc(national_number, metadata.fixed_line):
2068 if metadata.same_mobile_and_fixed_line_pattern:
2069 return PhoneNumberType.FIXED_LINE_OR_MOBILE
2070 elif _is_number_matching_desc(national_number, metadata.mobile):
2071 return PhoneNumberType.FIXED_LINE_OR_MOBILE
2072 return PhoneNumberType.FIXED_LINE
2074 # Otherwise, test to see if the number is mobile. Only do this if certain
2075 # that the patterns for mobile and fixed line aren't the same.
2076 if (not metadata.same_mobile_and_fixed_line_pattern and
2077 _is_number_matching_desc(national_number, metadata.mobile)):
2078 return PhoneNumberType.MOBILE
2079 return PhoneNumberType.UNKNOWN
2082def _is_number_matching_desc(national_number, number_desc):
2083 """Determine if the number matches the given PhoneNumberDesc"""
2084 # Check if any possible number lengths are present; if so, we use them to avoid checking the
2085 # validation pattern if they don't match. If they are absent, this means they match the general
2086 # description, which we have already checked before checking a specific number type.
2087 if number_desc is None:
2088 return False
2089 actual_length = len(national_number)
2090 possible_lengths = number_desc.possible_length
2091 if len(possible_lengths) > 0 and actual_length not in possible_lengths:
2092 return False
2093 return _match_national_number(national_number, number_desc, False)
2096def is_valid_number(numobj):
2097 """Tests whether a phone number matches a valid pattern.
2099 Note this doesn't verify the number is actually in use, which is
2100 impossible to tell by just looking at a number itself. It only verifies
2101 whether the parsed, canonicalised number is valid: not whether a
2102 particular series of digits entered by the user is diallable from the
2103 region provided when parsing. For example, the number +41 (0) 78 927 2696
2104 can be parsed into a number with country code "41" and national
2105 significant number "789272696". This is valid, while the original string
2106 is not diallable.
2108 Arguments:
2109 numobj -- The phone number object that we want to validate
2111 Returns a boolean that indicates whether the number is of a valid pattern.
2112 """
2113 region_code = region_code_for_number(numobj)
2114 return is_valid_number_for_region(numobj, region_code)
2117def is_valid_number_for_region(numobj, region_code):
2118 """Tests whether a phone number is valid for a certain region.
2120 Note this doesn't verify the number is actually in use, which is
2121 impossible to tell by just looking at a number itself. If the country
2122 calling code is not the same as the country calling code for the region,
2123 this immediately exits with false. After this, the specific number pattern
2124 rules for the region are examined. This is useful for determining for
2125 example whether a particular number is valid for Canada, rather than just
2126 a valid NANPA number.
2128 Warning: In most cases, you want to use is_valid_number instead. For
2129 example, this method will mark numbers from British Crown dependencies
2130 such as the Isle of Man as invalid for the region "GB" (United Kingdom),
2131 since it has its own region code, "IM", which may be undesirable.
2133 Arguments:
2134 numobj -- The phone number object that we want to validate.
2135 region_code -- The region that we want to validate the phone number for.
2137 Returns a boolean that indicates whether the number is of a valid pattern.
2138 """
2139 country_code = numobj.country_code
2140 if region_code is None:
2141 return False
2142 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code.upper())
2143 if (metadata is None or
2144 (region_code != REGION_CODE_FOR_NON_GEO_ENTITY and
2145 country_code != country_code_for_valid_region(region_code))):
2146 # Either the region code was invalid, or the country calling code for
2147 # this number does not match that of the region code.
2148 return False
2149 nsn = national_significant_number(numobj)
2150 return (_number_type_helper(nsn, metadata) != PhoneNumberType.UNKNOWN)
2153def region_code_for_number(numobj):
2154 """Returns the region where a phone number is from.
2156 This could be used for geocoding at the region level. Only guarantees
2157 correct results for valid, full numbers (not short-codes, or invalid
2158 numbers).
2160 Arguments:
2161 numobj -- The phone number object whose origin we want to know
2163 Returns the region where the phone number is from, or None if no region
2164 matches this calling code.
2166 """
2167 country_code = numobj.country_code
2168 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None)
2169 if regions is None:
2170 return None
2172 if len(regions) == 1:
2173 return regions[0]
2174 else:
2175 return _region_code_for_number_from_list(numobj, regions)
2178def _region_code_for_number_from_list(numobj, regions):
2179 """Find the region in a list that matches a number"""
2180 national_number = national_significant_number(numobj)
2181 for region_code in regions:
2182 # If leading_digits is present, use this. Otherwise, do full
2183 # validation.
2184 # Metadata cannot be None because the region codes come from
2185 # the country calling code map.
2186 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None)
2187 if metadata is None:
2188 continue
2189 if metadata.leading_digits is not None:
2190 leading_digit_re = re.compile(metadata.leading_digits)
2191 match = leading_digit_re.match(national_number)
2192 if match:
2193 return region_code
2194 elif _number_type_helper(national_number, metadata) != PhoneNumberType.UNKNOWN:
2195 return region_code
2196 return None
2199def region_code_for_country_code(country_code):
2200 """Returns the region code that matches a specific country calling code.
2202 In the case of no region code being found, UNKNOWN_REGION ('ZZ') will be
2203 returned. In the case of multiple regions, the one designated in the
2204 metadata as the "main" region for this calling code will be returned. If
2205 the country_code entered is valid but doesn't match a specific region
2206 (such as in the case of non-geographical calling codes like 800) the value
2207 "001" will be returned (corresponding to the value for World in the UN
2208 M.49 schema).
2209 """
2210 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None)
2211 if regions is None:
2212 return UNKNOWN_REGION
2213 else:
2214 return regions[0]
2217def region_codes_for_country_code(country_code):
2218 """Returns a list with the region codes that match the specific country calling code.
2220 For non-geographical country calling codes, the region code 001 is
2221 returned. Also, in the case of no region code being found, an empty
2222 list is returned.
2223 """
2224 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None)
2225 if regions is None:
2226 return ()
2227 else:
2228 return regions
2231def country_code_for_region(region_code):
2232 """Returns the country calling code for a specific region.
2234 For example, this would be 1 for the United States, and 64 for New
2235 Zealand.
2237 Arguments:
2238 region_code -- The region that we want to get the country calling code for.
2240 Returns the country calling code for the region denoted by region_code.
2241 """
2242 if not _is_valid_region_code(region_code):
2243 return 0
2244 return country_code_for_valid_region(region_code)
2247def country_code_for_valid_region(region_code):
2248 """Returns the country calling code for a specific region.
2250 For example, this would be 1 for the United States, and 64 for New
2251 Zealand. Assumes the region is already valid.
2253 Arguments:
2254 region_code -- The region that we want to get the country calling code for.
2256 Returns the country calling code for the region denoted by region_code.
2257 """
2258 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None)
2259 if metadata is None:
2260 raise Exception("Invalid region code %s" % region_code)
2261 return metadata.country_code
2264def ndd_prefix_for_region(region_code, strip_non_digits):
2265 """Returns the national dialling prefix for a specific region.
2267 For example, this would be 1 for the United States, and 0 for New
2268 Zealand. Set strip_non_digits to True to strip symbols like "~" (which
2269 indicates a wait for a dialling tone) from the prefix returned. If no
2270 national prefix is present, we return None.
2272 Warning: Do not use this method for do-your-own formatting - for some
2273 regions, the national dialling prefix is used only for certain types of
2274 numbers. Use the library's formatting functions to prefix the national
2275 prefix when required.
2277 Arguments:
2278 region_code -- The region that we want to get the dialling prefix for.
2279 strip_non_digits -- whether to strip non-digits from the national
2280 dialling prefix.
2282 Returns the dialling prefix for the region denoted by region_code.
2283 """
2284 if region_code is None:
2285 return None
2286 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None)
2287 if metadata is None:
2288 return None
2289 national_prefix = metadata.national_prefix
2290 if national_prefix is None or len(national_prefix) == 0:
2291 return None
2292 if strip_non_digits:
2293 # Note: if any other non-numeric symbols are ever used in national
2294 # prefixes, these would have to be removed here as well.
2295 national_prefix = re.sub(U_TILDE, U_EMPTY_STRING, national_prefix)
2296 return national_prefix
2299def is_nanpa_country(region_code):
2300 """Checks if this region is a NANPA region.
2302 Returns True if region_code is one of the regions under the North American
2303 Numbering Plan Administration (NANPA).
2304 """
2305 return region_code in _NANPA_REGIONS
2308def is_alpha_number(number):
2309 """Checks if the number is a valid vanity (alpha) number such as 800
2310 MICROSOFT. A valid vanity number will start with at least 3 digits and
2311 will have three or more alpha characters. This does not do region-specific
2312 checks - to work out if this number is actually valid for a region, it
2313 should be parsed and methods such as is_possible_number_with_reason() and
2314 is_valid_number() should be used.
2316 Arguments:
2317 number -- the number that needs to be checked
2319 Returns True if the number is a valid vanity number
2320 """
2321 if not _is_viable_phone_number(number):
2322 # Number is too short, or doesn't match the basic phone number pattern.
2323 return False
2324 extension, stripped_number = _maybe_strip_extension(number)
2325 return bool(fullmatch(_VALID_ALPHA_PHONE_PATTERN, stripped_number))
2328def is_possible_number(numobj):
2329 """Convenience wrapper around is_possible_number_with_reason.
2331 Instead of returning the reason for failure, this method returns true if
2332 the number is either a possible fully-qualified number (containing the area
2333 code and country code), or if the number could be a possible local number
2334 (with a country code, but missing an area code). Local numbers are
2335 considered possible if they could be possibly dialled in this format: if
2336 the area code is needed for a call to connect, the number is not considered
2337 possible without it.
2339 Arguments:
2340 numobj -- the number object that needs to be checked
2342 Returns True if the number is possible
2344 """
2345 result = is_possible_number_with_reason(numobj)
2346 return (result == ValidationResult.IS_POSSIBLE or
2347 result == ValidationResult.IS_POSSIBLE_LOCAL_ONLY)
2350def is_possible_number_for_type(numobj, numtype):
2351 """Convenience wrapper around is_possible_number_for_type_with_reason.
2353 Instead of returning the reason for failure, this method returns true if
2354 the number is either a possible fully-qualified number (containing the area
2355 code and country code), or if the number could be a possible local number
2356 (with a country code, but missing an area code). Local numbers are
2357 considered possible if they could be possibly dialled in this format: if
2358 the area code is needed for a call to connect, the number is not considered
2359 possible without it.
2361 Arguments:
2362 numobj -- the number object that needs to be checked
2363 numtype -- the type we are interested in
2365 Returns True if the number is possible
2367 """
2368 result = is_possible_number_for_type_with_reason(numobj, numtype)
2369 return (result == ValidationResult.IS_POSSIBLE or
2370 result == ValidationResult.IS_POSSIBLE_LOCAL_ONLY)
2373def _test_number_length(national_number, metadata, numtype=PhoneNumberType.UNKNOWN):
2374 """Helper method to check a number against possible lengths for this number,
2375 and determine whether it matches, or is too short or too long.
2376 """
2377 desc_for_type = _number_desc_by_type(metadata, numtype)
2378 if desc_for_type is None:
2379 possible_lengths = metadata.general_desc.possible_length
2380 local_lengths = ()
2381 else:
2382 # There should always be "possibleLengths" set for every element. This is declared in the XML
2383 # schema which is verified by PhoneNumberMetadataSchemaTest.
2384 # For size efficiency, where a sub-description (e.g. fixed-line) has the same possibleLengths
2385 # as the parent, this is missing, so we fall back to the general desc (where no numbers of the
2386 # type exist at all, there is one possible length (-1) which is guaranteed not to match the
2387 # length of any real phone number).
2388 possible_lengths = desc_for_type.possible_length
2389 if len(possible_lengths) == 0: # pragma no cover: Python sub-descs all have possible_length
2390 possible_lengths = metadata.general_desc.possible_length
2391 local_lengths = desc_for_type.possible_length_local_only
2393 if numtype == PhoneNumberType.FIXED_LINE_OR_MOBILE:
2394 if not _desc_has_possible_number_data(_number_desc_by_type(metadata, PhoneNumberType.FIXED_LINE)):
2395 # The rare case has been encountered where no fixedLine data is available (true for some
2396 # non-geographical entities), so we just check mobile.
2397 return _test_number_length(national_number, metadata, PhoneNumberType.MOBILE)
2398 else:
2399 mobile_desc = _number_desc_by_type(metadata, PhoneNumberType.MOBILE)
2400 if _desc_has_possible_number_data(mobile_desc):
2401 # Merge the mobile data in if there was any. We have to make a copy to do this.
2402 possible_lengths = list(possible_lengths)
2403 # Note that when adding the possible lengths from mobile, we have to again check they
2404 # aren't empty since if they are this indicates they are the same as the general desc and
2405 # should be obtained from there.
2406 if len(mobile_desc.possible_length) == 0: # pragma no cover: Python sub-descs all have possible_length
2407 possible_lengths += metadata.general_desc.possible_length
2408 else:
2409 possible_lengths += mobile_desc.possible_length
2410 # The current list is sorted; we need to merge in the new list and re-sort (duplicates
2411 # are okay). Sorting isn't so expensive because the lists are very small.
2412 list.sort(possible_lengths)
2414 if len(local_lengths) == 0:
2415 local_lengths = mobile_desc.possible_length_local_only
2416 else:
2417 local_lengths = list(local_lengths)
2418 local_lengths += mobile_desc.possible_length_local_only
2419 list.sort(local_lengths)
2421 # If the type is not supported at all (indicated by a missing PhoneNumberDesc) we return invalid length.
2422 if desc_for_type is None:
2423 return ValidationResult.INVALID_LENGTH
2425 actual_length = len(national_number)
2426 # This is safe because there is never an overlap between the possible lengths and the local-only
2427 # lengths; this is checked at build time.
2428 if actual_length in local_lengths:
2429 return ValidationResult.IS_POSSIBLE_LOCAL_ONLY
2431 minimum_length = possible_lengths[0]
2432 if minimum_length == actual_length:
2433 return ValidationResult.IS_POSSIBLE
2434 elif minimum_length > actual_length:
2435 return ValidationResult.TOO_SHORT
2436 elif possible_lengths[-1] < actual_length:
2437 return ValidationResult.TOO_LONG
2438 # We skip the first element; we've already checked it.
2439 if actual_length in possible_lengths[1:]:
2440 return ValidationResult.IS_POSSIBLE
2441 else:
2442 return ValidationResult.INVALID_LENGTH
2445def is_possible_number_with_reason(numobj):
2446 return is_possible_number_for_type_with_reason(numobj, PhoneNumberType.UNKNOWN)
2449def is_possible_number_for_type_with_reason(numobj, numtype):
2450 """Check whether a phone number is a possible number of a particular type.
2452 For types that don't exist in a particular region, this will return a result
2453 that isn't so useful; it is recommended that you use
2454 supported_types_for_region or supported_types_for_non_geo_entity
2455 respectively before calling this method to determine whether you should call
2456 it for this number at all.
2458 This provides a more lenient check than is_valid_number in the following sense:
2460 - It only checks the length of phone numbers. In particular, it doesn't
2461 check starting digits of the number.
2463 - For some numbers (particularly fixed-line), many regions have the
2464 concept of area code, which together with subscriber number constitute
2465 the national significant number. It is sometimes okay to dial only the
2466 subscriber number when dialing in the same area. This function will
2467 return IS_POSSIBLE_LOCAL_ONLY if the subscriber-number-only version is
2468 passed in. On the other hand, because is_valid_number validates using
2469 information on both starting digits (for fixed line numbers, that would
2470 most likely be area codes) and length (obviously includes the length of
2471 area codes for fixed line numbers), it will return false for the
2472 subscriber-number-only version.
2474 Arguments:
2475 numobj -- The number object that needs to be checked
2476 numtype -- The type we are interested in
2478 Returns a value from ValidationResult which indicates whether the number
2479 is possible
2480 """
2481 national_number = national_significant_number(numobj)
2482 country_code = numobj.country_code
2483 # Note: For regions that share a country calling code, like NANPA numbers,
2484 # we just use the rules from the default region (US in this case) since the
2485 # region_code_for_number will not work if the number is possible but not
2486 # valid. There is in fact one country calling code (290) where the possible
2487 # number pattern differs between various regions (Saint Helena and Tristan
2488 # da Cuñha), but this is handled by putting all possible lengths for any
2489 # country with this country calling code in the metadata for the default
2490 # region in this case.
2491 if not _has_valid_country_calling_code(country_code):
2492 return ValidationResult.INVALID_COUNTRY_CODE
2493 region_code = region_code_for_country_code(country_code)
2494 # Metadata cannot be None because the country calling code is valid.
2495 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
2496 return _test_number_length(national_number, metadata, numtype)
2499def is_possible_number_string(number, region_dialing_from):
2500 """Check whether a phone number string is a possible number.
2502 Takes a number in the form of a string, and the region where the number
2503 could be dialed from. It provides a more lenient check than
2504 is_valid_number; see is_possible_number_with_reason() for details.
2506 This method first parses the number, then invokes is_possible_number with
2507 the resultant PhoneNumber object.
2509 Arguments:
2510 number -- The number that needs to be checked, in the form of a string.
2511 region_dialling_from -- The region that we are expecting the number to be
2512 dialed from. Note this is different from the region where the
2513 number belongs. For example, the number +1 650 253 0000 is a
2514 number that belongs to US. When written in this form, it can be
2515 dialed from any region. When it is written as 00 1 650 253 0000,
2516 it can be dialed from any region which uses an international
2517 dialling prefix of 00. When it is written as 650 253 0000, it
2518 can only be dialed from within the US, and when written as 253
2519 0000, it can only be dialed from within a smaller area in the US
2520 (Mountain View, CA, to be more specific).
2522 Returns True if the number is possible
2523 """
2524 try:
2525 return is_possible_number(parse(number, region_dialing_from))
2526 except NumberParseException:
2527 return False
2530def truncate_too_long_number(numobj):
2531 """Truncate a number object that is too long.
2533 Attempts to extract a valid number from a phone number that is too long
2534 to be valid, and resets the PhoneNumber object passed in to that valid
2535 version. If no valid number could be extracted, the PhoneNumber object
2536 passed in will not be modified.
2538 Arguments:
2539 numobj -- A PhoneNumber object which contains a number that is too long to
2540 be valid.
2542 Returns True if a valid phone number can be successfully extracted.
2543 """
2544 if is_valid_number(numobj):
2545 return True
2546 numobj_copy = PhoneNumber()
2547 numobj_copy.merge_from(numobj)
2548 national_number = numobj.national_number
2550 while not is_valid_number(numobj_copy):
2551 # Strip a digit off the RHS
2552 national_number = national_number // 10
2553 numobj_copy.national_number = national_number
2554 validation_result = is_possible_number_with_reason(numobj_copy)
2555 if (validation_result == ValidationResult.TOO_SHORT or
2556 national_number == 0):
2557 return False
2558 # To reach here, numobj_copy is a valid number. Modify the original object
2559 numobj.national_number = national_number
2560 return True
2563def _extract_country_code(number):
2564 """Extracts country calling code from number.
2566 Returns a 2-tuple of (country_calling_code, rest_of_number). It assumes
2567 that the leading plus sign or IDD has already been removed. Returns (0,
2568 number) if number doesn't start with a valid country calling code.
2569 """
2571 if len(number) == 0 or number[0] == U_ZERO:
2572 # Country codes do not begin with a '0'.
2573 return (0, number)
2574 for ii in range(1, min(len(number), _MAX_LENGTH_COUNTRY_CODE) + 1):
2575 try:
2576 country_code = int(number[:ii])
2577 if country_code in COUNTRY_CODE_TO_REGION_CODE:
2578 return (country_code, number[ii:])
2579 except Exception:
2580 pass
2581 return (0, number)
2584def _maybe_extract_country_code(number, metadata, keep_raw_input, numobj):
2585 """Tries to extract a country calling code from a number.
2587 This method will return zero if no country calling code is considered to
2588 be present. Country calling codes are extracted in the following ways:
2590 - by stripping the international dialing prefix of the region the person
2591 is dialing from, if this is present in the number, and looking at the
2592 next digits
2594 - by stripping the '+' sign if present and then looking at the next
2595 digits
2597 - by comparing the start of the number and the country calling code of
2598 the default region. If the number is not considered possible for the
2599 numbering plan of the default region initially, but starts with the
2600 country calling code of this region, validation will be reattempted
2601 after stripping this country calling code. If this number is considered
2602 a possible number, then the first digits will be considered the country
2603 calling code and removed as such.
2605 It will raise a NumberParseException if the number starts with a '+' but
2606 the country calling code supplied after this does not match that of any
2607 known region.
2609 Arguments:
2610 number -- non-normalized telephone number that we wish to extract a
2611 country calling code from; may begin with '+'
2612 metadata -- metadata about the region this number may be from, or None
2613 keep_raw_input -- True if the country_code_source and
2614 preferred_carrier_code fields of numobj should be populated.
2615 numobj -- The PhoneNumber object where the country_code and
2616 country_code_source need to be populated. Note the country_code
2617 is always populated, whereas country_code_source is only
2618 populated when keep_raw_input is True.
2620 Returns a 2-tuple containing:
2621 - the country calling code extracted or 0 if none could be extracted
2622 - a string holding the national significant number, in the case
2623 that a country calling code was extracted. If no country calling code
2624 was extracted, this will be empty.
2625 """
2626 if len(number) == 0:
2627 return (0, U_EMPTY_STRING)
2628 full_number = number
2629 # Set the default prefix to be something that will never match.
2630 possible_country_idd_prefix = unicod("NonMatch")
2631 if metadata is not None and metadata.international_prefix is not None:
2632 possible_country_idd_prefix = metadata.international_prefix
2634 country_code_source, full_number = _maybe_strip_i18n_prefix_and_normalize(full_number,
2635 possible_country_idd_prefix)
2636 if keep_raw_input:
2637 numobj.country_code_source = country_code_source
2639 if country_code_source != CountryCodeSource.FROM_DEFAULT_COUNTRY:
2640 if len(full_number) <= _MIN_LENGTH_FOR_NSN:
2641 raise NumberParseException(NumberParseException.TOO_SHORT_AFTER_IDD,
2642 "Phone number had an IDD, but after this was not " +
2643 "long enough to be a viable phone number.")
2644 potential_country_code, rest_of_number = _extract_country_code(full_number)
2645 if potential_country_code != 0:
2646 numobj.country_code = potential_country_code
2647 return (potential_country_code, rest_of_number)
2649 # If this fails, they must be using a strange country calling code
2650 # that we don't recognize, or that doesn't exist.
2651 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE,
2652 "Country calling code supplied was not recognised.")
2653 elif metadata is not None:
2654 # Check to see if the number starts with the country calling code for
2655 # the default region. If so, we remove the country calling code, and
2656 # do some checks on the validity of the number before and after.
2657 default_country_code = metadata.country_code
2658 default_country_code_str = str(metadata.country_code)
2659 normalized_number = full_number
2660 if normalized_number.startswith(default_country_code_str):
2661 potential_national_number = full_number[len(default_country_code_str):]
2662 general_desc = metadata.general_desc
2663 _, potential_national_number, _ = _maybe_strip_national_prefix_carrier_code(potential_national_number,
2664 metadata)
2666 # If the number was not valid before but is valid now, or if it
2667 # was too long before, we consider the number with the country
2668 # calling code stripped to be a better result and keep that
2669 # instead.
2670 if ((not _match_national_number(full_number, general_desc, False) and
2671 _match_national_number(potential_national_number, general_desc, False)) or
2672 (_test_number_length(full_number, metadata) == ValidationResult.TOO_LONG)):
2673 if keep_raw_input:
2674 numobj.country_code_source = CountryCodeSource.FROM_NUMBER_WITHOUT_PLUS_SIGN
2675 numobj.country_code = default_country_code
2676 return (default_country_code, potential_national_number)
2678 # No country calling code present.
2679 numobj.country_code = 0
2680 return (0, U_EMPTY_STRING)
2683def _parse_prefix_as_idd(idd_pattern, number):
2684 """Strips the IDD from the start of the number if present.
2686 Helper function used by _maybe_strip_i18n_prefix_and_normalize().
2688 Returns a 2-tuple:
2689 - Boolean indicating if IDD was stripped
2690 - Number with IDD stripped
2691 """
2692 match = idd_pattern.match(number)
2693 if match:
2694 match_end = match.end()
2695 # Only strip this if the first digit after the match is not a 0, since
2696 # country calling codes cannot begin with 0.
2697 digit_match = _CAPTURING_DIGIT_PATTERN.search(number[match_end:])
2698 if digit_match:
2699 normalized_group = normalize_digits_only(digit_match.group(1))
2700 if normalized_group == U_ZERO:
2701 return (False, number)
2702 return (True, number[match_end:])
2703 return (False, number)
2706def _maybe_strip_i18n_prefix_and_normalize(number, possible_idd_prefix):
2707 """Strips any international prefix (such as +, 00, 011) present in the
2708 number provided, normalizes the resulting number, and indicates if an
2709 international prefix was present.
2711 Arguments:
2712 number -- The non-normalized telephone number that we wish to strip any international
2713 dialing prefix from.
2714 possible_idd_prefix -- The international direct dialing prefix from the region we
2715 think this number may be dialed in.
2717 Returns a 2-tuple containing:
2718 - The corresponding CountryCodeSource if an international dialing prefix
2719 could be removed from the number, otherwise
2720 CountryCodeSource.FROM_DEFAULT_COUNTRY if the number did not seem to
2721 be in international format.
2722 - The number with the prefix stripped.
2723 """
2724 if len(number) == 0:
2725 return (CountryCodeSource.FROM_DEFAULT_COUNTRY, number)
2726 # Check to see if the number begins with one or more plus signs.
2727 m = _PLUS_CHARS_PATTERN.match(number)
2728 if m:
2729 number = number[m.end():]
2730 # Can now normalize the rest of the number since we've consumed the
2731 # "+" sign at the start.
2732 return (CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN,
2733 _normalize(number))
2735 # Attempt to parse the first digits as an international prefix.
2736 idd_pattern = re.compile(possible_idd_prefix)
2737 number = _normalize(number)
2738 stripped, number = _parse_prefix_as_idd(idd_pattern, number)
2739 if stripped:
2740 return (CountryCodeSource.FROM_NUMBER_WITH_IDD, number)
2741 else:
2742 return (CountryCodeSource.FROM_DEFAULT_COUNTRY, number)
2745def _maybe_strip_national_prefix_carrier_code(number, metadata):
2746 """Strips any national prefix (such as 0, 1) present in a number.
2748 Arguments:
2749 number -- The normalized telephone number that we wish to strip any
2750 national dialing prefix from
2751 metadata -- The metadata for the region that we think this number
2752 is from.
2754 Returns a 3-tuple of
2755 - The carrier code extracted if it is present, otherwise an empty string.
2756 - The number with the prefix stripped.
2757 - Boolean indicating if a national prefix or carrier code (or both) could be extracted.
2758 """
2759 carrier_code = U_EMPTY_STRING
2760 possible_national_prefix = metadata.national_prefix_for_parsing
2761 if (len(number) == 0 or
2762 possible_national_prefix is None or
2763 len(possible_national_prefix) == 0):
2764 # Early return for numbers of zero length.
2765 return (U_EMPTY_STRING, number, False)
2767 # Attempt to parse the first digits as a national prefix.
2768 prefix_pattern = re.compile(possible_national_prefix)
2769 prefix_match = prefix_pattern.match(number)
2770 if prefix_match:
2771 general_desc = metadata.general_desc
2772 # Check if the original number is viable.
2773 is_viable_original_number = _match_national_number(number, general_desc, False)
2774 # prefix_match.groups() == () implies nothing was captured by the
2775 # capturing groups in possible_national_prefix; therefore, no
2776 # transformation is necessary, and we just remove the national prefix.
2777 num_groups = len(prefix_match.groups())
2778 transform_rule = metadata.national_prefix_transform_rule
2779 if (transform_rule is None or
2780 len(transform_rule) == 0 or
2781 prefix_match.groups()[num_groups - 1] is None):
2782 # If the original number was viable, and the resultant number is not, we return.
2783 # Check that the resultant number is viable. If not, return.
2784 national_number_match = _match_national_number(number[prefix_match.end():], general_desc, False)
2785 if (is_viable_original_number and not national_number_match):
2786 return (U_EMPTY_STRING, number, False)
2788 if (num_groups > 0 and
2789 prefix_match.groups(num_groups) is not None):
2790 carrier_code = prefix_match.group(1)
2791 return (carrier_code, number[prefix_match.end():], True)
2792 else:
2793 # Check that the resultant number is still viable. If not,
2794 # return. Check this by copying the number and making the
2795 # transformation on the copy first.
2796 transformed_number = re.sub(prefix_pattern, transform_rule, number, count=1)
2797 national_number_match = _match_national_number(transformed_number, general_desc, False)
2798 if (is_viable_original_number and not national_number_match):
2799 return ("", number, False)
2800 if num_groups > 1:
2801 carrier_code = prefix_match.group(1)
2802 return (carrier_code, transformed_number, True)
2803 else:
2804 return (carrier_code, number, False)
2807def _maybe_strip_extension(number):
2808 """Strip extension from the end of a number string.
2810 Strips any extension (as in, the part of the number dialled after the
2811 call is connected, usually indicated with extn, ext, x or similar) from
2812 the end of the number, and returns it.
2814 Arguments:
2815 number -- the non-normalized telephone number that we wish to strip the extension from.
2817 Returns a 2-tuple of:
2818 - the phone extension (or "" or not present)
2819 - the number before the extension.
2820 """
2821 match = _EXTN_PATTERN.search(number)
2822 # If we find a potential extension, and the number preceding this is a
2823 # viable number, we assume it is an extension.
2824 if match and _is_viable_phone_number(number[:match.start()]):
2825 # The numbers are captured into groups in the regular expression.
2826 for group in match.groups():
2827 # We go through the capturing groups until we find one that
2828 # captured some digits. If none did, then we will return the empty
2829 # string.
2830 if group is not None:
2831 return (group, number[:match.start()])
2832 return ("", number)
2835def _check_region_for_parsing(number, default_region):
2836 """Checks to see that the region code used is valid, or if it is not
2837 valid, that the number to parse starts with a + symbol so that we can
2838 attempt to infer the region from the number. Returns False if it cannot
2839 use the region provided and the region cannot be inferred.
2840 """
2841 if not _is_valid_region_code(default_region):
2842 # If the number is None or empty, we can't infer the region.
2843 if number is None or len(number) == 0:
2844 return False
2845 match = _PLUS_CHARS_PATTERN.match(number)
2846 if match is None:
2847 return False
2848 return True
2851def _set_italian_leading_zeros_for_phone_number(national_number, numobj):
2852 """A helper function to set the values related to leading zeros in a
2853 PhoneNumber."""
2854 if len(national_number) > 1 and national_number[0] == U_ZERO:
2855 numobj.italian_leading_zero = True
2856 number_of_leading_zeros = 1
2857 # Note that if the number is all "0"s, the last "0" is not counted as
2858 # a leading zero.
2859 while (number_of_leading_zeros < len(national_number) - 1 and
2860 national_number[number_of_leading_zeros] == U_ZERO):
2861 number_of_leading_zeros += 1
2862 if number_of_leading_zeros != 1:
2863 numobj.number_of_leading_zeros = number_of_leading_zeros
2866def parse(number, region=None, keep_raw_input=False,
2867 numobj=None, _check_region=True):
2868 """Parse a string and return a corresponding PhoneNumber object.
2870 The method is quite lenient and looks for a number in the input text
2871 (raw input) and does not check whether the string is definitely only a
2872 phone number. To do this, it ignores punctuation and white-space, as
2873 well as any text before the number (e.g. a leading "Tel: ") and trims
2874 the non-number bits. It will accept a number in any format (E164,
2875 national, international etc), assuming it can be interpreted with the
2876 defaultRegion supplied. It also attempts to convert any alpha characters
2877 into digits if it thinks this is a vanity number of the type "1800
2878 MICROSOFT".
2880 This method will throw a NumberParseException if the number is not
2881 considered to be a possible number. Note that validation of whether the
2882 number is actually a valid number for a particular region is not
2883 performed. This can be done separately with is_valid_number.
2885 Note this method canonicalizes the phone number such that different
2886 representations can be easily compared, no matter what form it was
2887 originally entered in (e.g. national, international). If you want to
2888 record context about the number being parsed, such as the raw input that
2889 was entered, how the country code was derived etc. then ensure
2890 keep_raw_input is set.
2892 Note if any new field is added to this method that should always be filled
2893 in, even when keep_raw_input is False, it should also be handled in the
2894 _copy_core_fields_only() function.
2896 Arguments:
2897 number -- The number that we are attempting to parse. This can
2898 contain formatting such as +, ( and -, as well as a phone
2899 number extension. It can also be provided in RFC3966 format.
2900 region -- The region that we are expecting the number to be from. This
2901 is only used if the number being parsed is not written in
2902 international format. The country_code for the number in
2903 this case would be stored as that of the default region
2904 supplied. If the number is guaranteed to start with a '+'
2905 followed by the country calling code, then None or
2906 UNKNOWN_REGION can be supplied.
2907 keep_raw_input -- Whether to populate the raw_input field of the
2908 PhoneNumber object with number (as well as the
2909 country_code_source field).
2910 numobj -- An optional existing PhoneNumber object to receive the
2911 parsing results
2912 _check_region -- Whether to check the supplied region parameter;
2913 should always be True for external callers.
2915 Returns a PhoneNumber object filled with the parse number.
2917 Raises:
2918 NumberParseException if the string is not considered to be a viable
2919 phone number (e.g. too few or too many digits) or if no default
2920 region was supplied and the number is not in international format
2921 (does not start with +).
2923 """
2924 if numobj is None:
2925 numobj = PhoneNumber()
2926 if number is None:
2927 raise NumberParseException(NumberParseException.NOT_A_NUMBER,
2928 "The phone number supplied was None.")
2929 elif len(number) > _MAX_INPUT_STRING_LENGTH:
2930 raise NumberParseException(NumberParseException.TOO_LONG,
2931 "The string supplied was too long to parse.")
2933 national_number = _build_national_number_for_parsing(number)
2935 if not _is_viable_phone_number(national_number):
2936 raise NumberParseException(NumberParseException.NOT_A_NUMBER,
2937 "The string supplied did not seem to be a phone number.")
2939 # Check the region supplied is valid, or that the extracted number starts
2940 # with some sort of + sign so the number's region can be determined.
2941 if _check_region and not _check_region_for_parsing(national_number, region):
2942 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE,
2943 "Missing or invalid default region.")
2944 if keep_raw_input:
2945 numobj.raw_input = number
2947 # Attempt to parse extension first, since it doesn't require
2948 # region-specific data and we want to have the non-normalised number here.
2949 extension, national_number = _maybe_strip_extension(national_number)
2950 if len(extension) > 0:
2951 numobj.extension = extension
2952 if region is None:
2953 metadata = None
2954 else:
2955 metadata = PhoneMetadata.metadata_for_region(region.upper(), None)
2957 country_code = 0
2958 try:
2959 country_code, normalized_national_number = _maybe_extract_country_code(national_number,
2960 metadata,
2961 keep_raw_input,
2962 numobj)
2963 except NumberParseException:
2964 _, e, _ = sys.exc_info()
2965 matchobj = _PLUS_CHARS_PATTERN.match(national_number)
2966 if (e.error_type == NumberParseException.INVALID_COUNTRY_CODE and
2967 matchobj is not None):
2968 # Strip the plus-char, and try again.
2969 country_code, normalized_national_number = _maybe_extract_country_code(national_number[matchobj.end():],
2970 metadata,
2971 keep_raw_input,
2972 numobj)
2973 if country_code == 0:
2974 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE,
2975 "Could not interpret numbers after plus-sign.")
2976 else:
2977 raise
2979 if country_code != 0:
2980 number_region = region_code_for_country_code(country_code)
2981 if number_region != region:
2982 # Metadata cannot be None because the country calling code is valid.
2983 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, number_region)
2984 assert metadata is not None
2985 else:
2986 # If no extracted country calling code, use the region supplied
2987 # instead. The national number is just the normalized version of the
2988 # number we were given to parse.
2989 normalized_national_number += _normalize(national_number)
2990 if region is not None:
2991 country_code = metadata.country_code
2992 numobj.country_code = country_code
2993 elif keep_raw_input:
2994 numobj.country_code_source = CountryCodeSource.UNSPECIFIED
2996 if len(normalized_national_number) < _MIN_LENGTH_FOR_NSN:
2997 raise NumberParseException(NumberParseException.TOO_SHORT_NSN,
2998 "The string supplied is too short to be a phone number.")
2999 if metadata is not None:
3000 potential_national_number = normalized_national_number
3001 carrier_code, potential_national_number, _ = _maybe_strip_national_prefix_carrier_code(potential_national_number,
3002 metadata)
3003 # We require that the NSN remaining after stripping the national
3004 # prefix and carrier code be long enough to be a possible length for
3005 # the region. Otherwise, we don't do the stripping, since the original
3006 # number could be a valid short number.
3007 validation_result = _test_number_length(potential_national_number, metadata)
3008 if validation_result not in (ValidationResult.TOO_SHORT,
3009 ValidationResult.IS_POSSIBLE_LOCAL_ONLY,
3010 ValidationResult.INVALID_LENGTH):
3011 normalized_national_number = potential_national_number
3012 if keep_raw_input and carrier_code is not None and len(carrier_code) > 0:
3013 numobj.preferred_domestic_carrier_code = carrier_code
3014 len_national_number = len(normalized_national_number)
3015 if len_national_number < _MIN_LENGTH_FOR_NSN: # pragma no cover
3016 # Check of _is_viable_phone_number() at the top of this function makes
3017 # this effectively unhittable.
3018 raise NumberParseException(NumberParseException.TOO_SHORT_NSN,
3019 "The string supplied is too short to be a phone number.")
3020 if len_national_number > _MAX_LENGTH_FOR_NSN:
3021 raise NumberParseException(NumberParseException.TOO_LONG,
3022 "The string supplied is too long to be a phone number.")
3023 _set_italian_leading_zeros_for_phone_number(normalized_national_number, numobj)
3024 numobj.national_number = to_long(normalized_national_number)
3025 return numobj
3028def _extract_phone_context(number_to_extract_from, index_of_phone_context):
3029 """Extracts the value of the phone-context parameter of number_to_extract_from where the index of
3030 ";phone-context=" is the parameter index_of_phone_context, following the syntax defined in
3031 RFC3966.
3033 Returns the extracted string (possibly empty), or None if no phone-context parameter is found."""
3034 # If no phone-context parameter is present
3035 if index_of_phone_context == -1:
3036 return None
3038 phone_context_start = index_of_phone_context + len(_RFC3966_PHONE_CONTEXT)
3039 # If phone-context parameter is empty
3040 if phone_context_start >= len(number_to_extract_from):
3041 return U_EMPTY_STRING
3043 phone_context_end = number_to_extract_from.find(';', phone_context_start)
3044 # If phone-context is not the last parameter
3045 if phone_context_end != -1:
3046 return number_to_extract_from[phone_context_start:phone_context_end]
3047 else:
3048 return number_to_extract_from[phone_context_start:]
3051def _is_phone_context_valid(phone_context):
3052 """"Returns whether the value of phoneContext follows the syntax defined in RFC3966."""
3053 if phone_context is None:
3054 return True
3055 if len(phone_context) == 0:
3056 return False
3058 # Does phone-context value match pattern of global-number-digits or domainname
3059 return (fullmatch(_RFC3966_GLOBAL_NUMBER_DIGITS_PATTERN, phone_context) or
3060 fullmatch(_RFC3966_DOMAINNAME_PATTERN, phone_context))
3063def _build_national_number_for_parsing(number):
3064 """Converts number to a form that we can parse and return it if it is
3065 written in RFC3966; otherwise extract a possible number out of it and return it."""
3066 index_of_phone_context = number.find(_RFC3966_PHONE_CONTEXT)
3068 phone_context = _extract_phone_context(number, index_of_phone_context)
3069 if not _is_phone_context_valid(phone_context):
3070 raise NumberParseException(NumberParseException.NOT_A_NUMBER, "The phone-context value is invalid")
3071 if phone_context is not None:
3072 # If the phone context contains a phone number prefix, we need to
3073 # capture it, whereas domains will be ignored.
3074 if phone_context[0] == _PLUS_SIGN:
3075 # Additional parameters might follow the phone context. If so, we
3076 # will remove them here because the parameters after phone context
3077 # are not important for parsing the phone number.
3078 national_number = phone_context
3079 else:
3080 national_number = U_EMPTY_STRING
3082 # Now append everything between the "tel:" prefix and the
3083 # phone-context. This should include the national number, an optional
3084 # extension or isdn-subaddress component. Note we also handle the case
3085 # when "tel:" is missing, as we have seen in some of the phone number
3086 # inputs. In that case we append everything from the beginning.
3087 index_of_rfc3996_prefix = number.find(_RFC3966_PREFIX)
3088 index_of_national_number = ((index_of_rfc3996_prefix + len(_RFC3966_PREFIX))
3089 if (index_of_rfc3996_prefix >= 0) else 0)
3090 national_number += number[index_of_national_number:index_of_phone_context]
3091 else:
3092 # Extract a possible number from the string passed in (this strips leading characters that
3093 # could not be the start of a phone number.)
3094 national_number = _extract_possible_number(number)
3096 # Delete the isdn-subaddress and everything after it if it is
3097 # present. Note extension won't appear at the same time with
3098 # isdn-subaddress according to paragraph 5.3 of the RFC3966 spec,
3099 index_of_isdn = national_number.find(_RFC3966_ISDN_SUBADDRESS)
3100 if index_of_isdn > 0:
3101 national_number = national_number[:index_of_isdn]
3102 # If both phone context and isdn-subaddress are absent but other
3103 # parameters are present, the parameters are left in national_number. This
3104 # is because we are concerned about deleting content from a potential
3105 # number string when there is no strong evidence that the number is
3106 # actually written in RFC3966.
3107 return national_number
3110def _copy_core_fields_only(inobj):
3111 """Returns a new phone number containing only the fields needed to uniquely
3112 identify a phone number, rather than any fields that capture the context in
3113 which the phone number was created.
3114 """
3115 numobj = PhoneNumber()
3116 numobj.country_code = inobj.country_code
3117 numobj.national_number = inobj.national_number
3118 if inobj.extension is not None and len(inobj.extension) > 0:
3119 numobj.extension = inobj.extension
3120 if inobj.italian_leading_zero:
3121 numobj.italian_leading_zero = True
3122 # This field is only relevant if there are leading zeros at all.
3123 numobj.number_of_leading_zeros = inobj.number_of_leading_zeros
3124 if numobj.number_of_leading_zeros is None:
3125 # No number set is implicitly a count of 1; make it explicit.
3126 numobj.number_of_leading_zeros = 1
3127 return numobj
3130def _is_number_match_OO(numobj1_in, numobj2_in):
3131 """Takes two phone number objects and compares them for equality."""
3132 # We only care about the fields that uniquely define a number, so we copy these across explicitly.
3133 numobj1 = _copy_core_fields_only(numobj1_in)
3134 numobj2 = _copy_core_fields_only(numobj2_in)
3136 # Early exit if both had extensions and these are different.
3137 if (numobj1.extension is not None and
3138 numobj2.extension is not None and
3139 numobj1.extension != numobj2.extension):
3140 return MatchType.NO_MATCH
3142 country_code1 = numobj1.country_code
3143 country_code2 = numobj2.country_code
3144 # Both had country_code specified.
3145 if country_code1 != 0 and country_code2 != 0:
3146 if numobj1 == numobj2:
3147 return MatchType.EXACT_MATCH
3148 elif (country_code1 == country_code2 and
3149 _is_national_number_suffix_of_other(numobj1, numobj2)):
3150 # A SHORT_NSN_MATCH occurs if there is a difference because of the
3151 # presence or absence of an 'Italian leading zero', the presence
3152 # or absence of an extension, or one NSN being a shorter variant
3153 # of the other.
3154 return MatchType.SHORT_NSN_MATCH
3155 # This is not a match.
3156 return MatchType.NO_MATCH
3158 # Checks cases where one or both country_code fields were not
3159 # specified. To make equality checks easier, we first set the country_code
3160 # fields to be equal.
3161 numobj1.country_code = country_code2
3162 # If all else was the same, then this is an NSN_MATCH.
3163 if numobj1 == numobj2:
3164 return MatchType.NSN_MATCH
3165 if _is_national_number_suffix_of_other(numobj1, numobj2):
3166 return MatchType.SHORT_NSN_MATCH
3167 return MatchType.NO_MATCH
3170def _is_national_number_suffix_of_other(numobj1, numobj2):
3171 """Returns true when one national number is the suffix of the other or both
3172 are the same.
3173 """
3174 nn1 = str(numobj1.national_number)
3175 nn2 = str(numobj2.national_number)
3176 # Note that endswith returns True if the numbers are equal.
3177 return nn1.endswith(nn2) or nn2.endswith(nn1)
3180def _is_number_match_SS(number1, number2):
3181 """Takes two phone numbers as strings and compares them for equality.
3183 This is a convenience wrapper for _is_number_match_OO/_is_number_match_OS.
3184 No default region is known.
3185 """
3186 try:
3187 numobj1 = parse(number1, UNKNOWN_REGION)
3188 return _is_number_match_OS(numobj1, number2)
3189 except NumberParseException:
3190 _, exc, _ = sys.exc_info()
3191 if exc.error_type == NumberParseException.INVALID_COUNTRY_CODE:
3192 try:
3193 numobj2 = parse(number2, UNKNOWN_REGION)
3194 return _is_number_match_OS(numobj2, number1)
3195 except NumberParseException:
3196 _, exc2, _ = sys.exc_info()
3197 if exc2.error_type == NumberParseException.INVALID_COUNTRY_CODE:
3198 try:
3199 numobj1 = parse(number1, None, keep_raw_input=False,
3200 _check_region=False, numobj=None)
3201 numobj2 = parse(number2, None, keep_raw_input=False,
3202 _check_region=False, numobj=None)
3203 return _is_number_match_OO(numobj1, numobj2)
3204 except NumberParseException:
3205 return MatchType.NOT_A_NUMBER
3207 # One or more of the phone numbers we are trying to match is not a viable
3208 # phone number.
3209 return MatchType.NOT_A_NUMBER
3212def _is_number_match_OS(numobj1, number2):
3213 """Wrapper variant of _is_number_match_OO that copes with one
3214 PhoneNumber object and one string."""
3215 # First see if the second number has an implicit country calling code, by
3216 # attempting to parse it.
3217 try:
3218 numobj2 = parse(number2, UNKNOWN_REGION)
3219 return _is_number_match_OO(numobj1, numobj2)
3220 except NumberParseException:
3221 _, exc, _ = sys.exc_info()
3222 if exc.error_type == NumberParseException.INVALID_COUNTRY_CODE:
3223 # The second number has no country calling code. EXACT_MATCH is no
3224 # longer possible. We parse it as if the region was the same as
3225 # that for the first number, and if EXACT_MATCH is returned, we
3226 # replace this with NSN_MATCH.
3227 region1 = region_code_for_country_code(numobj1.country_code)
3228 try:
3229 if region1 != UNKNOWN_REGION:
3230 numobj2 = parse(number2, region1)
3231 match = _is_number_match_OO(numobj1, numobj2)
3232 if match == MatchType.EXACT_MATCH:
3233 return MatchType.NSN_MATCH
3234 else:
3235 return match
3236 else:
3237 # If the first number didn't have a valid country calling
3238 # code, then we parse the second number without one as
3239 # well.
3240 numobj2 = parse(number2, None, keep_raw_input=False,
3241 _check_region=False, numobj=None)
3242 return _is_number_match_OO(numobj1, numobj2)
3243 except NumberParseException:
3244 return MatchType.NOT_A_NUMBER
3245 # One or more of the phone numbers we are trying to match is not a viable
3246 # phone number.
3247 return MatchType.NOT_A_NUMBER
3250def is_number_match(num1, num2):
3251 """Takes two phone numbers and compares them for equality.
3253 For example, the numbers +1 345 657 1234 and 657 1234 are a SHORT_NSN_MATCH.
3254 The numbers +1 345 657 1234 and 345 657 are a NO_MATCH.
3256 Arguments
3257 num1 -- First number object or string to compare. Can contain formatting,
3258 and can have country calling code specified with + at the start.
3259 num2 -- Second number object or string to compare. Can contain formatting,
3260 and can have country calling code specified with + at the start.
3262 Returns:
3263 - EXACT_MATCH if the country_code, NSN, presence of a leading zero for
3264 Italian numbers and any extension present are the same.
3265 - NSN_MATCH if either or both has no region specified, and the NSNs and
3266 extensions are the same.
3267 - SHORT_NSN_MATCH if either or both has no region specified, or the
3268 region specified is the same, and one NSN could be a shorter version of
3269 the other number. This includes the case where one has an extension
3270 specified, and the other does not.
3271 - NO_MATCH otherwise.
3272 """
3273 if isinstance(num1, PhoneNumber) and isinstance(num2, PhoneNumber):
3274 return _is_number_match_OO(num1, num2)
3275 elif isinstance(num1, PhoneNumber):
3276 return _is_number_match_OS(num1, num2)
3277 elif isinstance(num2, PhoneNumber):
3278 return _is_number_match_OS(num2, num1)
3279 else:
3280 return _is_number_match_SS(num1, num2)
3283def can_be_internationally_dialled(numobj):
3284 """Returns True if the number can only be dialled from outside the region,
3285 or unknown.
3287 If the number can only be dialled from within the region
3288 as well, returns False. Does not check the number is a valid number.
3289 Note that, at the moment, this method does not handle short numbers (which
3290 are currently all presumed to not be diallable from outside their country).
3292 Arguments:
3293 numobj -- the phone number objectfor which we want to know whether it is
3294 diallable from outside the region.
3295 """
3296 metadata = PhoneMetadata.metadata_for_region(region_code_for_number(numobj), None)
3297 if metadata is None:
3298 # Note numbers belonging to non-geographical entities (e.g. +800
3299 # numbers) are always internationally diallable, and will be caught
3300 # here.
3301 return True
3302 nsn = national_significant_number(numobj)
3303 return not _is_number_matching_desc(nsn, metadata.no_international_dialling)
3306def is_mobile_number_portable_region(region_code):
3307 """Returns true if the supplied region supports mobile number portability.
3308 Returns false for invalid, unknown or regions that don't support mobile
3309 number portability.
3311 Arguments:
3312 region_code -- the region for which we want to know whether it supports mobile number
3313 portability or not.
3314 """
3315 metadata = PhoneMetadata.metadata_for_region(region_code, None)
3316 if metadata is None:
3317 return False
3318 return metadata.mobile_number_portable_region
3321class NumberParseException(UnicodeMixin, Exception):
3322 """Exception when attempting to parse a putative phone number"""
3324 # The reason a string could not be interpreted as a phone number.
3326 # The country code supplied did not belong to a supported country or
3327 # non-geographical entity.
3328 INVALID_COUNTRY_CODE = 0
3330 # This generally indicates the string passed in had fewer than 3 digits in
3331 # it. The number failed to match the regular expression
3332 # _VALID_PHONE_NUMBER in phonenumberutil.py.
3334 # This indicates the string passed is not a valid number. Either the string
3335 # had less than 3 digits in it or had an invalid phone-context
3336 # parameter. More specifically, the number failed to match the regular
3337 # expression _VALID_PHONE_NUMBER, )RFC3966_GLOBAL_NUMBER_DIGITS, or
3338 # _RFC3966_DOMAINNAME in phonenumberutil.py.
3339 NOT_A_NUMBER = 1
3341 # This indicates the string started with an international dialing prefix,
3342 # but after this was removed, it had fewer digits than any valid phone
3343 # number (including country code) could have.
3344 TOO_SHORT_AFTER_IDD = 2
3346 # This indicates the string, after any country code has been stripped,
3347 # had fewer digits than any valid phone number could have.
3348 TOO_SHORT_NSN = 3
3350 # This indicates the string had more digits than any valid phone number
3351 # could have
3352 TOO_LONG = 4
3354 def __init__(self, error_type, msg):
3355 Exception.__init__(self, msg)
3356 self.error_type = error_type
3357 self._msg = msg
3359 def __reduce__(self):
3360 return (type(self), (self.error_type, self._msg))
3362 def __unicode__(self):
3363 return unicod("(%s) %s") % (self.error_type, self._msg)
3366def _match_national_number(number, number_desc, allow_prefix_match):
3367 """Returns whether the given national number (a string containing only decimal digits) matches
3368 the national number pattern defined in the given PhoneNumberDesc object.
3369 """
3370 # We don't want to consider it a prefix match when matching non-empty input against an empty
3371 # pattern.
3372 if number_desc is None or number_desc.national_number_pattern is None or len(number_desc.national_number_pattern) == 0:
3373 return False
3374 return _match(number, re.compile(number_desc.national_number_pattern), allow_prefix_match)
3377def _match(number, pattern, allow_prefix_match):
3378 if not pattern.match(number):
3379 return False
3380 else:
3381 if fullmatch(pattern, number):
3382 return True
3383 else:
3384 return allow_prefix_match