Coverage for /var/srv/projects/api.amasfac.comuna18.com/tmp/venv/lib/python3.9/site-packages/phonenumbers/phonenumberutil.py: 30%
1199 statements
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
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# Regexp of all known extension prefixes used by different regions followed by
372# 1 or more valid digits, for use when parsing.
373_EXTN_PATTERN = re.compile(u("(?:") + _EXTN_PATTERNS_FOR_PARSING + u(")$"), _REGEX_FLAGS)
375# We append optionally the extension pattern to the end here, as a valid phone
376# number may have an extension prefix appended, followed by 1 or more digits.
377_VALID_PHONE_NUMBER_PATTERN = re.compile(_VALID_PHONE_NUMBER + u("(?:") + _EXTN_PATTERNS_FOR_PARSING + u(")?"), _REGEX_FLAGS)
379# We use a non-capturing group because Python's re.split() returns any capturing
380# groups interspersed with the other results (unlike Java's Pattern.split()).
381NON_DIGITS_PATTERN = re.compile(u("(?:\\D+)"))
383# The FIRST_GROUP_PATTERN was originally set to \1 but there are some
384# countries for which the first group is not used in the national pattern
385# (e.g. Argentina) so the \1 group does not match correctly. Therefore, we
386# use \d, so that the first group actually used in the pattern will be
387# matched.
388_FIRST_GROUP_PATTERN = re.compile(u(r"(\\\d)"))
389# Constants used in the formatting rules to represent the national prefix, first group and
390# carrier code respectively.
391_NP_STRING = "$NP"
392_FG_STRING = "$FG"
393_CC_STRING = "$CC"
395# A pattern that is used to determine if the national prefix formatting rule
396# has the first group only, i.e., does not start with the national
397# prefix. Note that the pattern explicitly allows for unbalanced parentheses.
398_FIRST_GROUP_ONLY_PREFIX_PATTERN = re.compile("\\(?\\\\1\\)?")
401class PhoneNumberFormat(object):
402 """
403 Phone number format.
405 INTERNATIONAL and NATIONAL formats are consistent with the definition in
406 ITU-T Recommendation E123. However we follow local conventions such as using
407 '-' instead of whitespace as separators. For example, the number of the
408 Google Switzerland office will be written as "+41 44 668 1800" in
409 INTERNATIONAL format, and as "044 668 1800" in NATIONAL format. E164 format
410 is as per INTERNATIONAL format but with no formatting applied,
411 e.g. "+41446681800". RFC3966 is as per INTERNATIONAL format, but with all
412 spaces and other separating symbols replaced with a hyphen, and with any
413 phone number extension appended with ";ext=". It also will have a prefix of
414 "tel:" added, e.g. "tel:+41-44-668-1800".
416 Note: If you are considering storing the number in a neutral format, you
417 are highly advised to use the PhoneNumber class.
418 """
419 E164 = 0
420 INTERNATIONAL = 1
421 NATIONAL = 2
422 RFC3966 = 3
424 @classmethod
425 def to_string(cls, val):
426 """Return a string representation of a PhoneNumberFormat value"""
427 if val == PhoneNumberFormat.E164:
428 return u("E164")
429 elif val == PhoneNumberFormat.INTERNATIONAL:
430 return u("INTERNATIONAL")
431 elif val == PhoneNumberFormat.NATIONAL:
432 return u("NATIONAL")
433 elif val == PhoneNumberFormat.RFC3966:
434 return u("RFC3966")
435 else:
436 return u("INVALID (%d)" % val)
439class PhoneNumberType(object):
440 """Type of phone numbers."""
441 FIXED_LINE = 0
442 MOBILE = 1
443 # In some regions (e.g. the USA), it is impossible to distinguish between
444 # fixed-line and mobile numbers by looking at the phone number itself.
445 FIXED_LINE_OR_MOBILE = 2
446 # Freephone lines
447 TOLL_FREE = 3
448 PREMIUM_RATE = 4
449 # The cost of this call is shared between the caller and the recipient,
450 # and is hence typically less than PREMIUM_RATE calls. See
451 # http://en.wikipedia.org/wiki/Shared_Cost_Service for more information.
452 SHARED_COST = 5
453 # Voice over IP numbers. This includes TSoIP (Telephony Service over IP).
454 VOIP = 6
455 # A personal number is associated with a particular person, and may be
456 # routed to either a MOBILE or FIXED_LINE number. Some more information
457 # can be found here: http://en.wikipedia.org/wiki/Personal_Numbers
458 PERSONAL_NUMBER = 7
459 PAGER = 8
460 # Used for "Universal Access Numbers" or "Company Numbers". They may be
461 # further routed to specific offices, but allow one number to be used for
462 # a company.
463 UAN = 9
464 # Used for "Voice Mail Access Numbers".
465 VOICEMAIL = 10
466 # A phone number is of type UNKNOWN when it does not fit any of the known
467 # patterns for a specific region.
468 UNKNOWN = 99
470 @classmethod
471 def values(cls):
472 return (PhoneNumberType.FIXED_LINE,
473 PhoneNumberType.MOBILE,
474 PhoneNumberType.FIXED_LINE_OR_MOBILE,
475 PhoneNumberType.TOLL_FREE,
476 PhoneNumberType.PREMIUM_RATE,
477 PhoneNumberType.SHARED_COST,
478 PhoneNumberType.VOIP,
479 PhoneNumberType.PERSONAL_NUMBER,
480 PhoneNumberType.PAGER,
481 PhoneNumberType.UAN,
482 PhoneNumberType.VOICEMAIL,
483 PhoneNumberType.UNKNOWN)
485 @classmethod
486 def to_string(cls, val):
487 """Return a string representation of a PhoneNumberType value"""
488 if val == PhoneNumberType.FIXED_LINE:
489 return u("FIXED_LINE")
490 elif val == PhoneNumberType.MOBILE:
491 return u("MOBILE")
492 elif val == PhoneNumberType.FIXED_LINE_OR_MOBILE:
493 return u("FIXED_LINE_OR_MOBILE")
494 elif val == PhoneNumberType.TOLL_FREE:
495 return u("TOLL_FREE")
496 elif val == PhoneNumberType.PREMIUM_RATE:
497 return u("PREMIUM_RATE")
498 elif val == PhoneNumberType.SHARED_COST:
499 return u("SHARED_COST")
500 elif val == PhoneNumberType.VOIP:
501 return u("VOIP")
502 elif val == PhoneNumberType.PERSONAL_NUMBER:
503 return u("PERSONAL_NUMBER")
504 elif val == PhoneNumberType.PAGER:
505 return u("PAGER")
506 elif val == PhoneNumberType.UAN:
507 return u("UAN")
508 elif val == PhoneNumberType.VOICEMAIL:
509 return u("VOICEMAIL")
510 elif val == PhoneNumberType.UNKNOWN:
511 return u("UNKNOWN")
512 else:
513 return u("INVALID (%d)" % val)
516class MatchType(object):
517 """Types of phone number matches."""
518 # Not a telephone number
519 NOT_A_NUMBER = 0
520 # None of the match types below apply
521 NO_MATCH = 1
522 # Returns SHORT_NSN_MATCH if either or both has no region specified, or
523 # the region specified is the same, and one NSN could be a shorter version
524 # of the other number. This includes the case where one has an extension
525 # specified, and the other does not.
526 SHORT_NSN_MATCH = 2
527 # Either or both has no region specified, and the NSNs and extensions are
528 # the same.
529 NSN_MATCH = 3
530 # The country_code, NSN, presence of a leading zero for Italian numbers
531 # and any extension present are the same.
532 EXACT_MATCH = 4
534 @classmethod
535 def to_string(cls, val):
536 """Return a string representation of a MatchType value"""
537 if val == MatchType.NOT_A_NUMBER:
538 return u("NOT_A_NUMBER")
539 elif val == MatchType.NO_MATCH:
540 return u("NO_MATCH")
541 elif val == MatchType.SHORT_NSN_MATCH:
542 return u("SHORT_NSN_MATCH")
543 elif val == MatchType.NSN_MATCH:
544 return u("NSN_MATCH")
545 elif val == MatchType.EXACT_MATCH:
546 return u("EXACT_MATCH")
547 else:
548 return u("INVALID (%d)" % val)
551class ValidationResult(object):
552 """Possible outcomes when testing if a PhoneNumber is a possible number."""
553 # The number length matches that of valid numbers for this region.
554 IS_POSSIBLE = 0
555 # The number length matches that of local numbers for this region only
556 # (i.e. numbers that may be able to be dialled within an area, but do not
557 # have all the information to be dialled from anywhere inside or outside
558 # the country).
559 IS_POSSIBLE_LOCAL_ONLY = 4
560 # The number has an invalid country calling code.
561 INVALID_COUNTRY_CODE = 1
562 # The number is shorter than all valid numbers for this region.
563 TOO_SHORT = 2
564 # The number is longer than the shortest valid numbers for this region,
565 # shorter than the longest valid numbers for this region, and does not
566 # itself have a number length that matches valid numbers for this region.
567 # This can also be returned in the case where
568 # is_possible_number_for_type_with_reason was called, and there are no
569 # numbers of this type at all for this region.
570 INVALID_LENGTH = 5
571 # The number is longer than all valid numbers for this region.
572 TOO_LONG = 3
574 @classmethod
575 def to_string(cls, val):
576 """Return a string representation of a ValidationResult value"""
577 if val == ValidationResult.IS_POSSIBLE:
578 return u("IS_POSSIBLE")
579 elif val == ValidationResult.IS_POSSIBLE_LOCAL_ONLY:
580 return u("IS_POSSIBLE_LOCAL_ONLY")
581 elif val == ValidationResult.INVALID_COUNTRY_CODE:
582 return u("INVALID_COUNTRY_CODE")
583 elif val == ValidationResult.TOO_SHORT:
584 return u("TOO_SHORT")
585 elif val == ValidationResult.INVALID_LENGTH:
586 return u("INVALID_LENGTH")
587 elif val == ValidationResult.TOO_LONG:
588 return u("TOO_LONG")
589 else:
590 return u("INVALID (%d)" % val)
593# Derived data structures
594SUPPORTED_REGIONS = set()
595COUNTRY_CODES_FOR_NON_GEO_REGIONS = set()
596_NANPA_REGIONS = set()
599def _regenerate_derived_data():
600 global SUPPORTED_REGIONS, COUNTRY_CODES_FOR_NON_GEO_REGIONS, _NANPA_REGIONS
601 SUPPORTED_REGIONS.clear()
602 COUNTRY_CODES_FOR_NON_GEO_REGIONS.clear()
603 for cc, region_codes in COUNTRY_CODE_TO_REGION_CODE.items():
604 if (len(region_codes) == 1 and region_codes[0] == REGION_CODE_FOR_NON_GEO_ENTITY):
605 COUNTRY_CODES_FOR_NON_GEO_REGIONS.add(cc)
606 else:
607 SUPPORTED_REGIONS.update(region_codes)
608 if REGION_CODE_FOR_NON_GEO_ENTITY in SUPPORTED_REGIONS: # pragma no cover 608 ↛ 609line 608 didn't jump to line 609, because the condition on line 608 was never true
609 SUPPORTED_REGIONS.remove(REGION_CODE_FOR_NON_GEO_ENTITY)
610 _NANPA_REGIONS.clear()
611 _NANPA_REGIONS.update(COUNTRY_CODE_TO_REGION_CODE[_NANPA_COUNTRY_CODE])
614_regenerate_derived_data()
617def _copy_number_format(other):
618 """Return a mutable copy of the given NumberFormat object"""
619 copy = NumberFormat(pattern=other.pattern,
620 format=other.format,
621 leading_digits_pattern=list(other.leading_digits_pattern),
622 national_prefix_formatting_rule=other.national_prefix_formatting_rule,
623 national_prefix_optional_when_formatting=other.national_prefix_optional_when_formatting,
624 domestic_carrier_code_formatting_rule=other.domestic_carrier_code_formatting_rule)
625 copy._mutable = True
626 return copy
629def _extract_possible_number(number):
630 """Attempt to extract a possible number from the string passed in.
632 This currently strips all leading characters that cannot be used to
633 start a phone number. Characters that can be used to start a phone number
634 are defined in the VALID_START_CHAR_PATTERN. If none of these characters
635 are found in the number passed in, an empty string is returned. This
636 function also attempts to strip off any alternative extensions or endings
637 if two or more are present, such as in the case of: (530) 583-6985
638 x302/x2303. The second extension here makes this actually two phone
639 numbers, (530) 583-6985 x302 and (530) 583-6985 x2303. We remove the
640 second extension so that the first number is parsed correctly.
642 Arguments:
643 number -- The string that might contain a phone number.
645 Returns the number, stripped of any non-phone-number prefix (such
646 as "Tel:") or an empty string if no character used to start phone
647 numbers (such as + or any digit) is found in the number
648 """
649 match = _VALID_START_CHAR_PATTERN.search(number)
650 if match: 650 ↛ 662line 650 didn't jump to line 662, because the condition on line 650 was never false
651 number = number[match.start():]
652 # Remove trailing non-alpha non-numerical characters.
653 trailing_chars_match = _UNWANTED_END_CHAR_PATTERN.search(number)
654 if trailing_chars_match: 654 ↛ 655line 654 didn't jump to line 655, because the condition on line 654 was never true
655 number = number[:trailing_chars_match.start()]
656 # Check for extra numbers at the end.
657 second_number_match = _SECOND_NUMBER_START_PATTERN.search(number)
658 if second_number_match: 658 ↛ 659line 658 didn't jump to line 659, because the condition on line 658 was never true
659 number = number[:second_number_match.start()]
660 return number
661 else:
662 return U_EMPTY_STRING
665def _is_viable_phone_number(number):
666 """Checks to see if a string could possibly be a phone number.
668 At the moment, checks to see that the string begins with at least 2
669 digits, ignoring any punctuation commonly found in phone numbers. This
670 method does not require the number to be normalized in advance - but does
671 assume that leading non-number symbols have been removed, such as by the
672 method _extract_possible_number.
674 Arguments:
675 number -- string to be checked for viability as a phone number
677 Returns True if the number could be a phone number of some sort, otherwise
678 False
679 """
680 if len(number) < _MIN_LENGTH_FOR_NSN: 680 ↛ 681line 680 didn't jump to line 681, because the condition on line 680 was never true
681 return False
682 match = fullmatch(_VALID_PHONE_NUMBER_PATTERN, number)
683 return bool(match)
686def _normalize(number):
687 """Normalizes a string of characters representing a phone number.
689 This performs the following conversions:
690 - Punctuation is stripped.
691 - For ALPHA/VANITY numbers:
692 - Letters are converted to their numeric representation on a telephone
693 keypad. The keypad used here is the one defined in ITU
694 Recommendation E.161. This is only done if there are 3 or more
695 letters in the number, to lessen the risk that such letters are
696 typos.
697 - For other numbers:
698 - Wide-ascii digits are converted to normal ASCII (European) digits.
699 - Arabic-Indic numerals are converted to European numerals.
700 - Spurious alpha characters are stripped.
702 Arguments:
703 number -- string representing a phone number
705 Returns the normalized string version of the phone number.
706 """
707 m = fullmatch(_VALID_ALPHA_PHONE_PATTERN, number)
708 if m: 708 ↛ 709line 708 didn't jump to line 709, because the condition on line 708 was never true
709 return _normalize_helper(number, _ALPHA_PHONE_MAPPINGS, True)
710 else:
711 return normalize_digits_only(number)
714def normalize_digits_only(number, keep_non_digits=False):
715 """Normalizes a string of characters representing a phone number.
717 This converts wide-ascii and arabic-indic numerals to European numerals,
718 and strips punctuation and alpha characters (optional).
720 Arguments:
721 number -- a string representing a phone number
722 keep_non_digits -- whether to keep non-digits
724 Returns the normalized string version of the phone number.
725 """
726 number = unicod(number)
727 number_length = len(number)
728 normalized_digits = U_EMPTY_STRING
729 for ii in range(number_length):
730 d = unicode_digit(number[ii], -1)
731 if d != -1: 731 ↛ 733line 731 didn't jump to line 733, because the condition on line 731 was never false
732 normalized_digits += unicod(d)
733 elif keep_non_digits:
734 normalized_digits += number[ii]
735 return normalized_digits
738def normalize_diallable_chars_only(number):
739 """Normalizes a string of characters representing a phone number.
741 This strips all characters which are not diallable on a mobile phone
742 keypad (including all non-ASCII digits).
744 Arguments:
745 number -- a string of characters representing a phone number
747 Returns the normalized string version of the phone number.
748 """
749 return _normalize_helper(number, _DIALLABLE_CHAR_MAPPINGS, True)
752def convert_alpha_characters_in_number(number):
753 """Convert alpha chars in a number to their respective digits on a keypad,
754 but retains existing formatting."""
755 return _normalize_helper(number, _ALPHA_PHONE_MAPPINGS, False)
758def length_of_geographical_area_code(numobj):
759 """Return length of the geographical area code for a number.
761 Gets the length of the geographical area code from the PhoneNumber object
762 passed in, so that clients could use it to split a national significant
763 number into geographical area code and subscriber number. It works in such
764 a way that the resultant subscriber number should be diallable, at least
765 on some devices. An example of how this could be used:
767 >>> import phonenumbers
768 >>> numobj = phonenumbers.parse("16502530000", "US")
769 >>> nsn = phonenumbers.national_significant_number(numobj)
770 >>> ac_len = phonenumbers.length_of_geographical_area_code(numobj)
771 >>> if ac_len > 0:
772 ... area_code = nsn[:ac_len]
773 ... subscriber_number = nsn[ac_len:]
774 ... else:
775 ... area_code = ""
776 ... subscriber_number = nsn
778 N.B.: area code is a very ambiguous concept, so the I18N team generally
779 recommends against using it for most purposes, but recommends using the
780 more general national_number instead. Read the following carefully before
781 deciding to use this method:
783 - geographical area codes change over time, and this method honors those
784 changes; therefore, it doesn't guarantee the stability of the result it
785 produces.
786 - subscriber numbers may not be diallable from all devices (notably
787 mobile devices, which typically require the full national_number to be
788 dialled in most countries).
789 - most non-geographical numbers have no area codes, including numbers
790 from non-geographical entities.
791 - some geographical numbers have no area codes.
793 Arguments:
794 numobj -- The PhoneNumber object to find the length of the area code form.
796 Returns the length of area code of the PhoneNumber object passed in.
797 """
798 metadata = PhoneMetadata.metadata_for_region(region_code_for_number(numobj), None)
799 if metadata is None:
800 return 0
802 # If a country doesn't use a national prefix, and this number doesn't have
803 # an Italian leading zero, we assume it is a closed dialling plan with no
804 # area codes.
805 if metadata.national_prefix is None and not numobj.italian_leading_zero:
806 return 0
808 ntype = number_type(numobj)
809 country_code = numobj.country_code
810 if (ntype == PhoneNumberType.MOBILE and
811 (country_code in _GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES)):
812 # Note this is a rough heuristic; it doesn't cover Indonesia well, for
813 # example, where area codes are present for some mobile phones but not
814 # for others. We have no better way of representing this in the
815 # metadata at this point.
816 return 0
818 if not is_number_type_geographical(ntype, country_code):
819 return 0
821 return length_of_national_destination_code(numobj)
824def length_of_national_destination_code(numobj):
825 """Return length of the national destination code code for a number.
827 Gets the length of the national destination code (NDC) from the
828 PhoneNumber object passed in, so that clients could use it to split a
829 national significant number into NDC and subscriber number. The NDC of a
830 phone number is normally the first group of digit(s) right after the
831 country calling code when the number is formatted in the international
832 format, if there is a subscriber number part that follows.
834 N.B.: similar to an area code, not all numbers have an NDC!
836 An example of how this could be used:
838 >>> import phonenumbers
839 >>> numobj = phonenumbers.parse("18002530000", "US")
840 >>> nsn = phonenumbers.national_significant_number(numobj)
841 >>> ndc_len = phonenumbers.length_of_national_destination_code(numobj)
842 >>> if ndc_len > 0:
843 ... national_destination_code = nsn[:ndc_len]
844 ... subscriber_number = nsn[ndc_len:]
845 ... else:
846 ... national_destination_code = ""
847 ... subscriber_number = nsn
849 Refer to the unittests to see the difference between this function and
850 length_of_geographical_area_code.
852 Arguments:
853 numobj -- The PhoneNumber object to find the length of the NDC from.
855 Returns the length of NDC of the PhoneNumber object passed in, which
856 could be zero.
857 """
858 if numobj.extension is not None:
859 # We don't want to alter the object given to us, but we don't want to
860 # include the extension when we format it, so we copy it and clear the
861 # extension here.
862 copied_numobj = PhoneNumber()
863 copied_numobj.merge_from(numobj)
864 copied_numobj.extension = None
865 else:
866 copied_numobj = numobj
868 nsn = format_number(copied_numobj, PhoneNumberFormat.INTERNATIONAL)
869 number_groups = re.split(NON_DIGITS_PATTERN, nsn)
871 # The pattern will start with "+COUNTRY_CODE " so the first group will
872 # always be the empty string (before the + symbol) and the second group
873 # will be the country calling code. The third group will be area code if
874 # it is not the last group.
875 if len(number_groups) <= 3:
876 return 0
878 if number_type(numobj) == PhoneNumberType.MOBILE:
879 # For example Argentinian mobile numbers, when formatted in the
880 # international format, are in the form of +54 9 NDC XXXX... As a
881 # result, we take the length of the third group (NDC) and add the
882 # length of the second group (which is the mobile token), which also
883 # forms part of the national significant number. This assumes that
884 # the mobile token is always formatted separately from the rest of the
885 # phone number.
886 mobile_token = country_mobile_token(numobj.country_code)
887 if mobile_token != U_EMPTY_STRING:
888 return len(number_groups[2]) + len(number_groups[3])
889 return len(number_groups[2])
892def country_mobile_token(country_code):
893 """Returns the mobile token for the provided country calling code if it has one, otherwise
894 returns an empty string. A mobile token is a number inserted before the area code when dialing
895 a mobile number from that country from abroad.
897 Arguments:
898 country_code -- the country calling code for which we want the mobile token
899 Returns the mobile token, as a string, for the given country calling code.
900 """
901 return _MOBILE_TOKEN_MAPPINGS.get(country_code, U_EMPTY_STRING)
904def _normalize_helper(number, replacements, remove_non_matches):
905 """Normalizes a string of characters representing a phone number by
906 replacing all characters found in the accompanying map with the values
907 therein, and stripping all other characters if remove_non_matches is true.
909 Arguments:
910 number -- a string representing a phone number
911 replacements -- a mapping of characters to what they should be replaced
912 by in the normalized version of the phone number
913 remove_non_matches -- indicates whether characters that are not able to be
914 replaced should be stripped from the number. If this is False,
915 they will be left unchanged in the number.
917 Returns the normalized string version of the phone number.
918 """
919 normalized_number = []
920 for char in number:
921 new_digit = replacements.get(char.upper(), None)
922 if new_digit is not None:
923 normalized_number.append(new_digit)
924 elif not remove_non_matches:
925 normalized_number.append(char)
926 # If neither of the above are true, we remove this character
927 return U_EMPTY_STRING.join(normalized_number)
930def supported_calling_codes():
931 """Returns all country calling codes the library has metadata for, covering
932 both non-geographical entities (global network calling codes) and those
933 used for geographical entities. This could be used to populate a drop-down
934 box of country calling codes for a phone-number widget, for instance.
936 Returns an unordered set of the country calling codes for every geographica
937 and non-geographical entity the library supports.
938 """
939 return set(COUNTRY_CODE_TO_REGION_CODE.keys())
942def _desc_has_possible_number_data(desc):
944 """Returns true if there is any possible number data set for a particular PhoneNumberDesc."""
945 # If this is empty, it means numbers of this type inherit from the "general desc" -> the value
946 # "-1" means that no numbers exist for this type.
947 if desc is None:
948 return False
949 return len(desc.possible_length) != 1 or desc.possible_length[0] != -1
952# Note: desc_has_data must account for any of MetadataFilter's excludableChildFields potentially
953# being absent from the metadata. It must check them all. For any changes in descHasData, ensure
954# that all the excludableChildFields are still being checked. If your change is safe simply
955# mention why during a review without needing to change MetadataFilter.
956def _desc_has_data(desc):
957 """Returns true if there is any data set for a particular PhoneNumberDesc."""
958 if desc is None:
959 return False
960 # Checking most properties since we don't know what's present, since a custom build may have
961 # stripped just one of them (e.g. liteBuild strips exampleNumber). We don't bother checking the
962 # possibleLengthsLocalOnly, since if this is the only thing that's present we don't really
963 # support the type at all: no type-specific methods will work with only this data.
964 return ((desc.example_number is not None) or
965 _desc_has_possible_number_data(desc) or
966 (desc.national_number_pattern is not None))
969def _supported_types_for_metadata(metadata):
970 """Returns the types we have metadata for based on the PhoneMetadata object passed in, which must be non-None."""
971 numtypes = set()
972 for numtype in PhoneNumberType.values():
973 if numtype in (PhoneNumberType.FIXED_LINE_OR_MOBILE, PhoneNumberType.UNKNOWN):
974 # Never return FIXED_LINE_OR_MOBILE (it is a convenience type, and represents that a
975 # particular number type can't be determined) or UNKNOWN (the non-type).
976 continue
977 if _desc_has_data(_number_desc_by_type(metadata, numtype)):
978 numtypes.add(numtype)
979 return numtypes
982def supported_types_for_region(region_code):
983 """Returns the types for a given region which the library has metadata for.
985 Will not include FIXED_LINE_OR_MOBILE (if numbers in this region could
986 be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would
987 be present) and UNKNOWN.
989 No types will be returned for invalid or unknown region codes.
990 """
991 if not _is_valid_region_code(region_code):
992 return set()
993 metadata = PhoneMetadata.metadata_for_region(region_code.upper())
994 assert metadata is not None # due to _is_valid_region_code() check
995 return _supported_types_for_metadata(metadata)
998def supported_types_for_non_geo_entity(country_code):
999 """Returns the types for a country-code belonging to a non-geographical entity
1000 which the library has metadata for. Will not include FIXED_LINE_OR_MOBILE
1001 (if numbers for this non-geographical entity could be classified as
1002 FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would be present) and
1003 UNKNOWN.
1005 No types will be returned for country calling codes that do not map to a
1006 known non-geographical entity.
1007 """
1008 metadata = PhoneMetadata.metadata_for_nongeo_region(country_code, None)
1009 if metadata is None:
1010 return set()
1011 return _supported_types_for_metadata(metadata)
1014def _formatting_rule_has_first_group_only(national_prefix_formatting_rule):
1015 """Helper function to check if the national prefix formatting rule has the
1016 first group only, i.e., does not start with the national prefix.
1017 """
1018 if national_prefix_formatting_rule is None:
1019 return True
1020 return bool(fullmatch(_FIRST_GROUP_ONLY_PREFIX_PATTERN,
1021 national_prefix_formatting_rule))
1024def is_number_geographical(numobj):
1025 """Tests whether a phone number has a geographical association.
1027 It checks if the number is associated with a certain region in the country
1028 to which it belongs. Note that this doesn't verify if the number is
1029 actually in use.
1030 country_code -- the country calling code for which we want the mobile token
1031 """
1032 return is_number_type_geographical(number_type(numobj), numobj.country_code)
1035def is_number_type_geographical(num_type, country_code):
1036 """Tests whether a phone number has a geographical association,
1037 as represented by its type and the country it belongs to.
1039 This version of isNumberGeographical exists since calculating the phone
1040 number type is expensive; if we have already done this, we don't want to
1041 do it again.
1042 """
1043 return (num_type == PhoneNumberType.FIXED_LINE or
1044 num_type == PhoneNumberType.FIXED_LINE_OR_MOBILE or
1045 ((country_code in _GEO_MOBILE_COUNTRIES) and
1046 num_type == PhoneNumberType.MOBILE))
1049def _is_valid_region_code(region_code):
1050 """Helper function to check region code is not unknown or None"""
1051 if region_code is None: 1051 ↛ 1053line 1051 didn't jump to line 1053, because the condition on line 1051 was never false
1052 return False
1053 return (region_code in SUPPORTED_REGIONS)
1056def _has_valid_country_calling_code(country_calling_code):
1057 return (country_calling_code in COUNTRY_CODE_TO_REGION_CODE)
1060def format_number(numobj, num_format):
1061 """Formats a phone number in the specified format using default rules.
1063 Note that this does not promise to produce a phone number that the user
1064 can dial from where they are - although we do format in either 'national'
1065 or 'international' format depending on what the client asks for, we do not
1066 currently support a more abbreviated format, such as for users in the same
1067 "area" who could potentially dial the number without area code. Note that
1068 if the phone number has a country calling code of 0 or an otherwise
1069 invalid country calling code, we cannot work out which formatting rules to
1070 apply so we return the national significant number with no formatting
1071 applied.
1073 Arguments:
1074 numobj -- The phone number to be formatted.
1075 num_format -- The format the phone number should be formatted into
1077 Returns the formatted phone number.
1078 """
1079 if numobj.national_number == 0 and numobj.raw_input is not None: 1079 ↛ 1086line 1079 didn't jump to line 1086, because the condition on line 1079 was never true
1080 # Unparseable numbers that kept their raw input just use that. This
1081 # is the only case where a number can be formatted as E164 without a
1082 # leading '+' symbol (but the original number wasn't parseable
1083 # anyway).
1084 # TODO: Consider removing the 'if' above so that unparseable strings
1085 # without raw input format to the empty string instead of "+00".
1086 if len(numobj.raw_input) > 0:
1087 return numobj.raw_input
1088 country_calling_code = numobj.country_code
1089 nsn = national_significant_number(numobj)
1090 if num_format == PhoneNumberFormat.E164: 1090 ↛ 1095line 1090 didn't jump to line 1095, because the condition on line 1090 was never false
1091 # Early exit for E164 case (even if the country calling code is
1092 # invalid) since no formatting of the national number needs to be
1093 # applied. Extensions are not formatted.
1094 return _prefix_number_with_country_calling_code(country_calling_code, num_format, nsn)
1095 if not _has_valid_country_calling_code(country_calling_code):
1096 return nsn
1097 # Note region_code_for_country_code() is used because formatting
1098 # information for regions which share a country calling code is contained
1099 # by only one region for performance reasons. For example, for NANPA
1100 # regions it will be contained in the metadata for US.
1101 region_code = region_code_for_country_code(country_calling_code)
1102 # Metadata cannot be None because the country calling code is valid (which
1103 # means that the region code cannot be ZZ and must be one of our supported
1104 # region codes).
1105 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_calling_code, region_code.upper())
1106 formatted_number = _format_nsn(nsn, metadata, num_format)
1107 formatted_number = _maybe_append_formatted_extension(numobj,
1108 metadata,
1109 num_format,
1110 formatted_number)
1111 return _prefix_number_with_country_calling_code(country_calling_code,
1112 num_format,
1113 formatted_number)
1116def format_by_pattern(numobj, number_format, user_defined_formats):
1117 """Formats a phone number using client-defined formatting rules.
1119 Note that if the phone number has a country calling code of zero or an
1120 otherwise invalid country calling code, we cannot work out things like
1121 whether there should be a national prefix applied, or how to format
1122 extensions, so we return the national significant number with no
1123 formatting applied.
1125 Arguments:
1126 numobj -- The phone number to be formatted
1127 number_format -- The format the phone number should be formatted into,
1128 as a PhoneNumberFormat value.
1129 user_defined_formats -- formatting rules specified by clients, as a list
1130 of NumberFormat objects.
1132 Returns the formatted phone number.
1133 """
1134 country_code = numobj.country_code
1135 nsn = national_significant_number(numobj)
1136 if not _has_valid_country_calling_code(country_code):
1137 return nsn
1138 # Note region_code_for_country_code() is used because formatting
1139 # information for regions which share a country calling code is contained
1140 # by only one region for performance reasons. For example, for NANPA
1141 # regions it will be contained in the metadata for US.
1142 region_code = region_code_for_country_code(country_code)
1143 # Metadata cannot be None because the country calling code is valid.
1144 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
1146 formatted_number = U_EMPTY_STRING
1147 formatting_pattern = _choose_formatting_pattern_for_number(user_defined_formats, nsn)
1148 if formatting_pattern is None:
1149 # If no pattern above is matched, we format the number as a whole.
1150 formatted_number = nsn
1151 else:
1152 num_format_copy = _copy_number_format(formatting_pattern)
1153 # Before we do a replacement of the national prefix pattern $NP with
1154 # the national prefix, we need to copy the rule so that subsequent
1155 # replacements for different numbers have the appropriate national
1156 # prefix.
1157 np_formatting_rule = formatting_pattern.national_prefix_formatting_rule
1158 if np_formatting_rule:
1159 national_prefix = metadata.national_prefix
1160 if national_prefix:
1161 # Replace $NP with national prefix and $FG with the first
1162 # group (\1) matcher.
1163 np_formatting_rule = np_formatting_rule.replace(_NP_STRING, national_prefix)
1164 np_formatting_rule = np_formatting_rule.replace(_FG_STRING, unicod("\\1"))
1165 num_format_copy.national_prefix_formatting_rule = np_formatting_rule
1166 else:
1167 # We don't want to have a rule for how to format the national
1168 # prefix if there isn't one.
1169 num_format_copy.national_prefix_formatting_rule = None
1170 formatted_number = _format_nsn_using_pattern(nsn, num_format_copy, number_format)
1171 formatted_number = _maybe_append_formatted_extension(numobj,
1172 metadata,
1173 number_format,
1174 formatted_number)
1175 formatted_number = _prefix_number_with_country_calling_code(country_code,
1176 number_format,
1177 formatted_number)
1178 return formatted_number
1181def format_national_number_with_carrier_code(numobj, carrier_code):
1182 """Format a number in national format for dialing using the specified carrier.
1184 The carrier-code will always be used regardless of whether the phone
1185 number already has a preferred domestic carrier code stored. If
1186 carrier_code contains an empty string, returns the number in national
1187 format without any carrier code.
1189 Arguments:
1190 numobj -- The phone number to be formatted
1191 carrier_code -- The carrier selection code to be used
1193 Returns the formatted phone number in national format for dialing using
1194 the carrier as specified in the carrier_code.
1195 """
1196 country_code = numobj.country_code
1197 nsn = national_significant_number(numobj)
1198 if not _has_valid_country_calling_code(country_code):
1199 return nsn
1200 # Note region_code_for_country_code() is used because formatting
1201 # information for regions which share a country calling code is contained
1202 # by only one region for performance reasons. For example, for NANPA
1203 # regions it will be contained in the metadata for US.
1204 region_code = region_code_for_country_code(country_code)
1205 # Metadata cannot be None because the country calling code is valid
1206 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
1207 formatted_number = _format_nsn(nsn,
1208 metadata,
1209 PhoneNumberFormat.NATIONAL,
1210 carrier_code)
1211 formatted_number = _maybe_append_formatted_extension(numobj,
1212 metadata,
1213 PhoneNumberFormat.NATIONAL,
1214 formatted_number)
1215 formatted_number = _prefix_number_with_country_calling_code(country_code,
1216 PhoneNumberFormat.NATIONAL,
1217 formatted_number)
1218 return formatted_number
1221def format_national_number_with_preferred_carrier_code(numobj, fallback_carrier_code):
1222 """Formats a phone number in national format for dialing using the carrier
1223 as specified in the preferred_domestic_carrier_code field of the
1224 PhoneNumber object passed in. If that is missing, use the
1225 fallback_carrier_code passed in instead. If there is no
1226 preferred_domestic_carrier_code, and the fallback_carrier_code contains an
1227 empty string, return the number in national format without any carrier
1228 code.
1230 Use format_national_number_with_carrier_code instead if the carrier code
1231 passed in should take precedence over the number's
1232 preferred_domestic_carrier_code when formatting.
1234 Arguments:
1235 numobj -- The phone number to be formatted
1236 carrier_code -- The carrier selection code to be used, if none is found in the
1237 phone number itself.
1239 Returns the formatted phone number in national format for dialing using
1240 the number's preferred_domestic_carrier_code, or the fallback_carrier_code
1241 pass in if none is found.
1242 """
1243 # Historically, we set this to an empty string when parsing with raw input
1244 # if none was found in the input string. However, this doesn't result in a
1245 # number we can dial. For this reason, we treat the empty string the same
1246 # as if it isn't set at all.
1247 if (numobj.preferred_domestic_carrier_code is not None and
1248 len(numobj.preferred_domestic_carrier_code) > 0):
1249 carrier_code = numobj.preferred_domestic_carrier_code
1250 else:
1251 carrier_code = fallback_carrier_code
1252 return format_national_number_with_carrier_code(numobj, carrier_code)
1255def format_number_for_mobile_dialing(numobj, region_calling_from, with_formatting):
1256 """Returns a number formatted in such a way that it can be dialed from a
1257 mobile phone in a specific region.
1259 If the number cannot be reached from the region (e.g. some countries block
1260 toll-free numbers from being called outside of the country), the method
1261 returns an empty string.
1263 Arguments:
1264 numobj -- The phone number to be formatted
1265 region_calling_from -- The region where the call is being placed.
1267 with_formatting -- whether the number should be returned with formatting
1268 symbols, such as spaces and dashes.
1270 Returns the formatted phone number.
1271 """
1272 country_calling_code = numobj.country_code
1273 if not _has_valid_country_calling_code(country_calling_code):
1274 if numobj.raw_input is None:
1275 return U_EMPTY_STRING
1276 else:
1277 return numobj.raw_input
1278 formatted_number = U_EMPTY_STRING
1279 # Clear the extension, as that part cannot normally be dialed together with the main number.
1280 numobj_no_ext = PhoneNumber()
1281 numobj_no_ext.merge_from(numobj)
1282 numobj_no_ext.extension = None
1283 region_code = region_code_for_country_code(country_calling_code)
1284 numobj_type = number_type(numobj_no_ext)
1285 is_valid_number = (numobj_type != PhoneNumberType.UNKNOWN)
1286 if region_calling_from == region_code:
1287 is_fixed_line_or_mobile = ((numobj_type == PhoneNumberType.FIXED_LINE) or
1288 (numobj_type == PhoneNumberType.MOBILE) or
1289 (numobj_type == PhoneNumberType.FIXED_LINE_OR_MOBILE))
1290 # Carrier codes may be needed in some countries. We handle this here.
1291 if region_code == "BR" and is_fixed_line_or_mobile:
1292 # Historically, we set this to an empty string when parsing with
1293 # raw input if none was found in the input string. However, this
1294 # doesn't result in a number we can dial. For this reason, we
1295 # treat the empty string the same as if it isn't set at all.
1296 if (numobj_no_ext.preferred_domestic_carrier_code is not None and
1297 len(numobj_no_ext.preferred_domestic_carrier_code) > 0):
1298 formatted_number = format_national_number_with_preferred_carrier_code(numobj_no_ext, "")
1299 else:
1300 # Brazilian fixed line and mobile numbers need to be dialed with a
1301 # carrier code when called within Brazil. Without that, most of
1302 # the carriers won't connect the call. Because of that, we return
1303 # an empty string here.
1304 formatted_number = U_EMPTY_STRING
1305 elif country_calling_code == _NANPA_COUNTRY_CODE:
1306 # For NANPA countries, we output international format for numbers
1307 # that can be dialed internationally, since that always works,
1308 # except for numbers which might potentially be short numbers,
1309 # which are always dialled in national format.
1310 metadata = PhoneMetadata.metadata_for_region(region_calling_from)
1311 assert metadata is not None # due to _has_valid_country_calling_code() check
1312 if (can_be_internationally_dialled(numobj_no_ext) and
1313 _test_number_length(national_significant_number(numobj_no_ext),
1314 metadata) != ValidationResult.TOO_SHORT):
1315 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL)
1316 else:
1317 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL)
1318 else:
1319 # For non-geographical countries, and Mexican, Chilean, and Uzbek
1320 # fixed line and mobile numbers, we output international format for
1321 # numbers that can be dialed internationally as that always works.
1322 if ((region_code == REGION_CODE_FOR_NON_GEO_ENTITY or
1323 ((region_code == unicod("MX") or region_code == unicod("CL") or
1324 region_code == unicod("UZ")) and
1325 is_fixed_line_or_mobile)) and
1326 can_be_internationally_dialled(numobj_no_ext)):
1327 # MX fixed line and mobile numbers should always be formatted
1328 # in international format, even when dialed within MX. For
1329 # national format to work, a carrier code needs to be used,
1330 # and the correct carrier code depends on if the caller and
1331 # callee are from the same local area. It is trickier to get
1332 # that to work correctly than using international format,
1333 # which is tested to work fine on all carriers.
1334 # CL fixed line numbers need the national prefix when dialing
1335 # in the national format, but don't have it when used for
1336 # display. The reverse is true for mobile numbers. As a
1337 # result, we output them in the international format to make
1338 # it work.
1339 # UZ mobile and fixed-line numbers have to be formatted in
1340 # international format or prefixed with special codes like 03,
1341 # 04 (for fixed-line) and 05 (for mobile) for dialling
1342 # successfully from mobile devices. As we do not have complete
1343 # information on special codes and to be consistent with
1344 # formatting across all phone types we return the number in
1345 # international format here.
1346 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL)
1347 else:
1348 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL)
1349 elif is_valid_number and can_be_internationally_dialled(numobj_no_ext):
1350 # We assume that short numbers are not diallable from outside their
1351 # region, so if a number is not a valid regular length phone number,
1352 # we treat it as if it cannot be internationally dialled.
1353 if with_formatting:
1354 return format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL)
1355 else:
1356 return format_number(numobj_no_ext, PhoneNumberFormat.E164)
1358 if with_formatting:
1359 return formatted_number
1360 else:
1361 return normalize_diallable_chars_only(formatted_number)
1364def format_out_of_country_calling_number(numobj, region_calling_from):
1365 """Formats a phone number for out-of-country dialing purposes.
1367 If no region_calling_from is supplied, we format the number in its
1368 INTERNATIONAL format. If the country calling code is the same as that of
1369 the region where the number is from, then NATIONAL formatting will be
1370 applied.
1372 If the number itself has a country calling code of zero or an otherwise
1373 invalid country calling code, then we return the number with no formatting
1374 applied.
1376 Note this function takes care of the case for calling inside of NANPA and
1377 between Russia and Kazakhstan (who share the same country calling
1378 code). In those cases, no international prefix is used. For regions which
1379 have multiple international prefixes, the number in its INTERNATIONAL
1380 format will be returned instead.
1382 Arguments:
1383 numobj -- The phone number to be formatted
1384 region_calling_from -- The region where the call is being placed
1386 Returns the formatted phone number
1387 """
1388 if not _is_valid_region_code(region_calling_from):
1389 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL)
1390 country_code = numobj.country_code
1391 nsn = national_significant_number(numobj)
1392 if not _has_valid_country_calling_code(country_code):
1393 return nsn
1394 if country_code == _NANPA_COUNTRY_CODE:
1395 if is_nanpa_country(region_calling_from):
1396 # For NANPA regions, return the national format for these regions
1397 # but prefix it with the country calling code.
1398 return (unicod(country_code) + U_SPACE +
1399 format_number(numobj, PhoneNumberFormat.NATIONAL))
1400 elif country_code == country_code_for_valid_region(region_calling_from):
1401 # If regions share a country calling code, the country calling code
1402 # need not be dialled. This also applies when dialling within a
1403 # region, so this if clause covers both these cases. Technically this
1404 # is the case for dialling from La Reunion to other overseas
1405 # departments of France (French Guiana, Martinique, Guadeloupe), but
1406 # not vice versa - so we don't cover this edge case for now and for
1407 # those cases return the version including country calling code.
1408 # Details here:
1409 # http://www.petitfute.com/voyage/225-info-pratiques-reunion
1410 return format_number(numobj, PhoneNumberFormat.NATIONAL)
1412 # Metadata cannot be None because we checked '_is_valid_region_code()' above.
1413 metadata_for_region_calling_from = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_calling_from.upper())
1414 international_prefix = metadata_for_region_calling_from.international_prefix
1416 # In general, if there is a preferred international prefix, use that. Otherwise, for regions
1417 # that have multiple international prefixes, the international format of the number is
1418 # returned since we would not know which one to use.
1419 i18n_prefix_for_formatting = U_EMPTY_STRING
1420 if metadata_for_region_calling_from.preferred_international_prefix is not None:
1421 i18n_prefix_for_formatting = metadata_for_region_calling_from.preferred_international_prefix
1422 elif fullmatch(_SINGLE_INTERNATIONAL_PREFIX, international_prefix):
1423 i18n_prefix_for_formatting = international_prefix
1425 region_code = region_code_for_country_code(country_code)
1426 # Metadata cannot be None because the country calling code is valid.
1427 metadata_for_region = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code.upper())
1428 formatted_national_number = _format_nsn(nsn,
1429 metadata_for_region,
1430 PhoneNumberFormat.INTERNATIONAL)
1431 formatted_number = _maybe_append_formatted_extension(numobj,
1432 metadata_for_region,
1433 PhoneNumberFormat.INTERNATIONAL,
1434 formatted_national_number)
1435 if len(i18n_prefix_for_formatting) > 0:
1436 formatted_number = (i18n_prefix_for_formatting + U_SPACE +
1437 unicod(country_code) + U_SPACE + formatted_number)
1438 else:
1439 formatted_number = _prefix_number_with_country_calling_code(country_code,
1440 PhoneNumberFormat.INTERNATIONAL,
1441 formatted_number)
1442 return formatted_number
1445def format_in_original_format(numobj, region_calling_from):
1446 """Formats a phone number using the original phone number format
1447 (e.g. INTERNATIONAL or NATIONAL) that the number is parsed from, provided
1448 that the number has been parsed with parse_and_keep_raw_input. Otherwise the
1449 number will be formatted in NATIONAL format.
1451 The original format is embedded in the country_code_source field of the
1452 PhoneNumber object passed in, which is only set when parsing keeps the raw
1453 input. When we don't have a formatting pattern for the number, the method
1454 falls back to returning the raw input.
1456 Note this method guarantees no digit will be inserted, removed or modified
1457 as a result of formatting.
1459 Arguments:
1460 number -- The phone number that needs to be formatted in its original
1461 number format
1462 region_calling_from -- The region whose IDD needs to be prefixed if the
1463 original number has one.
1465 Returns the formatted phone number in its original number format.
1466 """
1467 if (numobj.raw_input is not None and not _has_formatting_pattern_for_number(numobj)):
1468 # We check if we have the formatting pattern because without that, we
1469 # might format the number as a group without national prefix.
1470 return numobj.raw_input
1471 if numobj.country_code_source is CountryCodeSource.UNSPECIFIED:
1472 return format_number(numobj, PhoneNumberFormat.NATIONAL)
1474 formatted_number = _format_original_allow_mods(numobj, region_calling_from)
1475 num_raw_input = numobj.raw_input
1476 # If no digit is inserted/removed/modified as a result of our formatting,
1477 # we return the formatted phone number; otherwise we return the raw input
1478 # the user entered.
1479 if (formatted_number is not None and num_raw_input):
1480 normalized_formatted_number = normalize_diallable_chars_only(formatted_number)
1481 normalized_raw_input = normalize_diallable_chars_only(num_raw_input)
1482 if normalized_formatted_number != normalized_raw_input:
1483 formatted_number = num_raw_input
1484 return formatted_number
1487def _format_original_allow_mods(numobj, region_calling_from):
1488 if (numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN):
1489 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL)
1490 elif numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITH_IDD:
1491 return format_out_of_country_calling_number(numobj, region_calling_from)
1492 elif (numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITHOUT_PLUS_SIGN):
1493 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL)[1:]
1494 else:
1495 region_code = region_code_for_country_code(numobj.country_code)
1496 # We strip non-digits from the NDD here, and from the raw input later, so that we can
1497 # compare them easily.
1498 national_prefix = ndd_prefix_for_region(region_code, True) # strip non-digits
1499 national_format = format_number(numobj, PhoneNumberFormat.NATIONAL)
1500 if (national_prefix is None or len(national_prefix) == 0):
1501 # If the region doesn't have a national prefix at all, we can
1502 # safely return the national format without worrying about a
1503 # national prefix being added.
1504 return national_format
1505 # Otherwise, we check if the original number was entered with a national prefix.
1506 if (_raw_input_contains_national_prefix(numobj.raw_input, national_prefix, region_code)):
1507 # If so, we can safely return the national format.
1508 return national_format
1509 # Metadata cannot be None here because ndd_prefix_for_region() (above) returns None if
1510 # there is no metadata for the region.
1511 metadata = PhoneMetadata.metadata_for_region(region_code)
1512 assert metadata is not None
1513 national_number = national_significant_number(numobj)
1514 format_rule = _choose_formatting_pattern_for_number(metadata.number_format, national_number)
1515 # The format rule could still be null here if the national number was
1516 # 0 and there was no raw input (this should not be possible for
1517 # numbers generated by the phonenumber library as they would also not
1518 # have a country calling code and we would have exited earlier).
1519 if format_rule is None:
1520 return national_format
1521 # When the format we apply to this number doesn't contain national
1522 # prefix, we can just return the national format.
1523 # TODO: Refactor the code below with the code in isNationalPrefixPresentIfRequired.
1524 candidate_national_prefix_rule = format_rule.national_prefix_formatting_rule
1525 # We assume that the first-group symbol will never be _before_ the national prefix.
1526 if candidate_national_prefix_rule is None:
1527 return national_format
1528 index_of_first_group = candidate_national_prefix_rule.find("\\1")
1529 if (index_of_first_group <= 0):
1530 return national_format
1531 candidate_national_prefix_rule = candidate_national_prefix_rule[:index_of_first_group]
1532 candidate_national_prefix_rule = normalize_digits_only(candidate_national_prefix_rule)
1533 if len(candidate_national_prefix_rule) == 0:
1534 # National prefix not used when formatting this number.
1535 return national_format
1536 # Otherwise, we need to remove the national prefix from our output.
1537 new_format_rule = _copy_number_format(format_rule)
1538 new_format_rule.national_prefix_formatting_rule = None
1539 return format_by_pattern(numobj, PhoneNumberFormat.NATIONAL, [new_format_rule])
1542def _raw_input_contains_national_prefix(raw_input, national_prefix, region_code):
1543 """Check if raw_input, which is assumed to be in the national format, has a
1544 national prefix. The national prefix is assumed to be in digits-only
1545 form."""
1546 nnn = normalize_digits_only(raw_input)
1547 if nnn.startswith(national_prefix):
1548 try:
1549 # Some Japanese numbers (e.g. 00777123) might be mistaken to
1550 # contain the national prefix when written without it
1551 # (e.g. 0777123) if we just do prefix matching. To tackle that, we
1552 # check the validity of the number if the assumed national prefix
1553 # is removed (777123 won't be valid in Japan).
1554 return is_valid_number(parse(nnn[len(national_prefix):], region_code))
1555 except NumberParseException:
1556 return False
1557 return False
1560def _has_formatting_pattern_for_number(numobj):
1561 country_code = numobj.country_code
1562 phone_number_region = region_code_for_country_code(country_code)
1563 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, phone_number_region)
1564 if metadata is None:
1565 return False
1566 national_number = national_significant_number(numobj)
1567 format_rule = _choose_formatting_pattern_for_number(metadata.number_format, national_number)
1568 return format_rule is not None
1571def format_out_of_country_keeping_alpha_chars(numobj, region_calling_from):
1572 """Formats a phone number for out-of-country dialing purposes.
1574 Note that in this version, if the number was entered originally using
1575 alpha characters and this version of the number is stored in raw_input,
1576 this representation of the number will be used rather than the digit
1577 representation. Grouping information, as specified by characters such as
1578 "-" and " ", will be retained.
1580 Caveats:
1582 - This will not produce good results if the country calling code is both
1583 present in the raw input _and_ is the start of the national
1584 number. This is not a problem in the regions which typically use alpha
1585 numbers.
1587 - This will also not produce good results if the raw input has any
1588 grouping information within the first three digits of the national
1589 number, and if the function needs to strip preceding digits/words in
1590 the raw input before these digits. Normally people group the first
1591 three digits together so this is not a huge problem - and will be fixed
1592 if it proves to be so.
1594 Arguments:
1595 numobj -- The phone number that needs to be formatted.
1596 region_calling_from -- The region where the call is being placed.
1598 Returns the formatted phone number
1599 """
1600 num_raw_input = numobj.raw_input
1601 # If there is no raw input, then we can't keep alpha characters because there aren't any.
1602 # In this case, we return format_out_of_country_calling_number.
1603 if num_raw_input is None or len(num_raw_input) == 0:
1604 return format_out_of_country_calling_number(numobj, region_calling_from)
1605 country_code = numobj.country_code
1606 if not _has_valid_country_calling_code(country_code):
1607 return num_raw_input
1608 # Strip any prefix such as country calling code, IDD, that was present. We
1609 # do this by comparing the number in raw_input with the parsed number. To
1610 # do this, first we normalize punctuation. We retain number grouping
1611 # symbols such as " " only.
1612 num_raw_input = _normalize_helper(num_raw_input,
1613 _ALL_PLUS_NUMBER_GROUPING_SYMBOLS,
1614 True)
1615 # Now we trim everything before the first three digits in the parsed
1616 # number. We choose three because all valid alpha numbers have 3 digits at
1617 # the start - if it does not, then we don't trim anything at
1618 # all. Similarly, if the national number was less than three digits, we
1619 # don't trim anything at all.
1620 national_number = national_significant_number(numobj)
1621 if len(national_number) > 3:
1622 first_national_number_digit = num_raw_input.find(national_number[:3])
1623 if first_national_number_digit != -1:
1624 num_raw_input = num_raw_input[first_national_number_digit:]
1626 metadata_for_region_calling_from = PhoneMetadata.metadata_for_region(region_calling_from.upper(), None)
1627 if country_code == _NANPA_COUNTRY_CODE:
1628 if is_nanpa_country(region_calling_from):
1629 return unicod(country_code) + U_SPACE + num_raw_input
1630 elif (metadata_for_region_calling_from is not None and
1631 country_code == country_code_for_region(region_calling_from)):
1632 formatting_pattern = _choose_formatting_pattern_for_number(metadata_for_region_calling_from.number_format,
1633 national_number)
1634 if formatting_pattern is None:
1635 # If no pattern above is matched, we format the original input
1636 return num_raw_input
1637 new_format = _copy_number_format(formatting_pattern)
1638 # The first group is the first group of digits that the user
1639 # wrote together.
1640 new_format.pattern = u("(\\d+)(.*)")
1641 # Here we just concatenate them back together after the national
1642 # prefix has been fixed.
1643 new_format.format = u(r"\1\2")
1644 # Now we format using this pattern instead of the default pattern,
1645 # but with the national prefix prefixed if necessary.
1646 # This will not work in the cases where the pattern (and not the
1647 # leading digits) decide whether a national prefix needs to be used,
1648 # since we have overridden the pattern to match anything, but that is
1649 # not the case in the metadata to date.
1650 return _format_nsn_using_pattern(num_raw_input,
1651 new_format,
1652 PhoneNumberFormat.NATIONAL)
1653 i18n_prefix_for_formatting = U_EMPTY_STRING
1654 # If an unsupported region-calling-from is entered, or a country with
1655 # multiple international prefixes, the international format of the number
1656 # is returned, unless there is a preferred international prefix.
1657 if metadata_for_region_calling_from is not None:
1658 international_prefix = metadata_for_region_calling_from.international_prefix
1659 i18n_match = fullmatch(_SINGLE_INTERNATIONAL_PREFIX, international_prefix)
1660 if i18n_match:
1661 i18n_prefix_for_formatting = international_prefix
1662 else:
1663 i18n_prefix_for_formatting = metadata_for_region_calling_from.preferred_international_prefix
1665 region_code = region_code_for_country_code(country_code)
1666 # Metadata cannot be None because the country calling code is valid.
1667 metadata_for_region = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
1668 formatted_number = _maybe_append_formatted_extension(numobj,
1669 metadata_for_region,
1670 PhoneNumberFormat.INTERNATIONAL,
1671 num_raw_input)
1672 if i18n_prefix_for_formatting:
1673 formatted_number = (i18n_prefix_for_formatting + U_SPACE +
1674 unicod(country_code) + U_SPACE + formatted_number)
1675 else:
1676 # Invalid region entered as country-calling-from (so no metadata was
1677 # found for it) or the region chosen has multiple international
1678 # dialling prefixes.
1679 formatted_number = _prefix_number_with_country_calling_code(country_code,
1680 PhoneNumberFormat.INTERNATIONAL,
1681 formatted_number)
1682 return formatted_number
1685def national_significant_number(numobj):
1686 """Gets the national significant number of a phone number.
1688 Note that a national significant number doesn't contain a national prefix
1689 or any formatting.
1691 Arguments:
1692 numobj -- The PhoneNumber object for which the national significant number
1693 is needed.
1695 Returns the national significant number of the PhoneNumber object passed
1696 in.
1697 """
1698 # If leading zero(s) have been set, we prefix this now. Note this is not a
1699 # national prefix.
1700 national_number = U_EMPTY_STRING
1701 if numobj.italian_leading_zero: 1701 ↛ 1702line 1701 didn't jump to line 1702, because the condition on line 1701 was never true
1702 num_zeros = numobj.number_of_leading_zeros
1703 if num_zeros is None:
1704 num_zeros = 1
1705 if num_zeros > 0:
1706 national_number = U_ZERO * num_zeros
1707 national_number += str(numobj.national_number)
1708 return national_number
1711def _prefix_number_with_country_calling_code(country_code, num_format, formatted_number):
1712 """A helper function that is used by format_number and format_by_pattern."""
1713 if num_format == PhoneNumberFormat.E164: 1713 ↛ 1715line 1713 didn't jump to line 1715, because the condition on line 1713 was never false
1714 return _PLUS_SIGN + unicod(country_code) + formatted_number
1715 elif num_format == PhoneNumberFormat.INTERNATIONAL:
1716 return _PLUS_SIGN + unicod(country_code) + U_SPACE + formatted_number
1717 elif num_format == PhoneNumberFormat.RFC3966:
1718 return _RFC3966_PREFIX + _PLUS_SIGN + unicod(country_code) + U_DASH + formatted_number
1719 else:
1720 return formatted_number
1723def _format_nsn(number, metadata, num_format, carrier_code=None):
1724 """Format a national number."""
1725 # Note in some regions, the national number can be written in two
1726 # completely different ways depending on whether it forms part of the
1727 # NATIONAL format or INTERNATIONAL format. The num_format parameter here
1728 # is used to specify which format to use for those cases. If a carrier_code
1729 # is specified, this will be inserted into the formatted string to replace
1730 # $CC.
1731 intl_number_formats = metadata.intl_number_format
1733 # When the intl_number_formats exists, we use that to format national
1734 # number for the INTERNATIONAL format instead of using the
1735 # number_desc.number_formats.
1736 if (len(intl_number_formats) == 0 or
1737 num_format == PhoneNumberFormat.NATIONAL):
1738 available_formats = metadata.number_format
1739 else:
1740 available_formats = metadata.intl_number_format
1741 formatting_pattern = _choose_formatting_pattern_for_number(available_formats, number)
1742 if formatting_pattern is None:
1743 return number
1744 else:
1745 return _format_nsn_using_pattern(number, formatting_pattern, num_format, carrier_code)
1748def _choose_formatting_pattern_for_number(available_formats, national_number):
1749 for num_format in available_formats:
1750 size = len(num_format.leading_digits_pattern)
1751 # We always use the last leading_digits_pattern, as it is the most detailed.
1752 if size > 0:
1753 ld_pattern = re.compile(num_format.leading_digits_pattern[-1])
1754 ld_match = ld_pattern.match(national_number)
1755 if size == 0 or ld_match:
1756 format_pattern = re.compile(num_format.pattern)
1757 if fullmatch(format_pattern, national_number):
1758 return num_format
1759 return None
1762def _format_nsn_using_pattern(national_number, formatting_pattern, number_format,
1763 carrier_code=None):
1764 # Note that carrier_code is optional - if None or an empty string, no
1765 # carrier code replacement will take place.
1766 number_format_rule = formatting_pattern.format
1767 m_re = re.compile(formatting_pattern.pattern)
1768 formatted_national_number = U_EMPTY_STRING
1770 if (number_format == PhoneNumberFormat.NATIONAL and carrier_code and
1771 formatting_pattern.domestic_carrier_code_formatting_rule):
1772 # Replace the $CC in the formatting rule with the desired
1773 # carrier code.
1774 cc_format_rule = formatting_pattern.domestic_carrier_code_formatting_rule
1775 cc_format_rule = cc_format_rule.replace(_CC_STRING, carrier_code)
1777 # Now replace the $FG in the formatting rule with the
1778 # first group and the carrier code combined in the
1779 # appropriate way.
1780 number_format_rule = re.sub(_FIRST_GROUP_PATTERN,
1781 cc_format_rule,
1782 number_format_rule,
1783 count=1)
1784 formatted_national_number = re.sub(m_re, number_format_rule, national_number)
1785 else:
1786 # Use the national prefix formatting rule instead.
1787 national_prefix_formatting_rule = formatting_pattern.national_prefix_formatting_rule
1788 if (number_format == PhoneNumberFormat.NATIONAL and
1789 national_prefix_formatting_rule):
1790 first_group_rule = re.sub(_FIRST_GROUP_PATTERN,
1791 national_prefix_formatting_rule,
1792 number_format_rule,
1793 count=1)
1794 formatted_national_number = re.sub(m_re, first_group_rule, national_number)
1795 else:
1796 formatted_national_number = re.sub(m_re, number_format_rule, national_number)
1798 if number_format == PhoneNumberFormat.RFC3966:
1799 # Strip any leading punctuation.
1800 m = _SEPARATOR_PATTERN.match(formatted_national_number)
1801 if m:
1802 formatted_national_number = re.sub(_SEPARATOR_PATTERN, U_EMPTY_STRING, formatted_national_number, count=1)
1803 # Replace the rest with a dash between each number group
1804 formatted_national_number = re.sub(_SEPARATOR_PATTERN, U_DASH, formatted_national_number)
1806 return formatted_national_number
1809def example_number(region_code):
1810 """Gets a valid number for the specified region.
1812 Arguments:
1813 region_code -- The region for which an example number is needed.
1815 Returns a valid fixed-line number for the specified region. Returns None
1816 when the metadata does not contain such information, or the region 001 is
1817 passed in. For 001 (representing non-geographical numbers), call
1818 example_number_for_non_geo_entity instead.
1819 """
1820 return example_number_for_type(region_code, PhoneNumberType.FIXED_LINE)
1823def invalid_example_number(region_code):
1824 """Gets an invalid number for the specified region.
1826 This is useful for unit-testing purposes, where you want to test what
1827 will happen with an invalid number. Note that the number that is
1828 returned will always be able to be parsed and will have the correct
1829 country code. It may also be a valid *short* number/code for this
1830 region. Validity checking such numbers is handled with shortnumberinfo.
1832 Arguments:
1833 region_code -- The region for which an example number is needed.
1836 Returns an invalid number for the specified region. Returns None when an
1837 unsupported region or the region 001 (Earth) is passed in.
1838 """
1839 if not _is_valid_region_code(region_code):
1840 return None
1841 # We start off with a valid fixed-line number since every country
1842 # supports this. Alternatively we could start with a different number
1843 # type, since fixed-line numbers typically have a wide breadth of valid
1844 # number lengths and we may have to make it very short before we get an
1845 # invalid number.
1846 metadata = PhoneMetadata.metadata_for_region(region_code.upper())
1847 assert metadata is not None # due to _is_valid_region_code() check
1848 desc = _number_desc_by_type(metadata, PhoneNumberType.FIXED_LINE)
1849 if desc is None or desc.example_number is None:
1850 # This shouldn't happen; we have a test for this.
1851 return None # pragma no cover
1852 example_number = desc.example_number
1853 # Try and make the number invalid. We do this by changing the length. We
1854 # try reducing the length of the number, since currently no region has a
1855 # number that is the same length as MIN_LENGTH_FOR_NSN. This is probably
1856 # quicker than making the number longer, which is another
1857 # alternative. We could also use the possible number pattern to extract
1858 # the possible lengths of the number to make this faster, but this
1859 # method is only for unit-testing so simplicity is preferred to
1860 # performance. We don't want to return a number that can't be parsed,
1861 # so we check the number is long enough. We try all possible lengths
1862 # because phone number plans often have overlapping prefixes so the
1863 # number 123456 might be valid as a fixed-line number, and 12345 as a
1864 # mobile number. It would be faster to loop in a different order, but we
1865 # prefer numbers that look closer to real numbers (and it gives us a
1866 # variety of different lengths for the resulting phone numbers -
1867 # otherwise they would all be MIN_LENGTH_FOR_NSN digits long.)
1868 phone_number_length = len(example_number) - 1
1869 while phone_number_length >= _MIN_LENGTH_FOR_NSN:
1870 number_to_try = example_number[:phone_number_length]
1871 try:
1872 possibly_valid_number = parse(number_to_try, region_code)
1873 if not is_valid_number(possibly_valid_number):
1874 return possibly_valid_number
1875 except NumberParseException: # pragma no cover
1876 # Shouldn't happen: we have already checked the length, we know
1877 # example numbers have only valid digits, and we know the region
1878 # code is fine.
1879 pass
1880 phone_number_length -= 1
1882 # We have a test to check that this doesn't happen for any of our
1883 # supported regions.
1884 return None # pragma no cover
1887def example_number_for_type(region_code, num_type):
1888 """Gets a valid number for the specified region and number type.
1890 If None is given as the region_code, then the returned number object
1891 may belong to any country.
1893 Arguments:
1894 region_code -- The region for which an example number is needed, or None.
1895 num_type -- The type of number that is needed.
1897 Returns a valid number for the specified region and type. Returns None
1898 when the metadata does not contain such information or if an invalid
1899 region or region 001 was specified. For 001 (representing
1900 non-geographical numbers), call example_number_for_non_geo_entity instead.
1901 """
1902 if region_code is None:
1903 return _example_number_anywhere_for_type(num_type)
1904 # Check the region code is valid.
1905 if not _is_valid_region_code(region_code):
1906 return None
1907 metadata = PhoneMetadata.metadata_for_region(region_code.upper())
1908 assert metadata is not None # due to _is_valid_region_code() check
1909 desc = _number_desc_by_type(metadata, num_type)
1910 if desc is not None and desc.example_number is not None:
1911 try:
1912 return parse(desc.example_number, region_code)
1913 except NumberParseException: # pragma no cover
1914 pass
1915 return None
1918def _example_number_anywhere_for_type(num_type):
1919 """Gets a valid number for the specified number type (it may belong to any country).
1921 Arguments:
1922 num_type -- The type of number that is needed.
1924 Returns a valid number for the specified type. Returns None when the
1925 metadata does not contain such information. This should only happen when
1926 no numbers of this type are allocated anywhere in the world anymore.
1927 """
1928 for region_code in SUPPORTED_REGIONS:
1929 example_numobj = example_number_for_type(region_code, num_type)
1930 if example_numobj is not None:
1931 return example_numobj
1932 # If there wasn't an example number for a region, try the non-geographical entities.
1933 for country_calling_code in COUNTRY_CODES_FOR_NON_GEO_REGIONS:
1934 metadata = PhoneMetadata.metadata_for_nongeo_region(country_calling_code, None)
1935 desc = _number_desc_by_type(metadata, num_type)
1936 if desc is not None and desc.example_number is not None:
1937 try:
1938 return parse(_PLUS_SIGN + unicod(country_calling_code) + desc.example_number, UNKNOWN_REGION)
1939 except NumberParseException: # pragma no cover
1940 pass
1942 # There are no example numbers of this type for any country in the library.
1943 return None # pragma no cover
1946def example_number_for_non_geo_entity(country_calling_code):
1947 """Gets a valid number for the specified country calling code for a non-geographical entity.
1949 Arguments:
1950 country_calling_code -- The country calling code for a non-geographical entity.
1952 Returns a valid number for the non-geographical entity. Returns None when
1953 the metadata does not contain such information, or the country calling
1954 code passed in does not belong to a non-geographical entity.
1955 """
1956 metadata = PhoneMetadata.metadata_for_nongeo_region(country_calling_code, None)
1957 if metadata is not None:
1958 # For geographical entities, fixed-line data is always present. However, for non-geographical
1959 # entities, this is not the case, so we have to go through different types to find the
1960 # example number. We don't check fixed-line or personal number since they aren't used by
1961 # non-geographical entities (if this changes, a unit-test will catch this.)
1962 for desc in (metadata.mobile, metadata.toll_free, metadata.shared_cost, metadata.voip,
1963 metadata.voicemail, metadata.uan, metadata.premium_rate):
1964 try:
1965 if (desc is not None and desc.example_number is not None):
1966 return parse(_PLUS_SIGN + unicod(country_calling_code) + desc.example_number, UNKNOWN_REGION)
1967 except NumberParseException:
1968 pass
1969 return None
1972def _maybe_append_formatted_extension(numobj, metadata, num_format, number):
1973 """Appends the formatted extension of a phone number to formatted number,
1974 if the phone number had an extension specified.
1975 """
1976 if numobj.extension:
1977 if num_format == PhoneNumberFormat.RFC3966:
1978 return number + _RFC3966_EXTN_PREFIX + numobj.extension
1979 else:
1980 if metadata.preferred_extn_prefix is not None:
1981 return number + metadata.preferred_extn_prefix + numobj.extension
1982 else:
1983 return number + _DEFAULT_EXTN_PREFIX + numobj.extension
1984 return number
1987def _number_desc_by_type(metadata, num_type):
1988 """Return the PhoneNumberDesc of the metadata for the given number type"""
1989 if num_type == PhoneNumberType.PREMIUM_RATE: 1989 ↛ 1990line 1989 didn't jump to line 1990, because the condition on line 1989 was never true
1990 return metadata.premium_rate
1991 elif num_type == PhoneNumberType.TOLL_FREE: 1991 ↛ 1992line 1991 didn't jump to line 1992, because the condition on line 1991 was never true
1992 return metadata.toll_free
1993 elif num_type == PhoneNumberType.MOBILE: 1993 ↛ 1994line 1993 didn't jump to line 1994, because the condition on line 1993 was never true
1994 return metadata.mobile
1995 elif (num_type == PhoneNumberType.FIXED_LINE or 1995 ↛ 1997line 1995 didn't jump to line 1997, because the condition on line 1995 was never true
1996 num_type == PhoneNumberType.FIXED_LINE_OR_MOBILE):
1997 return metadata.fixed_line
1998 elif num_type == PhoneNumberType.SHARED_COST: 1998 ↛ 1999line 1998 didn't jump to line 1999, because the condition on line 1998 was never true
1999 return metadata.shared_cost
2000 elif num_type == PhoneNumberType.VOIP: 2000 ↛ 2001line 2000 didn't jump to line 2001, because the condition on line 2000 was never true
2001 return metadata.voip
2002 elif num_type == PhoneNumberType.PERSONAL_NUMBER: 2002 ↛ 2003line 2002 didn't jump to line 2003, because the condition on line 2002 was never true
2003 return metadata.personal_number
2004 elif num_type == PhoneNumberType.PAGER: 2004 ↛ 2005line 2004 didn't jump to line 2005, because the condition on line 2004 was never true
2005 return metadata.pager
2006 elif num_type == PhoneNumberType.UAN: 2006 ↛ 2007line 2006 didn't jump to line 2007, because the condition on line 2006 was never true
2007 return metadata.uan
2008 elif num_type == PhoneNumberType.VOICEMAIL: 2008 ↛ 2009line 2008 didn't jump to line 2009, because the condition on line 2008 was never true
2009 return metadata.voicemail
2010 else:
2011 return metadata.general_desc
2014def number_type(numobj):
2015 """Gets the type of a valid phone number.
2017 Arguments:
2018 numobj -- The PhoneNumber object that we want to know the type of.
2020 Returns the type of the phone number, as a PhoneNumberType value;
2021 returns PhoneNumberType.UNKNOWN if it is invalid.
2022 """
2023 region_code = region_code_for_number(numobj)
2024 metadata = PhoneMetadata.metadata_for_region_or_calling_code(numobj.country_code, region_code)
2025 if metadata is None:
2026 return PhoneNumberType.UNKNOWN
2027 national_number = national_significant_number(numobj)
2028 return _number_type_helper(national_number, metadata)
2031def _number_type_helper(national_number, metadata):
2032 """Return the type of the given number against the metadata"""
2033 if not _is_number_matching_desc(national_number, metadata.general_desc): 2033 ↛ 2034line 2033 didn't jump to line 2034, because the condition on line 2033 was never true
2034 return PhoneNumberType.UNKNOWN
2035 if _is_number_matching_desc(national_number, metadata.premium_rate): 2035 ↛ 2036line 2035 didn't jump to line 2036, because the condition on line 2035 was never true
2036 return PhoneNumberType.PREMIUM_RATE
2037 if _is_number_matching_desc(national_number, metadata.toll_free): 2037 ↛ 2038line 2037 didn't jump to line 2038, because the condition on line 2037 was never true
2038 return PhoneNumberType.TOLL_FREE
2039 if _is_number_matching_desc(national_number, metadata.shared_cost): 2039 ↛ 2040line 2039 didn't jump to line 2040, because the condition on line 2039 was never true
2040 return PhoneNumberType.SHARED_COST
2041 if _is_number_matching_desc(national_number, metadata.voip): 2041 ↛ 2042line 2041 didn't jump to line 2042, because the condition on line 2041 was never true
2042 return PhoneNumberType.VOIP
2043 if _is_number_matching_desc(national_number, metadata.personal_number): 2043 ↛ 2044line 2043 didn't jump to line 2044, because the condition on line 2043 was never true
2044 return PhoneNumberType.PERSONAL_NUMBER
2045 if _is_number_matching_desc(national_number, metadata.pager): 2045 ↛ 2046line 2045 didn't jump to line 2046, because the condition on line 2045 was never true
2046 return PhoneNumberType.PAGER
2047 if _is_number_matching_desc(national_number, metadata.uan): 2047 ↛ 2048line 2047 didn't jump to line 2048, because the condition on line 2047 was never true
2048 return PhoneNumberType.UAN
2049 if _is_number_matching_desc(national_number, metadata.voicemail): 2049 ↛ 2050line 2049 didn't jump to line 2050, because the condition on line 2049 was never true
2050 return PhoneNumberType.VOICEMAIL
2052 if _is_number_matching_desc(national_number, metadata.fixed_line): 2052 ↛ 2061line 2052 didn't jump to line 2061, because the condition on line 2052 was never false
2053 if metadata.same_mobile_and_fixed_line_pattern: 2053 ↛ 2054line 2053 didn't jump to line 2054, because the condition on line 2053 was never true
2054 return PhoneNumberType.FIXED_LINE_OR_MOBILE
2055 elif _is_number_matching_desc(national_number, metadata.mobile): 2055 ↛ 2057line 2055 didn't jump to line 2057, because the condition on line 2055 was never false
2056 return PhoneNumberType.FIXED_LINE_OR_MOBILE
2057 return PhoneNumberType.FIXED_LINE
2059 # Otherwise, test to see if the number is mobile. Only do this if certain
2060 # that the patterns for mobile and fixed line aren't the same.
2061 if (not metadata.same_mobile_and_fixed_line_pattern and
2062 _is_number_matching_desc(national_number, metadata.mobile)):
2063 return PhoneNumberType.MOBILE
2064 return PhoneNumberType.UNKNOWN
2067def _is_number_matching_desc(national_number, number_desc):
2068 """Determine if the number matches the given PhoneNumberDesc"""
2069 # Check if any possible number lengths are present; if so, we use them to avoid checking the
2070 # validation pattern if they don't match. If they are absent, this means they match the general
2071 # description, which we have already checked before checking a specific number type.
2072 if number_desc is None:
2073 return False
2074 actual_length = len(national_number)
2075 possible_lengths = number_desc.possible_length
2076 if len(possible_lengths) > 0 and actual_length not in possible_lengths: 2076 ↛ 2077line 2076 didn't jump to line 2077, because the condition on line 2076 was never true
2077 return False
2078 return _match_national_number(national_number, number_desc, False)
2081def is_valid_number(numobj):
2082 """Tests whether a phone number matches a valid pattern.
2084 Note this doesn't verify the number is actually in use, which is
2085 impossible to tell by just looking at a number itself. It only verifies
2086 whether the parsed, canonicalised number is valid: not whether a
2087 particular series of digits entered by the user is diallable from the
2088 region provided when parsing. For example, the number +41 (0) 78 927 2696
2089 can be parsed into a number with country code "41" and national
2090 significant number "789272696". This is valid, while the original string
2091 is not diallable.
2093 Arguments:
2094 numobj -- The phone number object that we want to validate
2096 Returns a boolean that indicates whether the number is of a valid pattern.
2097 """
2098 region_code = region_code_for_number(numobj)
2099 return is_valid_number_for_region(numobj, region_code)
2102def is_valid_number_for_region(numobj, region_code):
2103 """Tests whether a phone number is valid for a certain region.
2105 Note this doesn't verify the number is actually in use, which is
2106 impossible to tell by just looking at a number itself. If the country
2107 calling code is not the same as the country calling code for the region,
2108 this immediately exits with false. After this, the specific number pattern
2109 rules for the region are examined. This is useful for determining for
2110 example whether a particular number is valid for Canada, rather than just
2111 a valid NANPA number.
2113 Warning: In most cases, you want to use is_valid_number instead. For
2114 example, this method will mark numbers from British Crown dependencies
2115 such as the Isle of Man as invalid for the region "GB" (United Kingdom),
2116 since it has its own region code, "IM", which may be undesirable.
2118 Arguments:
2119 numobj -- The phone number object that we want to validate.
2120 region_code -- The region that we want to validate the phone number for.
2122 Returns a boolean that indicates whether the number is of a valid pattern.
2123 """
2124 country_code = numobj.country_code
2125 if region_code is None: 2125 ↛ 2126line 2125 didn't jump to line 2126, because the condition on line 2125 was never true
2126 return False
2127 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code.upper())
2128 if (metadata is None or 2128 ↛ 2133line 2128 didn't jump to line 2133, because the condition on line 2128 was never true
2129 (region_code != REGION_CODE_FOR_NON_GEO_ENTITY and
2130 country_code != country_code_for_valid_region(region_code))):
2131 # Either the region code was invalid, or the country calling code for
2132 # this number does not match that of the region code.
2133 return False
2134 nsn = national_significant_number(numobj)
2135 return (_number_type_helper(nsn, metadata) != PhoneNumberType.UNKNOWN)
2138def region_code_for_number(numobj):
2139 """Returns the region where a phone number is from.
2141 This could be used for geocoding at the region level. Only guarantees
2142 correct results for valid, full numbers (not short-codes, or invalid
2143 numbers).
2145 Arguments:
2146 numobj -- The phone number object whose origin we want to know
2148 Returns the region where the phone number is from, or None if no region
2149 matches this calling code.
2151 """
2152 country_code = numobj.country_code
2153 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None)
2154 if regions is None: 2154 ↛ 2155line 2154 didn't jump to line 2155, because the condition on line 2154 was never true
2155 return None
2157 if len(regions) == 1: 2157 ↛ 2160line 2157 didn't jump to line 2160, because the condition on line 2157 was never false
2158 return regions[0]
2159 else:
2160 return _region_code_for_number_from_list(numobj, regions)
2163def _region_code_for_number_from_list(numobj, regions):
2164 """Find the region in a list that matches a number"""
2165 national_number = national_significant_number(numobj)
2166 for region_code in regions:
2167 # If leading_digits is present, use this. Otherwise, do full
2168 # validation.
2169 # Metadata cannot be None because the region codes come from
2170 # the country calling code map.
2171 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None)
2172 if metadata is None:
2173 continue
2174 if metadata.leading_digits is not None:
2175 leading_digit_re = re.compile(metadata.leading_digits)
2176 match = leading_digit_re.match(national_number)
2177 if match:
2178 return region_code
2179 elif _number_type_helper(national_number, metadata) != PhoneNumberType.UNKNOWN:
2180 return region_code
2181 return None
2184def region_code_for_country_code(country_code):
2185 """Returns the region code that matches a specific country calling code.
2187 In the case of no region code being found, UNKNOWN_REGION ('ZZ') will be
2188 returned. In the case of multiple regions, the one designated in the
2189 metadata as the "main" region for this calling code will be returned. If
2190 the country_code entered is valid but doesn't match a specific region
2191 (such as in the case of non-geographical calling codes like 800) the value
2192 "001" will be returned (corresponding to the value for World in the UN
2193 M.49 schema).
2194 """
2195 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None)
2196 if regions is None: 2196 ↛ 2197line 2196 didn't jump to line 2197, because the condition on line 2196 was never true
2197 return UNKNOWN_REGION
2198 else:
2199 return regions[0]
2202def region_codes_for_country_code(country_code):
2203 """Returns a list with the region codes that match the specific country calling code.
2205 For non-geographical country calling codes, the region code 001 is
2206 returned. Also, in the case of no region code being found, an empty
2207 list is returned.
2208 """
2209 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None)
2210 if regions is None:
2211 return ()
2212 else:
2213 return regions
2216def country_code_for_region(region_code):
2217 """Returns the country calling code for a specific region.
2219 For example, this would be 1 for the United States, and 64 for New
2220 Zealand.
2222 Arguments:
2223 region_code -- The region that we want to get the country calling code for.
2225 Returns the country calling code for the region denoted by region_code.
2226 """
2227 if not _is_valid_region_code(region_code):
2228 return 0
2229 return country_code_for_valid_region(region_code)
2232def country_code_for_valid_region(region_code):
2233 """Returns the country calling code for a specific region.
2235 For example, this would be 1 for the United States, and 64 for New
2236 Zealand. Assumes the region is already valid.
2238 Arguments:
2239 region_code -- The region that we want to get the country calling code for.
2241 Returns the country calling code for the region denoted by region_code.
2242 """
2243 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None)
2244 if metadata is None: 2244 ↛ 2245line 2244 didn't jump to line 2245, because the condition on line 2244 was never true
2245 raise Exception("Invalid region code %s" % region_code)
2246 return metadata.country_code
2249def ndd_prefix_for_region(region_code, strip_non_digits):
2250 """Returns the national dialling prefix for a specific region.
2252 For example, this would be 1 for the United States, and 0 for New
2253 Zealand. Set strip_non_digits to True to strip symbols like "~" (which
2254 indicates a wait for a dialling tone) from the prefix returned. If no
2255 national prefix is present, we return None.
2257 Warning: Do not use this method for do-your-own formatting - for some
2258 regions, the national dialling prefix is used only for certain types of
2259 numbers. Use the library's formatting functions to prefix the national
2260 prefix when required.
2262 Arguments:
2263 region_code -- The region that we want to get the dialling prefix for.
2264 strip_non_digits -- whether to strip non-digits from the national
2265 dialling prefix.
2267 Returns the dialling prefix for the region denoted by region_code.
2268 """
2269 if region_code is None:
2270 return None
2271 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None)
2272 if metadata is None:
2273 return None
2274 national_prefix = metadata.national_prefix
2275 if national_prefix is None or len(national_prefix) == 0:
2276 return None
2277 if strip_non_digits:
2278 # Note: if any other non-numeric symbols are ever used in national
2279 # prefixes, these would have to be removed here as well.
2280 national_prefix = re.sub(U_TILDE, U_EMPTY_STRING, national_prefix)
2281 return national_prefix
2284def is_nanpa_country(region_code):
2285 """Checks if this region is a NANPA region.
2287 Returns True if region_code is one of the regions under the North American
2288 Numbering Plan Administration (NANPA).
2289 """
2290 return region_code in _NANPA_REGIONS
2293def is_alpha_number(number):
2294 """Checks if the number is a valid vanity (alpha) number such as 800
2295 MICROSOFT. A valid vanity number will start with at least 3 digits and
2296 will have three or more alpha characters. This does not do region-specific
2297 checks - to work out if this number is actually valid for a region, it
2298 should be parsed and methods such as is_possible_number_with_reason() and
2299 is_valid_number() should be used.
2301 Arguments:
2302 number -- the number that needs to be checked
2304 Returns True if the number is a valid vanity number
2305 """
2306 if not _is_viable_phone_number(number):
2307 # Number is too short, or doesn't match the basic phone number pattern.
2308 return False
2309 extension, stripped_number = _maybe_strip_extension(number)
2310 return bool(fullmatch(_VALID_ALPHA_PHONE_PATTERN, stripped_number))
2313def is_possible_number(numobj):
2314 """Convenience wrapper around is_possible_number_with_reason.
2316 Instead of returning the reason for failure, this method returns true if
2317 the number is either a possible fully-qualified number (containing the area
2318 code and country code), or if the number could be a possible local number
2319 (with a country code, but missing an area code). Local numbers are
2320 considered possible if they could be possibly dialled in this format: if
2321 the area code is needed for a call to connect, the number is not considered
2322 possible without it.
2324 Arguments:
2325 numobj -- the number object that needs to be checked
2327 Returns True if the number is possible
2329 """
2330 result = is_possible_number_with_reason(numobj)
2331 return (result == ValidationResult.IS_POSSIBLE or
2332 result == ValidationResult.IS_POSSIBLE_LOCAL_ONLY)
2335def is_possible_number_for_type(numobj, numtype):
2336 """Convenience wrapper around is_possible_number_for_type_with_reason.
2338 Instead of returning the reason for failure, this method returns true if
2339 the number is either a possible fully-qualified number (containing the area
2340 code and country code), or if the number could be a possible local number
2341 (with a country code, but missing an area code). Local numbers are
2342 considered possible if they could be possibly dialled in this format: if
2343 the area code is needed for a call to connect, the number is not considered
2344 possible without it.
2346 Arguments:
2347 numobj -- the number object that needs to be checked
2348 numtype -- the type we are interested in
2350 Returns True if the number is possible
2352 """
2353 result = is_possible_number_for_type_with_reason(numobj, numtype)
2354 return (result == ValidationResult.IS_POSSIBLE or
2355 result == ValidationResult.IS_POSSIBLE_LOCAL_ONLY)
2358def _test_number_length(national_number, metadata, numtype=PhoneNumberType.UNKNOWN):
2359 """Helper method to check a number against possible lengths for this number,
2360 and determine whether it matches, or is too short or too long.
2361 """
2362 desc_for_type = _number_desc_by_type(metadata, numtype)
2363 if desc_for_type is None: 2363 ↛ 2364line 2363 didn't jump to line 2364, because the condition on line 2363 was never true
2364 possible_lengths = metadata.general_desc.possible_length
2365 local_lengths = ()
2366 else:
2367 # There should always be "possibleLengths" set for every element. This is declared in the XML
2368 # schema which is verified by PhoneNumberMetadataSchemaTest.
2369 # For size efficiency, where a sub-description (e.g. fixed-line) has the same possibleLengths
2370 # as the parent, this is missing, so we fall back to the general desc (where no numbers of the
2371 # type exist at all, there is one possible length (-1) which is guaranteed not to match the
2372 # length of any real phone number).
2373 possible_lengths = desc_for_type.possible_length
2374 if len(possible_lengths) == 0: # pragma no cover: Python sub-descs all have possible_length 2374 ↛ 2375line 2374 didn't jump to line 2375, because the condition on line 2374 was never true
2375 possible_lengths = metadata.general_desc.possible_length
2376 local_lengths = desc_for_type.possible_length_local_only
2378 if numtype == PhoneNumberType.FIXED_LINE_OR_MOBILE: 2378 ↛ 2379line 2378 didn't jump to line 2379, because the condition on line 2378 was never true
2379 if not _desc_has_possible_number_data(_number_desc_by_type(metadata, PhoneNumberType.FIXED_LINE)):
2380 # The rare case has been encountered where no fixedLine data is available (true for some
2381 # non-geographical entities), so we just check mobile.
2382 return _test_number_length(national_number, metadata, PhoneNumberType.MOBILE)
2383 else:
2384 mobile_desc = _number_desc_by_type(metadata, PhoneNumberType.MOBILE)
2385 if _desc_has_possible_number_data(mobile_desc):
2386 # Merge the mobile data in if there was any. We have to make a copy to do this.
2387 possible_lengths = list(possible_lengths)
2388 # Note that when adding the possible lengths from mobile, we have to again check they
2389 # aren't empty since if they are this indicates they are the same as the general desc and
2390 # should be obtained from there.
2391 if len(mobile_desc.possible_length) == 0: # pragma no cover: Python sub-descs all have possible_length
2392 possible_lengths += metadata.general_desc.possible_length
2393 else:
2394 possible_lengths += mobile_desc.possible_length
2395 # The current list is sorted; we need to merge in the new list and re-sort (duplicates
2396 # are okay). Sorting isn't so expensive because the lists are very small.
2397 list.sort(possible_lengths)
2399 if len(local_lengths) == 0:
2400 local_lengths = mobile_desc.possible_length_local_only
2401 else:
2402 local_lengths = list(local_lengths)
2403 local_lengths += mobile_desc.possible_length_local_only
2404 list.sort(local_lengths)
2406 # If the type is not supported at all (indicated by a missing PhoneNumberDesc) we return invalid length.
2407 if desc_for_type is None: 2407 ↛ 2408line 2407 didn't jump to line 2408, because the condition on line 2407 was never true
2408 return ValidationResult.INVALID_LENGTH
2410 actual_length = len(national_number)
2411 # This is safe because there is never an overlap between the possible lengths and the local-only
2412 # lengths; this is checked at build time.
2413 if actual_length in local_lengths: 2413 ↛ 2414line 2413 didn't jump to line 2414, because the condition on line 2413 was never true
2414 return ValidationResult.IS_POSSIBLE_LOCAL_ONLY
2416 minimum_length = possible_lengths[0]
2417 if minimum_length == actual_length: 2417 ↛ 2419line 2417 didn't jump to line 2419, because the condition on line 2417 was never false
2418 return ValidationResult.IS_POSSIBLE
2419 elif minimum_length > actual_length:
2420 return ValidationResult.TOO_SHORT
2421 elif possible_lengths[-1] < actual_length:
2422 return ValidationResult.TOO_LONG
2423 # We skip the first element; we've already checked it.
2424 if actual_length in possible_lengths[1:]:
2425 return ValidationResult.IS_POSSIBLE
2426 else:
2427 return ValidationResult.INVALID_LENGTH
2430def is_possible_number_with_reason(numobj):
2431 return is_possible_number_for_type_with_reason(numobj, PhoneNumberType.UNKNOWN)
2434def is_possible_number_for_type_with_reason(numobj, numtype):
2435 """Check whether a phone number is a possible number of a particular type.
2437 For types that don't exist in a particular region, this will return a result
2438 that isn't so useful; it is recommended that you use
2439 supported_types_for_region or supported_types_for_non_geo_entity
2440 respectively before calling this method to determine whether you should call
2441 it for this number at all.
2443 This provides a more lenient check than is_valid_number in the following sense:
2445 - It only checks the length of phone numbers. In particular, it doesn't
2446 check starting digits of the number.
2448 - For some numbers (particularly fixed-line), many regions have the
2449 concept of area code, which together with subscriber number constitute
2450 the national significant number. It is sometimes okay to dial only the
2451 subscriber number when dialing in the same area. This function will
2452 return IS_POSSIBLE_LOCAL_ONLY if the subscriber-number-only version is
2453 passed in. On the other hand, because is_valid_number validates using
2454 information on both starting digits (for fixed line numbers, that would
2455 most likely be area codes) and length (obviously includes the length of
2456 area codes for fixed line numbers), it will return false for the
2457 subscriber-number-only version.
2459 Arguments:
2460 numobj -- The number object that needs to be checked
2461 numtype -- The type we are interested in
2463 Returns a value from ValidationResult which indicates whether the number
2464 is possible
2465 """
2466 national_number = national_significant_number(numobj)
2467 country_code = numobj.country_code
2468 # Note: For regions that share a country calling code, like NANPA numbers,
2469 # we just use the rules from the default region (US in this case) since the
2470 # region_code_for_number will not work if the number is possible but not
2471 # valid. There is in fact one country calling code (290) where the possible
2472 # number pattern differs between various regions (Saint Helena and Tristan
2473 # da Cuñha), but this is handled by putting all possible lengths for any
2474 # country with this country calling code in the metadata for the default
2475 # region in this case.
2476 if not _has_valid_country_calling_code(country_code):
2477 return ValidationResult.INVALID_COUNTRY_CODE
2478 region_code = region_code_for_country_code(country_code)
2479 # Metadata cannot be None because the country calling code is valid.
2480 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code)
2481 return _test_number_length(national_number, metadata, numtype)
2484def is_possible_number_string(number, region_dialing_from):
2485 """Check whether a phone number string is a possible number.
2487 Takes a number in the form of a string, and the region where the number
2488 could be dialed from. It provides a more lenient check than
2489 is_valid_number; see is_possible_number_with_reason() for details.
2491 This method first parses the number, then invokes is_possible_number with
2492 the resultant PhoneNumber object.
2494 Arguments:
2495 number -- The number that needs to be checked, in the form of a string.
2496 region_dialling_from -- The region that we are expecting the number to be
2497 dialed from. Note this is different from the region where the
2498 number belongs. For example, the number +1 650 253 0000 is a
2499 number that belongs to US. When written in this form, it can be
2500 dialed from any region. When it is written as 00 1 650 253 0000,
2501 it can be dialed from any region which uses an international
2502 dialling prefix of 00. When it is written as 650 253 0000, it
2503 can only be dialed from within the US, and when written as 253
2504 0000, it can only be dialed from within a smaller area in the US
2505 (Mountain View, CA, to be more specific).
2507 Returns True if the number is possible
2508 """
2509 try:
2510 return is_possible_number(parse(number, region_dialing_from))
2511 except NumberParseException:
2512 return False
2515def truncate_too_long_number(numobj):
2516 """Truncate a number object that is too long.
2518 Attempts to extract a valid number from a phone number that is too long
2519 to be valid, and resets the PhoneNumber object passed in to that valid
2520 version. If no valid number could be extracted, the PhoneNumber object
2521 passed in will not be modified.
2523 Arguments:
2524 numobj -- A PhoneNumber object which contains a number that is too long to
2525 be valid.
2527 Returns True if a valid phone number can be successfully extracted.
2528 """
2529 if is_valid_number(numobj):
2530 return True
2531 numobj_copy = PhoneNumber()
2532 numobj_copy.merge_from(numobj)
2533 national_number = numobj.national_number
2535 while not is_valid_number(numobj_copy):
2536 # Strip a digit off the RHS
2537 national_number = national_number // 10
2538 numobj_copy.national_number = national_number
2539 validation_result = is_possible_number_with_reason(numobj_copy)
2540 if (validation_result == ValidationResult.TOO_SHORT or
2541 national_number == 0):
2542 return False
2543 # To reach here, numobj_copy is a valid number. Modify the original object
2544 numobj.national_number = national_number
2545 return True
2548def _extract_country_code(number):
2549 """Extracts country calling code from number.
2551 Returns a 2-tuple of (country_calling_code, rest_of_number). It assumes
2552 that the leading plus sign or IDD has already been removed. Returns (0,
2553 number) if number doesn't start with a valid country calling code.
2554 """
2556 if len(number) == 0 or number[0] == U_ZERO: 2556 ↛ 2558line 2556 didn't jump to line 2558, because the condition on line 2556 was never true
2557 # Country codes do not begin with a '0'.
2558 return (0, number)
2559 for ii in range(1, min(len(number), _MAX_LENGTH_COUNTRY_CODE) + 1): 2559 ↛ 2566line 2559 didn't jump to line 2566, because the loop on line 2559 didn't complete
2560 try:
2561 country_code = int(number[:ii])
2562 if country_code in COUNTRY_CODE_TO_REGION_CODE:
2563 return (country_code, number[ii:])
2564 except Exception:
2565 pass
2566 return (0, number)
2569def _maybe_extract_country_code(number, metadata, keep_raw_input, numobj):
2570 """Tries to extract a country calling code from a number.
2572 This method will return zero if no country calling code is considered to
2573 be present. Country calling codes are extracted in the following ways:
2575 - by stripping the international dialing prefix of the region the person
2576 is dialing from, if this is present in the number, and looking at the
2577 next digits
2579 - by stripping the '+' sign if present and then looking at the next
2580 digits
2582 - by comparing the start of the number and the country calling code of
2583 the default region. If the number is not considered possible for the
2584 numbering plan of the default region initially, but starts with the
2585 country calling code of this region, validation will be reattempted
2586 after stripping this country calling code. If this number is considered
2587 a possible number, then the first digits will be considered the country
2588 calling code and removed as such.
2590 It will raise a NumberParseException if the number starts with a '+' but
2591 the country calling code supplied after this does not match that of any
2592 known region.
2594 Arguments:
2595 number -- non-normalized telephone number that we wish to extract a
2596 country calling code from; may begin with '+'
2597 metadata -- metadata about the region this number may be from, or None
2598 keep_raw_input -- True if the country_code_source and
2599 preferred_carrier_code fields of numobj should be populated.
2600 numobj -- The PhoneNumber object where the country_code and
2601 country_code_source need to be populated. Note the country_code
2602 is always populated, whereas country_code_source is only
2603 populated when keep_raw_input is True.
2605 Returns a 2-tuple containing:
2606 - the country calling code extracted or 0 if none could be extracted
2607 - a string holding the national significant number, in the case
2608 that a country calling code was extracted. If no country calling code
2609 was extracted, this will be empty.
2610 """
2611 if len(number) == 0: 2611 ↛ 2612line 2611 didn't jump to line 2612, because the condition on line 2611 was never true
2612 return (0, U_EMPTY_STRING)
2613 full_number = number
2614 # Set the default prefix to be something that will never match.
2615 possible_country_idd_prefix = unicod("NonMatch")
2616 if metadata is not None and metadata.international_prefix is not None: 2616 ↛ 2617line 2616 didn't jump to line 2617, because the condition on line 2616 was never true
2617 possible_country_idd_prefix = metadata.international_prefix
2619 country_code_source, full_number = _maybe_strip_i18n_prefix_and_normalize(full_number,
2620 possible_country_idd_prefix)
2621 if keep_raw_input: 2621 ↛ 2624line 2621 didn't jump to line 2624, because the condition on line 2621 was never false
2622 numobj.country_code_source = country_code_source
2624 if country_code_source != CountryCodeSource.FROM_DEFAULT_COUNTRY: 2624 ↛ 2638line 2624 didn't jump to line 2638, because the condition on line 2624 was never false
2625 if len(full_number) <= _MIN_LENGTH_FOR_NSN: 2625 ↛ 2626line 2625 didn't jump to line 2626, because the condition on line 2625 was never true
2626 raise NumberParseException(NumberParseException.TOO_SHORT_AFTER_IDD,
2627 "Phone number had an IDD, but after this was not " +
2628 "long enough to be a viable phone number.")
2629 potential_country_code, rest_of_number = _extract_country_code(full_number)
2630 if potential_country_code != 0: 2630 ↛ 2636line 2630 didn't jump to line 2636, because the condition on line 2630 was never false
2631 numobj.country_code = potential_country_code
2632 return (potential_country_code, rest_of_number)
2634 # If this fails, they must be using a strange country calling code
2635 # that we don't recognize, or that doesn't exist.
2636 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE,
2637 "Country calling code supplied was not recognised.")
2638 elif metadata is not None:
2639 # Check to see if the number starts with the country calling code for
2640 # the default region. If so, we remove the country calling code, and
2641 # do some checks on the validity of the number before and after.
2642 default_country_code = metadata.country_code
2643 default_country_code_str = str(metadata.country_code)
2644 normalized_number = full_number
2645 if normalized_number.startswith(default_country_code_str):
2646 potential_national_number = full_number[len(default_country_code_str):]
2647 general_desc = metadata.general_desc
2648 _, potential_national_number, _ = _maybe_strip_national_prefix_carrier_code(potential_national_number,
2649 metadata)
2651 # If the number was not valid before but is valid now, or if it
2652 # was too long before, we consider the number with the country
2653 # calling code stripped to be a better result and keep that
2654 # instead.
2655 if ((not _match_national_number(full_number, general_desc, False) and
2656 _match_national_number(potential_national_number, general_desc, False)) or
2657 (_test_number_length(full_number, metadata) == ValidationResult.TOO_LONG)):
2658 if keep_raw_input:
2659 numobj.country_code_source = CountryCodeSource.FROM_NUMBER_WITHOUT_PLUS_SIGN
2660 numobj.country_code = default_country_code
2661 return (default_country_code, potential_national_number)
2663 # No country calling code present.
2664 numobj.country_code = 0
2665 return (0, U_EMPTY_STRING)
2668def _parse_prefix_as_idd(idd_pattern, number):
2669 """Strips the IDD from the start of the number if present.
2671 Helper function used by _maybe_strip_i18n_prefix_and_normalize().
2673 Returns a 2-tuple:
2674 - Boolean indicating if IDD was stripped
2675 - Number with IDD stripped
2676 """
2677 match = idd_pattern.match(number)
2678 if match:
2679 match_end = match.end()
2680 # Only strip this if the first digit after the match is not a 0, since
2681 # country calling codes cannot begin with 0.
2682 digit_match = _CAPTURING_DIGIT_PATTERN.search(number[match_end:])
2683 if digit_match:
2684 normalized_group = normalize_digits_only(digit_match.group(1))
2685 if normalized_group == U_ZERO:
2686 return (False, number)
2687 return (True, number[match_end:])
2688 return (False, number)
2691def _maybe_strip_i18n_prefix_and_normalize(number, possible_idd_prefix):
2692 """Strips any international prefix (such as +, 00, 011) present in the
2693 number provided, normalizes the resulting number, and indicates if an
2694 international prefix was present.
2696 Arguments:
2697 number -- The non-normalized telephone number that we wish to strip any international
2698 dialing prefix from.
2699 possible_idd_prefix -- The international direct dialing prefix from the region we
2700 think this number may be dialed in.
2702 Returns a 2-tuple containing:
2703 - The corresponding CountryCodeSource if an international dialing prefix
2704 could be removed from the number, otherwise
2705 CountryCodeSource.FROM_DEFAULT_COUNTRY if the number did not seem to
2706 be in international format.
2707 - The number with the prefix stripped.
2708 """
2709 if len(number) == 0: 2709 ↛ 2710line 2709 didn't jump to line 2710, because the condition on line 2709 was never true
2710 return (CountryCodeSource.FROM_DEFAULT_COUNTRY, number)
2711 # Check to see if the number begins with one or more plus signs.
2712 m = _PLUS_CHARS_PATTERN.match(number)
2713 if m: 2713 ↛ 2721line 2713 didn't jump to line 2721, because the condition on line 2713 was never false
2714 number = number[m.end():]
2715 # Can now normalize the rest of the number since we've consumed the
2716 # "+" sign at the start.
2717 return (CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN,
2718 _normalize(number))
2720 # Attempt to parse the first digits as an international prefix.
2721 idd_pattern = re.compile(possible_idd_prefix)
2722 number = _normalize(number)
2723 stripped, number = _parse_prefix_as_idd(idd_pattern, number)
2724 if stripped:
2725 return (CountryCodeSource.FROM_NUMBER_WITH_IDD, number)
2726 else:
2727 return (CountryCodeSource.FROM_DEFAULT_COUNTRY, number)
2730def _maybe_strip_national_prefix_carrier_code(number, metadata):
2731 """Strips any national prefix (such as 0, 1) present in a number.
2733 Arguments:
2734 number -- The normalized telephone number that we wish to strip any
2735 national dialing prefix from
2736 metadata -- The metadata for the region that we think this number
2737 is from.
2739 Returns a 3-tuple of
2740 - The carrier code extracted if it is present, otherwise an empty string.
2741 - The number with the prefix stripped.
2742 - Boolean indicating if a national prefix or carrier code (or both) could be extracted.
2743 """
2744 carrier_code = U_EMPTY_STRING
2745 possible_national_prefix = metadata.national_prefix_for_parsing
2746 if (len(number) == 0 or 2746 ↛ 2750line 2746 didn't jump to line 2750, because the condition on line 2746 was never true
2747 possible_national_prefix is None or
2748 len(possible_national_prefix) == 0):
2749 # Early return for numbers of zero length.
2750 return (U_EMPTY_STRING, number, False)
2752 # Attempt to parse the first digits as a national prefix.
2753 prefix_pattern = re.compile(possible_national_prefix)
2754 prefix_match = prefix_pattern.match(number)
2755 if prefix_match: 2755 ↛ 2756line 2755 didn't jump to line 2756, because the condition on line 2755 was never true
2756 general_desc = metadata.general_desc
2757 # Check if the original number is viable.
2758 is_viable_original_number = _match_national_number(number, general_desc, False)
2759 # prefix_match.groups() == () implies nothing was captured by the
2760 # capturing groups in possible_national_prefix; therefore, no
2761 # transformation is necessary, and we just remove the national prefix.
2762 num_groups = len(prefix_match.groups())
2763 transform_rule = metadata.national_prefix_transform_rule
2764 if (transform_rule is None or
2765 len(transform_rule) == 0 or
2766 prefix_match.groups()[num_groups - 1] is None):
2767 # If the original number was viable, and the resultant number is not, we return.
2768 # Check that the resultant number is viable. If not, return.
2769 national_number_match = _match_national_number(number[prefix_match.end():], general_desc, False)
2770 if (is_viable_original_number and not national_number_match):
2771 return (U_EMPTY_STRING, number, False)
2773 if (num_groups > 0 and
2774 prefix_match.groups(num_groups) is not None):
2775 carrier_code = prefix_match.group(1)
2776 return (carrier_code, number[prefix_match.end():], True)
2777 else:
2778 # Check that the resultant number is still viable. If not,
2779 # return. Check this by copying the number and making the
2780 # transformation on the copy first.
2781 transformed_number = re.sub(prefix_pattern, transform_rule, number, count=1)
2782 national_number_match = _match_national_number(transformed_number, general_desc, False)
2783 if (is_viable_original_number and not national_number_match):
2784 return ("", number, False)
2785 if num_groups > 1:
2786 carrier_code = prefix_match.group(1)
2787 return (carrier_code, transformed_number, True)
2788 else:
2789 return (carrier_code, number, False)
2792def _maybe_strip_extension(number):
2793 """Strip extension from the end of a number string.
2795 Strips any extension (as in, the part of the number dialled after the
2796 call is connected, usually indicated with extn, ext, x or similar) from
2797 the end of the number, and returns it.
2799 Arguments:
2800 number -- the non-normalized telephone number that we wish to strip the extension from.
2802 Returns a 2-tuple of:
2803 - the phone extension (or "" or not present)
2804 - the number before the extension.
2805 """
2806 match = _EXTN_PATTERN.search(number)
2807 # If we find a potential extension, and the number preceding this is a
2808 # viable number, we assume it is an extension.
2809 if match and _is_viable_phone_number(number[:match.start()]): 2809 ↛ 2811line 2809 didn't jump to line 2811, because the condition on line 2809 was never true
2810 # The numbers are captured into groups in the regular expression.
2811 for group in match.groups():
2812 # We go through the capturing groups until we find one that
2813 # captured some digits. If none did, then we will return the empty
2814 # string.
2815 if group is not None:
2816 return (group, number[:match.start()])
2817 return ("", number)
2820def _check_region_for_parsing(number, default_region):
2821 """Checks to see that the region code used is valid, or if it is not
2822 valid, that the number to parse starts with a + symbol so that we can
2823 attempt to infer the region from the number. Returns False if it cannot
2824 use the region provided and the region cannot be inferred.
2825 """
2826 if not _is_valid_region_code(default_region): 2826 ↛ 2833line 2826 didn't jump to line 2833, because the condition on line 2826 was never false
2827 # If the number is None or empty, we can't infer the region.
2828 if number is None or len(number) == 0: 2828 ↛ 2829line 2828 didn't jump to line 2829, because the condition on line 2828 was never true
2829 return False
2830 match = _PLUS_CHARS_PATTERN.match(number)
2831 if match is None: 2831 ↛ 2832line 2831 didn't jump to line 2832, because the condition on line 2831 was never true
2832 return False
2833 return True
2836def _set_italian_leading_zeros_for_phone_number(national_number, numobj):
2837 """A helper function to set the values related to leading zeros in a
2838 PhoneNumber."""
2839 if len(national_number) > 1 and national_number[0] == U_ZERO: 2839 ↛ 2840line 2839 didn't jump to line 2840, because the condition on line 2839 was never true
2840 numobj.italian_leading_zero = True
2841 number_of_leading_zeros = 1
2842 # Note that if the number is all "0"s, the last "0" is not counted as
2843 # a leading zero.
2844 while (number_of_leading_zeros < len(national_number) - 1 and
2845 national_number[number_of_leading_zeros] == U_ZERO):
2846 number_of_leading_zeros += 1
2847 if number_of_leading_zeros != 1:
2848 numobj.number_of_leading_zeros = number_of_leading_zeros
2851def parse(number, region=None, keep_raw_input=False,
2852 numobj=None, _check_region=True):
2853 """Parse a string and return a corresponding PhoneNumber object.
2855 The method is quite lenient and looks for a number in the input text
2856 (raw input) and does not check whether the string is definitely only a
2857 phone number. To do this, it ignores punctuation and white-space, as
2858 well as any text before the number (e.g. a leading "Tel: ") and trims
2859 the non-number bits. It will accept a number in any format (E164,
2860 national, international etc), assuming it can be interpreted with the
2861 defaultRegion supplied. It also attempts to convert any alpha characters
2862 into digits if it thinks this is a vanity number of the type "1800
2863 MICROSOFT".
2865 This method will throw a NumberParseException if the number is not
2866 considered to be a possible number. Note that validation of whether the
2867 number is actually a valid number for a particular region is not
2868 performed. This can be done separately with is_valid_number.
2870 Note this method canonicalizes the phone number such that different
2871 representations can be easily compared, no matter what form it was
2872 originally entered in (e.g. national, international). If you want to
2873 record context about the number being parsed, such as the raw input that
2874 was entered, how the country code was derived etc. then ensure
2875 keep_raw_input is set.
2877 Note if any new field is added to this method that should always be filled
2878 in, even when keep_raw_input is False, it should also be handled in the
2879 _copy_core_fields_only() function.
2881 Arguments:
2882 number -- The number that we are attempting to parse. This can
2883 contain formatting such as +, ( and -, as well as a phone
2884 number extension. It can also be provided in RFC3966 format.
2885 region -- The region that we are expecting the number to be from. This
2886 is only used if the number being parsed is not written in
2887 international format. The country_code for the number in
2888 this case would be stored as that of the default region
2889 supplied. If the number is guaranteed to start with a '+'
2890 followed by the country calling code, then None or
2891 UNKNOWN_REGION can be supplied.
2892 keep_raw_input -- Whether to populate the raw_input field of the
2893 PhoneNumber object with number (as well as the
2894 country_code_source field).
2895 numobj -- An optional existing PhoneNumber object to receive the
2896 parsing results
2897 _check_region -- Whether to check the supplied region parameter;
2898 should always be True for external callers.
2900 Returns a PhoneNumber object filled with the parse number.
2902 Raises:
2903 NumberParseException if the string is not considered to be a viable
2904 phone number (e.g. too few or too many digits) or if no default
2905 region was supplied and the number is not in international format
2906 (does not start with +).
2908 """
2909 if numobj is None: 2909 ↛ 2910line 2909 didn't jump to line 2910, because the condition on line 2909 was never true
2910 numobj = PhoneNumber()
2911 if number is None: 2911 ↛ 2912line 2911 didn't jump to line 2912, because the condition on line 2911 was never true
2912 raise NumberParseException(NumberParseException.NOT_A_NUMBER,
2913 "The phone number supplied was None.")
2914 elif len(number) > _MAX_INPUT_STRING_LENGTH: 2914 ↛ 2915line 2914 didn't jump to line 2915, because the condition on line 2914 was never true
2915 raise NumberParseException(NumberParseException.TOO_LONG,
2916 "The string supplied was too long to parse.")
2918 national_number = _build_national_number_for_parsing(number)
2920 if not _is_viable_phone_number(national_number): 2920 ↛ 2921line 2920 didn't jump to line 2921, because the condition on line 2920 was never true
2921 raise NumberParseException(NumberParseException.NOT_A_NUMBER,
2922 "The string supplied did not seem to be a phone number.")
2924 # Check the region supplied is valid, or that the extracted number starts
2925 # with some sort of + sign so the number's region can be determined.
2926 if _check_region and not _check_region_for_parsing(national_number, region): 2926 ↛ 2927line 2926 didn't jump to line 2927, because the condition on line 2926 was never true
2927 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE,
2928 "Missing or invalid default region.")
2929 if keep_raw_input: 2929 ↛ 2934line 2929 didn't jump to line 2934, because the condition on line 2929 was never false
2930 numobj.raw_input = number
2932 # Attempt to parse extension first, since it doesn't require
2933 # region-specific data and we want to have the non-normalised number here.
2934 extension, national_number = _maybe_strip_extension(national_number)
2935 if len(extension) > 0: 2935 ↛ 2936line 2935 didn't jump to line 2936, because the condition on line 2935 was never true
2936 numobj.extension = extension
2937 if region is None: 2937 ↛ 2940line 2937 didn't jump to line 2940, because the condition on line 2937 was never false
2938 metadata = None
2939 else:
2940 metadata = PhoneMetadata.metadata_for_region(region.upper(), None)
2942 country_code = 0
2943 try:
2944 country_code, normalized_national_number = _maybe_extract_country_code(national_number,
2945 metadata,
2946 keep_raw_input,
2947 numobj)
2948 except NumberParseException:
2949 _, e, _ = sys.exc_info()
2950 matchobj = _PLUS_CHARS_PATTERN.match(national_number)
2951 if (e.error_type == NumberParseException.INVALID_COUNTRY_CODE and
2952 matchobj is not None):
2953 # Strip the plus-char, and try again.
2954 country_code, normalized_national_number = _maybe_extract_country_code(national_number[matchobj.end():],
2955 metadata,
2956 keep_raw_input,
2957 numobj)
2958 if country_code == 0:
2959 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE,
2960 "Could not interpret numbers after plus-sign.")
2961 else:
2962 raise
2964 if country_code != 0: 2964 ↛ 2974line 2964 didn't jump to line 2974, because the condition on line 2964 was never false
2965 number_region = region_code_for_country_code(country_code)
2966 if number_region != region: 2966 ↛ 2981line 2966 didn't jump to line 2981, because the condition on line 2966 was never false
2967 # Metadata cannot be None because the country calling code is valid.
2968 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, number_region)
2969 assert metadata is not None
2970 else:
2971 # If no extracted country calling code, use the region supplied
2972 # instead. The national number is just the normalized version of the
2973 # number we were given to parse.
2974 normalized_national_number += _normalize(national_number)
2975 if region is not None:
2976 country_code = metadata.country_code
2977 numobj.country_code = country_code
2978 elif keep_raw_input:
2979 numobj.country_code_source = CountryCodeSource.UNSPECIFIED
2981 if len(normalized_national_number) < _MIN_LENGTH_FOR_NSN: 2981 ↛ 2982line 2981 didn't jump to line 2982, because the condition on line 2981 was never true
2982 raise NumberParseException(NumberParseException.TOO_SHORT_NSN,
2983 "The string supplied is too short to be a phone number.")
2984 if metadata is not None: 2984 ↛ 2999line 2984 didn't jump to line 2999, because the condition on line 2984 was never false
2985 potential_national_number = normalized_national_number
2986 carrier_code, potential_national_number, _ = _maybe_strip_national_prefix_carrier_code(potential_national_number,
2987 metadata)
2988 # We require that the NSN remaining after stripping the national
2989 # prefix and carrier code be long enough to be a possible length for
2990 # the region. Otherwise, we don't do the stripping, since the original
2991 # number could be a valid short number.
2992 validation_result = _test_number_length(potential_national_number, metadata)
2993 if validation_result not in (ValidationResult.TOO_SHORT, 2993 ↛ 2999line 2993 didn't jump to line 2999, because the condition on line 2993 was never false
2994 ValidationResult.IS_POSSIBLE_LOCAL_ONLY,
2995 ValidationResult.INVALID_LENGTH):
2996 normalized_national_number = potential_national_number
2997 if keep_raw_input and carrier_code is not None and len(carrier_code) > 0: 2997 ↛ 2998line 2997 didn't jump to line 2998, because the condition on line 2997 was never true
2998 numobj.preferred_domestic_carrier_code = carrier_code
2999 len_national_number = len(normalized_national_number)
3000 if len_national_number < _MIN_LENGTH_FOR_NSN: # pragma no cover 3000 ↛ 3003line 3000 didn't jump to line 3003, because the condition on line 3000 was never true
3001 # Check of _is_viable_phone_number() at the top of this function makes
3002 # this effectively unhittable.
3003 raise NumberParseException(NumberParseException.TOO_SHORT_NSN,
3004 "The string supplied is too short to be a phone number.")
3005 if len_national_number > _MAX_LENGTH_FOR_NSN: 3005 ↛ 3006line 3005 didn't jump to line 3006, because the condition on line 3005 was never true
3006 raise NumberParseException(NumberParseException.TOO_LONG,
3007 "The string supplied is too long to be a phone number.")
3008 _set_italian_leading_zeros_for_phone_number(normalized_national_number, numobj)
3009 numobj.national_number = to_long(normalized_national_number)
3010 return numobj
3013def _build_national_number_for_parsing(number):
3014 """Converts number to a form that we can parse and return it if it is
3015 written in RFC3966; otherwise extract a possible number out of it and return it."""
3016 index_of_phone_context = number.find(_RFC3966_PHONE_CONTEXT)
3017 if index_of_phone_context >= 0: 3017 ↛ 3018line 3017 didn't jump to line 3018, because the condition on line 3017 was never true
3018 phone_context_start = index_of_phone_context + len(_RFC3966_PHONE_CONTEXT)
3019 # If the phone context contains a phone number prefix, we need to
3020 # capture it, whereas domains will be ignored.
3021 if (phone_context_start < (len(number) - 1) and
3022 number[phone_context_start] == _PLUS_SIGN):
3023 # Additional parameters might follow the phone context. If so, we
3024 # will remove them here because the parameters after phone context
3025 # are not important for parsing the phone number.
3026 phone_context_end = number.find(U_SEMICOLON, phone_context_start)
3027 if phone_context_end > 0:
3028 national_number = number[phone_context_start:phone_context_end]
3029 else:
3030 national_number = number[phone_context_start:]
3031 else:
3032 national_number = U_EMPTY_STRING
3033 # Now append everything between the "tel:" prefix and the
3034 # phone-context. This should include the national number, an optional
3035 # extension or isdn-subaddress component. Note we also handle the case
3036 # when "tel:" is missing, as we have seen in some of the phone number
3037 # inputs. In that case we append everything from the beginning.
3038 index_of_rfc3996_prefix = number.find(_RFC3966_PREFIX)
3039 index_of_national_number = ((index_of_rfc3996_prefix + len(_RFC3966_PREFIX))
3040 if (index_of_rfc3996_prefix >= 0) else 0)
3041 national_number += number[index_of_national_number:index_of_phone_context]
3042 else:
3043 # Extract a possible number from the string passed in (this strips leading characters that
3044 # could not be the start of a phone number.)
3045 national_number = _extract_possible_number(number)
3047 # Delete the isdn-subaddress and everything after it if it is
3048 # present. Note extension won't appear at the same time with
3049 # isdn-subaddress according to paragraph 5.3 of the RFC3966 spec,
3050 index_of_isdn = national_number.find(_RFC3966_ISDN_SUBADDRESS)
3051 if index_of_isdn > 0: 3051 ↛ 3052line 3051 didn't jump to line 3052, because the condition on line 3051 was never true
3052 national_number = national_number[:index_of_isdn]
3053 # If both phone context and isdn-subaddress are absent but other
3054 # parameters are present, the parameters are left in national_number. This
3055 # is because we are concerned about deleting content from a potential
3056 # number string when there is no strong evidence that the number is
3057 # actually written in RFC3966.
3058 return national_number
3061def _copy_core_fields_only(inobj):
3062 """Returns a new phone number containing only the fields needed to uniquely
3063 identify a phone number, rather than any fields that capture the context in
3064 which the phone number was created.
3065 """
3066 numobj = PhoneNumber()
3067 numobj.country_code = inobj.country_code
3068 numobj.national_number = inobj.national_number
3069 if inobj.extension is not None and len(inobj.extension) > 0:
3070 numobj.extension = inobj.extension
3071 if inobj.italian_leading_zero:
3072 numobj.italian_leading_zero = True
3073 # This field is only relevant if there are leading zeros at all.
3074 numobj.number_of_leading_zeros = inobj.number_of_leading_zeros
3075 if numobj.number_of_leading_zeros is None:
3076 # No number set is implicitly a count of 1; make it explicit.
3077 numobj.number_of_leading_zeros = 1
3078 return numobj
3081def _is_number_match_OO(numobj1_in, numobj2_in):
3082 """Takes two phone number objects and compares them for equality."""
3083 # We only care about the fields that uniquely define a number, so we copy these across explicitly.
3084 numobj1 = _copy_core_fields_only(numobj1_in)
3085 numobj2 = _copy_core_fields_only(numobj2_in)
3087 # Early exit if both had extensions and these are different.
3088 if (numobj1.extension is not None and
3089 numobj2.extension is not None and
3090 numobj1.extension != numobj2.extension):
3091 return MatchType.NO_MATCH
3093 country_code1 = numobj1.country_code
3094 country_code2 = numobj2.country_code
3095 # Both had country_code specified.
3096 if country_code1 != 0 and country_code2 != 0:
3097 if numobj1 == numobj2:
3098 return MatchType.EXACT_MATCH
3099 elif (country_code1 == country_code2 and
3100 _is_national_number_suffix_of_other(numobj1, numobj2)):
3101 # A SHORT_NSN_MATCH occurs if there is a difference because of the
3102 # presence or absence of an 'Italian leading zero', the presence
3103 # or absence of an extension, or one NSN being a shorter variant
3104 # of the other.
3105 return MatchType.SHORT_NSN_MATCH
3106 # This is not a match.
3107 return MatchType.NO_MATCH
3109 # Checks cases where one or both country_code fields were not
3110 # specified. To make equality checks easier, we first set the country_code
3111 # fields to be equal.
3112 numobj1.country_code = country_code2
3113 # If all else was the same, then this is an NSN_MATCH.
3114 if numobj1 == numobj2:
3115 return MatchType.NSN_MATCH
3116 if _is_national_number_suffix_of_other(numobj1, numobj2):
3117 return MatchType.SHORT_NSN_MATCH
3118 return MatchType.NO_MATCH
3121def _is_national_number_suffix_of_other(numobj1, numobj2):
3122 """Returns true when one national number is the suffix of the other or both
3123 are the same.
3124 """
3125 nn1 = str(numobj1.national_number)
3126 nn2 = str(numobj2.national_number)
3127 # Note that endswith returns True if the numbers are equal.
3128 return nn1.endswith(nn2) or nn2.endswith(nn1)
3131def _is_number_match_SS(number1, number2):
3132 """Takes two phone numbers as strings and compares them for equality.
3134 This is a convenience wrapper for _is_number_match_OO/_is_number_match_OS.
3135 No default region is known.
3136 """
3137 try:
3138 numobj1 = parse(number1, UNKNOWN_REGION)
3139 return _is_number_match_OS(numobj1, number2)
3140 except NumberParseException:
3141 _, exc, _ = sys.exc_info()
3142 if exc.error_type == NumberParseException.INVALID_COUNTRY_CODE:
3143 try:
3144 numobj2 = parse(number2, UNKNOWN_REGION)
3145 return _is_number_match_OS(numobj2, number1)
3146 except NumberParseException:
3147 _, exc2, _ = sys.exc_info()
3148 if exc2.error_type == NumberParseException.INVALID_COUNTRY_CODE:
3149 try:
3150 numobj1 = parse(number1, None, keep_raw_input=False,
3151 _check_region=False, numobj=None)
3152 numobj2 = parse(number2, None, keep_raw_input=False,
3153 _check_region=False, numobj=None)
3154 return _is_number_match_OO(numobj1, numobj2)
3155 except NumberParseException:
3156 return MatchType.NOT_A_NUMBER
3158 # One or more of the phone numbers we are trying to match is not a viable
3159 # phone number.
3160 return MatchType.NOT_A_NUMBER
3163def _is_number_match_OS(numobj1, number2):
3164 """Wrapper variant of _is_number_match_OO that copes with one
3165 PhoneNumber object and one string."""
3166 # First see if the second number has an implicit country calling code, by
3167 # attempting to parse it.
3168 try:
3169 numobj2 = parse(number2, UNKNOWN_REGION)
3170 return _is_number_match_OO(numobj1, numobj2)
3171 except NumberParseException:
3172 _, exc, _ = sys.exc_info()
3173 if exc.error_type == NumberParseException.INVALID_COUNTRY_CODE:
3174 # The second number has no country calling code. EXACT_MATCH is no
3175 # longer possible. We parse it as if the region was the same as
3176 # that for the first number, and if EXACT_MATCH is returned, we
3177 # replace this with NSN_MATCH.
3178 region1 = region_code_for_country_code(numobj1.country_code)
3179 try:
3180 if region1 != UNKNOWN_REGION:
3181 numobj2 = parse(number2, region1)
3182 match = _is_number_match_OO(numobj1, numobj2)
3183 if match == MatchType.EXACT_MATCH:
3184 return MatchType.NSN_MATCH
3185 else:
3186 return match
3187 else:
3188 # If the first number didn't have a valid country calling
3189 # code, then we parse the second number without one as
3190 # well.
3191 numobj2 = parse(number2, None, keep_raw_input=False,
3192 _check_region=False, numobj=None)
3193 return _is_number_match_OO(numobj1, numobj2)
3194 except NumberParseException:
3195 return MatchType.NOT_A_NUMBER
3196 # One or more of the phone numbers we are trying to match is not a viable
3197 # phone number.
3198 return MatchType.NOT_A_NUMBER
3201def is_number_match(num1, num2):
3202 """Takes two phone numbers and compares them for equality.
3204 For example, the numbers +1 345 657 1234 and 657 1234 are a SHORT_NSN_MATCH.
3205 The numbers +1 345 657 1234 and 345 657 are a NO_MATCH.
3207 Arguments
3208 num1 -- First number object or string to compare. Can contain formatting,
3209 and can have country calling code specified with + at the start.
3210 num2 -- Second number object or string to compare. Can contain formatting,
3211 and can have country calling code specified with + at the start.
3213 Returns:
3214 - EXACT_MATCH if the country_code, NSN, presence of a leading zero for
3215 Italian numbers and any extension present are the same.
3216 - NSN_MATCH if either or both has no region specified, and the NSNs and
3217 extensions are the same.
3218 - SHORT_NSN_MATCH if either or both has no region specified, or the
3219 region specified is the same, and one NSN could be a shorter version of
3220 the other number. This includes the case where one has an extension
3221 specified, and the other does not.
3222 - NO_MATCH otherwise.
3223 """
3224 if isinstance(num1, PhoneNumber) and isinstance(num2, PhoneNumber):
3225 return _is_number_match_OO(num1, num2)
3226 elif isinstance(num1, PhoneNumber):
3227 return _is_number_match_OS(num1, num2)
3228 elif isinstance(num2, PhoneNumber):
3229 return _is_number_match_OS(num2, num1)
3230 else:
3231 return _is_number_match_SS(num1, num2)
3234def can_be_internationally_dialled(numobj):
3235 """Returns True if the number can only be dialled from outside the region,
3236 or unknown.
3238 If the number can only be dialled from within the region
3239 as well, returns False. Does not check the number is a valid number.
3240 Note that, at the moment, this method does not handle short numbers (which
3241 are currently all presumed to not be diallable from outside their country).
3243 Arguments:
3244 numobj -- the phone number objectfor which we want to know whether it is
3245 diallable from outside the region.
3246 """
3247 metadata = PhoneMetadata.metadata_for_region(region_code_for_number(numobj), None)
3248 if metadata is None:
3249 # Note numbers belonging to non-geographical entities (e.g. +800
3250 # numbers) are always internationally diallable, and will be caught
3251 # here.
3252 return True
3253 nsn = national_significant_number(numobj)
3254 return not _is_number_matching_desc(nsn, metadata.no_international_dialling)
3257def is_mobile_number_portable_region(region_code):
3258 """Returns true if the supplied region supports mobile number portability.
3259 Returns false for invalid, unknown or regions that don't support mobile
3260 number portability.
3262 Arguments:
3263 region_code -- the region for which we want to know whether it supports mobile number
3264 portability or not.
3265 """
3266 metadata = PhoneMetadata.metadata_for_region(region_code, None)
3267 if metadata is None:
3268 return False
3269 return metadata.mobile_number_portable_region
3272class NumberParseException(UnicodeMixin, Exception):
3273 """Exception when attempting to parse a putative phone number"""
3275 # The reason a string could not be interpreted as a phone number.
3277 # The country code supplied did not belong to a supported country or
3278 # non-geographical entity.
3279 INVALID_COUNTRY_CODE = 0
3281 # This generally indicates the string passed in had fewer than 3 digits in
3282 # it. The number failed to match the regular expression
3283 # _VALID_PHONE_NUMBER in phonenumberutil.py.
3284 NOT_A_NUMBER = 1
3286 # This indicates the string started with an international dialing prefix,
3287 # but after this was removed, it had fewer digits than any valid phone
3288 # number (including country code) could have.
3289 TOO_SHORT_AFTER_IDD = 2
3291 # This indicates the string, after any country code has been stripped,
3292 # had fewer digits than any valid phone number could have.
3293 TOO_SHORT_NSN = 3
3295 # This indicates the string had more digits than any valid phone number
3296 # could have
3297 TOO_LONG = 4
3299 def __init__(self, error_type, msg):
3300 Exception.__init__(self, msg)
3301 self.error_type = error_type
3302 self._msg = msg
3304 def __reduce__(self):
3305 return (type(self), (self.error_type, self._msg))
3307 def __unicode__(self):
3308 return unicod("(%s) %s") % (self.error_type, self._msg)
3311def _match_national_number(number, number_desc, allow_prefix_match):
3312 """Returns whether the given national number (a string containing only decimal digits) matches
3313 the national number pattern defined in the given PhoneNumberDesc object.
3314 """
3315 # We don't want to consider it a prefix match when matching non-empty input against an empty
3316 # pattern.
3317 if number_desc is None or number_desc.national_number_pattern is None or len(number_desc.national_number_pattern) == 0: 3317 ↛ 3318line 3317 didn't jump to line 3318, because the condition on line 3317 was never true
3318 return False
3319 return _match(number, re.compile(number_desc.national_number_pattern), allow_prefix_match)
3322def _match(number, pattern, allow_prefix_match):
3323 if not pattern.match(number):
3324 return False
3325 else:
3326 if fullmatch(pattern, number): 3326 ↛ 3329line 3326 didn't jump to line 3329, because the condition on line 3326 was never false
3327 return True
3328 else:
3329 return allow_prefix_match