{"id":13398302,"url":"https://github.com/daviddrysdale/python-phonenumbers","last_synced_at":"2025-05-12T05:32:39.959Z","repository":{"id":40643494,"uuid":"1643611","full_name":"daviddrysdale/python-phonenumbers","owner":"daviddrysdale","description":"Python port of Google's libphonenumber","archived":false,"fork":false,"pushed_at":"2025-05-08T05:59:15.000Z","size":80710,"stargazers_count":3588,"open_issues_count":13,"forks_count":428,"subscribers_count":88,"default_branch":"dev","last_synced_at":"2025-05-12T02:45:23.691Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daviddrysdale.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2011-04-21T03:06:38.000Z","updated_at":"2025-05-09T13:35:42.000Z","dependencies_parsed_at":"2022-07-20T13:48:08.080Z","dependency_job_id":"af14ada3-d84e-4b85-9719-e2ffed327238","html_url":"https://github.com/daviddrysdale/python-phonenumbers","commit_stats":{"total_commits":1500,"total_committers":28,"mean_commits":53.57142857142857,"dds":0.4766666666666667,"last_synced_commit":"a7a9796ff097d1193377f3e28f33439d6296add0"},"previous_names":[],"tags_count":311,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daviddrysdale%2Fpython-phonenumbers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daviddrysdale%2Fpython-phonenumbers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daviddrysdale%2Fpython-phonenumbers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daviddrysdale%2Fpython-phonenumbers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daviddrysdale","download_url":"https://codeload.github.com/daviddrysdale/python-phonenumbers/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253672731,"owners_count":21945482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T19:00:22.270Z","updated_at":"2025-05-12T05:32:39.892Z","avatar_url":"https://github.com/daviddrysdale.png","language":"Python","readme":"phonenumbers Python Library\n===========================\n\n[![Coverage Status](https://coveralls.io/repos/daviddrysdale/python-phonenumbers/badge.svg?branch=dev\u0026service=github)](https://coveralls.io/github/daviddrysdale/python-phonenumbers?branch=dev)\n\nThis is a Python port of [Google's libphonenumber library](https://github.com/google/libphonenumber)\nIt supports Python 2.5-2.7 and Python 3.x (in the same codebase, with no\n[2to3](http://docs.python.org/2/library/2to3.html) conversion needed).\n\nOriginal Java code is Copyright (C) 2009-2015 The Libphonenumber Authors.\n\nRelease [HISTORY](https://github.com/daviddrysdale/python-phonenumbers/blob/dev/python/HISTORY.md),\nderived from [upstream release notes](https://github.com/google/libphonenumber/blob/master/release_notes.txt).\n\n[Documentation](https://daviddrysdale.github.io/python-phonenumbers/)\n\nInstallation\n------------\n\nInstall using [pip](https://pypi.org/project/phonenumbers/) with:\n```\npip install phonenumbers\n```\n\nExample Usage\n-------------\n\nThe main object that the library deals with is a `PhoneNumber` object.  You can create this from a string\nrepresenting a phone number using the `parse` function, but you also need to specify the country\nthat the phone number is being dialled from (unless the number is in E.164 format, which is globally\nunique).\n\n```pycon\n\u003e\u003e\u003e import phonenumbers\n\u003e\u003e\u003e x = phonenumbers.parse(\"+442083661177\", None)\n\u003e\u003e\u003e print(x)\nCountry Code: 44 National Number: 2083661177 Leading Zero: False\n\u003e\u003e\u003e type(x)\n\u003cclass 'phonenumbers.phonenumber.PhoneNumber'\u003e\n\u003e\u003e\u003e y = phonenumbers.parse(\"020 8366 1177\", \"GB\")\n\u003e\u003e\u003e print(y)\nCountry Code: 44 National Number: 2083661177 Leading Zero: False\n\u003e\u003e\u003e x == y\nTrue\n\u003e\u003e\u003e z = phonenumbers.parse(\"00 1 650 253 2222\", \"GB\")  # as dialled from GB, not a GB number\n\u003e\u003e\u003e print(z)\nCountry Code: 1 National Number: 6502532222 Leading Zero(s): False\n```\n\nThe `PhoneNumber` object that `parse` produces typically still needs to be validated, to check whether\nit's a *possible* number (e.g. it has the right number of digits) or a *valid* number (e.g. it's\nin an assigned exchange).\n\n```pycon\n\u003e\u003e\u003e z = phonenumbers.parse(\"+120012301\", None)\n\u003e\u003e\u003e print(z)\nCountry Code: 1 National Number: 20012301 Leading Zero: False\n\u003e\u003e\u003e phonenumbers.is_possible_number(z)  # too few digits for USA\nFalse\n\u003e\u003e\u003e phonenumbers.is_valid_number(z)\nFalse\n\u003e\u003e\u003e z = phonenumbers.parse(\"+12001230101\", None)\n\u003e\u003e\u003e print(z)\nCountry Code: 1 National Number: 2001230101 Leading Zero: False\n\u003e\u003e\u003e phonenumbers.is_possible_number(z)\nTrue\n\u003e\u003e\u003e phonenumbers.is_valid_number(z)  # NPA 200 not used\nFalse\n```\n\nThe `parse` function will also fail completely (with a `NumberParseException`) on inputs that cannot\nbe uniquely parsed, or that  can't possibly be phone numbers.\n\n```pycon\n\u003e\u003e\u003e z = phonenumbers.parse(\"02081234567\", None)  # no region, no + =\u003e unparseable\nTraceback (most recent call last):\n  File \"phonenumbers/phonenumberutil.py\", line 2350, in parse\n    \"Missing or invalid default region.\")\nphonenumbers.phonenumberutil.NumberParseException: (0) Missing or invalid default region.\n\u003e\u003e\u003e z = phonenumbers.parse(\"gibberish\", None)\nTraceback (most recent call last):\n  File \"phonenumbers/phonenumberutil.py\", line 2344, in parse\n    \"The string supplied did not seem to be a phone number.\")\nphonenumbers.phonenumberutil.NumberParseException: (1) The string supplied did not seem to be a phone number.\n```\n\nOnce you've got a phone number, a common task is to format it in a standardized format.  There are a few\nformats available (under `PhoneNumberFormat`), and the `format_number` function does the formatting.\n\n```pycon\n\u003e\u003e\u003e phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.NATIONAL)\n'020 8366 1177'\n\u003e\u003e\u003e phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.INTERNATIONAL)\n'+44 20 8366 1177'\n\u003e\u003e\u003e phonenumbers.format_number(x, phonenumbers.PhoneNumberFormat.E164)\n'+442083661177'\n```\n\nIf your application has a UI that allows the user to type in a phone number, it's nice to get the formatting\napplied as the user types.   The `AsYouTypeFormatter` object allows this.\n\n```pycon\n\u003e\u003e\u003e formatter = phonenumbers.AsYouTypeFormatter(\"US\")\n\u003e\u003e\u003e formatter.input_digit(\"6\")\n'6'\n\u003e\u003e\u003e formatter.input_digit(\"5\")\n'65'\n\u003e\u003e\u003e formatter.input_digit(\"0\")\n'650'\n\u003e\u003e\u003e formatter.input_digit(\"2\")\n'650 2'\n\u003e\u003e\u003e formatter.input_digit(\"5\")\n'650 25'\n\u003e\u003e\u003e formatter.input_digit(\"3\")\n'650 253'\n\u003e\u003e\u003e formatter.input_digit(\"2\")\n'650-2532'\n\u003e\u003e\u003e formatter.input_digit(\"2\")\n'(650) 253-22'\n\u003e\u003e\u003e formatter.input_digit(\"2\")\n'(650) 253-222'\n\u003e\u003e\u003e formatter.input_digit(\"2\")\n'(650) 253-2222'\n```\n\nSometimes, you've got a larger block of text that may or may not have some phone numbers inside it.  For this,\nthe `PhoneNumberMatcher` object provides the relevant functionality; you can iterate over it to retrieve a\nsequence of `PhoneNumberMatch` objects.  Each of these match objects holds a `PhoneNumber` object together\nwith information about where the match occurred in the original string.\n\n```pycon\n\u003e\u003e\u003e text = \"Call me at 510-748-8230 if it's before 9:30, or on 703-4800500 after 10am.\"\n\u003e\u003e\u003e for match in phonenumbers.PhoneNumberMatcher(text, \"US\"):\n...     print(match)\n...\nPhoneNumberMatch [11,23) 510-748-8230\nPhoneNumberMatch [51,62) 703-4800500\n\u003e\u003e\u003e for match in phonenumbers.PhoneNumberMatcher(text, \"US\"):\n...     print(phonenumbers.format_number(match.number, phonenumbers.PhoneNumberFormat.E164))\n...\n+15107488230\n+17034800500\n```\n\nYou might want to get some information about the location that corresponds to a phone number.  The\n`geocoder.description_for_number` does this, when possible.\n\n```pycon\n\u003e\u003e\u003e from phonenumbers import geocoder\n\u003e\u003e\u003e ch_number = phonenumbers.parse(\"0431234567\", \"CH\")\n\u003e\u003e\u003e geocoder.description_for_number(ch_number, \"de\")\n'Zürich'\n\u003e\u003e\u003e geocoder.description_for_number(ch_number, \"en\")\n'Zurich'\n\u003e\u003e\u003e geocoder.description_for_number(ch_number, \"fr\")\n'Zurich'\n\u003e\u003e\u003e geocoder.description_for_number(ch_number, \"it\")\n'Zurigo'\n```\n\nFor mobile numbers in some countries, you can also find out information about which carrier\noriginally owned a phone number.\n\n```pycon\n\u003e\u003e\u003e from phonenumbers import carrier\n\u003e\u003e\u003e ro_number = phonenumbers.parse(\"+40721234567\", \"RO\")\n\u003e\u003e\u003e carrier.name_for_number(ro_number, \"en\")\n'Vodafone'\n```\n\nYou might also be able to retrieve a list of time zone names that the number potentially\nbelongs to.\n\n```pycon\n\u003e\u003e\u003e from phonenumbers import timezone\n\u003e\u003e\u003e gb_number = phonenumbers.parse(\"+447986123456\", \"GB\")\n\u003e\u003e\u003e timezone.time_zones_for_number(gb_number)\n('Atlantic/Reykjavik', 'Europe/London')\n```\n\nFor more information about the other functionality available from the library, look in the unit tests or in the original\n[libphonenumber project](https://github.com/google/libphonenumber).\n\nMemory Usage\n------------\n\nThe library includes a lot of metadata, potentially giving a significant memory overhead.  There are two mechanisms\nfor dealing with this.\n\n* The normal metadata (just over 2 MiB of generated Python code) for the core functionality of the library is loaded\n  on-demand, on a region-by-region basis (i.e. the metadata for a region is only loaded on the first time it is needed).\n* Metadata for extended functionality is held in separate packages, which therefore need to be explicitly\n  loaded separately.  This affects:\n    * The geocoding metadata (~19 MiB), which is held in `phonenumbers.geocoder` and used by the geocoding functions\n      (`geocoder.description_for_number`, `geocoder.description_for_valid_number` or\n      `geocoder.country_name_for_number`).\n    * The carrier metadata (~1 MiB), which is held in `phonenumbers.carrier` and used by the mapping functions\n      (`carrier.name_for_number` or `carrier.name_for_valid_number`).\n    * The timezone metadata (~100 KiB), which is held in `phonenumbers.timezone` and used by the timezone functions\n      (`time_zones_for_number` or `time_zones_for_geographical_number`).\n\nThe `phonenumberslite` version of the library does not include the geocoder, carrier and timezone packages,\nwhich can be useful if you have problems installing the main `phonenumbers` library due to space/memory limitations.\n\nIf you need to ensure that the metadata memory use is accounted for at start of day (i.e. that a subsequent on-demand\nload of metadata will not cause a pause or memory exhaustion):\n\n* Force-load the normal metadata by calling `phonenumbers.PhoneMetadata.load_all()`.\n* Force-load the extended metadata by `import`ing the appropriate packages (`phonenumbers.geocoder`,\n  `phonenumbers.carrier`, `phonenumbers.timezone`).\n\nStatic Typing\n-------------\n\nThe library includes a set of type [stub files](https://www.python.org/dev/peps/pep-0484/#stub-files) to support static\ntype checking by library users. These stub files signal the types that should be used, and may also be of use in IDEs \nwhich have integrated type checking functionalities.\n\nThese files are written for Python 3, and as such type checking the library with these stubs on Python 2.5-2.7 is\nunsupported.\n\nProject Layout\n--------------\n\n* The `python/` directory holds the Python code.\n* The `resources/` directory is a copy of the `resources/`\n  directory from\n  [libphonenumber](https://github.com/google/libphonenumber/tree/master/resources).\n  This is not needed to run the Python code, but is needed when upstream\n  changes to the master metadata need to be incorporated.\n* The `tools/` directory holds the tools that are used to process upstream\n  changes to the master metadata.\n","funding_links":[],"categories":["Text Processing","Python","资源列表","Data Format \u0026 I/O","文本处理","Phone Numbers","Text Data","文本数据和NLP","Text Processing [🔝](#readme)","Uncategorized","Awesome Python","Feature Extraction","Specialized Tools"],"sub_categories":["文本处理","For Python","Uncategorized","Text Processing","Text/NLP"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaviddrysdale%2Fpython-phonenumbers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaviddrysdale%2Fpython-phonenumbers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaviddrysdale%2Fpython-phonenumbers/lists"}