The PhoneNumber wrapperο
- class phonenumber_field.phonenumber.PhoneNumberο
A extended version of phonenumbers.PhoneNumber that provides some neat and more pythonic, easy to access methods. This makes using a PhoneNumber instance much easier, especially in templates and such.
- classmethod from_string(phone_number, region=None)ο
- Parameters:
region (str) β 2-letter country code as defined in ISO 3166-1. When not supplied, defaults to
PHONENUMBER_DEFAULT_REGION
- is_valid()ο
Whether the number supplied is actually valid.
- Returns:
True
when the phone number is valid.- Return type:
- property as_internationalο
- property as_nationalο
- property as_e164ο
- property as_rfc3966ο
Usageο
>>> from phonenumber_field.phonenumber import PhoneNumber
>>> number = PhoneNumber.from_string("+16044011234")
>>> print(number.as_national)
(604) 401-1234
>>> print(number.as_e164)
+16044011234
>>> print(number.as_international)
+1 604-401-1234
>>> print(number.as_rfc3966)
tel:+1-604-401-1234
# Using national numbers with the region keyword argument.
>>> canadian_number = "(604) 401 1234"
>>> number = PhoneNumber.from_string(canadian_number, region="CA")
>>> print(number.as_e164)
+16044011234
Model fieldο
The PhoneNumberField
model field allows storing
PhoneNumber
s in the database, based
on a CharField
.
The phone number format used by the database is controlled with
PHONENUMBER_DB_FORMAT
. When no region is specified, a phone number
in the "NATIONAL"
format will be assumed to be from the
PHONENUMBER_DEFAULT_REGION
.
The default form field for this field is the
PhoneNumberField
.The default form widget for this field is the
RegionalPhoneNumberWidget
.
- class phonenumber_field.modelfields.PhoneNumberField(*args, region=None, **kwargs)ο
- __init__(*args, region=None, **kwargs)ο
- Parameters:
region (str) β 2-letter country code as defined in ISO 3166-1. When not supplied, defaults to
PHONENUMBER_DEFAULT_REGION
max_length (int) β The maximum length of the underlying char field.
Usageο
from django.db import models
from phonenumber_field.modelfields import PhoneNumberField
class Customer(models.Model):
name = models.TextField()
# An optional phone number.
phone_number = PhoneNumberField(blank=True)
Form fieldο
The PhoneNumberField
form field to validate
PhoneNumber
, based on a
CharField
.
Default widget:
RegionalPhoneNumberWidget
Empty value:
""
Normalizes to: A
PhoneNumber
or an emptystr
(""
)
- class phonenumber_field.formfields.PhoneNumberField(*args, region=None, widget=None, **kwargs)ο
- __init__(*args, region=None, widget=None, **kwargs)ο
- Parameters:
region (str) β 2-letter country code as defined in ISO 3166-1. When not supplied, defaults to
PHONENUMBER_DEFAULT_REGION
widget (django.forms.Widget) β defaults to
RegionalPhoneNumberWidget
Usageο
>>> from django import forms
>>> from phonenumber_field.formfields import PhoneNumberField
>>> class PhoneForm(forms.Form):
... number = PhoneNumberField(region="CA")
...
# Manipulating data
>>> form = PhoneForm({"number": "+1 604 401 1234"})
>>> form.is_valid()
True
>>> form.cleaned_data
{'number': PhoneNumber(country_code=1, national_number=6044011234, extension=None, italian_leading_zero=None, number_of_leading_zeros=None, country_code_source=1, preferred_domestic_carrier_code=None)}
>>> print_html(form.as_div())
<div>
<label for="id_number">
Number:
</label>
<input id="id_number" name="number" required="" type="tel" value="(604) 401-1234"/>
</div>
# Handling errors
>>> form = PhoneForm({"number": "invalid"})
>>> form.is_valid()
False
>>> print_html(form.as_div())
<div>
<label for="id_number">
Number:
</label>
<ul class="errorlist">
<li>
Enter a valid phone number (e.g. (506) 234-5678) or a number with an international call prefix.
</li>
</ul>
<input id="id_number" name="number" required="" type="tel" value="invalid"/>
</div>
Note
Because the PhoneNumberField specifies a region, the example number is a national number from that region. When no region is specified, an international example phone number in the E.164 format is suggested.
Widgetsο
RegionalPhoneNumberWidgetο
Default widget for PhoneNumberField
.
input_type:
tel
Renders as
<input type="tel" β¦ >
Important
The region should be specified (either per field using the
region
keyword argument, or with the
PHONENUMBER_DEFAULT_REGION
setting) in order to know which
national number format to recognize.
- class phonenumber_field.widgets.RegionalPhoneNumberWidget(region=None, attrs=None)ο
A
Widget
that prefers displaying numbers in the national format, and falls back toPHONENUMBER_DEFAULT_FORMAT
for international numbers.- __init__(region=None, attrs=None)ο
- Parameters:
region (str) β 2-letter country code as defined in ISO 3166-1. When not supplied, defaults to
PHONENUMBER_DEFAULT_REGION
attrs (dict) β See
django.forms.Widget.attrs
Usageο
>>> from django import forms
>>> from phonenumber_field.formfields import PhoneNumberField
>>> class CanadianPhoneForm(forms.Form):
... # RegionalPhoneNumberWidget is the default widget.
... number = PhoneNumberField(region="CA")
...
# Using the national format for the fieldβs region.
>>> form = CanadianPhoneForm({"number": "+16044011234"})
>>> print_html(form.as_div())
<div>
<label for="id_number">
Number:
</label>
<input id="id_number" name="number" required="" type="tel" value="(604) 401-1234"/>
</div>
# Using E164 for an international number.
>>> french_number = "+33612345678"
>>> form = CanadianPhoneForm({"number": french_number})
>>> print_html(form.as_div())
<div>
<label for="id_number">
Number:
</label>
<input id="id_number" name="number" required="" type="tel" value="+33612345678"/>
</div>
PhoneNumberPrefixWidgetο
Important
Requires the Babel package be installed.
- class phonenumber_field.widgets.PhoneNumberPrefixWidget(attrs=None, initial=None, country_attrs=None, country_choices=None, number_attrs=None)ο
A Widget that splits a phone number into fields:
- __init__(attrs=None, initial=None, country_attrs=None, country_choices=None, number_attrs=None)ο
Usageο
>>> from django import forms
>>> from phonenumber_field.formfields import PhoneNumberField
>>> from phonenumber_field.widgets import PhoneNumberPrefixWidget
# Limiting country choices.
>>> class CanadianPhoneForm(forms.Form):
... # RegionalPhoneNumberWidget is the default widget.
... number = PhoneNumberField(
... region="CA",
... widget=PhoneNumberPrefixWidget(
... country_choices=[
... ("CA", "Canada"),
... ("FR", "France"),
... ],
... ),
... )
...
>>> form = CanadianPhoneForm({"number_0": "CA", "number_1": "6044011234"})
>>> print_html(form.as_div())
<div>
<fieldset>
<legend>
Number:
</legend>
<select id="id_number_0" name="number_0" required="">
<option selected="" value="CA">
Canada
</option>
<option value="FR">
France
</option>
</select>
<input id="id_number_1" name="number_1" required="" type="text" value="6044011234"/>
</fieldset>
</div>
# Pre-selecting a country.
>>> class FrenchPhoneForm(forms.Form):
... # RegionalPhoneNumberWidget is the default widget.
... number = PhoneNumberField(
... region="FR",
... widget=PhoneNumberPrefixWidget(
... initial="FR",
... country_choices=[
... ("CA", "Canada"),
... ("FR", "France"),
... ],
... ),
... )
...
>>> form = FrenchPhoneForm()
>>> print_html(form.as_div())
<div>
<fieldset>
<legend>
Number:
</legend>
<select id="id_number_0" name="number_0" required="">
<option value="CA">
Canada
</option>
<option selected="" value="FR">
France
</option>
</select>
<input id="id_number_1" name="number_1" required="" type="text"/>
</fieldset>
</div>
Serializer fieldο
The PhoneNumberField
serializer
field, based on the
CharField.
The serialization format is controlled by the
PHONENUMBER_DEFAULT_FORMAT
.
- class phonenumber_field.serializerfields.PhoneNumberField(*args, **kwargs)ο
- __init__(*args, region=None, **kwargs)ο
- Parameters:
region (str) β 2-letter country code as defined in ISO 3166-1. When not supplied, defaults to
PHONENUMBER_DEFAULT_REGION
Usageο
>>> from django.conf import settings
>>> from rest_framework import renderers, serializers
>>> from phonenumber_field.serializerfields import PhoneNumberField
>>> class PhoneNumberSerializer(serializers.Serializer):
... number = PhoneNumberField(region="CA")
...
>>> serializer = PhoneNumberSerializer(data={"number": "604 401 1234"})
>>> serializer.is_valid()
True
>>> serializer.validated_data
OrderedDict([('number', PhoneNumber(country_code=1, national_number=6044011234, extension=None, italian_leading_zero=None, number_of_leading_zeros=None, country_code_source=20, preferred_domestic_carrier_code=None))])
# Using the PHONENUMBER_DEFAULT_FORMAT.
>>> renderers.JSONRenderer().render(serializer.data)
b'{"number":"+16044011234"}'
Validatorο
Validates:
a
PhoneNumber
instance, oran
str
in an international format (with a prefix), oran
str
thatβs a local phone number according toPHONENUMBER_DEFAULT_REGION
.
Note
Not all well-formed phone numbers are valid. The rules to construct phone numbers vary per region of the world.
Falsehoods Programmers Believe About Phone Numbers is a good read.
- phonenumber_field.validators.validate_international_phonenumber(value)ο
code: "invalid_phone_number"
Settingsο
PHONENUMBER_DB_FORMAT
ο
Store phone numbers strings in the specified format.
Default: "E164"
.
Choices:
"E164"
(public international numbers),"INTERNATIONAL"
(international numbers, possibly with phone extensions),"RFC3966"
(international numbers, possibly with phone extensions),"NATIONAL"
(discouraged, 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"
(no support of phone extensions),"INTERNATIONAL"
,"RFC3966"
,"NATIONAL"
(discouraged, fails to represent international phone numbers).