A Django app for l10n of postal addresses.
Project description
django-postal
============
A django application that provides a location agnostic model for postal addresses.
The motivation behind this project is that most countries have different forms of
postal addresses e.g. http://www.bitboost.com/ref/international-address-formats.html ,
http://en.wikipedia.org/wiki/Address_%28geography%29
This app assumes that all postal addresses worldwide can be made up of 5 optional
address lines plus a country code.
It then localizes the title of each line dependant on the country selected.
Further information on each address line can be gleaned from
django.contrib.localflavor fields and widgets e.g. for the UK
from django import forms
from django.utils.translation import ugettext_lazy as _
from django.contrib.localflavor.uk.forms import UKPostcodeField, UKCountySelect
from postal.forms import PostalAddressForm
class GBPostalAddressForm(PostalAddressForm):
line1 = forms.CharField(label=_(u"Company name"), required=False, max_length=50)
line2 = forms.CharField(label=_(u"Street"), max_length=50)
city = forms.CharField(label=_(u"Town"), max_length=50)
state = forms.CharField(label=_(u"County"), widget=UKCountySelect, max_length=50)
code = UKPostcodeField(label=_(u"Postcode"))
It is hoped that various contributors will contribute address formats per country
and that eventually this address information could find it's way back in to
django.contrib.localflavor
Dependencies
============
django-countries (http://code.google.com/p/django-countries/)
Developers, How to Contribute
==========
$ git clone git@github.com:mthornhill/django-postal.git
$ cd django-postal
$ virtualenv . --no-site-packages
$ source bin/activate
$ python bootstrap.py
$ bin/buildout -v
$ bin/django syncdb
$ bin/test
$ bin/django runserver
browse to http://localhost:8000
new countries can be added to the src/postal folder by their
2 letter country code e.g. us
Each country folder contains an __init__.py and a forms.py
forms.py contains the localized address
Usage
=====
1. Add django-countries and django-postal to your INSTALLED_APPS in settings.py
e.g.
INSTALLED_APPS = (
"countries",
"postal",
...
)
2. In your view code import the code for getting a localized postal address
views.py
from postal.library import get_postal_form_class
form_class = get_postal_form_class("us")
postal_form = form_class()
3. Add postal_form to your templates
some_template.html
{{postal_form}}
4. In this case we will have a US postal form
How to use localized addresses
==============================
Address localisation is turned on by default.
To turn off Address l10n: in settings.py set
::
POSTAL_ADDRESS_L10N = False
Customize address labels and requirement
----------------------------------------
If you wish to customize the address labels and whether the address line is
required or not, you can add the following variables to settings.py
::
POSTAL_ADDRESS_LINE1, POSTAL_ADDRESS_LINE2, POSTAL_ADDRESS_CITY, POSTAL_ADDRESS_STATE, POSTAL_ADDRESS_CODE
each of these variables is set to a tuple of the format ('label', True/False)
'label' is used to label the field, and the second boolean value sets whether
the field is required or not, e.g.
::
POSTAL_ADDRESS_LINE1 = ("Department", True)
TODO
====
1. Create method of allowning third party app to register a localized postal form
a) Registry match with regular expressions cf urls.py
b) admin site approach
2. Templatetag for modifying a form in a template
e.g. {{postal_form|localize:country_code}}
BUILD HISTORY
=============
0.4
Don't enforce uniqueness on postal addresses
============
A django application that provides a location agnostic model for postal addresses.
The motivation behind this project is that most countries have different forms of
postal addresses e.g. http://www.bitboost.com/ref/international-address-formats.html ,
http://en.wikipedia.org/wiki/Address_%28geography%29
This app assumes that all postal addresses worldwide can be made up of 5 optional
address lines plus a country code.
It then localizes the title of each line dependant on the country selected.
Further information on each address line can be gleaned from
django.contrib.localflavor fields and widgets e.g. for the UK
from django import forms
from django.utils.translation import ugettext_lazy as _
from django.contrib.localflavor.uk.forms import UKPostcodeField, UKCountySelect
from postal.forms import PostalAddressForm
class GBPostalAddressForm(PostalAddressForm):
line1 = forms.CharField(label=_(u"Company name"), required=False, max_length=50)
line2 = forms.CharField(label=_(u"Street"), max_length=50)
city = forms.CharField(label=_(u"Town"), max_length=50)
state = forms.CharField(label=_(u"County"), widget=UKCountySelect, max_length=50)
code = UKPostcodeField(label=_(u"Postcode"))
It is hoped that various contributors will contribute address formats per country
and that eventually this address information could find it's way back in to
django.contrib.localflavor
Dependencies
============
django-countries (http://code.google.com/p/django-countries/)
Developers, How to Contribute
==========
$ git clone git@github.com:mthornhill/django-postal.git
$ cd django-postal
$ virtualenv . --no-site-packages
$ source bin/activate
$ python bootstrap.py
$ bin/buildout -v
$ bin/django syncdb
$ bin/test
$ bin/django runserver
browse to http://localhost:8000
new countries can be added to the src/postal folder by their
2 letter country code e.g. us
Each country folder contains an __init__.py and a forms.py
forms.py contains the localized address
Usage
=====
1. Add django-countries and django-postal to your INSTALLED_APPS in settings.py
e.g.
INSTALLED_APPS = (
"countries",
"postal",
...
)
2. In your view code import the code for getting a localized postal address
views.py
from postal.library import get_postal_form_class
form_class = get_postal_form_class("us")
postal_form = form_class()
3. Add postal_form to your templates
some_template.html
{{postal_form}}
4. In this case we will have a US postal form
How to use localized addresses
==============================
Address localisation is turned on by default.
To turn off Address l10n: in settings.py set
::
POSTAL_ADDRESS_L10N = False
Customize address labels and requirement
----------------------------------------
If you wish to customize the address labels and whether the address line is
required or not, you can add the following variables to settings.py
::
POSTAL_ADDRESS_LINE1, POSTAL_ADDRESS_LINE2, POSTAL_ADDRESS_CITY, POSTAL_ADDRESS_STATE, POSTAL_ADDRESS_CODE
each of these variables is set to a tuple of the format ('label', True/False)
'label' is used to label the field, and the second boolean value sets whether
the field is required or not, e.g.
::
POSTAL_ADDRESS_LINE1 = ("Department", True)
TODO
====
1. Create method of allowning third party app to register a localized postal form
a) Registry match with regular expressions cf urls.py
b) admin site approach
2. Templatetag for modifying a form in a template
e.g. {{postal_form|localize:country_code}}
BUILD HISTORY
=============
0.4
Don't enforce uniqueness on postal addresses
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
django-postal-0.5.1.tar.gz
(8.7 kB
view hashes)