fst-20251008 https://dialpad.atlassian.net/browse/TEL-25836

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,23 @@
+---
+name: Bug report
+about: Create a bug report for Python-specific problems
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+Only raise issues that are **specific to the Python version** here, please.
+
+Before reporting an issue with parsing particular numbers, check if the problem also occurs with the online version of the Java code at <https://libphonenumber.appspot.com/>
+
+If the same problem is visible with the Java code, **report the problem upstream** not here:
+
+- [checklist](https://github.com/google/libphonenumber/blob/master/CONTRIBUTING.md#checklist-before-filing-an-issue)
+- (non-GitHub) [issue tracker](http://issuetracker.google.com/issues/new?component=192347).
+
+If the problem **only** occurs with the Python version of the library, continue opening an Issue:
+
+- Delete this template text.
+- Include Python version (`python --version`)
+- Include library version (`python -c "import phonenumbers; print(phonenumbers.__version__)"`)

.github/workflows/ci.yml

@@ -6,17 +6,18 @@ permissions:
 jobs:
   build:
 
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
-        python-version: [2.7, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, "3.10", pypy2, pypy3]
+        python-version: [3.8, 3.9, "3.10", 3.11, 3.12, 3.13, pypy2.7, pypy3.9]
 
     steps:
-    - uses: actions/checkout@629c2de402a417ea7690ca6ce3f33229e27606a5 # v2
+    - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@f38219332975fe8f9c04cca981d674bf22aea1d3 # v2
+      uses: actions/setup-python@61a6322f88396a6271a6ee3565807d608ecaddd1 # v4.7.0
       with:
         python-version: ${{ matrix.python-version }}
+        allow-prereleases: true
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip

.github/workflows/coverage.yml

@@ -8,15 +8,15 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@629c2de402a417ea7690ca6ce3f33229e27606a5 # v2
+    - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3
     - name: Set up latest Python 3
-      uses: actions/setup-python@f38219332975fe8f9c04cca981d674bf22aea1d3 # v2
+      uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4
       with:
         python-version: 3
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install protobuf pycodestyle coverage coveralls
+        pip install protobuf==3.17.3 pycodestyle coverage coveralls
     - name: Test with coverage
       run: |
         cd python

.github/workflows/typing.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install mypy==0.921 types-protobuf
+          pip install mypy==0.921 types-protobuf==3.19.21
 
       - name: Execute run_stubtest.py
         run: |
@@ -39,7 +39,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install mypy types-protobuf
+          pip install mypy==0.921 types-protobuf==3.19.21
 
       - name: Run mypy
         run: |

.github/workflows/upstream.yml

@@ -0,0 +1,21 @@
+name: Check libphonenumbers releases
+
+on:
+  schedule:
+    - cron: '30 7,19 * * *'  # Run daily at 07:30 and 19:30
+  workflow_dispatch:
+
+jobs:
+  versioncheck:
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'daviddrysdale'
+    steps:
+      - uses: actions/checkout@ac593985615ec2ede58e132d2e21d2b1cbd6127c # v3
+      - uses: actions/setup-python@d27e3f3d7c64b4bbf8e4abfb9b63b83e846e0435 # v4
+        with:
+          python-version: 3
+      - name: Check upstream version
+        run: |
+          pip install -U pip
+          pip install requests
+          python3 tools/python/checkupstreamversion.py

README.md

@@ -12,6 +12,8 @@ Original Java code is Copyright (C) 2009-2015 The Libphonenumber Authors.
 Release [HISTORY](https://github.com/daviddrysdale/python-phonenumbers/blob/dev/python/HISTORY.md),
 derived from [upstream release notes](https://github.com/google/libphonenumber/blob/master/release_notes.txt).
 
+[Documentation](https://daviddrysdale.github.io/python-phonenumbers/)
+
 Installation
 ------------
 
@@ -141,7 +143,7 @@ PhoneNumberMatch [51,62) 703-4800500
 ```
 
 You might want to get some information about the location that corresponds to a phone number.  The
-`geocoder.area_description_for_number` does this, when possible.
+`geocoder.description_for_number` does this, when possible.
 
 ```pycon
 >>> from phonenumbers import geocoder
@@ -207,9 +209,6 @@ load of metadata will not cause a pause or memory exhaustion):
 * Force-load the extended metadata by `import`ing the appropriate packages (`phonenumbers.geocoder`,
   `phonenumbers.carrier`, `phonenumbers.timezone`).
 
-The `phonenumberslite` version of the package does not include the geocoding, carrier and timezone metadata,
-which can be useful if you have problems installing the main `phonenumbers` package due to space/memory limitations.
-
 Static Typing
 -------------
 

docs/phonenumbers.asyoutypeformatter.html

@@ -58,7 +58,7 @@
 Arguments:<br>
 region_code&nbsp;--&nbsp;The&nbsp;region&nbsp;where&nbsp;the&nbsp;phone&nbsp;number&nbsp;is&nbsp;being&nbsp;entered<br>
 &nbsp;<br>
-Return&nbsp;an&nbsp;<a href="#AsYouTypeFormatter">AsYouTypeFormatter</a>}&nbsp;<a href="builtins.html#object">object</a>,&nbsp;which&nbsp;could&nbsp;be&nbsp;used&nbsp;to&nbsp;format<br>
+Return&nbsp;an&nbsp;<a href="#AsYouTypeFormatter">AsYouTypeFormatter</a>&nbsp;<a href="builtins.html#object">object</a>,&nbsp;which&nbsp;could&nbsp;be&nbsp;used&nbsp;to&nbsp;format<br>
 phone&nbsp;numbers&nbsp;in&nbsp;the&nbsp;specific&nbsp;region&nbsp;"as&nbsp;you&nbsp;type"</tt></dd></dl>
 
 <dl><dt><a name="AsYouTypeFormatter-clear"><strong>clear</strong></a>(self)</dt><dd><tt>Clears&nbsp;the&nbsp;internal&nbsp;state&nbsp;of&nbsp;the&nbsp;formatter,&nbsp;so&nbsp;it&nbsp;can&nbsp;be&nbsp;reused.</tt></dd></dl>
@@ -105,4 +105,4 @@
 <td width="100%"><strong>REGION_CODE_FOR_NON_GEO_ENTITY</strong> = '001'<br>
 <strong>U_EMPTY_STRING</strong> = ''<br>
 <strong>U_SPACE</strong> = ' '</td></tr></table>
-</body></html>
+</body></html>

docs/phonenumbers.html

@@ -6,7 +6,7 @@
 <table width="100%" cellspacing=0 cellpadding=2 border=0 summary="heading">
 <tr bgcolor="#7799ee">
 <td valign=bottom>&nbsp;<br>
-<font color="#ffffff" face="helvetica, arial">&nbsp;<br><big><big><strong>phonenumbers</strong></big></big> (version 8.12.40)</font></td
+<font color="#ffffff" face="helvetica, arial">&nbsp;<br><big><big><strong>phonenumbers</strong></big></big> (version 8.13.17)</font></td
 ><td align=right valign=bottom
 ><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="https://github.com/daviddrysdale/python-phonenumbers/blob/dev/python/phonenumbers/__init__.py">phonenumbers/__init__.py</a></font></td></tr></table>
     <p><tt>Python&nbsp;phone&nbsp;number&nbsp;parsing&nbsp;and&nbsp;formatting&nbsp;library<br>
@@ -162,7 +162,7 @@
 Arguments:<br>
 region_code&nbsp;--&nbsp;The&nbsp;region&nbsp;where&nbsp;the&nbsp;phone&nbsp;number&nbsp;is&nbsp;being&nbsp;entered<br>
 &nbsp;<br>
-Return&nbsp;an&nbsp;<a href="#AsYouTypeFormatter">AsYouTypeFormatter</a>}&nbsp;<a href="builtins.html#object">object</a>,&nbsp;which&nbsp;could&nbsp;be&nbsp;used&nbsp;to&nbsp;format<br>
+Return&nbsp;an&nbsp;<a href="#AsYouTypeFormatter">AsYouTypeFormatter</a>&nbsp;<a href="builtins.html#object">object</a>,&nbsp;which&nbsp;could&nbsp;be&nbsp;used&nbsp;to&nbsp;format<br>
 phone&nbsp;numbers&nbsp;in&nbsp;the&nbsp;specific&nbsp;region&nbsp;"as&nbsp;you&nbsp;type"</tt></dd></dl>
 
 <dl><dt><a name="AsYouTypeFormatter-clear"><strong>clear</strong></a>(self)</dt><dd><tt>Clears&nbsp;the&nbsp;internal&nbsp;state&nbsp;of&nbsp;the&nbsp;formatter,&nbsp;so&nbsp;it&nbsp;can&nbsp;be&nbsp;reused.</tt></dd></dl>
@@ -208,7 +208,11 @@
 <tr bgcolor="#ffc8d8"><td rowspan=2><tt>&nbsp;&nbsp;&nbsp;</tt></td>
 <td colspan=2><tt>The&nbsp;source&nbsp;from&nbsp;which&nbsp;a&nbsp;country&nbsp;code&nbsp;is&nbsp;derived.<br>&nbsp;</tt></td></tr>
 <tr><td>&nbsp;</td>
-<td width="100%">Data descriptors defined here:<br>
+<td width="100%">Class methods defined here:<br>
+<dl><dt><a name="CountryCodeSource-to_string"><strong>to_string</strong></a>(val)<font color="#909090"><font face="helvetica, arial"> from <a href="builtins.html#type">builtins.type</a></font></font></dt><dd><tt>Return&nbsp;a&nbsp;string&nbsp;representation&nbsp;of&nbsp;a&nbsp;<a href="#CountryCodeSource">CountryCodeSource</a>&nbsp;value</tt></dd></dl>
+
+<hr>
+Data descriptors defined here:<br>
 <dl><dt><strong>__dict__</strong></dt>
 <dd><tt>dictionary&nbsp;for&nbsp;instance&nbsp;variables&nbsp;(if&nbsp;defined)</tt></dd>
 </dl>
@@ -1082,14 +1086,15 @@
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;of&nbsp;<a href="#NumberFormat">NumberFormat</a>&nbsp;objects.<br>
 &nbsp;<br>
 Returns&nbsp;the&nbsp;formatted&nbsp;phone&nbsp;number.</tt></dd></dl>
- <dl><dt><a name="-format_in_original_format"><strong>format_in_original_format</strong></a>(numobj, region_calling_from)</dt><dd><tt>Format&nbsp;a&nbsp;number&nbsp;using&nbsp;the&nbsp;original&nbsp;format&nbsp;that&nbsp;the&nbsp;number&nbsp;was&nbsp;parsed&nbsp;from.<br>
+ <dl><dt><a name="-format_in_original_format"><strong>format_in_original_format</strong></a>(numobj, region_calling_from)</dt><dd><tt>Formats&nbsp;a&nbsp;phone&nbsp;number&nbsp;using&nbsp;the&nbsp;original&nbsp;phone&nbsp;number&nbsp;format<br>
+(e.g.&nbsp;INTERNATIONAL&nbsp;or&nbsp;NATIONAL)&nbsp;that&nbsp;the&nbsp;number&nbsp;is&nbsp;parsed&nbsp;from,&nbsp;provided<br>
+that&nbsp;the&nbsp;number&nbsp;has&nbsp;been&nbsp;parsed&nbsp;with&nbsp;<a href="#-parse">parse</a>(..,&nbsp;keep_raw_input=True).<br>
+Otherwise&nbsp;the&nbsp;number&nbsp;will&nbsp;be&nbsp;formatted&nbsp;in&nbsp;NATIONAL&nbsp;format.<br>
 &nbsp;<br>
 The&nbsp;original&nbsp;format&nbsp;is&nbsp;embedded&nbsp;in&nbsp;the&nbsp;country_code_source&nbsp;field&nbsp;of&nbsp;the<br>
-<a href="#PhoneNumber">PhoneNumber</a>&nbsp;<a href="builtins.html#object">object</a>&nbsp;passed&nbsp;in.&nbsp;If&nbsp;such&nbsp;information&nbsp;is&nbsp;missing,&nbsp;the&nbsp;number<br>
-will&nbsp;be&nbsp;formatted&nbsp;into&nbsp;the&nbsp;NATIONAL&nbsp;format&nbsp;by&nbsp;default.<br>
-&nbsp;<br>
-When&nbsp;&nbsp;we&nbsp;don't&nbsp;have&nbsp;a&nbsp;formatting&nbsp;pattern&nbsp;for&nbsp;the&nbsp;number,&nbsp;the&nbsp;method<br>
-returns&nbsp;the&nbsp;raw&nbsp;input&nbsp;when&nbsp;it&nbsp;is&nbsp;available.<br>
+<a href="#PhoneNumber">PhoneNumber</a>&nbsp;<a href="builtins.html#object">object</a>&nbsp;passed&nbsp;in,&nbsp;which&nbsp;is&nbsp;only&nbsp;set&nbsp;when&nbsp;parsing&nbsp;keeps&nbsp;the&nbsp;raw<br>
+input.&nbsp;When&nbsp;we&nbsp;don't&nbsp;have&nbsp;a&nbsp;formatting&nbsp;pattern&nbsp;for&nbsp;the&nbsp;number,&nbsp;the&nbsp;method<br>
+falls&nbsp;back&nbsp;to&nbsp;returning&nbsp;the&nbsp;raw&nbsp;input.<br>
 &nbsp;<br>
 Note&nbsp;this&nbsp;method&nbsp;guarantees&nbsp;no&nbsp;digit&nbsp;will&nbsp;be&nbsp;inserted,&nbsp;removed&nbsp;or&nbsp;modified<br>
 as&nbsp;a&nbsp;result&nbsp;of&nbsp;formatting.<br>
@@ -1750,4 +1755,4 @@
 <strong>SUPPORTED_SHORT_REGIONS</strong> = ['AC', 'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', ...]<br>
 <strong>UNKNOWN_REGION</strong> = 'ZZ'<br>
 <strong>__all__</strong> = ['PhoneNumber', 'CountryCodeSource', 'FrozenPhoneNumber', 'REGION_CODE_FOR_NON_GEO_ENTITY', 'NumberFormat', 'PhoneNumberDesc', 'PhoneMetadata', 'AsYouTypeFormatter', 'COUNTRY_CODE_TO_REGION_CODE', 'SUPPORTED_REGIONS', 'UNKNOWN_REGION', 'COUNTRY_CODES_FOR_NON_GEO_REGIONS', 'NON_DIGITS_PATTERN', 'MatchType', 'NumberParseException', 'PhoneNumberFormat', 'PhoneNumberType', 'ValidationResult', 'can_be_internationally_dialled', 'convert_alpha_characters_in_number', ...]</td></tr></table>
-</body></html>
+</body></html>

docs/phonenumbers.phonemetadata.html

@@ -235,4 +235,4 @@
 
 <tr><td bgcolor="#55aa55"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
 <td width="100%"><strong>REGION_CODE_FOR_NON_GEO_ENTITY</strong> = '001'</td></tr></table>
-</body></html>
+</body></html>

docs/phonenumbers.phonenumber.html

@@ -45,7 +45,11 @@
 <tr bgcolor="#ffc8d8"><td rowspan=2><tt>&nbsp;&nbsp;&nbsp;</tt></td>
 <td colspan=2><tt>The&nbsp;source&nbsp;from&nbsp;which&nbsp;a&nbsp;country&nbsp;code&nbsp;is&nbsp;derived.<br>&nbsp;</tt></td></tr>
 <tr><td>&nbsp;</td>
-<td width="100%">Data descriptors defined here:<br>
+<td width="100%">Class methods defined here:<br>
+<dl><dt><a name="CountryCodeSource-to_string"><strong>to_string</strong></a>(val)<font color="#909090"><font face="helvetica, arial"> from <a href="builtins.html#type">builtins.type</a></font></font></dt><dd><tt>Return&nbsp;a&nbsp;string&nbsp;representation&nbsp;of&nbsp;a&nbsp;<a href="#CountryCodeSource">CountryCodeSource</a>&nbsp;value</tt></dd></dl>
+
+<hr>
+Data descriptors defined here:<br>
 <dl><dt><strong>__dict__</strong></dt>
 <dd><tt>dictionary&nbsp;for&nbsp;instance&nbsp;variables&nbsp;(if&nbsp;defined)</tt></dd>
 </dl>
@@ -172,4 +176,4 @@
 <dd><tt>list&nbsp;of&nbsp;weak&nbsp;references&nbsp;to&nbsp;the&nbsp;object&nbsp;(if&nbsp;defined)</tt></dd>
 </dl>
 </td></tr></table></td></tr></table>
-</body></html>
+</body></html>

docs/phonenumbers.phonenumberutil.html

@@ -392,14 +392,15 @@
 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;of&nbsp;NumberFormat&nbsp;objects.<br>
 &nbsp;<br>
 Returns&nbsp;the&nbsp;formatted&nbsp;phone&nbsp;number.</tt></dd></dl>
- <dl><dt><a name="-format_in_original_format"><strong>format_in_original_format</strong></a>(numobj, region_calling_from)</dt><dd><tt>Format&nbsp;a&nbsp;number&nbsp;using&nbsp;the&nbsp;original&nbsp;format&nbsp;that&nbsp;the&nbsp;number&nbsp;was&nbsp;parsed&nbsp;from.<br>
+ <dl><dt><a name="-format_in_original_format"><strong>format_in_original_format</strong></a>(numobj, region_calling_from)</dt><dd><tt>Formats&nbsp;a&nbsp;phone&nbsp;number&nbsp;using&nbsp;the&nbsp;original&nbsp;phone&nbsp;number&nbsp;format<br>
+(e.g.&nbsp;INTERNATIONAL&nbsp;or&nbsp;NATIONAL)&nbsp;that&nbsp;the&nbsp;number&nbsp;is&nbsp;parsed&nbsp;from,&nbsp;provided<br>
+that&nbsp;the&nbsp;number&nbsp;has&nbsp;been&nbsp;parsed&nbsp;with&nbsp;<a href="#-parse">parse</a>(..,&nbsp;keep_raw_input=True).<br>
+Otherwise&nbsp;the&nbsp;number&nbsp;will&nbsp;be&nbsp;formatted&nbsp;in&nbsp;NATIONAL&nbsp;format.<br>
 &nbsp;<br>
 The&nbsp;original&nbsp;format&nbsp;is&nbsp;embedded&nbsp;in&nbsp;the&nbsp;country_code_source&nbsp;field&nbsp;of&nbsp;the<br>
-PhoneNumber&nbsp;<a href="builtins.html#object">object</a>&nbsp;passed&nbsp;in.&nbsp;If&nbsp;such&nbsp;information&nbsp;is&nbsp;missing,&nbsp;the&nbsp;number<br>
-will&nbsp;be&nbsp;formatted&nbsp;into&nbsp;the&nbsp;NATIONAL&nbsp;format&nbsp;by&nbsp;default.<br>
-&nbsp;<br>
-When&nbsp;&nbsp;we&nbsp;don't&nbsp;have&nbsp;a&nbsp;formatting&nbsp;pattern&nbsp;for&nbsp;the&nbsp;number,&nbsp;the&nbsp;method<br>
-returns&nbsp;the&nbsp;raw&nbsp;input&nbsp;when&nbsp;it&nbsp;is&nbsp;available.<br>
+PhoneNumber&nbsp;<a href="builtins.html#object">object</a>&nbsp;passed&nbsp;in,&nbsp;which&nbsp;is&nbsp;only&nbsp;set&nbsp;when&nbsp;parsing&nbsp;keeps&nbsp;the&nbsp;raw<br>
+input.&nbsp;When&nbsp;we&nbsp;don't&nbsp;have&nbsp;a&nbsp;formatting&nbsp;pattern&nbsp;for&nbsp;the&nbsp;number,&nbsp;the&nbsp;method<br>
+falls&nbsp;back&nbsp;to&nbsp;returning&nbsp;the&nbsp;raw&nbsp;input.<br>
 &nbsp;<br>
 Note&nbsp;this&nbsp;method&nbsp;guarantees&nbsp;no&nbsp;digit&nbsp;will&nbsp;be&nbsp;inserted,&nbsp;removed&nbsp;or&nbsp;modified<br>
 as&nbsp;a&nbsp;result&nbsp;of&nbsp;formatting.<br>
@@ -969,4 +970,4 @@
 <strong>U_SPACE</strong> = ' '<br>
 <strong>U_TILDE</strong> = '~'<br>
 <strong>U_ZERO</strong> = '0'</td></tr></table>
-</body></html>
+</body></html>

docs/phonenumbers.shortnumberinfo.html

@@ -226,4 +226,4 @@
 <tr><td bgcolor="#55aa55"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</td>
 <td width="100%"><strong>SUPPORTED_SHORT_REGIONS</strong> = ['AC', 'AD', 'AE', 'AF', 'AG', 'AI', 'AL', 'AM', 'AO', 'AR', 'AS', 'AT', 'AU', 'AW', 'AX', 'AZ', 'BA', 'BB', 'BD', 'BE', ...]<br>
 <strong>U_EMPTY_STRING</strong> = ''</td></tr></table>
-</body></html>
+</body></html>

python/HISTORY.md

@@ -12,6 +12,30 @@ This file does not generally include descriptions of patch releases (vX.Y.Z
 changes.  (Metadata updates are best checked
 [upstream](https://github.com/google/libphonenumber/blob/master/release_notes.txt).)
 
+What's new in 9.0.0
+--------------------
+
+Merge to upstream version 9.0.0.  This is a major version change in the upstream code due to an update in the required
+Java version; however, the Python version only has metadata changes.
+
+What's new in 8.13.8
+--------------------
+
+Merge to
+[upstream commit 07cd7bbb8a2f](https://github.com/google/libphonenumber/commit/07cd7bbb8a2f);
+relevant code changes:
+
+- Added a check to phonenumberutil.py that the value of the `phone-context` parameter of the tel URI follows the correct
+  syntax as defined in [RFC3966](https://www.rfc-editor.org/rfc/rfc3966#section-3).
+
+What's new in 8.13.0
+--------------------
+
+Merge to [upstream commit
+185004cabd1bb4d3](https://github.com/google/libphonenumber/commit/185004cabd1bb4d3).  Upstream has
+removed the `leading_zero_possible` field from the `PhoneMetadata` type as part of this version;
+however, this change is *not* mirrored in the Python code due to back-compatibility concerns.
+
 What's new in 8.12.40
 ---------------------