Usage

There are three models Address, PhoneNumber and Email which all present essentially the same API.

For the examples below let’s assume you have the following model;

# models.py

from django.db import models
from django_teledex.fields import AddressRelation, PhoneNumberRelation, EmailRelation


class Company(models.Model):
    title = models.CharField(max_length=100)
    addresses = AddressRelation('companies')
    phonenumbers = PhoneNumberRelation('companies')
    emails = EmailRelation('companies')

Address

If you want to add an address you can then do the following;

from django_teledex.models import Address
from django_teledex.choices import AddressKind


company = Company.objects.create(title='Evelyn Hotel')

address = Address.objects.create(
    organisation=company.title,
    kind=AddressKind.physical,
    owner=company,
    address_line='351 Brunswick St',
    locality='Fitzroy',
    region='VIC',
    postcode='3065',
    country='AU',
)

company.addresses.all() # returns all addresses for company
company.addresses.active() # all active addresses

# Make an address inactive
address.deactivate()

company.addresses.inactive() # all inactive addresses
company.addresses.kind(AddressKind.physical) # get addresses by kind
company.addresses.filter(postcode=3065) # filter works as you'd expect...

# Make an address active
address.activate()

A complete list of QuerySet methods available on Address.objects is available in django_teledex.models.AddressQuerySet.

PhoneNumber

The PhoneNumber model behaves in pretty much the same way, for example;

from django_teledex.models import PhoneNumber
from django_teledex.choices import PhoneNumberKind

company = Company.objects.create(title='Evelyn Hotel')

phonenumber = PhoneNumber.objects.create(
    kind=PhoneNumberKind.mobile,
    owner=company,
    number='+61 3 9419 5500'
)

company.phonenumbers.all() # returns all phone numbers for company
company.phonenumbers.active() # all active phone numbers

# Make an phone number inactive
phonenumber.deactivate()

company.phonenumbers.inactive() # all inactive addresses
company.phonenumbers.kind(PhoneNumberKind.mobile) # by kind
company.phonenumbers.filter(kind=PhoneNumberKind.mobile) # filter works as you'd expect...

# Make an phone number active
phonenumber.activate()

A complete list of QuerySet methods available on PhoneNumber.objects is available in django_teledex.models.PhoneNumberQuerySet.

Validation

PhoneNumber is a PhoneNumberField which comes from django-phonenumber-field which;

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

You’ll probably want to look into the above to get familiar with how they are useful to your project.

Email

The Email model also behaves in pretty much the same way, for example;

from django_teledex.models import Email
from django_teledex.choices import EmailKind

company = Company.objects.create(title='Evelyn Hotel')

email = Email.objects.create(
    kind=EmailKind.work,
    owner=company,
    email='guys@example.com'
)

company.emails.all() # returns all phone numbers for company
company.emails.active() # all active phone numbers

# Make an phone number inactive
email.deactivate()

company.emails.inactive() # all inactive addresses
company.emails.kind(EmailKind.work) # by kind
company.emails.filter(email__icontains='guys@') # filter works as you'd expect...

# Make an phone number active
email.activate()

A complete list of QuerySet methods available on Email.objects is available in django_teledex.models.EmailQuerySet.

Reverse Relations

You can also traverse back from an Address, PhoneNumber or Email to the owner, in this case the Company - all thanks to Django’s reverse generic relations.

django_teledex.fields.AddressRelation, django_teledex.fields.PhoneNumberRelation and django_teledex.fields.EmailRelation are simply helper classes that inherit from GenericRelation that set some defaults.

The first, and only required, argument to each of the *Relation classes is the related_query_name used by the GenericRelation which django_teledex.fields.AddressRelation, django_teledex.fields.PhoneNumberRelation and django_teledex.fields.EmailRelation inherit from. In the Company model above it’s set to companies.

Thus;

# Reverse relations
Address.objects.filter(companies__title='Evelyn Hotel')