Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

Lightweight model and form field for phone numbers in Django

Project description

# django-phone-field
Lightweight model and form field for phone numbers in Django

* View and edit phone numbers in forms and the Django admin in pretty format: `(415) 123-4567`
* Store all phone numbers canonically in the database for easy searching & uniqueness: `+14151234567`
* Built-in support for simple extensions: `(415) 123-4567, press 88`
* Doesn't choke on international numbers (but doesn't format them, either)
* Automatically format phone numbers in templates

This package is simple, lightweight, and without dependencies. However, it doesn't attempt to solve fancy
problems or deal with international phone numbers. For a full-featured phone number package, take a look at
[`django-phonenumber-field`](https://github.com/stefanfoulis/django-phonenumber-field).

## Installation

This package is designed for Python 3 and Django 1.10+. Install via:

```
pip install django-phone-field
```

Then add `'phone_field'` to your `INSTALLED_APPS` setting.

## Usage

In your `models.py`:

```
from django.db import models
from phone_field import PhoneField


class MyModel(models.Model):
name = models.CharField(max_length=128)
phone = PhoneField(blank=True, help_text='Contact phone number')
```

`PhoneField` accepts standard options for a Django `CharField`. By default it sets `max_length=31`. Feel
free to override this, set `blank=True`, etc. as you would otherwise.

There is one special argument, `E164_only=False`, which adds a form validator to only accept numbers in
the E164 format (currently, only supported for US phone numbers).

In your template:

```
User {{ obj.name }} has phone number {{ obj.phone }}
```

Result:

```
User Ted has phone number (415) 123-1233
```

## Database representation

`PhoneField` attempts to coerce all phone numbers to the following format:

```
+[country code][number]x[extension]
+12223334444x55
```

where the extension part is optional. If the input phone number can't be coerced to this
format, `PhoneField` gives up and simply stores it as-is.

Because all phone numbers are stored without formatting, you can set this field to be unique
on a Django model and it will actually work.

## Extras

Use the `|phone` template filter to attempt to display a formatted phone number from arbitrary text. Use
the `|raw_phone` template filter to display the raw, un-formatted value.

Use property `.is_E164` to check if a PhoneNumber object is in E164 format.

Also provided are `.is_standard` (E164 but with extensions allowed) and `.is_usa`.

Project details


Release history Release notifications

This version
History Node

1.5.4

History Node

1.5.3

History Node

1.5.2

History Node

1.5.1

History Node

1.5.0

History Node

1.4.0

History Node

1.3.0

History Node

1.0.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
django_phone_field-1.5.4-py3-none-any.whl (9.3 kB) Copy SHA256 hash SHA256 Wheel py3 Feb 23, 2018
django-phone-field-1.5.4.tar.gz (19.5 kB) Copy SHA256 hash SHA256 Source None Feb 23, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page