Skip to content

Latest commit

 

History

History
425 lines (316 loc) · 13.1 KB

reference.rst

File metadata and controls

425 lines (316 loc) · 13.1 KB
Raw

import django from bs4 import BeautifulSoup

django.setup()

def print_html(html):

print(BeautifulSoup(html).prettify().strip())

The PhoneNumber wrapper

phonenumber_field.phonenumber.PhoneNumber()

phonenumber_field.phonenumber.PhoneNumber.from_string

phonenumber_field.phonenumber.PhoneNumber.is_valid

phonenumber_field.phonenumber.PhoneNumber.as_international

phonenumber_field.phonenumber.PhoneNumber.as_national

phonenumber_field.phonenumber.PhoneNumber.as_e164

phonenumber_field.phonenumber.PhoneNumber.as_rfc3966

Usage

wrapper

>>> 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 ~phonenumber_field.modelfields.PhoneNumberField model field <topics/db/models:fields> allows storing ~phonenumber_field.phonenumber.PhoneNumbers in the database, based on a ~django.db.models.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 <ref/forms/fields:form fields> for this field is the ~phonenumber_field.formfields.PhoneNumberField.
  • The default form widget <ref/forms/widgets:widgets> for this field is the ~phonenumber_field.widgets.RegionalPhoneNumberWidget.

phonenumber_field.modelfields.PhoneNumberField

__init__

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 ~phonenumber_field.formfields.PhoneNumberField form field <ref/forms/fields:form fields> to validate ~phonenumber_field.phonenumber.PhoneNumber, based on a ~django.forms.CharField.

  • Default widget: ~phonenumber_field.widgets.RegionalPhoneNumberWidget
  • Empty value: ""
  • Normalizes to: A ~phonenumber_field.phonenumber.PhoneNumber or an empty str ("")
  • Uses ~phonenumber_field.validators.validate_international_phonenumber

phonenumber_field.formfields.PhoneNumberField

__init__

Usage

formfield

>>> 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 aria-invalid="true" 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 ~phonenumber_field.formfields.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.

phonenumber_field.widgets.RegionalPhoneNumberWidget

__init__

Usage

fallbackwidget

>>> 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.

phonenumber_field.widgets.PhoneNumberPrefixWidget

__init__

Usage

prefixwidget

>>> 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 ~phonenumber_field.serializersfields.PhoneNumberField serializer field, based on the CharField.

The serialization format is controlled by the PHONENUMBER_DEFAULT_FORMAT.

phonenumber_field.serializerfields.PhoneNumberField

__init__

Usage

serializerfield

>>> 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_field.phonenumber.PhoneNumber instance, or
  • an str in an international format (with a prefix), or
  • an str that’s a local phone number according to PHONENUMBER_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

code: "invalid_phone_number"

Settings

Phone number format choices

Setting value International Extensions Notes
"E164" (default) ✓ ❌ | https://en.wikipedia.org/wiki/E.164
"INTERNATIONAL" ✓ ✓ https://en.wikipedia.org/wiki/E.123#Telephone_number
"RFC3966" ✓ ✓ https://www.rfc-editor.org/rfc/rfc3966.html
"NATIONAL" ❌ | ✓ | DISCOURAGED, requires PHONENUMBER_DEFAULT_REGION

Warning

By default, the library uses E.164, the international public telecommunication numbering plan, which does not support phone numbers extensions. Set both PHONENUMBER_DB_FORMAT and PHONENUMBER_DEFAULT_FORMAT to an extension-compatible format to handle phone numbers extensions.

PHONENUMBER_DB_FORMAT

PHONENUMBER_DB_FORMAT

Store phone numbers strings in the specified format in the database.

Default: "E164".

See settings-format-choices.

Warning

Data loss may occur when changing the DB format.

Phone numbers stored in the database are parsed every time they are loaded from the database.

When switching from a format that can represent extensions to a format that cannot, the extension information is definitely lost.

When using PHONENUMBER_DB_FORMAT="NATIONAL", changing the PHONENUMBER_DEFAULT_REGION will cause phone numbers stored in the database to be interpreted differently, resulting in data corruption.

PHONENUMBER_DEFAULT_FORMAT

PHONENUMBER_DEFAULT_FORMAT

String formatting of phone numbers.

Default: "E164".

See settings-format-choices.

PHONENUMBER_DEFAULT_REGION

PHONENUMBER_DEFAULT_REGION

ISO-3166-1 two-letter country code indicating how to interpret regional phone numbers.

Default: None.