django-phonenumber-field
A Django library which interfaces with python-phonenumbers to validate, pretty print and convert phone numbers. python-phonenumbers
is a port of Google's libphonenumber library, which powers Android's phone number handling.
Included are:
PhoneNumber
, a pythonic wrapper aroundpython-phonenumbers
'PhoneNumber
classPhoneNumberField
, a model fieldPhoneNumberField
, a form fieldPhoneNumberField
, a serializer fieldPhoneNumberPrefixWidget
, a form widget for selecting a region code and entering a national number. Requires the Babel package be installed.PhoneNumberInternationalFallbackWidget
, a form widget that uses national numbers unless an international number is entered. APHONENUMBER_DEFAULT_REGION
setting needs to be added to your Django settings in order to know which national number format to recognize.
Installation
pip install django-phonenumber-field[phonenumbers]
As an alternative to the phonenumbers
package, it is possible to install the phonenumberslite
package which has a lower memory footprint.
pip install django-phonenumber-field[phonenumberslite]
Basic usage
First, add phonenumber_field
to the list of the installed apps in your settings.py
file:
INSTALLED_APPS = [ ... 'phonenumber_field', ... ]
Then, you can use it like any regular model field:
from phonenumber_field.modelfields import PhoneNumberField class MyModel(models.Model): name = models.CharField(max_length=255) phone_number = PhoneNumberField() fax_number = PhoneNumberField(blank=True)
Internally, PhoneNumberField is based upon CharField
and by default represents the number as a string of an international phonenumber in the database (e.g '+41524204242'
).
The object returned is a PhoneNumber instance, not a string. If strings are used to initialize it, e.g. via MyModel(phone_number='+41524204242')
or form handling, it has to be a phone number with country code.
Settings
PHONENUMBER_DB_FORMAT
Store phone numbers strings in the specified format.
Default: "E164"
.
Choices:
"E164"
,"INTERNATIONAL"
,"NATIONAL"
(requiresPHONENUMBER_DEFAULT_REGION
),"RFC3966"
(requiresPHONENUMBER_DEFAULT_REGION
).
PHONENUMBER_DEFAULT_REGION
ISO-3166-1 two-letter country code indicating how to interpret regional phone numbers.
Default: None
.
PHONENUMBER_DEFAULT_FORMAT
String formatting of phone numbers.
Default: "E164"
.
Choices:
"E164"
,"INTERNATIONAL"
,"NATIONAL"
,"RFC3966"
.
Running tests
tox needs to be installed. To run the whole test matrix with the locally available Python interpreters and generate a combined coverage report:
tox
run a specific combination:
tox -e py36-djmain,py39-djmain