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
The latest version of django-locality is currently not available on PyPi
Install from GitHub with pip:
pip install -e git+https://github.com/naftulikay/django-locality.git#egg=django-locality==0.2.4
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.
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')
Please report all bugs to the GitHub issue tracker, and enjoy the library :-)
Wishlist:
- template tags
- translated country names (see issue #1)
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.
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.