Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.10/site-packages/phonenumbers/phonenumberutil.py: 34%

Shortcuts on this page

r m x   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1203 statements  

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

2"""Python phone number parsing and formatting library 

3 

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. 

7 

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 

30 

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 

35 

36# Data class definitions 

37from .phonenumber import PhoneNumber, CountryCodeSource 

38from .phonemetadata import NumberFormat, PhoneMetadata, REGION_CODE_FOR_NON_GEO_ENTITY 

39 

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 

54 

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 

59 

60# Naming convention for phone number arguments and variables: 

61# - string arguments are named 'number' 

62# - PhoneNumber objects are named 'numobj' 

63 

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 codes that doesn't have national prefix, but it has area codes. 

93_COUNTRIES_WITHOUT_NATIONAL_PREFIX_WITH_AREA_CODES = frozenset(( 

94 52,)) # Mexico 

95 

96# Set of country calling codes that have geographically assigned mobile 

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

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

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

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

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

102_GEO_MOBILE_COUNTRIES = _GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES | set(( 

103 52, # Mexico 

104 54, # Argentina 

105 55, # Brazil 

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

107# The PLUS_SIGN signifies the international prefix. 

108_PLUS_SIGN = u("+") 

109_STAR_SIGN = u('*') 

110_RFC3966_EXTN_PREFIX = u(";ext=") 

111_RFC3966_PREFIX = u("tel:") 

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

113_RFC3966_ISDN_SUBADDRESS = u(";isub=") 

114 

115# Simple ASCII digits map used to populate _ALPHA_PHONE_MAPPINGS and 

116# _ALL_PLUS_NUMBER_GROUPING_SYMBOLS. 

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

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

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

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

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

122 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

150# For performance reasons, amalgamate both into one map. 

151_ALPHA_PHONE_MAPPINGS = dict(_ALPHA_MAPPINGS, **_ASCII_DIGITS_MAP) 

152 

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

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

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

156_DIALLABLE_CHAR_MAPPINGS = dict({_PLUS_SIGN: _PLUS_SIGN, 

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

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

159 **_ASCII_DIGITS_MAP) 

160 

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

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

163# such as "-" and " ". 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

180 # Put (lower letter -> upper letter) and 

181 # (upper letter -> upper letter) mappings. 

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

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

184 **_ASCII_DIGITS_MAP)) 

185 

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

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

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

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

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

191# that are not ASCII digits or a tilde. 

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

193 

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

195# excludes punctuation found as a leading character only. 

196 

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

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

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

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

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

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

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

204 

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

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

207# case. 

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

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

210_PLUS_CHARS = u("+\uFF0B") 

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

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

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

214 

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

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

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

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

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

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

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

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

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

224 

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

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

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

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

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

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

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

232_SECOND_NUMBER_START_PATTERN = re.compile(_SECOND_NUMBER_START) 

233 

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

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

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

237# extension. 

238# 

239# The original Java regexp is: 

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

241# which splits out as: 

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

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

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

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

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

247# [^#] : character other than hash 

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

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

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

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

252_UNWANTED_END_CHAR_PATTERN = re.compile(_UNWANTED_END_CHARS) 

253 

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

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

256# are represented by letters. 

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

258 

259# Regular expression of viable phone numbers. This is location 

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

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

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

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

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

265# Corresponds to the following: 

266# [digits]{minLengthNsn}| 

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

268# 

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

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

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

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

273# alpha-characters and punctuation. 

274# 

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

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

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

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

279 

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

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

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

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

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

285_DEFAULT_EXTN_PREFIX = u(" ext. ") 

286 

287 

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

289# captures up to max_length digits. 

290def _extn_digits(max_length): 

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

292 

293 

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

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

296# changed, _maybe_strip_extension needs to be updated. 

297def _create_extn_pattern(for_parsing): 

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

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

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

301 # interpretations as the extension labels are not standardized. 

302 ext_limit_after_explicit_label = 20 

303 ext_limit_after_likely_label = 15 

304 ext_limit_after_ambiguous_char = 9 

305 ext_limit_when_not_sure = 6 

306 

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

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

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

310 optional_extn_suffix = u("#?") 

311 

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

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

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

315 # unicode decomposed form with the combining acute accent. 

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

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

318 # or more ambiguous extension labels. 

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

320 # When extension is not separated clearly. 

321 ambiguous_separator = u("[- ]+") 

322 

323 rfc_extn = _RFC3966_EXTN_PREFIX + _extn_digits(ext_limit_after_explicit_label) 

324 explicit_extn = (possible_separators_between_number_and_ext_label + explicit_ext_labels + 

325 possible_chars_after_ext_label + _extn_digits(ext_limit_after_explicit_label) + 

326 optional_extn_suffix) 

327 ambiguous_extn = (possible_separators_between_number_and_ext_label + ambiguous_ext_labels + 

328 possible_chars_after_ext_label + _extn_digits(ext_limit_after_ambiguous_char) + optional_extn_suffix) 

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

330 

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

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

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

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

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

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

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

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

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

340 explicit_extn + u("|") + 

341 ambiguous_extn + u("|") + 

342 american_style_extn_with_suffix) 

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

344 if for_parsing: 

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

346 # extension label may have it. 

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

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

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

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

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

352 

353 auto_dialling_extn = (possible_separators_number_ext_label_no_comma + 

354 auto_dialling_and_ext_labels_found + possible_chars_after_ext_label + 

355 _extn_digits(ext_limit_after_likely_label) + optional_extn_suffix) 

356 only_commas_extn = (possible_separators_number_ext_label_no_comma + 

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

358 optional_extn_suffix) 

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

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

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

362 # cap on the number of digits in such extensions. 

363 return (extension_pattern + u("|") + 

364 auto_dialling_extn + u("|") + 

365 only_commas_extn) 

366 return extension_pattern 

367 

368 

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

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

371# also provided after each ASCII version. 

372_EXTN_PATTERNS_FOR_PARSING = _create_extn_pattern(True) 

373_EXTN_PATTERNS_FOR_MATCHING = _create_extn_pattern(False) 

374 

375# Regular expression of valid global-number-digits for the phone-context 

376# parameter, following the syntax defined in RFC3966. 

377_RFC3966_VISUAL_SEPARATOR = "[\\-\\.\\(\\)]?" 

378_RFC3966_PHONE_DIGIT = "(" + _DIGITS + "|" + _RFC3966_VISUAL_SEPARATOR + ")" 

379_RFC3966_GLOBAL_NUMBER_DIGITS = "^\\" + _PLUS_SIGN + _RFC3966_PHONE_DIGIT + "*" + _DIGITS + _RFC3966_PHONE_DIGIT + "*$" 

380_RFC3966_GLOBAL_NUMBER_DIGITS_PATTERN = re.compile(_RFC3966_GLOBAL_NUMBER_DIGITS) 

381 

382# Regular expression of valid domainname for the phone-context parameter, 

383# following the syntax defined in RFC3966. 

384_ALPHANUM = _VALID_ALPHA + _DIGITS 

385_RFC3966_DOMAINLABEL = "[" + _ALPHANUM + "]+((\\-)*[" + _ALPHANUM + "])*" 

386_RFC3966_TOPLABEL = "[" + _VALID_ALPHA + "]+((\\-)*[" + _ALPHANUM + "])*" 

387_RFC3966_DOMAINNAME = "^(" + _RFC3966_DOMAINLABEL + "\\.)*" + _RFC3966_TOPLABEL + "\\.?$" 

388_RFC3966_DOMAINNAME_PATTERN = re.compile(_RFC3966_DOMAINNAME) 

389 

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

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

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

393 

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

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

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

397 

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

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

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

401 

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

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

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

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

406# matched. 

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

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

409# carrier code respectively. 

410_NP_STRING = "$NP" 

411_FG_STRING = "$FG" 

412_CC_STRING = "$CC" 

413 

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

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

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

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

418 

419 

420class PhoneNumberFormat(object): 

421 """ 

422 Phone number format. 

423 

424 INTERNATIONAL and NATIONAL formats are consistent with the definition in 

425 ITU-T Recommendation E123. However we follow local conventions such as using 

426 '-' instead of whitespace as separators. For example, the number of the 

427 Google Switzerland office will be written as "+41 44 668 1800" in 

428 INTERNATIONAL format, and as "044 668 1800" in NATIONAL format. E164 format 

429 is as per INTERNATIONAL format but with no formatting applied, 

430 e.g. "+41446681800". RFC3966 is as per INTERNATIONAL format, but with all 

431 spaces and other separating symbols replaced with a hyphen, and with any 

432 phone number extension appended with ";ext=". It also will have a prefix of 

433 "tel:" added, e.g. "tel:+41-44-668-1800". 

434 

435 Note: If you are considering storing the number in a neutral format, you 

436 are highly advised to use the PhoneNumber class. 

437 """ 

438 E164 = 0 

439 INTERNATIONAL = 1 

440 NATIONAL = 2 

441 RFC3966 = 3 

442 

443 @classmethod 

444 def to_string(cls, val): 

445 """Return a string representation of a PhoneNumberFormat value""" 

446 if val == PhoneNumberFormat.E164: 

447 return u("E164") 

448 elif val == PhoneNumberFormat.INTERNATIONAL: 

449 return u("INTERNATIONAL") 

450 elif val == PhoneNumberFormat.NATIONAL: 

451 return u("NATIONAL") 

452 elif val == PhoneNumberFormat.RFC3966: 

453 return u("RFC3966") 

454 else: 

455 return u("INVALID (%d)" % val) 

456 

457 

458class PhoneNumberType(object): 

459 """Type of phone numbers.""" 

460 FIXED_LINE = 0 

461 MOBILE = 1 

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

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

464 FIXED_LINE_OR_MOBILE = 2 

465 # Freephone lines 

466 TOLL_FREE = 3 

467 PREMIUM_RATE = 4 

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

469 # and is hence typically less than PREMIUM_RATE calls. See 

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

471 SHARED_COST = 5 

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

473 VOIP = 6 

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

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

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

477 PERSONAL_NUMBER = 7 

478 PAGER = 8 

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

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

481 # a company. 

482 UAN = 9 

483 # Used for "Voice Mail Access Numbers". 

484 VOICEMAIL = 10 

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

486 # patterns for a specific region. 

487 UNKNOWN = 99 

488 

489 @classmethod 

490 def values(cls): 

491 return (PhoneNumberType.FIXED_LINE, 

492 PhoneNumberType.MOBILE, 

493 PhoneNumberType.FIXED_LINE_OR_MOBILE, 

494 PhoneNumberType.TOLL_FREE, 

495 PhoneNumberType.PREMIUM_RATE, 

496 PhoneNumberType.SHARED_COST, 

497 PhoneNumberType.VOIP, 

498 PhoneNumberType.PERSONAL_NUMBER, 

499 PhoneNumberType.PAGER, 

500 PhoneNumberType.UAN, 

501 PhoneNumberType.VOICEMAIL, 

502 PhoneNumberType.UNKNOWN) 

503 

504 @classmethod 

505 def to_string(cls, val): 

506 """Return a string representation of a PhoneNumberType value""" 

507 if val == PhoneNumberType.FIXED_LINE: 

508 return u("FIXED_LINE") 

509 elif val == PhoneNumberType.MOBILE: 

510 return u("MOBILE") 

511 elif val == PhoneNumberType.FIXED_LINE_OR_MOBILE: 

512 return u("FIXED_LINE_OR_MOBILE") 

513 elif val == PhoneNumberType.TOLL_FREE: 

514 return u("TOLL_FREE") 

515 elif val == PhoneNumberType.PREMIUM_RATE: 

516 return u("PREMIUM_RATE") 

517 elif val == PhoneNumberType.SHARED_COST: 

518 return u("SHARED_COST") 

519 elif val == PhoneNumberType.VOIP: 

520 return u("VOIP") 

521 elif val == PhoneNumberType.PERSONAL_NUMBER: 

522 return u("PERSONAL_NUMBER") 

523 elif val == PhoneNumberType.PAGER: 

524 return u("PAGER") 

525 elif val == PhoneNumberType.UAN: 

526 return u("UAN") 

527 elif val == PhoneNumberType.VOICEMAIL: 

528 return u("VOICEMAIL") 

529 elif val == PhoneNumberType.UNKNOWN: 

530 return u("UNKNOWN") 

531 else: 

532 return u("INVALID (%d)" % val) 

533 

534 

535class MatchType(object): 

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

537 # Not a telephone number 

538 NOT_A_NUMBER = 0 

539 # None of the match types below apply 

540 NO_MATCH = 1 

541 # Returns SHORT_NSN_MATCH if either or both has no region specified, or 

542 # the region specified is the same, and one NSN could be a shorter version 

543 # of the other number. This includes the case where one has an extension 

544 # specified, and the other does not. 

545 SHORT_NSN_MATCH = 2 

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

547 # the same. 

548 NSN_MATCH = 3 

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

550 # and any extension present are the same. 

551 EXACT_MATCH = 4 

552 

553 @classmethod 

554 def to_string(cls, val): 

555 """Return a string representation of a MatchType value""" 

556 if val == MatchType.NOT_A_NUMBER: 

557 return u("NOT_A_NUMBER") 

558 elif val == MatchType.NO_MATCH: 

559 return u("NO_MATCH") 

560 elif val == MatchType.SHORT_NSN_MATCH: 

561 return u("SHORT_NSN_MATCH") 

562 elif val == MatchType.NSN_MATCH: 

563 return u("NSN_MATCH") 

564 elif val == MatchType.EXACT_MATCH: 

565 return u("EXACT_MATCH") 

566 else: 

567 return u("INVALID (%d)" % val) 

568 

569 

570class ValidationResult(object): 

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

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

573 IS_POSSIBLE = 0 

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

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

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

577 # the country). 

578 IS_POSSIBLE_LOCAL_ONLY = 4 

579 # The number has an invalid country calling code. 

580 INVALID_COUNTRY_CODE = 1 

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

582 TOO_SHORT = 2 

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

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

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

586 # This can also be returned in the case where 

587 # is_possible_number_for_type_with_reason was called, and there are no 

588 # numbers of this type at all for this region. 

589 INVALID_LENGTH = 5 

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

591 TOO_LONG = 3 

592 

593 @classmethod 

594 def to_string(cls, val): 

595 """Return a string representation of a ValidationResult value""" 

596 if val == ValidationResult.IS_POSSIBLE: 

597 return u("IS_POSSIBLE") 

598 elif val == ValidationResult.IS_POSSIBLE_LOCAL_ONLY: 

599 return u("IS_POSSIBLE_LOCAL_ONLY") 

600 elif val == ValidationResult.INVALID_COUNTRY_CODE: 

601 return u("INVALID_COUNTRY_CODE") 

602 elif val == ValidationResult.TOO_SHORT: 

603 return u("TOO_SHORT") 

604 elif val == ValidationResult.INVALID_LENGTH: 

605 return u("INVALID_LENGTH") 

606 elif val == ValidationResult.TOO_LONG: 

607 return u("TOO_LONG") 

608 else: 

609 return u("INVALID (%d)" % val) 

610 

611 

612# Derived data structures 

613SUPPORTED_REGIONS = set() 

614COUNTRY_CODES_FOR_NON_GEO_REGIONS = set() 

615_NANPA_REGIONS = set() 

616 

617 

618def _regenerate_derived_data(): 

619 global SUPPORTED_REGIONS, COUNTRY_CODES_FOR_NON_GEO_REGIONS, _NANPA_REGIONS 

620 SUPPORTED_REGIONS.clear() 

621 COUNTRY_CODES_FOR_NON_GEO_REGIONS.clear() 

622 for cc, region_codes in COUNTRY_CODE_TO_REGION_CODE.items(): 

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

624 COUNTRY_CODES_FOR_NON_GEO_REGIONS.add(cc) 

625 else: 

626 SUPPORTED_REGIONS.update(region_codes) 

627 if REGION_CODE_FOR_NON_GEO_ENTITY in SUPPORTED_REGIONS: # pragma no cover 

628 SUPPORTED_REGIONS.remove(REGION_CODE_FOR_NON_GEO_ENTITY) 

629 _NANPA_REGIONS.clear() 

630 _NANPA_REGIONS.update(COUNTRY_CODE_TO_REGION_CODE[_NANPA_COUNTRY_CODE]) 

631 

632 

633_regenerate_derived_data() 

634 

635 

636def _copy_number_format(other): 

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

638 copy = NumberFormat(pattern=other.pattern, 

639 format=other.format, 

640 leading_digits_pattern=list(other.leading_digits_pattern), 

641 national_prefix_formatting_rule=other.national_prefix_formatting_rule, 

642 national_prefix_optional_when_formatting=other.national_prefix_optional_when_formatting, 

643 domestic_carrier_code_formatting_rule=other.domestic_carrier_code_formatting_rule) 

644 copy._mutable = True 

645 return copy 

646 

647 

648def _extract_possible_number(number): 

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

650 

651 This currently strips all leading characters that cannot be used to 

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

653 are defined in the VALID_START_CHAR_PATTERN. If none of these characters 

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

655 function also attempts to strip off any alternative extensions or endings 

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

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

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

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

660 

661 Arguments: 

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

663 

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

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

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

667 """ 

668 match = _VALID_START_CHAR_PATTERN.search(number) 

669 if match: 

670 number = number[match.start():] 

671 # Remove trailing non-alpha non-numerical characters. 

672 trailing_chars_match = _UNWANTED_END_CHAR_PATTERN.search(number) 

673 if trailing_chars_match: 

674 number = number[:trailing_chars_match.start()] 

675 # Check for extra numbers at the end. 

676 second_number_match = _SECOND_NUMBER_START_PATTERN.search(number) 

677 if second_number_match: 

678 number = number[:second_number_match.start()] 

679 return number 

680 else: 

681 return U_EMPTY_STRING 

682 

683 

684def _is_viable_phone_number(number): 

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

686 

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

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

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

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

691 method _extract_possible_number. 

692 

693 Arguments: 

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

695 

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

697 False 

698 """ 

699 if len(number) < _MIN_LENGTH_FOR_NSN: 

700 return False 

701 match = fullmatch(_VALID_PHONE_NUMBER_PATTERN, number) 

702 return bool(match) 

703 

704 

705def _normalize(number): 

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

707 

708 This performs the following conversions: 

709 - Punctuation is stripped. 

710 - For ALPHA/VANITY numbers: 

711 - Letters are converted to their numeric representation on a telephone 

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

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

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

715 typos. 

716 - For other numbers: 

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

718 - Arabic-Indic numerals are converted to European numerals. 

719 - Spurious alpha characters are stripped. 

720 

721 Arguments: 

722 number -- string representing a phone number 

723 

724 Returns the normalized string version of the phone number. 

725 """ 

726 m = fullmatch(_VALID_ALPHA_PHONE_PATTERN, number) 

727 if m: 

728 return _normalize_helper(number, _ALPHA_PHONE_MAPPINGS, True) 

729 else: 

730 return normalize_digits_only(number) 

731 

732 

733def normalize_digits_only(number, keep_non_digits=False): 

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

735 

736 This converts wide-ascii and arabic-indic numerals to European numerals, 

737 and strips punctuation and alpha characters (optional). 

738 

739 Arguments: 

740 number -- a string representing a phone number 

741 keep_non_digits -- whether to keep non-digits 

742 

743 Returns the normalized string version of the phone number. 

744 """ 

745 number = unicod(number) 

746 number_length = len(number) 

747 normalized_digits = U_EMPTY_STRING 

748 for ii in range(number_length): 

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

750 if d != -1: 

751 normalized_digits += unicod(d) 

752 elif keep_non_digits: 

753 normalized_digits += number[ii] 

754 return normalized_digits 

755 

756 

757def normalize_diallable_chars_only(number): 

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

759 

760 This strips all characters which are not diallable on a mobile phone 

761 keypad (including all non-ASCII digits). 

762 

763 Arguments: 

764 number -- a string of characters representing a phone number 

765 

766 Returns the normalized string version of the phone number. 

767 """ 

768 return _normalize_helper(number, _DIALLABLE_CHAR_MAPPINGS, True) 

769 

770 

771def convert_alpha_characters_in_number(number): 

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

773 but retains existing formatting.""" 

774 return _normalize_helper(number, _ALPHA_PHONE_MAPPINGS, False) 

775 

776 

777def length_of_geographical_area_code(numobj): 

778 """Return length of the geographical area code for a number. 

779 

780 Gets the length of the geographical area code from the PhoneNumber object 

781 passed in, so that clients could use it to split a national significant 

782 number into geographical area code and subscriber number. It works in such 

783 a way that the resultant subscriber number should be diallable, at least 

784 on some devices. An example of how this could be used: 

785 

786 >>> import phonenumbers 

787 >>> numobj = phonenumbers.parse("16502530000", "US") 

788 >>> nsn = phonenumbers.national_significant_number(numobj) 

789 >>> ac_len = phonenumbers.length_of_geographical_area_code(numobj) 

790 >>> if ac_len > 0: 

791 ... area_code = nsn[:ac_len] 

792 ... subscriber_number = nsn[ac_len:] 

793 ... else: 

794 ... area_code = "" 

795 ... subscriber_number = nsn 

796 

797 N.B.: area code is a very ambiguous concept, so the I18N team generally 

798 recommends against using it for most purposes, but recommends using the 

799 more general national_number instead. Read the following carefully before 

800 deciding to use this method: 

801 

802 - geographical area codes change over time, and this method honors those 

803 changes; therefore, it doesn't guarantee the stability of the result it 

804 produces. 

805 - subscriber numbers may not be diallable from all devices (notably 

806 mobile devices, which typically require the full national_number to be 

807 dialled in most countries). 

808 - most non-geographical numbers have no area codes, including numbers 

809 from non-geographical entities. 

810 - some geographical numbers have no area codes. 

811 

812 Arguments: 

813 numobj -- The PhoneNumber object to find the length of the area code form. 

814 

815 Returns the length of area code of the PhoneNumber object passed in. 

816 """ 

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

818 if metadata is None: 

819 return 0 

820 

821 ntype = number_type(numobj) 

822 country_code = numobj.country_code 

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

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

825 # area codes. 

826 # Note:this is our general assumption, but there are exceptions which are tracked in 

827 # _COUNTRIES_WITHOUT_NATIONAL_PREFIX_WITH_AREA_CODES. 

828 if (metadata.national_prefix is None and not numobj.italian_leading_zero and 

829 country_code not in _COUNTRIES_WITHOUT_NATIONAL_PREFIX_WITH_AREA_CODES): 

830 return 0 

831 

832 if (ntype == PhoneNumberType.MOBILE and 

833 (country_code in _GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES)): 

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

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

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

837 # metadata at this point. 

838 return 0 

839 

840 if not is_number_type_geographical(ntype, country_code): 

841 return 0 

842 

843 return length_of_national_destination_code(numobj) 

844 

845 

846def length_of_national_destination_code(numobj): 

847 """Return length of the national destination code code for a number. 

848 

849 Gets the length of the national destination code (NDC) from the 

850 PhoneNumber object passed in, so that clients could use it to split a 

851 national significant number into NDC and subscriber number. The NDC of a 

852 phone number is normally the first group of digit(s) right after the 

853 country calling code when the number is formatted in the international 

854 format, if there is a subscriber number part that follows. 

855 

856 N.B.: similar to an area code, not all numbers have an NDC! 

857 

858 An example of how this could be used: 

859 

860 >>> import phonenumbers 

861 >>> numobj = phonenumbers.parse("18002530000", "US") 

862 >>> nsn = phonenumbers.national_significant_number(numobj) 

863 >>> ndc_len = phonenumbers.length_of_national_destination_code(numobj) 

864 >>> if ndc_len > 0: 

865 ... national_destination_code = nsn[:ndc_len] 

866 ... subscriber_number = nsn[ndc_len:] 

867 ... else: 

868 ... national_destination_code = "" 

869 ... subscriber_number = nsn 

870 

871 Refer to the unittests to see the difference between this function and 

872 length_of_geographical_area_code. 

873 

874 Arguments: 

875 numobj -- The PhoneNumber object to find the length of the NDC from. 

876 

877 Returns the length of NDC of the PhoneNumber object passed in, which 

878 could be zero. 

879 """ 

880 if numobj.extension is not None: 

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

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

883 # extension here. 

884 copied_numobj = PhoneNumber() 

885 copied_numobj.merge_from(numobj) 

886 copied_numobj.extension = None 

887 else: 

888 copied_numobj = numobj 

889 

890 nsn = format_number(copied_numobj, PhoneNumberFormat.INTERNATIONAL) 

891 number_groups = re.split(NON_DIGITS_PATTERN, nsn) 

892 

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

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

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

896 # it is not the last group. 

897 if len(number_groups) <= 3: 

898 return 0 

899 

900 if number_type(numobj) == PhoneNumberType.MOBILE: 

901 # For example Argentinian mobile numbers, when formatted in the 

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

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

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

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

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

907 # phone number. 

908 mobile_token = country_mobile_token(numobj.country_code) 

909 if mobile_token != U_EMPTY_STRING: 

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

911 return len(number_groups[2]) 

912 

913 

914def country_mobile_token(country_code): 

915 """Returns the mobile token for the provided country calling code if it has one, otherwise 

916 returns an empty string. A mobile token is a number inserted before the area code when dialing 

917 a mobile number from that country from abroad. 

918 

919 Arguments: 

920 country_code -- the country calling code for which we want the mobile token 

921 Returns the mobile token, as a string, for the given country calling code. 

922 """ 

923 return _MOBILE_TOKEN_MAPPINGS.get(country_code, U_EMPTY_STRING) 

924 

925 

926def _normalize_helper(number, replacements, remove_non_matches): 

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

928 replacing all characters found in the accompanying map with the values 

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

930 

931 Arguments: 

932 number -- a string representing a phone number 

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

934 by in the normalized version of the phone number 

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

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

937 they will be left unchanged in the number. 

938 

939 Returns the normalized string version of the phone number. 

940 """ 

941 normalized_number = [] 

942 for char in number: 

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

944 if new_digit is not None: 

945 normalized_number.append(new_digit) 

946 elif not remove_non_matches: 

947 normalized_number.append(char) 

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

949 return U_EMPTY_STRING.join(normalized_number) 

950 

951 

952def supported_calling_codes(): 

953 """Returns all country calling codes the library has metadata for, covering 

954 both non-geographical entities (global network calling codes) and those 

955 used for geographical entities. This could be used to populate a drop-down 

956 box of country calling codes for a phone-number widget, for instance. 

957 

958 Returns an unordered set of the country calling codes for every geographica 

959 and non-geographical entity the library supports. 

960 """ 

961 return set(COUNTRY_CODE_TO_REGION_CODE.keys()) 

962 

963 

964def _desc_has_possible_number_data(desc): 

965 

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

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

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

969 if desc is None: 

970 return False 

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

972 

973 

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

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

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

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

978def _desc_has_data(desc): 

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

980 if desc is None: 

981 return False 

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

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

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

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

986 return ((desc.example_number is not None) or 

987 _desc_has_possible_number_data(desc) or 

988 (desc.national_number_pattern is not None)) 

989 

990 

991def _supported_types_for_metadata(metadata): 

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

993 numtypes = set() 

994 for numtype in PhoneNumberType.values(): 

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

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

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

998 continue 

999 if _desc_has_data(_number_desc_by_type(metadata, numtype)): 

1000 numtypes.add(numtype) 

1001 return numtypes 

1002 

1003 

1004def supported_types_for_region(region_code): 

1005 """Returns the types for a given region which the library has metadata for. 

1006 

1007 Will not include FIXED_LINE_OR_MOBILE (if numbers in this region could 

1008 be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would 

1009 be present) and UNKNOWN. 

1010 

1011 No types will be returned for invalid or unknown region codes. 

1012 """ 

1013 if not _is_valid_region_code(region_code): 

1014 return set() 

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

1016 assert metadata is not None # due to _is_valid_region_code() check 

1017 return _supported_types_for_metadata(metadata) 

1018 

1019 

1020def supported_types_for_non_geo_entity(country_code): 

1021 """Returns the types for a country-code belonging to a non-geographical entity 

1022 which the library has metadata for. Will not include FIXED_LINE_OR_MOBILE 

1023 (if numbers for this non-geographical entity could be classified as 

1024 FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would be present) and 

1025 UNKNOWN. 

1026 

1027 No types will be returned for country calling codes that do not map to a 

1028 known non-geographical entity. 

1029 """ 

1030 metadata = PhoneMetadata.metadata_for_nongeo_region(country_code, None) 

1031 if metadata is None: 

1032 return set() 

1033 return _supported_types_for_metadata(metadata) 

1034 

1035 

1036def _formatting_rule_has_first_group_only(national_prefix_formatting_rule): 

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

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

1039 """ 

1040 if national_prefix_formatting_rule is None: 

1041 return True 

1042 return bool(fullmatch(_FIRST_GROUP_ONLY_PREFIX_PATTERN, 

1043 national_prefix_formatting_rule)) 

1044 

1045 

1046def is_number_geographical(numobj): 

1047 """Tests whether a phone number has a geographical association. 

1048 

1049 It checks if the number is associated with a certain region in the country 

1050 to which it belongs. Note that this doesn't verify if the number is 

1051 actually in use. 

1052 country_code -- the country calling code for which we want the mobile token 

1053 """ 

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

1055 

1056 

1057def is_number_type_geographical(num_type, country_code): 

1058 """Tests whether a phone number has a geographical association, 

1059 as represented by its type and the country it belongs to. 

1060 

1061 This version of isNumberGeographical exists since calculating the phone 

1062 number type is expensive; if we have already done this, we don't want to 

1063 do it again. 

1064 """ 

1065 return (num_type == PhoneNumberType.FIXED_LINE or 

1066 num_type == PhoneNumberType.FIXED_LINE_OR_MOBILE or 

1067 ((country_code in _GEO_MOBILE_COUNTRIES) and 

1068 num_type == PhoneNumberType.MOBILE)) 

1069 

1070 

1071def _is_valid_region_code(region_code): 

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

1073 if region_code is None: 

1074 return False 

1075 return (region_code in SUPPORTED_REGIONS) 

1076 

1077 

1078def _has_valid_country_calling_code(country_calling_code): 

1079 return (country_calling_code in COUNTRY_CODE_TO_REGION_CODE) 

1080 

1081 

1082def format_number(numobj, num_format): 

1083 """Formats a phone number in the specified format using default rules. 

1084 

1085 Note that this does not promise to produce a phone number that the user 

1086 can dial from where they are - although we do format in either 'national' 

1087 or 'international' format depending on what the client asks for, we do not 

1088 currently support a more abbreviated format, such as for users in the same 

1089 "area" who could potentially dial the number without area code. Note that 

1090 if the phone number has a country calling code of 0 or an otherwise 

1091 invalid country calling code, we cannot work out which formatting rules to 

1092 apply so we return the national significant number with no formatting 

1093 applied. 

1094 

1095 Arguments: 

1096 numobj -- The phone number to be formatted. 

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

1098 

1099 Returns the formatted phone number. 

1100 """ 

1101 if numobj.national_number == 0: 

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

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

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

1105 # anyway). 

1106 raw_input = numobj.raw_input or "" 

1107 if len(raw_input) > 0 or numobj.country_code is None: 

1108 return numobj.raw_input 

1109 country_calling_code = numobj.country_code 

1110 nsn = national_significant_number(numobj) 

1111 if num_format == PhoneNumberFormat.E164: 

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

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

1114 # applied. Extensions are not formatted. 

1115 return _prefix_number_with_country_calling_code(country_calling_code, num_format, nsn) 

1116 if not _has_valid_country_calling_code(country_calling_code): 

1117 return nsn 

1118 # Note region_code_for_country_code() is used because formatting 

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

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

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

1122 region_code = region_code_for_country_code(country_calling_code) 

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

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

1125 # region codes). 

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

1127 formatted_number = _format_nsn(nsn, metadata, num_format) 

1128 formatted_number = _maybe_append_formatted_extension(numobj, 

1129 metadata, 

1130 num_format, 

1131 formatted_number) 

1132 return _prefix_number_with_country_calling_code(country_calling_code, 

1133 num_format, 

1134 formatted_number) 

1135 

1136 

1137def format_by_pattern(numobj, number_format, user_defined_formats): 

1138 """Formats a phone number using client-defined formatting rules. 

1139 

1140 Note that if the phone number has a country calling code of zero or an 

1141 otherwise invalid country calling code, we cannot work out things like 

1142 whether there should be a national prefix applied, or how to format 

1143 extensions, so we return the national significant number with no 

1144 formatting applied. 

1145 

1146 Arguments: 

1147 numobj -- The phone number to be formatted 

1148 number_format -- The format the phone number should be formatted into, 

1149 as a PhoneNumberFormat value. 

1150 user_defined_formats -- formatting rules specified by clients, as a list 

1151 of NumberFormat objects. 

1152 

1153 Returns the formatted phone number. 

1154 """ 

1155 country_code = numobj.country_code 

1156 nsn = national_significant_number(numobj) 

1157 if not _has_valid_country_calling_code(country_code): 

1158 return nsn 

1159 # Note region_code_for_country_code() is used because formatting 

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

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

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

1163 region_code = region_code_for_country_code(country_code) 

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

1165 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code) 

1166 

1167 formatted_number = U_EMPTY_STRING 

1168 formatting_pattern = _choose_formatting_pattern_for_number(user_defined_formats, nsn) 

1169 if formatting_pattern is None: 

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

1171 formatted_number = nsn 

1172 else: 

1173 num_format_copy = _copy_number_format(formatting_pattern) 

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

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

1176 # replacements for different numbers have the appropriate national 

1177 # prefix. 

1178 np_formatting_rule = formatting_pattern.national_prefix_formatting_rule 

1179 if np_formatting_rule: 

1180 national_prefix = metadata.national_prefix 

1181 if national_prefix: 

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

1183 # group (\1) matcher. 

1184 np_formatting_rule = np_formatting_rule.replace(_NP_STRING, national_prefix) 

1185 np_formatting_rule = np_formatting_rule.replace(_FG_STRING, unicod("\\1")) 

1186 num_format_copy.national_prefix_formatting_rule = np_formatting_rule 

1187 else: 

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

1189 # prefix if there isn't one. 

1190 num_format_copy.national_prefix_formatting_rule = None 

1191 formatted_number = _format_nsn_using_pattern(nsn, num_format_copy, number_format) 

1192 formatted_number = _maybe_append_formatted_extension(numobj, 

1193 metadata, 

1194 number_format, 

1195 formatted_number) 

1196 formatted_number = _prefix_number_with_country_calling_code(country_code, 

1197 number_format, 

1198 formatted_number) 

1199 return formatted_number 

1200 

1201 

1202def format_national_number_with_carrier_code(numobj, carrier_code): 

1203 """Format a number in national format for dialing using the specified carrier. 

1204 

1205 The carrier-code will always be used regardless of whether the phone 

1206 number already has a preferred domestic carrier code stored. If 

1207 carrier_code contains an empty string, returns the number in national 

1208 format without any carrier code. 

1209 

1210 Arguments: 

1211 numobj -- The phone number to be formatted 

1212 carrier_code -- The carrier selection code to be used 

1213 

1214 Returns the formatted phone number in national format for dialing using 

1215 the carrier as specified in the carrier_code. 

1216 """ 

1217 country_code = numobj.country_code 

1218 nsn = national_significant_number(numobj) 

1219 if not _has_valid_country_calling_code(country_code): 

1220 return nsn 

1221 # Note region_code_for_country_code() is used because formatting 

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

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

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

1225 region_code = region_code_for_country_code(country_code) 

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

1227 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code) 

1228 formatted_number = _format_nsn(nsn, 

1229 metadata, 

1230 PhoneNumberFormat.NATIONAL, 

1231 carrier_code) 

1232 formatted_number = _maybe_append_formatted_extension(numobj, 

1233 metadata, 

1234 PhoneNumberFormat.NATIONAL, 

1235 formatted_number) 

1236 formatted_number = _prefix_number_with_country_calling_code(country_code, 

1237 PhoneNumberFormat.NATIONAL, 

1238 formatted_number) 

1239 return formatted_number 

1240 

1241 

1242def format_national_number_with_preferred_carrier_code(numobj, fallback_carrier_code): 

1243 """Formats a phone number in national format for dialing using the carrier 

1244 as specified in the preferred_domestic_carrier_code field of the 

1245 PhoneNumber object passed in. If that is missing, use the 

1246 fallback_carrier_code passed in instead. If there is no 

1247 preferred_domestic_carrier_code, and the fallback_carrier_code contains an 

1248 empty string, return the number in national format without any carrier 

1249 code. 

1250 

1251 Use format_national_number_with_carrier_code instead if the carrier code 

1252 passed in should take precedence over the number's 

1253 preferred_domestic_carrier_code when formatting. 

1254 

1255 Arguments: 

1256 numobj -- The phone number to be formatted 

1257 carrier_code -- The carrier selection code to be used, if none is found in the 

1258 phone number itself. 

1259 

1260 Returns the formatted phone number in national format for dialing using 

1261 the number's preferred_domestic_carrier_code, or the fallback_carrier_code 

1262 pass in if none is found. 

1263 """ 

1264 # Historically, we set this to an empty string when parsing with raw input 

1265 # if none was found in the input string. However, this doesn't result in a 

1266 # number we can dial. For this reason, we treat the empty string the same 

1267 # as if it isn't set at all. 

1268 if (numobj.preferred_domestic_carrier_code is not None and 

1269 len(numobj.preferred_domestic_carrier_code) > 0): 

1270 carrier_code = numobj.preferred_domestic_carrier_code 

1271 else: 

1272 carrier_code = fallback_carrier_code 

1273 return format_national_number_with_carrier_code(numobj, carrier_code) 

1274 

1275 

1276def format_number_for_mobile_dialing(numobj, region_calling_from, with_formatting): 

1277 """Returns a number formatted in such a way that it can be dialed from a 

1278 mobile phone in a specific region. 

1279 

1280 If the number cannot be reached from the region (e.g. some countries block 

1281 toll-free numbers from being called outside of the country), the method 

1282 returns an empty string. 

1283 

1284 Arguments: 

1285 numobj -- The phone number to be formatted 

1286 region_calling_from -- The region where the call is being placed. 

1287 

1288 with_formatting -- whether the number should be returned with formatting 

1289 symbols, such as spaces and dashes. 

1290 

1291 Returns the formatted phone number. 

1292 """ 

1293 country_calling_code = numobj.country_code 

1294 if not _has_valid_country_calling_code(country_calling_code): 

1295 if numobj.raw_input is None: 

1296 return U_EMPTY_STRING 

1297 else: 

1298 return numobj.raw_input 

1299 formatted_number = U_EMPTY_STRING 

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

1301 numobj_no_ext = PhoneNumber() 

1302 numobj_no_ext.merge_from(numobj) 

1303 numobj_no_ext.extension = None 

1304 region_code = region_code_for_country_code(country_calling_code) 

1305 numobj_type = number_type(numobj_no_ext) 

1306 is_valid_number = (numobj_type != PhoneNumberType.UNKNOWN) 

1307 if region_calling_from == region_code: 

1308 is_fixed_line_or_mobile = ((numobj_type == PhoneNumberType.FIXED_LINE) or 

1309 (numobj_type == PhoneNumberType.MOBILE) or 

1310 (numobj_type == PhoneNumberType.FIXED_LINE_OR_MOBILE)) 

1311 # Carrier codes may be needed in some countries. We handle this here. 

1312 if region_code == "BR" and is_fixed_line_or_mobile: 

1313 # Historically, we set this to an empty string when parsing with 

1314 # raw input if none was found in the input string. However, this 

1315 # doesn't result in a number we can dial. For this reason, we 

1316 # treat the empty string the same as if it isn't set at all. 

1317 if (numobj_no_ext.preferred_domestic_carrier_code is not None and 

1318 len(numobj_no_ext.preferred_domestic_carrier_code) > 0): 

1319 formatted_number = format_national_number_with_preferred_carrier_code(numobj_no_ext, "") 

1320 else: 

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

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

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

1324 # an empty string here. 

1325 formatted_number = U_EMPTY_STRING 

1326 elif country_calling_code == _NANPA_COUNTRY_CODE: 

1327 # For NANPA countries, we output international format for numbers 

1328 # that can be dialed internationally, since that always works, 

1329 # except for numbers which might potentially be short numbers, 

1330 # which are always dialled in national format. 

1331 metadata = PhoneMetadata.metadata_for_region(region_calling_from) 

1332 assert metadata is not None # due to _has_valid_country_calling_code() check 

1333 if (can_be_internationally_dialled(numobj_no_ext) and 

1334 _test_number_length(national_significant_number(numobj_no_ext), 

1335 metadata) != ValidationResult.TOO_SHORT): 

1336 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL) 

1337 else: 

1338 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL) 

1339 else: 

1340 # For non-geographical countries, and Mexican, Chilean, and Uzbek 

1341 # fixed line and mobile numbers, we output international format for 

1342 # numbers that can be dialed internationally as that always works. 

1343 if ((region_code == REGION_CODE_FOR_NON_GEO_ENTITY or 

1344 ((region_code == unicod("MX") or region_code == unicod("CL") or 

1345 region_code == unicod("UZ")) and 

1346 is_fixed_line_or_mobile)) and 

1347 can_be_internationally_dialled(numobj_no_ext)): 

1348 # MX fixed line and mobile numbers should always be formatted 

1349 # in international format, even when dialed within MX. For 

1350 # national format to work, a carrier code needs to be used, 

1351 # and the correct carrier code depends on if the caller and 

1352 # callee are from the same local area. It is trickier to get 

1353 # that to work correctly than using international format, 

1354 # which is tested to work fine on all carriers. 

1355 # CL fixed line numbers need the national prefix when dialing 

1356 # in the national format, but don't have it when used for 

1357 # display. The reverse is true for mobile numbers. As a 

1358 # result, we output them in the international format to make 

1359 # it work. 

1360 # UZ mobile and fixed-line numbers have to be formatted in 

1361 # international format or prefixed with special codes like 03, 

1362 # 04 (for fixed-line) and 05 (for mobile) for dialling 

1363 # successfully from mobile devices. As we do not have complete 

1364 # information on special codes and to be consistent with 

1365 # formatting across all phone types we return the number in 

1366 # international format here. 

1367 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL) 

1368 else: 

1369 formatted_number = format_number(numobj_no_ext, PhoneNumberFormat.NATIONAL) 

1370 elif is_valid_number and can_be_internationally_dialled(numobj_no_ext): 

1371 # We assume that short numbers are not diallable from outside their 

1372 # region, so if a number is not a valid regular length phone number, 

1373 # we treat it as if it cannot be internationally dialled. 

1374 if with_formatting: 

1375 return format_number(numobj_no_ext, PhoneNumberFormat.INTERNATIONAL) 

1376 else: 

1377 return format_number(numobj_no_ext, PhoneNumberFormat.E164) 

1378 

1379 if with_formatting: 

1380 return formatted_number 

1381 else: 

1382 return normalize_diallable_chars_only(formatted_number) 

1383 

1384 

1385def format_out_of_country_calling_number(numobj, region_calling_from): 

1386 """Formats a phone number for out-of-country dialing purposes. 

1387 

1388 If no region_calling_from is supplied, we format the number in its 

1389 INTERNATIONAL format. If the country calling code is the same as that of 

1390 the region where the number is from, then NATIONAL formatting will be 

1391 applied. 

1392 

1393 If the number itself has a country calling code of zero or an otherwise 

1394 invalid country calling code, then we return the number with no formatting 

1395 applied. 

1396 

1397 Note this function takes care of the case for calling inside of NANPA and 

1398 between Russia and Kazakhstan (who share the same country calling 

1399 code). In those cases, no international prefix is used. For regions which 

1400 have multiple international prefixes, the number in its INTERNATIONAL 

1401 format will be returned instead. 

1402 

1403 Arguments: 

1404 numobj -- The phone number to be formatted 

1405 region_calling_from -- The region where the call is being placed 

1406 

1407 Returns the formatted phone number 

1408 """ 

1409 if not _is_valid_region_code(region_calling_from): 

1410 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL) 

1411 country_code = numobj.country_code 

1412 nsn = national_significant_number(numobj) 

1413 if not _has_valid_country_calling_code(country_code): 

1414 return nsn 

1415 if country_code == _NANPA_COUNTRY_CODE: 

1416 if is_nanpa_country(region_calling_from): 

1417 # For NANPA regions, return the national format for these regions 

1418 # but prefix it with the country calling code. 

1419 return (unicod(country_code) + U_SPACE + 

1420 format_number(numobj, PhoneNumberFormat.NATIONAL)) 

1421 elif country_code == country_code_for_valid_region(region_calling_from): 

1422 # If regions share a country calling code, the country calling code 

1423 # need not be dialled. This also applies when dialling within a 

1424 # region, so this if clause covers both these cases. Technically this 

1425 # is the case for dialling from La Reunion to other overseas 

1426 # departments of France (French Guiana, Martinique, Guadeloupe), but 

1427 # not vice versa - so we don't cover this edge case for now and for 

1428 # those cases return the version including country calling code. 

1429 # Details here: 

1430 # http://www.petitfute.com/voyage/225-info-pratiques-reunion 

1431 return format_number(numobj, PhoneNumberFormat.NATIONAL) 

1432 

1433 # Metadata cannot be None because we checked '_is_valid_region_code()' above. 

1434 metadata_for_region_calling_from = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_calling_from.upper()) 

1435 international_prefix = metadata_for_region_calling_from.international_prefix 

1436 

1437 # In general, if there is a preferred international prefix, use that. Otherwise, for regions 

1438 # that have multiple international prefixes, the international format of the number is 

1439 # returned since we would not know which one to use. 

1440 i18n_prefix_for_formatting = U_EMPTY_STRING 

1441 if metadata_for_region_calling_from.preferred_international_prefix is not None: 

1442 i18n_prefix_for_formatting = metadata_for_region_calling_from.preferred_international_prefix 

1443 elif fullmatch(_SINGLE_INTERNATIONAL_PREFIX, international_prefix): 

1444 i18n_prefix_for_formatting = international_prefix 

1445 

1446 region_code = region_code_for_country_code(country_code) 

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

1448 metadata_for_region = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code.upper()) 

1449 formatted_national_number = _format_nsn(nsn, 

1450 metadata_for_region, 

1451 PhoneNumberFormat.INTERNATIONAL) 

1452 formatted_number = _maybe_append_formatted_extension(numobj, 

1453 metadata_for_region, 

1454 PhoneNumberFormat.INTERNATIONAL, 

1455 formatted_national_number) 

1456 if len(i18n_prefix_for_formatting) > 0: 

1457 formatted_number = (i18n_prefix_for_formatting + U_SPACE + 

1458 unicod(country_code) + U_SPACE + formatted_number) 

1459 else: 

1460 formatted_number = _prefix_number_with_country_calling_code(country_code, 

1461 PhoneNumberFormat.INTERNATIONAL, 

1462 formatted_number) 

1463 return formatted_number 

1464 

1465 

1466def format_in_original_format(numobj, region_calling_from): 

1467 """Formats a phone number using the original phone number format 

1468 (e.g. INTERNATIONAL or NATIONAL) that the number is parsed from, provided 

1469 that the number has been parsed with parse(.., keep_raw_input=True). 

1470 Otherwise the number will be formatted in NATIONAL format. 

1471 

1472 The original format is embedded in the country_code_source field of the 

1473 PhoneNumber object passed in, which is only set when parsing keeps the raw 

1474 input. When we don't have a formatting pattern for the number, the method 

1475 falls back to returning the raw input. 

1476 

1477 Note this method guarantees no digit will be inserted, removed or modified 

1478 as a result of formatting. 

1479 

1480 Arguments: 

1481 number -- The phone number that needs to be formatted in its original 

1482 number format 

1483 region_calling_from -- The region whose IDD needs to be prefixed if the 

1484 original number has one. 

1485 

1486 Returns the formatted phone number in its original number format. 

1487 """ 

1488 if (numobj.raw_input is not None and not _has_formatting_pattern_for_number(numobj)): 

1489 # We check if we have the formatting pattern because without that, we 

1490 # might format the number as a group without national prefix. 

1491 return numobj.raw_input 

1492 if numobj.country_code_source is CountryCodeSource.UNSPECIFIED: 

1493 return format_number(numobj, PhoneNumberFormat.NATIONAL) 

1494 

1495 formatted_number = _format_original_allow_mods(numobj, region_calling_from) 

1496 num_raw_input = numobj.raw_input 

1497 # If no digit is inserted/removed/modified as a result of our formatting, 

1498 # we return the formatted phone number; otherwise we return the raw input 

1499 # the user entered. 

1500 if (formatted_number is not None and num_raw_input): 

1501 normalized_formatted_number = normalize_diallable_chars_only(formatted_number) 

1502 normalized_raw_input = normalize_diallable_chars_only(num_raw_input) 

1503 if normalized_formatted_number != normalized_raw_input: 

1504 formatted_number = num_raw_input 

1505 return formatted_number 

1506 

1507 

1508def _format_original_allow_mods(numobj, region_calling_from): 

1509 if (numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN): 

1510 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL) 

1511 elif numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITH_IDD: 

1512 return format_out_of_country_calling_number(numobj, region_calling_from) 

1513 elif (numobj.country_code_source == CountryCodeSource.FROM_NUMBER_WITHOUT_PLUS_SIGN): 

1514 return format_number(numobj, PhoneNumberFormat.INTERNATIONAL)[1:] 

1515 else: 

1516 region_code = region_code_for_country_code(numobj.country_code) 

1517 # We strip non-digits from the NDD here, and from the raw input later, so that we can 

1518 # compare them easily. 

1519 national_prefix = ndd_prefix_for_region(region_code, True) # strip non-digits 

1520 national_format = format_number(numobj, PhoneNumberFormat.NATIONAL) 

1521 if (national_prefix is None or len(national_prefix) == 0): 

1522 # If the region doesn't have a national prefix at all, we can 

1523 # safely return the national format without worrying about a 

1524 # national prefix being added. 

1525 return national_format 

1526 # Otherwise, we check if the original number was entered with a national prefix. 

1527 if (_raw_input_contains_national_prefix(numobj.raw_input, national_prefix, region_code)): 

1528 # If so, we can safely return the national format. 

1529 return national_format 

1530 # Metadata cannot be None here because ndd_prefix_for_region() (above) returns None if 

1531 # there is no metadata for the region. 

1532 metadata = PhoneMetadata.metadata_for_region(region_code) 

1533 assert metadata is not None 

1534 national_number = national_significant_number(numobj) 

1535 format_rule = _choose_formatting_pattern_for_number(metadata.number_format, national_number) 

1536 # The format rule could still be null here if the national number was 

1537 # 0 and there was no raw input (this should not be possible for 

1538 # numbers generated by the phonenumber library as they would also not 

1539 # have a country calling code and we would have exited earlier). 

1540 if format_rule is None: 

1541 return national_format 

1542 # When the format we apply to this number doesn't contain national 

1543 # prefix, we can just return the national format. 

1544 # TODO: Refactor the code below with the code in isNationalPrefixPresentIfRequired. 

1545 candidate_national_prefix_rule = format_rule.national_prefix_formatting_rule 

1546 # We assume that the first-group symbol will never be _before_ the national prefix. 

1547 if candidate_national_prefix_rule is None: 

1548 return national_format 

1549 index_of_first_group = candidate_national_prefix_rule.find("\\1") 

1550 if (index_of_first_group <= 0): 

1551 return national_format 

1552 candidate_national_prefix_rule = candidate_national_prefix_rule[:index_of_first_group] 

1553 candidate_national_prefix_rule = normalize_digits_only(candidate_national_prefix_rule) 

1554 if len(candidate_national_prefix_rule) == 0: 

1555 # National prefix not used when formatting this number. 

1556 return national_format 

1557 # Otherwise, we need to remove the national prefix from our output. 

1558 new_format_rule = _copy_number_format(format_rule) 

1559 new_format_rule.national_prefix_formatting_rule = None 

1560 return format_by_pattern(numobj, PhoneNumberFormat.NATIONAL, [new_format_rule]) 

1561 

1562 

1563def _raw_input_contains_national_prefix(raw_input, national_prefix, region_code): 

1564 """Check if raw_input, which is assumed to be in the national format, has a 

1565 national prefix. The national prefix is assumed to be in digits-only 

1566 form.""" 

1567 nnn = normalize_digits_only(raw_input) 

1568 if nnn.startswith(national_prefix): 

1569 try: 

1570 # Some Japanese numbers (e.g. 00777123) might be mistaken to 

1571 # contain the national prefix when written without it 

1572 # (e.g. 0777123) if we just do prefix matching. To tackle that, we 

1573 # check the validity of the number if the assumed national prefix 

1574 # is removed (777123 won't be valid in Japan). 

1575 return is_valid_number(parse(nnn[len(national_prefix):], region_code)) 

1576 except NumberParseException: 

1577 return False 

1578 return False 

1579 

1580 

1581def _has_formatting_pattern_for_number(numobj): 

1582 country_code = numobj.country_code 

1583 phone_number_region = region_code_for_country_code(country_code) 

1584 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, phone_number_region) 

1585 if metadata is None: 

1586 return False 

1587 national_number = national_significant_number(numobj) 

1588 format_rule = _choose_formatting_pattern_for_number(metadata.number_format, national_number) 

1589 return format_rule is not None 

1590 

1591 

1592def format_out_of_country_keeping_alpha_chars(numobj, region_calling_from): 

1593 """Formats a phone number for out-of-country dialing purposes. 

1594 

1595 Note that in this version, if the number was entered originally using 

1596 alpha characters and this version of the number is stored in raw_input, 

1597 this representation of the number will be used rather than the digit 

1598 representation. Grouping information, as specified by characters such as 

1599 "-" and " ", will be retained. 

1600 

1601 Caveats: 

1602 

1603 - This will not produce good results if the country calling code is both 

1604 present in the raw input _and_ is the start of the national 

1605 number. This is not a problem in the regions which typically use alpha 

1606 numbers. 

1607 

1608 - This will also not produce good results if the raw input has any 

1609 grouping information within the first three digits of the national 

1610 number, and if the function needs to strip preceding digits/words in 

1611 the raw input before these digits. Normally people group the first 

1612 three digits together so this is not a huge problem - and will be fixed 

1613 if it proves to be so. 

1614 

1615 Arguments: 

1616 numobj -- The phone number that needs to be formatted. 

1617 region_calling_from -- The region where the call is being placed. 

1618 

1619 Returns the formatted phone number 

1620 """ 

1621 num_raw_input = numobj.raw_input 

1622 # If there is no raw input, then we can't keep alpha characters because there aren't any. 

1623 # In this case, we return format_out_of_country_calling_number. 

1624 if num_raw_input is None or len(num_raw_input) == 0: 

1625 return format_out_of_country_calling_number(numobj, region_calling_from) 

1626 country_code = numobj.country_code 

1627 if not _has_valid_country_calling_code(country_code): 

1628 return num_raw_input 

1629 # Strip any prefix such as country calling code, IDD, that was present. We 

1630 # do this by comparing the number in raw_input with the parsed number. To 

1631 # do this, first we normalize punctuation. We retain number grouping 

1632 # symbols such as " " only. 

1633 num_raw_input = _normalize_helper(num_raw_input, 

1634 _ALL_PLUS_NUMBER_GROUPING_SYMBOLS, 

1635 True) 

1636 # Now we trim everything before the first three digits in the parsed 

1637 # number. We choose three because all valid alpha numbers have 3 digits at 

1638 # the start - if it does not, then we don't trim anything at 

1639 # all. Similarly, if the national number was less than three digits, we 

1640 # don't trim anything at all. 

1641 national_number = national_significant_number(numobj) 

1642 if len(national_number) > 3: 

1643 first_national_number_digit = num_raw_input.find(national_number[:3]) 

1644 if first_national_number_digit != -1: 

1645 num_raw_input = num_raw_input[first_national_number_digit:] 

1646 

1647 metadata_for_region_calling_from = PhoneMetadata.metadata_for_region(region_calling_from.upper(), None) 

1648 if country_code == _NANPA_COUNTRY_CODE: 

1649 if is_nanpa_country(region_calling_from): 

1650 return unicod(country_code) + U_SPACE + num_raw_input 

1651 elif (metadata_for_region_calling_from is not None and 

1652 country_code == country_code_for_region(region_calling_from)): 

1653 formatting_pattern = _choose_formatting_pattern_for_number(metadata_for_region_calling_from.number_format, 

1654 national_number) 

1655 if formatting_pattern is None: 

1656 # If no pattern above is matched, we format the original input 

1657 return num_raw_input 

1658 new_format = _copy_number_format(formatting_pattern) 

1659 # The first group is the first group of digits that the user 

1660 # wrote together. 

1661 new_format.pattern = u("(\\d+)(.*)") 

1662 # Here we just concatenate them back together after the national 

1663 # prefix has been fixed. 

1664 new_format.format = u(r"\1\2") 

1665 # Now we format using this pattern instead of the default pattern, 

1666 # but with the national prefix prefixed if necessary. 

1667 # This will not work in the cases where the pattern (and not the 

1668 # leading digits) decide whether a national prefix needs to be used, 

1669 # since we have overridden the pattern to match anything, but that is 

1670 # not the case in the metadata to date. 

1671 return _format_nsn_using_pattern(num_raw_input, 

1672 new_format, 

1673 PhoneNumberFormat.NATIONAL) 

1674 i18n_prefix_for_formatting = U_EMPTY_STRING 

1675 # If an unsupported region-calling-from is entered, or a country with 

1676 # multiple international prefixes, the international format of the number 

1677 # is returned, unless there is a preferred international prefix. 

1678 if metadata_for_region_calling_from is not None: 

1679 international_prefix = metadata_for_region_calling_from.international_prefix 

1680 i18n_match = fullmatch(_SINGLE_INTERNATIONAL_PREFIX, international_prefix) 

1681 if i18n_match: 

1682 i18n_prefix_for_formatting = international_prefix 

1683 else: 

1684 i18n_prefix_for_formatting = metadata_for_region_calling_from.preferred_international_prefix 

1685 

1686 region_code = region_code_for_country_code(country_code) 

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

1688 metadata_for_region = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code) 

1689 # Strip any extension 

1690 extension, stripped_number = _maybe_strip_extension(num_raw_input) 

1691 # Append the formatted extension 

1692 formatted_number = _maybe_append_formatted_extension(numobj, 

1693 metadata_for_region, 

1694 PhoneNumberFormat.INTERNATIONAL, 

1695 stripped_number) 

1696 if i18n_prefix_for_formatting: 

1697 formatted_number = (i18n_prefix_for_formatting + U_SPACE + 

1698 unicod(country_code) + U_SPACE + formatted_number) 

1699 else: 

1700 # Invalid region entered as country-calling-from (so no metadata was 

1701 # found for it) or the region chosen has multiple international 

1702 # dialling prefixes. 

1703 formatted_number = _prefix_number_with_country_calling_code(country_code, 

1704 PhoneNumberFormat.INTERNATIONAL, 

1705 formatted_number) 

1706 return formatted_number 

1707 

1708 

1709def national_significant_number(numobj): 

1710 """Gets the national significant number of a phone number. 

1711 

1712 Note that a national significant number doesn't contain a national prefix 

1713 or any formatting. 

1714 

1715 Arguments: 

1716 numobj -- The PhoneNumber object for which the national significant number 

1717 is needed. 

1718 

1719 Returns the national significant number of the PhoneNumber object passed 

1720 in. 

1721 """ 

1722 # If leading zero(s) have been set, we prefix this now. Note this is not a 

1723 # national prefix. 

1724 national_number = U_EMPTY_STRING 

1725 if numobj.italian_leading_zero: 

1726 num_zeros = numobj.number_of_leading_zeros 

1727 if num_zeros is None: 

1728 num_zeros = 1 

1729 if num_zeros > 0: 

1730 national_number = U_ZERO * num_zeros 

1731 national_number += str(numobj.national_number) 

1732 return national_number 

1733 

1734 

1735def _prefix_number_with_country_calling_code(country_code, num_format, formatted_number): 

1736 """A helper function that is used by format_number and format_by_pattern.""" 

1737 if num_format == PhoneNumberFormat.E164: 

1738 return _PLUS_SIGN + unicod(country_code) + formatted_number 

1739 elif num_format == PhoneNumberFormat.INTERNATIONAL: 

1740 return _PLUS_SIGN + unicod(country_code) + U_SPACE + formatted_number 

1741 elif num_format == PhoneNumberFormat.RFC3966: 

1742 return _RFC3966_PREFIX + _PLUS_SIGN + unicod(country_code) + U_DASH + formatted_number 

1743 else: 

1744 return formatted_number 

1745 

1746 

1747def _format_nsn(number, metadata, num_format, carrier_code=None): 

1748 """Format a national number.""" 

1749 # Note in some regions, the national number can be written in two 

1750 # completely different ways depending on whether it forms part of the 

1751 # NATIONAL format or INTERNATIONAL format. The num_format parameter here 

1752 # is used to specify which format to use for those cases. If a carrier_code 

1753 # is specified, this will be inserted into the formatted string to replace 

1754 # $CC. 

1755 intl_number_formats = metadata.intl_number_format 

1756 

1757 # When the intl_number_formats exists, we use that to format national 

1758 # number for the INTERNATIONAL format instead of using the 

1759 # number_desc.number_formats. 

1760 if (len(intl_number_formats) == 0 or 

1761 num_format == PhoneNumberFormat.NATIONAL): 

1762 available_formats = metadata.number_format 

1763 else: 

1764 available_formats = metadata.intl_number_format 

1765 formatting_pattern = _choose_formatting_pattern_for_number(available_formats, number) 

1766 if formatting_pattern is None: 

1767 return number 

1768 else: 

1769 return _format_nsn_using_pattern(number, formatting_pattern, num_format, carrier_code) 

1770 

1771 

1772def _choose_formatting_pattern_for_number(available_formats, national_number): 

1773 for num_format in available_formats: 

1774 size = len(num_format.leading_digits_pattern) 

1775 # We always use the last leading_digits_pattern, as it is the most detailed. 

1776 if size > 0: 

1777 ld_pattern = re.compile(num_format.leading_digits_pattern[-1]) 

1778 ld_match = ld_pattern.match(national_number) 

1779 if size == 0 or ld_match: 

1780 format_pattern = re.compile(num_format.pattern) 

1781 if fullmatch(format_pattern, national_number): 

1782 return num_format 

1783 return None 

1784 

1785 

1786def _format_nsn_using_pattern(national_number, formatting_pattern, number_format, 

1787 carrier_code=None): 

1788 # Note that carrier_code is optional - if None or an empty string, no 

1789 # carrier code replacement will take place. 

1790 number_format_rule = formatting_pattern.format 

1791 m_re = re.compile(formatting_pattern.pattern) 

1792 formatted_national_number = U_EMPTY_STRING 

1793 

1794 if (number_format == PhoneNumberFormat.NATIONAL and carrier_code and 

1795 formatting_pattern.domestic_carrier_code_formatting_rule): 

1796 # Replace the $CC in the formatting rule with the desired 

1797 # carrier code. 

1798 cc_format_rule = formatting_pattern.domestic_carrier_code_formatting_rule 

1799 cc_format_rule = cc_format_rule.replace(_CC_STRING, carrier_code) 

1800 

1801 # Now replace the $FG in the formatting rule with the 

1802 # first group and the carrier code combined in the 

1803 # appropriate way. 

1804 number_format_rule = re.sub(_FIRST_GROUP_PATTERN, 

1805 cc_format_rule, 

1806 number_format_rule, 

1807 count=1) 

1808 formatted_national_number = re.sub(m_re, number_format_rule, national_number) 

1809 else: 

1810 # Use the national prefix formatting rule instead. 

1811 national_prefix_formatting_rule = formatting_pattern.national_prefix_formatting_rule 

1812 if (number_format == PhoneNumberFormat.NATIONAL and 

1813 national_prefix_formatting_rule): 

1814 first_group_rule = re.sub(_FIRST_GROUP_PATTERN, 

1815 national_prefix_formatting_rule, 

1816 number_format_rule, 

1817 count=1) 

1818 formatted_national_number = re.sub(m_re, first_group_rule, national_number) 

1819 else: 

1820 formatted_national_number = re.sub(m_re, number_format_rule, national_number) 

1821 

1822 if number_format == PhoneNumberFormat.RFC3966: 

1823 # Strip any leading punctuation. 

1824 m = _SEPARATOR_PATTERN.match(formatted_national_number) 

1825 if m: 

1826 formatted_national_number = re.sub(_SEPARATOR_PATTERN, U_EMPTY_STRING, formatted_national_number, count=1) 

1827 # Replace the rest with a dash between each number group 

1828 formatted_national_number = re.sub(_SEPARATOR_PATTERN, U_DASH, formatted_national_number) 

1829 

1830 return formatted_national_number 

1831 

1832 

1833def example_number(region_code): 

1834 """Gets a valid number for the specified region. 

1835 

1836 Arguments: 

1837 region_code -- The region for which an example number is needed. 

1838 

1839 Returns a valid fixed-line number for the specified region. Returns None 

1840 when the metadata does not contain such information, or the region 001 is 

1841 passed in. For 001 (representing non-geographical numbers), call 

1842 example_number_for_non_geo_entity instead. 

1843 """ 

1844 return example_number_for_type(region_code, PhoneNumberType.FIXED_LINE) 

1845 

1846 

1847def invalid_example_number(region_code): 

1848 """Gets an invalid number for the specified region. 

1849 

1850 This is useful for unit-testing purposes, where you want to test what 

1851 will happen with an invalid number. Note that the number that is 

1852 returned will always be able to be parsed and will have the correct 

1853 country code. It may also be a valid *short* number/code for this 

1854 region. Validity checking such numbers is handled with shortnumberinfo. 

1855 

1856 Arguments: 

1857 region_code -- The region for which an example number is needed. 

1858 

1859 

1860 Returns an invalid number for the specified region. Returns None when an 

1861 unsupported region or the region 001 (Earth) is passed in. 

1862 """ 

1863 if not _is_valid_region_code(region_code): 

1864 return None 

1865 # We start off with a valid fixed-line number since every country 

1866 # supports this. Alternatively we could start with a different number 

1867 # type, since fixed-line numbers typically have a wide breadth of valid 

1868 # number lengths and we may have to make it very short before we get an 

1869 # invalid number. 

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

1871 assert metadata is not None # due to _is_valid_region_code() check 

1872 desc = _number_desc_by_type(metadata, PhoneNumberType.FIXED_LINE) 

1873 if desc is None or desc.example_number is None: 

1874 # This shouldn't happen; we have a test for this. 

1875 return None # pragma no cover 

1876 example_number = desc.example_number 

1877 # Try and make the number invalid. We do this by changing the length. We 

1878 # try reducing the length of the number, since currently no region has a 

1879 # number that is the same length as MIN_LENGTH_FOR_NSN. This is probably 

1880 # quicker than making the number longer, which is another 

1881 # alternative. We could also use the possible number pattern to extract 

1882 # the possible lengths of the number to make this faster, but this 

1883 # method is only for unit-testing so simplicity is preferred to 

1884 # performance. We don't want to return a number that can't be parsed, 

1885 # so we check the number is long enough. We try all possible lengths 

1886 # because phone number plans often have overlapping prefixes so the 

1887 # number 123456 might be valid as a fixed-line number, and 12345 as a 

1888 # mobile number. It would be faster to loop in a different order, but we 

1889 # prefer numbers that look closer to real numbers (and it gives us a 

1890 # variety of different lengths for the resulting phone numbers - 

1891 # otherwise they would all be MIN_LENGTH_FOR_NSN digits long.) 

1892 phone_number_length = len(example_number) - 1 

1893 while phone_number_length >= _MIN_LENGTH_FOR_NSN: 

1894 number_to_try = example_number[:phone_number_length] 

1895 try: 

1896 possibly_valid_number = parse(number_to_try, region_code) 

1897 if not is_valid_number(possibly_valid_number): 

1898 return possibly_valid_number 

1899 except NumberParseException: # pragma no cover 

1900 # Shouldn't happen: we have already checked the length, we know 

1901 # example numbers have only valid digits, and we know the region 

1902 # code is fine. 

1903 pass 

1904 phone_number_length -= 1 

1905 

1906 # We have a test to check that this doesn't happen for any of our 

1907 # supported regions. 

1908 return None # pragma no cover 

1909 

1910 

1911def example_number_for_type(region_code, num_type): 

1912 """Gets a valid number for the specified region and number type. 

1913 

1914 If None is given as the region_code, then the returned number object 

1915 may belong to any country. 

1916 

1917 Arguments: 

1918 region_code -- The region for which an example number is needed, or None. 

1919 num_type -- The type of number that is needed. 

1920 

1921 Returns a valid number for the specified region and type. Returns None 

1922 when the metadata does not contain such information or if an invalid 

1923 region or region 001 was specified. For 001 (representing 

1924 non-geographical numbers), call example_number_for_non_geo_entity instead. 

1925 """ 

1926 if region_code is None: 

1927 return _example_number_anywhere_for_type(num_type) 

1928 # Check the region code is valid. 

1929 if not _is_valid_region_code(region_code): 

1930 return None 

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

1932 assert metadata is not None # due to _is_valid_region_code() check 

1933 desc = _number_desc_by_type(metadata, num_type) 

1934 if desc is not None and desc.example_number is not None: 

1935 try: 

1936 return parse(desc.example_number, region_code) 

1937 except NumberParseException: # pragma no cover 

1938 pass 

1939 return None 

1940 

1941 

1942def _example_number_anywhere_for_type(num_type): 

1943 """Gets a valid number for the specified number type (it may belong to any country). 

1944 

1945 Arguments: 

1946 num_type -- The type of number that is needed. 

1947 

1948 Returns a valid number for the specified type. Returns None when the 

1949 metadata does not contain such information. This should only happen when 

1950 no numbers of this type are allocated anywhere in the world anymore. 

1951 """ 

1952 for region_code in SUPPORTED_REGIONS: 

1953 example_numobj = example_number_for_type(region_code, num_type) 

1954 if example_numobj is not None: 

1955 return example_numobj 

1956 # If there wasn't an example number for a region, try the non-geographical entities. 

1957 for country_calling_code in COUNTRY_CODES_FOR_NON_GEO_REGIONS: 

1958 metadata = PhoneMetadata.metadata_for_nongeo_region(country_calling_code, None) 

1959 desc = _number_desc_by_type(metadata, num_type) 

1960 if desc is not None and desc.example_number is not None: 

1961 try: 

1962 return parse(_PLUS_SIGN + unicod(country_calling_code) + desc.example_number, UNKNOWN_REGION) 

1963 except NumberParseException: # pragma no cover 

1964 pass 

1965 

1966 # There are no example numbers of this type for any country in the library. 

1967 return None # pragma no cover 

1968 

1969 

1970def example_number_for_non_geo_entity(country_calling_code): 

1971 """Gets a valid number for the specified country calling code for a non-geographical entity. 

1972 

1973 Arguments: 

1974 country_calling_code -- The country calling code for a non-geographical entity. 

1975 

1976 Returns a valid number for the non-geographical entity. Returns None when 

1977 the metadata does not contain such information, or the country calling 

1978 code passed in does not belong to a non-geographical entity. 

1979 """ 

1980 metadata = PhoneMetadata.metadata_for_nongeo_region(country_calling_code, None) 

1981 if metadata is not None: 

1982 # For geographical entities, fixed-line data is always present. However, for non-geographical 

1983 # entities, this is not the case, so we have to go through different types to find the 

1984 # example number. We don't check fixed-line or personal number since they aren't used by 

1985 # non-geographical entities (if this changes, a unit-test will catch this.) 

1986 for desc in (metadata.mobile, metadata.toll_free, metadata.shared_cost, metadata.voip, 

1987 metadata.voicemail, metadata.uan, metadata.premium_rate): 

1988 try: 

1989 if (desc is not None and desc.example_number is not None): 

1990 return parse(_PLUS_SIGN + unicod(country_calling_code) + desc.example_number, UNKNOWN_REGION) 

1991 except NumberParseException: 

1992 pass 

1993 return None 

1994 

1995 

1996def _maybe_append_formatted_extension(numobj, metadata, num_format, number): 

1997 """Appends the formatted extension of a phone number to formatted number, 

1998 if the phone number had an extension specified. 

1999 """ 

2000 if numobj.extension: 

2001 if num_format == PhoneNumberFormat.RFC3966: 

2002 return number + _RFC3966_EXTN_PREFIX + numobj.extension 

2003 else: 

2004 if metadata.preferred_extn_prefix is not None: 

2005 return number + metadata.preferred_extn_prefix + numobj.extension 

2006 else: 

2007 return number + _DEFAULT_EXTN_PREFIX + numobj.extension 

2008 return number 

2009 

2010 

2011def _number_desc_by_type(metadata, num_type): 

2012 """Return the PhoneNumberDesc of the metadata for the given number type""" 

2013 if num_type == PhoneNumberType.PREMIUM_RATE: 

2014 return metadata.premium_rate 

2015 elif num_type == PhoneNumberType.TOLL_FREE: 

2016 return metadata.toll_free 

2017 elif num_type == PhoneNumberType.MOBILE: 

2018 return metadata.mobile 

2019 elif (num_type == PhoneNumberType.FIXED_LINE or 

2020 num_type == PhoneNumberType.FIXED_LINE_OR_MOBILE): 

2021 return metadata.fixed_line 

2022 elif num_type == PhoneNumberType.SHARED_COST: 

2023 return metadata.shared_cost 

2024 elif num_type == PhoneNumberType.VOIP: 

2025 return metadata.voip 

2026 elif num_type == PhoneNumberType.PERSONAL_NUMBER: 

2027 return metadata.personal_number 

2028 elif num_type == PhoneNumberType.PAGER: 

2029 return metadata.pager 

2030 elif num_type == PhoneNumberType.UAN: 

2031 return metadata.uan 

2032 elif num_type == PhoneNumberType.VOICEMAIL: 

2033 return metadata.voicemail 

2034 else: 

2035 return metadata.general_desc 

2036 

2037 

2038def number_type(numobj): 

2039 """Gets the type of a valid phone number. 

2040 

2041 Arguments: 

2042 numobj -- The PhoneNumber object that we want to know the type of. 

2043 

2044 Returns the type of the phone number, as a PhoneNumberType value; 

2045 returns PhoneNumberType.UNKNOWN if it is invalid. 

2046 """ 

2047 region_code = region_code_for_number(numobj) 

2048 metadata = PhoneMetadata.metadata_for_region_or_calling_code(numobj.country_code, region_code) 

2049 if metadata is None: 

2050 return PhoneNumberType.UNKNOWN 

2051 national_number = national_significant_number(numobj) 

2052 return _number_type_helper(national_number, metadata) 

2053 

2054 

2055def _number_type_helper(national_number, metadata): 

2056 """Return the type of the given number against the metadata""" 

2057 if not _is_number_matching_desc(national_number, metadata.general_desc): 

2058 return PhoneNumberType.UNKNOWN 

2059 if _is_number_matching_desc(national_number, metadata.premium_rate): 

2060 return PhoneNumberType.PREMIUM_RATE 

2061 if _is_number_matching_desc(national_number, metadata.toll_free): 

2062 return PhoneNumberType.TOLL_FREE 

2063 if _is_number_matching_desc(national_number, metadata.shared_cost): 

2064 return PhoneNumberType.SHARED_COST 

2065 if _is_number_matching_desc(national_number, metadata.voip): 

2066 return PhoneNumberType.VOIP 

2067 if _is_number_matching_desc(national_number, metadata.personal_number): 

2068 return PhoneNumberType.PERSONAL_NUMBER 

2069 if _is_number_matching_desc(national_number, metadata.pager): 

2070 return PhoneNumberType.PAGER 

2071 if _is_number_matching_desc(national_number, metadata.uan): 

2072 return PhoneNumberType.UAN 

2073 if _is_number_matching_desc(national_number, metadata.voicemail): 

2074 return PhoneNumberType.VOICEMAIL 

2075 

2076 if _is_number_matching_desc(national_number, metadata.fixed_line): 

2077 if metadata.same_mobile_and_fixed_line_pattern: 

2078 return PhoneNumberType.FIXED_LINE_OR_MOBILE 

2079 elif _is_number_matching_desc(national_number, metadata.mobile): 

2080 return PhoneNumberType.FIXED_LINE_OR_MOBILE 

2081 return PhoneNumberType.FIXED_LINE 

2082 

2083 # Otherwise, test to see if the number is mobile. Only do this if certain 

2084 # that the patterns for mobile and fixed line aren't the same. 

2085 if (not metadata.same_mobile_and_fixed_line_pattern and 

2086 _is_number_matching_desc(national_number, metadata.mobile)): 

2087 return PhoneNumberType.MOBILE 

2088 return PhoneNumberType.UNKNOWN 

2089 

2090 

2091def _is_number_matching_desc(national_number, number_desc): 

2092 """Determine if the number matches the given PhoneNumberDesc""" 

2093 # Check if any possible number lengths are present; if so, we use them to avoid checking the 

2094 # validation pattern if they don't match. If they are absent, this means they match the general 

2095 # description, which we have already checked before checking a specific number type. 

2096 if number_desc is None: 

2097 return False 

2098 actual_length = len(national_number) 

2099 possible_lengths = number_desc.possible_length 

2100 if len(possible_lengths) > 0 and actual_length not in possible_lengths: 

2101 return False 

2102 return _match_national_number(national_number, number_desc, False) 

2103 

2104 

2105def is_valid_number(numobj): 

2106 """Tests whether a phone number matches a valid pattern. 

2107 

2108 Note this doesn't verify the number is actually in use, which is 

2109 impossible to tell by just looking at a number itself. It only verifies 

2110 whether the parsed, canonicalised number is valid: not whether a 

2111 particular series of digits entered by the user is diallable from the 

2112 region provided when parsing. For example, the number +41 (0) 78 927 2696 

2113 can be parsed into a number with country code "41" and national 

2114 significant number "789272696". This is valid, while the original string 

2115 is not diallable. 

2116 

2117 Arguments: 

2118 numobj -- The phone number object that we want to validate 

2119 

2120 Returns a boolean that indicates whether the number is of a valid pattern. 

2121 """ 

2122 region_code = region_code_for_number(numobj) 

2123 return is_valid_number_for_region(numobj, region_code) 

2124 

2125 

2126def is_valid_number_for_region(numobj, region_code): 

2127 """Tests whether a phone number is valid for a certain region. 

2128 

2129 Note this doesn't verify the number is actually in use, which is 

2130 impossible to tell by just looking at a number itself. If the country 

2131 calling code is not the same as the country calling code for the region, 

2132 this immediately exits with false. After this, the specific number pattern 

2133 rules for the region are examined. This is useful for determining for 

2134 example whether a particular number is valid for Canada, rather than just 

2135 a valid NANPA number. 

2136 

2137 Warning: In most cases, you want to use is_valid_number instead. For 

2138 example, this method will mark numbers from British Crown dependencies 

2139 such as the Isle of Man as invalid for the region "GB" (United Kingdom), 

2140 since it has its own region code, "IM", which may be undesirable. 

2141 

2142 Arguments: 

2143 numobj -- The phone number object that we want to validate. 

2144 region_code -- The region that we want to validate the phone number for. 

2145 

2146 Returns a boolean that indicates whether the number is of a valid pattern. 

2147 """ 

2148 country_code = numobj.country_code 

2149 if region_code is None: 

2150 return False 

2151 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code.upper()) 

2152 if (metadata is None or 

2153 (region_code != REGION_CODE_FOR_NON_GEO_ENTITY and 

2154 country_code != country_code_for_valid_region(region_code))): 

2155 # Either the region code was invalid, or the country calling code for 

2156 # this number does not match that of the region code. 

2157 return False 

2158 nsn = national_significant_number(numobj) 

2159 return (_number_type_helper(nsn, metadata) != PhoneNumberType.UNKNOWN) 

2160 

2161 

2162def region_code_for_number(numobj): 

2163 """Returns the region where a phone number is from. 

2164 

2165 This could be used for geocoding at the region level. Only guarantees 

2166 correct results for valid, full numbers (not short-codes, or invalid 

2167 numbers). 

2168 

2169 Arguments: 

2170 numobj -- The phone number object whose origin we want to know 

2171 

2172 Returns the region where the phone number is from, or None if no region 

2173 matches this calling code. 

2174 

2175 """ 

2176 country_code = numobj.country_code 

2177 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None) 

2178 if regions is None: 

2179 return None 

2180 

2181 if len(regions) == 1: 

2182 return regions[0] 

2183 else: 

2184 return _region_code_for_number_from_list(numobj, regions) 

2185 

2186 

2187def _region_code_for_number_from_list(numobj, regions): 

2188 """Find the region in a list that matches a number""" 

2189 national_number = national_significant_number(numobj) 

2190 for region_code in regions: 

2191 # If leading_digits is present, use this. Otherwise, do full 

2192 # validation. 

2193 # Metadata cannot be None because the region codes come from 

2194 # the country calling code map. 

2195 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None) 

2196 if metadata is None: 

2197 continue 

2198 if metadata.leading_digits is not None: 

2199 leading_digit_re = re.compile(metadata.leading_digits) 

2200 match = leading_digit_re.match(national_number) 

2201 if match: 

2202 return region_code 

2203 elif _number_type_helper(national_number, metadata) != PhoneNumberType.UNKNOWN: 

2204 return region_code 

2205 return None 

2206 

2207 

2208def region_code_for_country_code(country_code): 

2209 """Returns the region code that matches a specific country calling code. 

2210 

2211 In the case of no region code being found, UNKNOWN_REGION ('ZZ') will be 

2212 returned. In the case of multiple regions, the one designated in the 

2213 metadata as the "main" region for this calling code will be returned. If 

2214 the country_code entered is valid but doesn't match a specific region 

2215 (such as in the case of non-geographical calling codes like 800) the value 

2216 "001" will be returned (corresponding to the value for World in the UN 

2217 M.49 schema). 

2218 """ 

2219 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None) 

2220 if regions is None: 

2221 return UNKNOWN_REGION 

2222 else: 

2223 return regions[0] 

2224 

2225 

2226def region_codes_for_country_code(country_code): 

2227 """Returns a list with the region codes that match the specific country calling code. 

2228 

2229 For non-geographical country calling codes, the region code 001 is 

2230 returned. Also, in the case of no region code being found, an empty 

2231 list is returned. 

2232 """ 

2233 regions = COUNTRY_CODE_TO_REGION_CODE.get(country_code, None) 

2234 if regions is None: 

2235 return () 

2236 else: 

2237 return regions 

2238 

2239 

2240def country_code_for_region(region_code): 

2241 """Returns the country calling code for a specific region. 

2242 

2243 For example, this would be 1 for the United States, and 64 for New 

2244 Zealand. 

2245 

2246 Arguments: 

2247 region_code -- The region that we want to get the country calling code for. 

2248 

2249 Returns the country calling code for the region denoted by region_code. 

2250 """ 

2251 if not _is_valid_region_code(region_code): 

2252 return 0 

2253 return country_code_for_valid_region(region_code) 

2254 

2255 

2256def country_code_for_valid_region(region_code): 

2257 """Returns the country calling code for a specific region. 

2258 

2259 For example, this would be 1 for the United States, and 64 for New 

2260 Zealand. Assumes the region is already valid. 

2261 

2262 Arguments: 

2263 region_code -- The region that we want to get the country calling code for. 

2264 

2265 Returns the country calling code for the region denoted by region_code. 

2266 """ 

2267 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None) 

2268 if metadata is None: 

2269 raise Exception("Invalid region code %s" % region_code) 

2270 return metadata.country_code 

2271 

2272 

2273def ndd_prefix_for_region(region_code, strip_non_digits): 

2274 """Returns the national dialling prefix for a specific region. 

2275 

2276 For example, this would be 1 for the United States, and 0 for New 

2277 Zealand. Set strip_non_digits to True to strip symbols like "~" (which 

2278 indicates a wait for a dialling tone) from the prefix returned. If no 

2279 national prefix is present, we return None. 

2280 

2281 Warning: Do not use this method for do-your-own formatting - for some 

2282 regions, the national dialling prefix is used only for certain types of 

2283 numbers. Use the library's formatting functions to prefix the national 

2284 prefix when required. 

2285 

2286 Arguments: 

2287 region_code -- The region that we want to get the dialling prefix for. 

2288 strip_non_digits -- whether to strip non-digits from the national 

2289 dialling prefix. 

2290 

2291 Returns the dialling prefix for the region denoted by region_code. 

2292 """ 

2293 if region_code is None: 

2294 return None 

2295 metadata = PhoneMetadata.metadata_for_region(region_code.upper(), None) 

2296 if metadata is None: 

2297 return None 

2298 national_prefix = metadata.national_prefix 

2299 if national_prefix is None or len(national_prefix) == 0: 

2300 return None 

2301 if strip_non_digits: 

2302 # Note: if any other non-numeric symbols are ever used in national 

2303 # prefixes, these would have to be removed here as well. 

2304 national_prefix = re.sub(U_TILDE, U_EMPTY_STRING, national_prefix) 

2305 return national_prefix 

2306 

2307 

2308def is_nanpa_country(region_code): 

2309 """Checks if this region is a NANPA region. 

2310 

2311 Returns True if region_code is one of the regions under the North American 

2312 Numbering Plan Administration (NANPA). 

2313 """ 

2314 return region_code in _NANPA_REGIONS 

2315 

2316 

2317def is_alpha_number(number): 

2318 """Checks if the number is a valid vanity (alpha) number such as 800 

2319 MICROSOFT. A valid vanity number will start with at least 3 digits and 

2320 will have three or more alpha characters. This does not do region-specific 

2321 checks - to work out if this number is actually valid for a region, it 

2322 should be parsed and methods such as is_possible_number_with_reason() and 

2323 is_valid_number() should be used. 

2324 

2325 Arguments: 

2326 number -- the number that needs to be checked 

2327 

2328 Returns True if the number is a valid vanity number 

2329 """ 

2330 if not _is_viable_phone_number(number): 

2331 # Number is too short, or doesn't match the basic phone number pattern. 

2332 return False 

2333 extension, stripped_number = _maybe_strip_extension(number) 

2334 return bool(fullmatch(_VALID_ALPHA_PHONE_PATTERN, stripped_number)) 

2335 

2336 

2337def is_possible_number(numobj): 

2338 """Convenience wrapper around is_possible_number_with_reason. 

2339 

2340 Instead of returning the reason for failure, this method returns true if 

2341 the number is either a possible fully-qualified number (containing the area 

2342 code and country code), or if the number could be a possible local number 

2343 (with a country code, but missing an area code). Local numbers are 

2344 considered possible if they could be possibly dialled in this format: if 

2345 the area code is needed for a call to connect, the number is not considered 

2346 possible without it. 

2347 

2348 Arguments: 

2349 numobj -- the number object that needs to be checked 

2350 

2351 Returns True if the number is possible 

2352 

2353 """ 

2354 result = is_possible_number_with_reason(numobj) 

2355 return (result == ValidationResult.IS_POSSIBLE or 

2356 result == ValidationResult.IS_POSSIBLE_LOCAL_ONLY) 

2357 

2358 

2359def is_possible_number_for_type(numobj, numtype): 

2360 """Convenience wrapper around is_possible_number_for_type_with_reason. 

2361 

2362 Instead of returning the reason for failure, this method returns true if 

2363 the number is either a possible fully-qualified number (containing the area 

2364 code and country code), or if the number could be a possible local number 

2365 (with a country code, but missing an area code). Local numbers are 

2366 considered possible if they could be possibly dialled in this format: if 

2367 the area code is needed for a call to connect, the number is not considered 

2368 possible without it. 

2369 

2370 Arguments: 

2371 numobj -- the number object that needs to be checked 

2372 numtype -- the type we are interested in 

2373 

2374 Returns True if the number is possible 

2375 

2376 """ 

2377 result = is_possible_number_for_type_with_reason(numobj, numtype) 

2378 return (result == ValidationResult.IS_POSSIBLE or 

2379 result == ValidationResult.IS_POSSIBLE_LOCAL_ONLY) 

2380 

2381 

2382def _test_number_length(national_number, metadata, numtype=PhoneNumberType.UNKNOWN): 

2383 """Helper method to check a number against possible lengths for this number, 

2384 and determine whether it matches, or is too short or too long. 

2385 """ 

2386 desc_for_type = _number_desc_by_type(metadata, numtype) 

2387 if desc_for_type is None: 

2388 possible_lengths = metadata.general_desc.possible_length 

2389 local_lengths = () 

2390 else: 

2391 # There should always be "possibleLengths" set for every element. This is declared in the XML 

2392 # schema which is verified by PhoneNumberMetadataSchemaTest. 

2393 # For size efficiency, where a sub-description (e.g. fixed-line) has the same possibleLengths 

2394 # as the parent, this is missing, so we fall back to the general desc (where no numbers of the 

2395 # type exist at all, there is one possible length (-1) which is guaranteed not to match the 

2396 # length of any real phone number). 

2397 possible_lengths = desc_for_type.possible_length 

2398 if len(possible_lengths) == 0: # pragma no cover: Python sub-descs all have possible_length 

2399 possible_lengths = metadata.general_desc.possible_length 

2400 local_lengths = desc_for_type.possible_length_local_only 

2401 

2402 if numtype == PhoneNumberType.FIXED_LINE_OR_MOBILE: 

2403 if not _desc_has_possible_number_data(_number_desc_by_type(metadata, PhoneNumberType.FIXED_LINE)): 

2404 # The rare case has been encountered where no fixedLine data is available (true for some 

2405 # non-geographical entities), so we just check mobile. 

2406 return _test_number_length(national_number, metadata, PhoneNumberType.MOBILE) 

2407 else: 

2408 mobile_desc = _number_desc_by_type(metadata, PhoneNumberType.MOBILE) 

2409 if _desc_has_possible_number_data(mobile_desc): 

2410 # Merge the mobile data in if there was any. We have to make a copy to do this. 

2411 possible_lengths = list(possible_lengths) 

2412 # Note that when adding the possible lengths from mobile, we have to again check they 

2413 # aren't empty since if they are this indicates they are the same as the general desc and 

2414 # should be obtained from there. 

2415 if len(mobile_desc.possible_length) == 0: # pragma no cover: Python sub-descs all have possible_length 

2416 possible_lengths += metadata.general_desc.possible_length 

2417 else: 

2418 possible_lengths += mobile_desc.possible_length 

2419 # The current list is sorted; we need to merge in the new list and re-sort (duplicates 

2420 # are okay). Sorting isn't so expensive because the lists are very small. 

2421 list.sort(possible_lengths) 

2422 

2423 if len(local_lengths) == 0: 

2424 local_lengths = mobile_desc.possible_length_local_only 

2425 else: 

2426 local_lengths = list(local_lengths) 

2427 local_lengths += mobile_desc.possible_length_local_only 

2428 list.sort(local_lengths) 

2429 

2430 # If the type is not supported at all (indicated by a missing PhoneNumberDesc) we return invalid length. 

2431 if desc_for_type is None: 

2432 return ValidationResult.INVALID_LENGTH 

2433 

2434 actual_length = len(national_number) 

2435 # This is safe because there is never an overlap between the possible lengths and the local-only 

2436 # lengths; this is checked at build time. 

2437 if actual_length in local_lengths: 

2438 return ValidationResult.IS_POSSIBLE_LOCAL_ONLY 

2439 

2440 minimum_length = possible_lengths[0] 

2441 if minimum_length == actual_length: 

2442 return ValidationResult.IS_POSSIBLE 

2443 elif minimum_length > actual_length: 

2444 return ValidationResult.TOO_SHORT 

2445 elif possible_lengths[-1] < actual_length: 

2446 return ValidationResult.TOO_LONG 

2447 # We skip the first element; we've already checked it. 

2448 if actual_length in possible_lengths[1:]: 

2449 return ValidationResult.IS_POSSIBLE 

2450 else: 

2451 return ValidationResult.INVALID_LENGTH 

2452 

2453 

2454def is_possible_number_with_reason(numobj): 

2455 """See documentation for is_possible_number_for_type_with_reason""" 

2456 return is_possible_number_for_type_with_reason(numobj, PhoneNumberType.UNKNOWN) 

2457 

2458 

2459def is_possible_number_for_type_with_reason(numobj, numtype): 

2460 """Check whether a phone number is a possible number of a particular type. 

2461 

2462 For types that don't exist in a particular region, this will return a result 

2463 that isn't so useful; it is recommended that you use 

2464 supported_types_for_region or supported_types_for_non_geo_entity 

2465 respectively before calling this method to determine whether you should call 

2466 it for this number at all. 

2467 

2468 This provides a more lenient check than is_valid_number in the following sense: 

2469 

2470 - It only checks the length of phone numbers. In particular, it doesn't 

2471 check starting digits of the number. 

2472 

2473 - For some numbers (particularly fixed-line), many regions have the 

2474 concept of area code, which together with subscriber number constitute 

2475 the national significant number. It is sometimes okay to dial only the 

2476 subscriber number when dialing in the same area. This function will 

2477 return IS_POSSIBLE_LOCAL_ONLY if the subscriber-number-only version is 

2478 passed in. On the other hand, because is_valid_number validates using 

2479 information on both starting digits (for fixed line numbers, that would 

2480 most likely be area codes) and length (obviously includes the length of 

2481 area codes for fixed line numbers), it will return false for the 

2482 subscriber-number-only version. 

2483 

2484 There is a known <a 

2485 href="https://issuetracker.google.com/issues/335892662">issue</a> with this 

2486 method: if a number is possible only in a certain region among several 

2487 regions that share the same country calling code, this method will consider 

2488 only the "main" region. For example, +1310xxxx are valid numbers in 

2489 Canada. However, they are not possible in the US. As a result, this method 

2490 will return IS_POSSIBLE_LOCAL_ONLY for +1310xxxx. 

2491 

2492 Arguments: 

2493 numobj -- The number object that needs to be checked 

2494 numtype -- The type we are interested in 

2495 

2496 Returns a value from ValidationResult which indicates whether the number 

2497 is possible 

2498 """ 

2499 national_number = national_significant_number(numobj) 

2500 country_code = numobj.country_code 

2501 # Note: For regions that share a country calling code, like NANPA numbers, 

2502 # we just use the rules from the default region (US in this case) since the 

2503 # region_code_for_number will not work if the number is possible but not 

2504 # valid. There is in fact one country calling code (290) where the possible 

2505 # number pattern differs between various regions (Saint Helena and Tristan 

2506 # da Cuñha), but this is handled by putting all possible lengths for any 

2507 # country with this country calling code in the metadata for the default 

2508 # region in this case. 

2509 if not _has_valid_country_calling_code(country_code): 

2510 return ValidationResult.INVALID_COUNTRY_CODE 

2511 region_code = region_code_for_country_code(country_code) 

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

2513 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, region_code) 

2514 return _test_number_length(national_number, metadata, numtype) 

2515 

2516 

2517def is_possible_number_string(number, region_dialing_from): 

2518 """Check whether a phone number string is a possible number. 

2519 

2520 Takes a number in the form of a string, and the region where the number 

2521 could be dialed from. It provides a more lenient check than 

2522 is_valid_number; see is_possible_number_with_reason() for details. 

2523 

2524 This method first parses the number, then invokes is_possible_number with 

2525 the resultant PhoneNumber object. 

2526 

2527 Arguments: 

2528 number -- The number that needs to be checked, in the form of a string. 

2529 region_dialling_from -- The region that we are expecting the number to be 

2530 dialed from. Note this is different from the region where the 

2531 number belongs. For example, the number +1 650 253 0000 is a 

2532 number that belongs to US. When written in this form, it can be 

2533 dialed from any region. When it is written as 00 1 650 253 0000, 

2534 it can be dialed from any region which uses an international 

2535 dialling prefix of 00. When it is written as 650 253 0000, it 

2536 can only be dialed from within the US, and when written as 253 

2537 0000, it can only be dialed from within a smaller area in the US 

2538 (Mountain View, CA, to be more specific). 

2539 

2540 Returns True if the number is possible 

2541 """ 

2542 try: 

2543 return is_possible_number(parse(number, region_dialing_from)) 

2544 except NumberParseException: 

2545 return False 

2546 

2547 

2548def truncate_too_long_number(numobj): 

2549 """Truncate a number object that is too long. 

2550 

2551 Attempts to extract a valid number from a phone number that is too long 

2552 to be valid, and resets the PhoneNumber object passed in to that valid 

2553 version. If no valid number could be extracted, the PhoneNumber object 

2554 passed in will not be modified. 

2555 

2556 Arguments: 

2557 numobj -- A PhoneNumber object which contains a number that is too long to 

2558 be valid. 

2559 

2560 Returns True if a valid phone number can be successfully extracted. 

2561 """ 

2562 if is_valid_number(numobj): 

2563 return True 

2564 numobj_copy = PhoneNumber() 

2565 numobj_copy.merge_from(numobj) 

2566 national_number = numobj.national_number 

2567 

2568 while not is_valid_number(numobj_copy): 

2569 # Strip a digit off the RHS 

2570 national_number = national_number // 10 

2571 numobj_copy.national_number = national_number 

2572 validation_result = is_possible_number_with_reason(numobj_copy) 

2573 if (validation_result == ValidationResult.TOO_SHORT or 

2574 national_number == 0): 

2575 return False 

2576 # To reach here, numobj_copy is a valid number. Modify the original object 

2577 numobj.national_number = national_number 

2578 return True 

2579 

2580 

2581def _extract_country_code(number): 

2582 """Extracts country calling code from number. 

2583 

2584 Returns a 2-tuple of (country_calling_code, rest_of_number). It assumes 

2585 that the leading plus sign or IDD has already been removed. Returns (0, 

2586 number) if number doesn't start with a valid country calling code. 

2587 """ 

2588 

2589 if len(number) == 0 or number[0] == U_ZERO: 

2590 # Country codes do not begin with a '0'. 

2591 return (0, number) 

2592 for ii in range(1, min(len(number), _MAX_LENGTH_COUNTRY_CODE) + 1): 

2593 try: 

2594 country_code = int(number[:ii]) 

2595 if country_code in COUNTRY_CODE_TO_REGION_CODE: 

2596 return (country_code, number[ii:]) 

2597 except Exception: 

2598 pass 

2599 return (0, number) 

2600 

2601 

2602def _maybe_extract_country_code(number, metadata, keep_raw_input, numobj): 

2603 """Tries to extract a country calling code from a number. 

2604 

2605 This method will return zero if no country calling code is considered to 

2606 be present. Country calling codes are extracted in the following ways: 

2607 

2608 - by stripping the international dialing prefix of the region the person 

2609 is dialing from, if this is present in the number, and looking at the 

2610 next digits 

2611 

2612 - by stripping the '+' sign if present and then looking at the next 

2613 digits 

2614 

2615 - by comparing the start of the number and the country calling code of 

2616 the default region. If the number is not considered possible for the 

2617 numbering plan of the default region initially, but starts with the 

2618 country calling code of this region, validation will be reattempted 

2619 after stripping this country calling code. If this number is considered 

2620 a possible number, then the first digits will be considered the country 

2621 calling code and removed as such. 

2622 

2623 It will raise a NumberParseException if the number starts with a '+' but 

2624 the country calling code supplied after this does not match that of any 

2625 known region. 

2626 

2627 Arguments: 

2628 number -- non-normalized telephone number that we wish to extract a 

2629 country calling code from; may begin with '+' 

2630 metadata -- metadata about the region this number may be from, or None 

2631 keep_raw_input -- True if the country_code_source and 

2632 preferred_carrier_code fields of numobj should be populated. 

2633 numobj -- The PhoneNumber object where the country_code and 

2634 country_code_source need to be populated. Note the country_code 

2635 is always populated, whereas country_code_source is only 

2636 populated when keep_raw_input is True. 

2637 

2638 Returns a 2-tuple containing: 

2639 - the country calling code extracted or 0 if none could be extracted 

2640 - a string holding the national significant number, in the case 

2641 that a country calling code was extracted. If no country calling code 

2642 was extracted, this will be empty. 

2643 """ 

2644 if len(number) == 0: 

2645 return (0, U_EMPTY_STRING) 

2646 full_number = number 

2647 # Set the default prefix to be something that will never match. 

2648 possible_country_idd_prefix = unicod("NonMatch") 

2649 if metadata is not None and metadata.international_prefix is not None: 

2650 possible_country_idd_prefix = metadata.international_prefix 

2651 

2652 country_code_source, full_number = _maybe_strip_i18n_prefix_and_normalize(full_number, 

2653 possible_country_idd_prefix) 

2654 if keep_raw_input: 

2655 numobj.country_code_source = country_code_source 

2656 

2657 if country_code_source != CountryCodeSource.FROM_DEFAULT_COUNTRY: 

2658 if len(full_number) <= _MIN_LENGTH_FOR_NSN: 

2659 raise NumberParseException(NumberParseException.TOO_SHORT_AFTER_IDD, 

2660 "Phone number had an IDD, but after this was not " + 

2661 "long enough to be a viable phone number.") 

2662 potential_country_code, rest_of_number = _extract_country_code(full_number) 

2663 if potential_country_code != 0: 

2664 numobj.country_code = potential_country_code 

2665 return (potential_country_code, rest_of_number) 

2666 

2667 # If this fails, they must be using a strange country calling code 

2668 # that we don't recognize, or that doesn't exist. 

2669 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE, 

2670 "Country calling code supplied was not recognised.") 

2671 elif metadata is not None: 

2672 # Check to see if the number starts with the country calling code for 

2673 # the default region. If so, we remove the country calling code, and 

2674 # do some checks on the validity of the number before and after. 

2675 default_country_code = metadata.country_code 

2676 default_country_code_str = str(metadata.country_code) 

2677 normalized_number = full_number 

2678 if normalized_number.startswith(default_country_code_str): 

2679 potential_national_number = full_number[len(default_country_code_str):] 

2680 general_desc = metadata.general_desc 

2681 _, potential_national_number, _ = _maybe_strip_national_prefix_carrier_code(potential_national_number, 

2682 metadata) 

2683 

2684 # If the number was not valid before but is valid now, or if it 

2685 # was too long before, we consider the number with the country 

2686 # calling code stripped to be a better result and keep that 

2687 # instead. 

2688 if ((not _match_national_number(full_number, general_desc, False) and 

2689 _match_national_number(potential_national_number, general_desc, False)) or 

2690 (_test_number_length(full_number, metadata) == ValidationResult.TOO_LONG)): 

2691 if keep_raw_input: 

2692 numobj.country_code_source = CountryCodeSource.FROM_NUMBER_WITHOUT_PLUS_SIGN 

2693 numobj.country_code = default_country_code 

2694 return (default_country_code, potential_national_number) 

2695 

2696 # No country calling code present. 

2697 numobj.country_code = 0 

2698 return (0, U_EMPTY_STRING) 

2699 

2700 

2701def _parse_prefix_as_idd(idd_pattern, number): 

2702 """Strips the IDD from the start of the number if present. 

2703 

2704 Helper function used by _maybe_strip_i18n_prefix_and_normalize(). 

2705 

2706 Returns a 2-tuple: 

2707 - Boolean indicating if IDD was stripped 

2708 - Number with IDD stripped 

2709 """ 

2710 match = idd_pattern.match(number) 

2711 if match: 

2712 match_end = match.end() 

2713 # Only strip this if the first digit after the match is not a 0, since 

2714 # country calling codes cannot begin with 0. 

2715 digit_match = _CAPTURING_DIGIT_PATTERN.search(number[match_end:]) 

2716 if digit_match: 

2717 normalized_group = normalize_digits_only(digit_match.group(1)) 

2718 if normalized_group == U_ZERO: 

2719 return (False, number) 

2720 return (True, number[match_end:]) 

2721 return (False, number) 

2722 

2723 

2724def _maybe_strip_i18n_prefix_and_normalize(number, possible_idd_prefix): 

2725 """Strips any international prefix (such as +, 00, 011) present in the 

2726 number provided, normalizes the resulting number, and indicates if an 

2727 international prefix was present. 

2728 

2729 Arguments: 

2730 number -- The non-normalized telephone number that we wish to strip any international 

2731 dialing prefix from. 

2732 possible_idd_prefix -- The international direct dialing prefix from the region we 

2733 think this number may be dialed in. 

2734 

2735 Returns a 2-tuple containing: 

2736 - The corresponding CountryCodeSource if an international dialing prefix 

2737 could be removed from the number, otherwise 

2738 CountryCodeSource.FROM_DEFAULT_COUNTRY if the number did not seem to 

2739 be in international format. 

2740 - The number with the prefix stripped. 

2741 """ 

2742 if len(number) == 0: 

2743 return (CountryCodeSource.FROM_DEFAULT_COUNTRY, number) 

2744 # Check to see if the number begins with one or more plus signs. 

2745 m = _PLUS_CHARS_PATTERN.match(number) 

2746 if m: 

2747 number = number[m.end():] 

2748 # Can now normalize the rest of the number since we've consumed the 

2749 # "+" sign at the start. 

2750 return (CountryCodeSource.FROM_NUMBER_WITH_PLUS_SIGN, 

2751 _normalize(number)) 

2752 

2753 # Attempt to parse the first digits as an international prefix. 

2754 idd_pattern = re.compile(possible_idd_prefix) 

2755 number = _normalize(number) 

2756 stripped, number = _parse_prefix_as_idd(idd_pattern, number) 

2757 if stripped: 

2758 return (CountryCodeSource.FROM_NUMBER_WITH_IDD, number) 

2759 else: 

2760 return (CountryCodeSource.FROM_DEFAULT_COUNTRY, number) 

2761 

2762 

2763def _maybe_strip_national_prefix_carrier_code(number, metadata): 

2764 """Strips any national prefix (such as 0, 1) present in a number. 

2765 

2766 Arguments: 

2767 number -- The normalized telephone number that we wish to strip any 

2768 national dialing prefix from 

2769 metadata -- The metadata for the region that we think this number 

2770 is from. 

2771 

2772 Returns a 3-tuple of 

2773 - The carrier code extracted if it is present, otherwise an empty string. 

2774 - The number with the prefix stripped. 

2775 - Boolean indicating if a national prefix or carrier code (or both) could be extracted. 

2776 """ 

2777 carrier_code = U_EMPTY_STRING 

2778 possible_national_prefix = metadata.national_prefix_for_parsing 

2779 if (len(number) == 0 or 

2780 possible_national_prefix is None or 

2781 len(possible_national_prefix) == 0): 

2782 # Early return for numbers of zero length. 

2783 return (U_EMPTY_STRING, number, False) 

2784 

2785 # Attempt to parse the first digits as a national prefix. 

2786 prefix_pattern = re.compile(possible_national_prefix) 

2787 prefix_match = prefix_pattern.match(number) 

2788 if prefix_match: 

2789 general_desc = metadata.general_desc 

2790 # Check if the original number is viable. 

2791 is_viable_original_number = _match_national_number(number, general_desc, False) 

2792 # prefix_match.groups() == () implies nothing was captured by the 

2793 # capturing groups in possible_national_prefix; therefore, no 

2794 # transformation is necessary, and we just remove the national prefix. 

2795 num_groups = len(prefix_match.groups()) 

2796 transform_rule = metadata.national_prefix_transform_rule 

2797 if (transform_rule is None or 

2798 len(transform_rule) == 0 or 

2799 prefix_match.groups()[num_groups - 1] is None): 

2800 # If the original number was viable, and the resultant number is not, we return. 

2801 # Check that the resultant number is viable. If not, return. 

2802 national_number_match = _match_national_number(number[prefix_match.end():], general_desc, False) 

2803 if (is_viable_original_number and not national_number_match): 

2804 return (U_EMPTY_STRING, number, False) 

2805 

2806 if (num_groups > 0 and 

2807 prefix_match.groups(num_groups) is not None): 

2808 carrier_code = prefix_match.group(1) 

2809 return (carrier_code, number[prefix_match.end():], True) 

2810 else: 

2811 # Check that the resultant number is still viable. If not, 

2812 # return. Check this by copying the number and making the 

2813 # transformation on the copy first. 

2814 transformed_number = re.sub(prefix_pattern, transform_rule, number, count=1) 

2815 national_number_match = _match_national_number(transformed_number, general_desc, False) 

2816 if (is_viable_original_number and not national_number_match): 

2817 return ("", number, False) 

2818 if num_groups > 1: 

2819 carrier_code = prefix_match.group(1) 

2820 return (carrier_code, transformed_number, True) 

2821 else: 

2822 return (carrier_code, number, False) 

2823 

2824 

2825def _maybe_strip_extension(number): 

2826 """Strip extension from the end of a number string. 

2827 

2828 Strips any extension (as in, the part of the number dialled after the 

2829 call is connected, usually indicated with extn, ext, x or similar) from 

2830 the end of the number, and returns it. 

2831 

2832 Arguments: 

2833 number -- the non-normalized telephone number that we wish to strip the extension from. 

2834 

2835 Returns a 2-tuple of: 

2836 - the phone extension (or "" or not present) 

2837 - the number before the extension. 

2838 """ 

2839 match = _EXTN_PATTERN.search(number) 

2840 # If we find a potential extension, and the number preceding this is a 

2841 # viable number, we assume it is an extension. 

2842 if match and _is_viable_phone_number(number[:match.start()]): 

2843 # The numbers are captured into groups in the regular expression. 

2844 for group in match.groups(): 

2845 # We go through the capturing groups until we find one that 

2846 # captured some digits. If none did, then we will return the empty 

2847 # string. 

2848 if group is not None: 

2849 return (group, number[:match.start()]) 

2850 return ("", number) 

2851 

2852 

2853def _check_region_for_parsing(number, default_region): 

2854 """Checks to see that the region code used is valid, or if it is not 

2855 valid, that the number to parse starts with a + symbol so that we can 

2856 attempt to infer the region from the number. Returns False if it cannot 

2857 use the region provided and the region cannot be inferred. 

2858 """ 

2859 if not _is_valid_region_code(default_region): 

2860 # If the number is None or empty, we can't infer the region. 

2861 if number is None or len(number) == 0: 

2862 return False 

2863 match = _PLUS_CHARS_PATTERN.match(number) 

2864 if match is None: 

2865 return False 

2866 return True 

2867 

2868 

2869def _set_italian_leading_zeros_for_phone_number(national_number, numobj): 

2870 """A helper function to set the values related to leading zeros in a 

2871 PhoneNumber.""" 

2872 if len(national_number) > 1 and national_number[0] == U_ZERO: 

2873 numobj.italian_leading_zero = True 

2874 number_of_leading_zeros = 1 

2875 # Note that if the number is all "0"s, the last "0" is not counted as 

2876 # a leading zero. 

2877 while (number_of_leading_zeros < len(national_number) - 1 and 

2878 national_number[number_of_leading_zeros] == U_ZERO): 

2879 number_of_leading_zeros += 1 

2880 if number_of_leading_zeros != 1: 

2881 numobj.number_of_leading_zeros = number_of_leading_zeros 

2882 

2883 

2884def parse(number, region=None, keep_raw_input=False, 

2885 numobj=None, _check_region=True): 

2886 """Parse a string and return a corresponding PhoneNumber object. 

2887 

2888 The method is quite lenient and looks for a number in the input text 

2889 (raw input) and does not check whether the string is definitely only a 

2890 phone number. To do this, it ignores punctuation and white-space, as 

2891 well as any text before the number (e.g. a leading "Tel: ") and trims 

2892 the non-number bits. It will accept a number in any format (E164, 

2893 national, international etc), assuming it can be interpreted with the 

2894 defaultRegion supplied. It also attempts to convert any alpha characters 

2895 into digits if it thinks this is a vanity number of the type "1800 

2896 MICROSOFT". 

2897 

2898 This method will throw a NumberParseException if the number is not 

2899 considered to be a possible number. Note that validation of whether the 

2900 number is actually a valid number for a particular region is not 

2901 performed. This can be done separately with is_valid_number. 

2902 

2903 Note this method canonicalizes the phone number such that different 

2904 representations can be easily compared, no matter what form it was 

2905 originally entered in (e.g. national, international). If you want to 

2906 record context about the number being parsed, such as the raw input that 

2907 was entered, how the country code was derived etc. then ensure 

2908 keep_raw_input is set. 

2909 

2910 Note if any new field is added to this method that should always be filled 

2911 in, even when keep_raw_input is False, it should also be handled in the 

2912 _copy_core_fields_only() function. 

2913 

2914 Arguments: 

2915 number -- The number that we are attempting to parse. This can 

2916 contain formatting such as +, ( and -, as well as a phone 

2917 number extension. It can also be provided in RFC3966 format. 

2918 region -- The region that we are expecting the number to be from. This 

2919 is only used if the number being parsed is not written in 

2920 international format. The country_code for the number in 

2921 this case would be stored as that of the default region 

2922 supplied. If the number is guaranteed to start with a '+' 

2923 followed by the country calling code, then None or 

2924 UNKNOWN_REGION can be supplied. 

2925 keep_raw_input -- Whether to populate the raw_input field of the 

2926 PhoneNumber object with number (as well as the 

2927 country_code_source field). 

2928 numobj -- An optional existing PhoneNumber object to receive the 

2929 parsing results 

2930 _check_region -- Whether to check the supplied region parameter; 

2931 should always be True for external callers. 

2932 

2933 Returns a PhoneNumber object filled with the parse number. 

2934 

2935 Raises: 

2936 NumberParseException if the string is not considered to be a viable 

2937 phone number (e.g. too few or too many digits) or if no default 

2938 region was supplied and the number is not in international format 

2939 (does not start with +). 

2940 

2941 """ 

2942 if numobj is None: 

2943 numobj = PhoneNumber() 

2944 if number is None: 

2945 raise NumberParseException(NumberParseException.NOT_A_NUMBER, 

2946 "The phone number supplied was None.") 

2947 elif len(number) > _MAX_INPUT_STRING_LENGTH: 

2948 raise NumberParseException(NumberParseException.TOO_LONG, 

2949 "The string supplied was too long to parse.") 

2950 

2951 national_number = _build_national_number_for_parsing(number) 

2952 

2953 if not _is_viable_phone_number(national_number): 

2954 raise NumberParseException(NumberParseException.NOT_A_NUMBER, 

2955 "The string supplied did not seem to be a phone number.") 

2956 

2957 # Check the region supplied is valid, or that the extracted number starts 

2958 # with some sort of + sign so the number's region can be determined. 

2959 if _check_region and not _check_region_for_parsing(national_number, region): 

2960 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE, 

2961 "Missing or invalid default region.") 

2962 if keep_raw_input: 

2963 numobj.raw_input = number 

2964 

2965 # Attempt to parse extension first, since it doesn't require 

2966 # region-specific data and we want to have the non-normalised number here. 

2967 extension, national_number = _maybe_strip_extension(national_number) 

2968 if len(extension) > 0: 

2969 numobj.extension = extension 

2970 if region is None: 

2971 metadata = None 

2972 else: 

2973 metadata = PhoneMetadata.metadata_for_region(region.upper(), None) 

2974 

2975 country_code = 0 

2976 try: 

2977 country_code, normalized_national_number = _maybe_extract_country_code(national_number, 

2978 metadata, 

2979 keep_raw_input, 

2980 numobj) 

2981 except NumberParseException: 

2982 _, e, _ = sys.exc_info() 

2983 matchobj = _PLUS_CHARS_PATTERN.match(national_number) 

2984 if (e.error_type == NumberParseException.INVALID_COUNTRY_CODE and 

2985 matchobj is not None): 

2986 # Strip the plus-char, and try again. 

2987 country_code, normalized_national_number = _maybe_extract_country_code(national_number[matchobj.end():], 

2988 metadata, 

2989 keep_raw_input, 

2990 numobj) 

2991 if country_code == 0: 

2992 raise NumberParseException(NumberParseException.INVALID_COUNTRY_CODE, 

2993 "Could not interpret numbers after plus-sign.") 

2994 else: 

2995 raise 

2996 

2997 if country_code != 0: 

2998 number_region = region_code_for_country_code(country_code) 

2999 if number_region != region: 

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

3001 metadata = PhoneMetadata.metadata_for_region_or_calling_code(country_code, number_region) 

3002 assert metadata is not None 

3003 else: 

3004 # If no extracted country calling code, use the region supplied 

3005 # instead. The national number is just the normalized version of the 

3006 # number we were given to parse. 

3007 normalized_national_number += _normalize(national_number) 

3008 if region is not None: 

3009 country_code = metadata.country_code 

3010 numobj.country_code = country_code 

3011 elif keep_raw_input: 

3012 numobj.country_code_source = CountryCodeSource.UNSPECIFIED 

3013 

3014 if len(normalized_national_number) < _MIN_LENGTH_FOR_NSN: 

3015 raise NumberParseException(NumberParseException.TOO_SHORT_NSN, 

3016 "The string supplied is too short to be a phone number.") 

3017 if metadata is not None: 

3018 potential_national_number = normalized_national_number 

3019 carrier_code, potential_national_number, _ = _maybe_strip_national_prefix_carrier_code(potential_national_number, 

3020 metadata) 

3021 # We require that the NSN remaining after stripping the national 

3022 # prefix and carrier code be long enough to be a possible length for 

3023 # the region. Otherwise, we don't do the stripping, since the original 

3024 # number could be a valid short number. 

3025 validation_result = _test_number_length(potential_national_number, metadata) 

3026 if validation_result not in (ValidationResult.TOO_SHORT, 

3027 ValidationResult.IS_POSSIBLE_LOCAL_ONLY, 

3028 ValidationResult.INVALID_LENGTH): 

3029 normalized_national_number = potential_national_number 

3030 if keep_raw_input and carrier_code is not None and len(carrier_code) > 0: 

3031 numobj.preferred_domestic_carrier_code = carrier_code 

3032 len_national_number = len(normalized_national_number) 

3033 if len_national_number < _MIN_LENGTH_FOR_NSN: # pragma no cover 

3034 # Check of _is_viable_phone_number() at the top of this function makes 

3035 # this effectively unhittable. 

3036 raise NumberParseException(NumberParseException.TOO_SHORT_NSN, 

3037 "The string supplied is too short to be a phone number.") 

3038 if len_national_number > _MAX_LENGTH_FOR_NSN: 

3039 raise NumberParseException(NumberParseException.TOO_LONG, 

3040 "The string supplied is too long to be a phone number.") 

3041 _set_italian_leading_zeros_for_phone_number(normalized_national_number, numobj) 

3042 numobj.national_number = to_long(normalized_national_number) 

3043 return numobj 

3044 

3045 

3046def _extract_phone_context(number_to_extract_from, index_of_phone_context): 

3047 """Extracts the value of the phone-context parameter of number_to_extract_from where the index of 

3048 ";phone-context=" is the parameter index_of_phone_context, following the syntax defined in 

3049 RFC3966. 

3050 

3051 Returns the extracted string (possibly empty), or None if no phone-context parameter is found.""" 

3052 # If no phone-context parameter is present 

3053 if index_of_phone_context == -1: 

3054 return None 

3055 

3056 phone_context_start = index_of_phone_context + len(_RFC3966_PHONE_CONTEXT) 

3057 # If phone-context parameter is empty 

3058 if phone_context_start >= len(number_to_extract_from): 

3059 return U_EMPTY_STRING 

3060 

3061 phone_context_end = number_to_extract_from.find(';', phone_context_start) 

3062 # If phone-context is not the last parameter 

3063 if phone_context_end != -1: 

3064 return number_to_extract_from[phone_context_start:phone_context_end] 

3065 else: 

3066 return number_to_extract_from[phone_context_start:] 

3067 

3068 

3069def _is_phone_context_valid(phone_context): 

3070 """"Returns whether the value of phoneContext follows the syntax defined in RFC3966.""" 

3071 if phone_context is None: 

3072 return True 

3073 if len(phone_context) == 0: 

3074 return False 

3075 

3076 # Does phone-context value match pattern of global-number-digits or domainname 

3077 return (fullmatch(_RFC3966_GLOBAL_NUMBER_DIGITS_PATTERN, phone_context) or 

3078 fullmatch(_RFC3966_DOMAINNAME_PATTERN, phone_context)) 

3079 

3080 

3081def _build_national_number_for_parsing(number): 

3082 """Converts number to a form that we can parse and return it if it is 

3083 written in RFC3966; otherwise extract a possible number out of it and return it.""" 

3084 index_of_phone_context = number.find(_RFC3966_PHONE_CONTEXT) 

3085 

3086 phone_context = _extract_phone_context(number, index_of_phone_context) 

3087 if not _is_phone_context_valid(phone_context): 

3088 raise NumberParseException(NumberParseException.NOT_A_NUMBER, "The phone-context value is invalid") 

3089 if phone_context is not None: 

3090 # If the phone context contains a phone number prefix, we need to 

3091 # capture it, whereas domains will be ignored. 

3092 if phone_context[0] == _PLUS_SIGN: 

3093 # Additional parameters might follow the phone context. If so, we 

3094 # will remove them here because the parameters after phone context 

3095 # are not important for parsing the phone number. 

3096 national_number = phone_context 

3097 else: 

3098 national_number = U_EMPTY_STRING 

3099 

3100 # Now append everything between the "tel:" prefix and the 

3101 # phone-context. This should include the national number, an optional 

3102 # extension or isdn-subaddress component. Note we also handle the case 

3103 # when "tel:" is missing, as we have seen in some of the phone number 

3104 # inputs. In that case we append everything from the beginning. 

3105 index_of_rfc3996_prefix = number.find(_RFC3966_PREFIX) 

3106 index_of_national_number = ((index_of_rfc3996_prefix + len(_RFC3966_PREFIX)) 

3107 if (index_of_rfc3996_prefix >= 0) else 0) 

3108 national_number += number[index_of_national_number:index_of_phone_context] 

3109 else: 

3110 # Extract a possible number from the string passed in (this strips leading characters that 

3111 # could not be the start of a phone number.) 

3112 national_number = _extract_possible_number(number) 

3113 

3114 # Delete the isdn-subaddress and everything after it if it is 

3115 # present. Note extension won't appear at the same time with 

3116 # isdn-subaddress according to paragraph 5.3 of the RFC3966 spec, 

3117 index_of_isdn = national_number.find(_RFC3966_ISDN_SUBADDRESS) 

3118 if index_of_isdn > 0: 

3119 national_number = national_number[:index_of_isdn] 

3120 # If both phone context and isdn-subaddress are absent but other 

3121 # parameters are present, the parameters are left in national_number. This 

3122 # is because we are concerned about deleting content from a potential 

3123 # number string when there is no strong evidence that the number is 

3124 # actually written in RFC3966. 

3125 return national_number 

3126 

3127 

3128def _copy_core_fields_only(inobj): 

3129 """Returns a new phone number containing only the fields needed to uniquely 

3130 identify a phone number, rather than any fields that capture the context in 

3131 which the phone number was created. 

3132 """ 

3133 numobj = PhoneNumber() 

3134 numobj.country_code = inobj.country_code 

3135 numobj.national_number = inobj.national_number 

3136 if inobj.extension is not None and len(inobj.extension) > 0: 

3137 numobj.extension = inobj.extension 

3138 if inobj.italian_leading_zero: 

3139 numobj.italian_leading_zero = True 

3140 # This field is only relevant if there are leading zeros at all. 

3141 numobj.number_of_leading_zeros = inobj.number_of_leading_zeros 

3142 if numobj.number_of_leading_zeros is None: 

3143 # No number set is implicitly a count of 1; make it explicit. 

3144 numobj.number_of_leading_zeros = 1 

3145 return numobj 

3146 

3147 

3148def _is_number_match_OO(numobj1_in, numobj2_in): 

3149 """Takes two phone number objects and compares them for equality.""" 

3150 # We only care about the fields that uniquely define a number, so we copy these across explicitly. 

3151 numobj1 = _copy_core_fields_only(numobj1_in) 

3152 numobj2 = _copy_core_fields_only(numobj2_in) 

3153 

3154 # Early exit if both had extensions and these are different. 

3155 if (numobj1.extension is not None and 

3156 numobj2.extension is not None and 

3157 numobj1.extension != numobj2.extension): 

3158 return MatchType.NO_MATCH 

3159 

3160 country_code1 = numobj1.country_code 

3161 country_code2 = numobj2.country_code 

3162 # Both had country_code specified. 

3163 if country_code1 != 0 and country_code2 != 0: 

3164 if numobj1 == numobj2: 

3165 return MatchType.EXACT_MATCH 

3166 elif (country_code1 == country_code2 and 

3167 _is_national_number_suffix_of_other(numobj1, numobj2)): 

3168 # A SHORT_NSN_MATCH occurs if there is a difference because of the 

3169 # presence or absence of an 'Italian leading zero', the presence 

3170 # or absence of an extension, or one NSN being a shorter variant 

3171 # of the other. 

3172 return MatchType.SHORT_NSN_MATCH 

3173 # This is not a match. 

3174 return MatchType.NO_MATCH 

3175 

3176 # Checks cases where one or both country_code fields were not 

3177 # specified. To make equality checks easier, we first set the country_code 

3178 # fields to be equal. 

3179 numobj1.country_code = country_code2 

3180 # If all else was the same, then this is an NSN_MATCH. 

3181 if numobj1 == numobj2: 

3182 return MatchType.NSN_MATCH 

3183 if _is_national_number_suffix_of_other(numobj1, numobj2): 

3184 return MatchType.SHORT_NSN_MATCH 

3185 return MatchType.NO_MATCH 

3186 

3187 

3188def _is_national_number_suffix_of_other(numobj1, numobj2): 

3189 """Returns true when one national number is the suffix of the other or both 

3190 are the same. 

3191 """ 

3192 nn1 = str(numobj1.national_number) 

3193 nn2 = str(numobj2.national_number) 

3194 # Note that endswith returns True if the numbers are equal. 

3195 return nn1.endswith(nn2) or nn2.endswith(nn1) 

3196 

3197 

3198def _is_number_match_SS(number1, number2): 

3199 """Takes two phone numbers as strings and compares them for equality. 

3200 

3201 This is a convenience wrapper for _is_number_match_OO/_is_number_match_OS. 

3202 No default region is known. 

3203 """ 

3204 try: 

3205 numobj1 = parse(number1, UNKNOWN_REGION) 

3206 return _is_number_match_OS(numobj1, number2) 

3207 except NumberParseException: 

3208 _, exc, _ = sys.exc_info() 

3209 if exc.error_type == NumberParseException.INVALID_COUNTRY_CODE: 

3210 try: 

3211 numobj2 = parse(number2, UNKNOWN_REGION) 

3212 return _is_number_match_OS(numobj2, number1) 

3213 except NumberParseException: 

3214 _, exc2, _ = sys.exc_info() 

3215 if exc2.error_type == NumberParseException.INVALID_COUNTRY_CODE: 

3216 try: 

3217 numobj1 = parse(number1, None, keep_raw_input=False, 

3218 _check_region=False, numobj=None) 

3219 numobj2 = parse(number2, None, keep_raw_input=False, 

3220 _check_region=False, numobj=None) 

3221 return _is_number_match_OO(numobj1, numobj2) 

3222 except NumberParseException: 

3223 return MatchType.NOT_A_NUMBER 

3224 

3225 # One or more of the phone numbers we are trying to match is not a viable 

3226 # phone number. 

3227 return MatchType.NOT_A_NUMBER 

3228 

3229 

3230def _is_number_match_OS(numobj1, number2): 

3231 """Wrapper variant of _is_number_match_OO that copes with one 

3232 PhoneNumber object and one string.""" 

3233 # First see if the second number has an implicit country calling code, by 

3234 # attempting to parse it. 

3235 try: 

3236 numobj2 = parse(number2, UNKNOWN_REGION) 

3237 return _is_number_match_OO(numobj1, numobj2) 

3238 except NumberParseException: 

3239 _, exc, _ = sys.exc_info() 

3240 if exc.error_type == NumberParseException.INVALID_COUNTRY_CODE: 

3241 # The second number has no country calling code. EXACT_MATCH is no 

3242 # longer possible. We parse it as if the region was the same as 

3243 # that for the first number, and if EXACT_MATCH is returned, we 

3244 # replace this with NSN_MATCH. 

3245 region1 = region_code_for_country_code(numobj1.country_code) 

3246 try: 

3247 if region1 != UNKNOWN_REGION: 

3248 numobj2 = parse(number2, region1) 

3249 match = _is_number_match_OO(numobj1, numobj2) 

3250 if match == MatchType.EXACT_MATCH: 

3251 return MatchType.NSN_MATCH 

3252 else: 

3253 return match 

3254 else: 

3255 # If the first number didn't have a valid country calling 

3256 # code, then we parse the second number without one as 

3257 # well. 

3258 numobj2 = parse(number2, None, keep_raw_input=False, 

3259 _check_region=False, numobj=None) 

3260 return _is_number_match_OO(numobj1, numobj2) 

3261 except NumberParseException: 

3262 return MatchType.NOT_A_NUMBER 

3263 # One or more of the phone numbers we are trying to match is not a viable 

3264 # phone number. 

3265 return MatchType.NOT_A_NUMBER 

3266 

3267 

3268def is_number_match(num1, num2): 

3269 """Takes two phone numbers and compares them for equality. 

3270 

3271 For example, the numbers +1 345 657 1234 and 657 1234 are a SHORT_NSN_MATCH. 

3272 The numbers +1 345 657 1234 and 345 657 are a NO_MATCH. 

3273 

3274 Arguments 

3275 num1 -- First number object or string to compare. Can contain formatting, 

3276 and can have country calling code specified with + at the start. 

3277 num2 -- Second number object or string to compare. Can contain formatting, 

3278 and can have country calling code specified with + at the start. 

3279 

3280 Returns: 

3281 - EXACT_MATCH if the country_code, NSN, presence of a leading zero for 

3282 Italian numbers and any extension present are the same. 

3283 - NSN_MATCH if either or both has no region specified, and the NSNs and 

3284 extensions are the same. 

3285 - SHORT_NSN_MATCH if either or both has no region specified, or the 

3286 region specified is the same, and one NSN could be a shorter version of 

3287 the other number. This includes the case where one has an extension 

3288 specified, and the other does not. 

3289 - NO_MATCH otherwise. 

3290 """ 

3291 if isinstance(num1, PhoneNumber) and isinstance(num2, PhoneNumber): 

3292 return _is_number_match_OO(num1, num2) 

3293 elif isinstance(num1, PhoneNumber): 

3294 return _is_number_match_OS(num1, num2) 

3295 elif isinstance(num2, PhoneNumber): 

3296 return _is_number_match_OS(num2, num1) 

3297 else: 

3298 return _is_number_match_SS(num1, num2) 

3299 

3300 

3301def can_be_internationally_dialled(numobj): 

3302 """Returns True if the number can only be dialled from outside the region, 

3303 or unknown. 

3304 

3305 If the number can only be dialled from within the region 

3306 as well, returns False. Does not check the number is a valid number. 

3307 Note that, at the moment, this method does not handle short numbers (which 

3308 are currently all presumed to not be diallable from outside their country). 

3309 

3310 Arguments: 

3311 numobj -- the phone number objectfor which we want to know whether it is 

3312 diallable from outside the region. 

3313 """ 

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

3315 if metadata is None: 

3316 # Note numbers belonging to non-geographical entities (e.g. +800 

3317 # numbers) are always internationally diallable, and will be caught 

3318 # here. 

3319 return True 

3320 nsn = national_significant_number(numobj) 

3321 return not _is_number_matching_desc(nsn, metadata.no_international_dialling) 

3322 

3323 

3324def is_mobile_number_portable_region(region_code): 

3325 """Returns true if the supplied region supports mobile number portability. 

3326 Returns false for invalid, unknown or regions that don't support mobile 

3327 number portability. 

3328 

3329 Arguments: 

3330 region_code -- the region for which we want to know whether it supports mobile number 

3331 portability or not. 

3332 """ 

3333 metadata = PhoneMetadata.metadata_for_region(region_code, None) 

3334 if metadata is None: 

3335 return False 

3336 return metadata.mobile_number_portable_region 

3337 

3338 

3339class NumberParseException(UnicodeMixin, Exception): 

3340 """Exception when attempting to parse a putative phone number""" 

3341 

3342 # The reason a string could not be interpreted as a phone number. 

3343 

3344 # The country code supplied did not belong to a supported country or 

3345 # non-geographical entity. 

3346 INVALID_COUNTRY_CODE = 0 

3347 

3348 # This generally indicates the string passed in had fewer than 3 digits in 

3349 # it. The number failed to match the regular expression 

3350 # _VALID_PHONE_NUMBER in phonenumberutil.py. 

3351 

3352 # This indicates the string passed is not a valid number. Either the string 

3353 # had less than 3 digits in it or had an invalid phone-context 

3354 # parameter. More specifically, the number failed to match the regular 

3355 # expression _VALID_PHONE_NUMBER, )RFC3966_GLOBAL_NUMBER_DIGITS, or 

3356 # _RFC3966_DOMAINNAME in phonenumberutil.py. 

3357 NOT_A_NUMBER = 1 

3358 

3359 # This indicates the string started with an international dialing prefix, 

3360 # but after this was removed, it had fewer digits than any valid phone 

3361 # number (including country code) could have. 

3362 TOO_SHORT_AFTER_IDD = 2 

3363 

3364 # This indicates the string, after any country code has been stripped, 

3365 # had fewer digits than any valid phone number could have. 

3366 TOO_SHORT_NSN = 3 

3367 

3368 # This indicates the string had more digits than any valid phone number 

3369 # could have 

3370 TOO_LONG = 4 

3371 

3372 def __init__(self, error_type, msg): 

3373 Exception.__init__(self, msg) 

3374 self.error_type = error_type 

3375 self._msg = msg 

3376 

3377 def __reduce__(self): 

3378 return (type(self), (self.error_type, self._msg)) 

3379 

3380 def __unicode__(self): 

3381 return unicod("(%s) %s") % (self.error_type, self._msg) 

3382 

3383 

3384def _match_national_number(number, number_desc, allow_prefix_match): 

3385 """Returns whether the given national number (a string containing only decimal digits) matches 

3386 the national number pattern defined in the given PhoneNumberDesc object. 

3387 """ 

3388 # We don't want to consider it a prefix match when matching non-empty input against an empty 

3389 # pattern. 

3390 if number_desc is None or number_desc.national_number_pattern is None or len(number_desc.national_number_pattern) == 0: 

3391 return False 

3392 return _match(number, re.compile(number_desc.national_number_pattern), allow_prefix_match) 

3393 

3394 

3395def _match(number, pattern, allow_prefix_match): 

3396 if not pattern.match(number): 

3397 return False 

3398 else: 

3399 if fullmatch(pattern, number): 

3400 return True 

3401 else: 

3402 return allow_prefix_match