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')