django-locality

django-locality is a collection of helpers for handling countries and territories in Django. Currently, it includes:

• locality.json, a fixture with the world's countries and territories (if you notice any missing, open an issue or submit a pull request)
• views for getting serialized values (e.g. for use in a form)
• nifty form fields and widgets

Installation

The latest version of django-locality is currently not available on PyPi

Install from GitHub with pip:

pip install -e git+https://github.com/rfkrocktk/django-locality.git#egg=django-locality==0.2.2

Then add locality to INSTALLED_APPS in your Django settings. To load the included data, run:

python manage.py loaddata locality

(or whichever equivalent method you use to run "manage.py" commands)

The fixture is not installed as initial_data.json to give you the option of using your own, and to prevent changes being overwritten whenever you run syncdb.

Usage

List all countries:

>>> from locality.models import Country
>>> print Country.objects.all()
[<Country: Andorra>, <Country: United Arab Emirates>, 
<Country: Antigua and Barbuda>, ...]

or list territories by country:

>>> from locality.models import Country
>>> for country in locality.models.Country.objects.all():
>>>     print country.territories.all()
...
[<Territory: Salta, Argentina>, <Territory: Buenos Aires, Argentina>,
<Territory: Ciudad Autónoma de Buen os Aires, Argentina>, ...]

You can create your own models around countries and territories:

class Address(models.Model):
    country = models.ForeignKey('locality.models.Country')
    territory = models.ForeignKey('locality.models.Territory')

Bugs / TODO

Please report all bugs to the GitHub issue tracker, and enjoy the library :-)

Wishlist:

• template tags
• translated country names (see issue #1)

MySQL issues

You will have issues loading fixture data with MySQL if your database's default character set is not utf8. You can check your tables' charsets by running:

SHOW FULL COLUMNS tablename;

You can alter the charsets via:

ALTER TABLE tablename CONVERT TO CHARACTER SET utf8;

To do this for django-locality, you can first sync the database, alter the character set for the resulting tables, and then load the fixtures.

Upgrading from previous versions

django-locality used to create a locality_country table with a too-small name field, and does not (yet) include database migrations. If you were previously using an earlier version and encounter errors when trying to load locality.json, try deleting and recreating the relevant tables:

$ python manage.py dbshell
MariaDB [awesomeproj]> DROP TABLE locality_territory;
Query OK, 0 rows affected (0.01 sec)

MariaDB [awesomeproj]> DROP TABLE locality_country;
Query OK, 0 rows affected (0.01 sec)

MariaDB [awesomeproj]> exit
Bye
$ python manage.py syncdb

and then attempt to load the fixture again.