Populating the database

Data install or update

Populate your database with command:

./manage.py cities_light

By default, this command attempts to do the least work possible, update what is necessary only. If you want to disable all these optimisations/skips, use –force-all.

This command is well documented, consult the help with:

./manage.py help cities_light


Signals for this application.


Emited by city_import() in the cities_light command for each row parsed in the data file. If a signal reciever raises InvalidItems then it will be skipped.

An example is worth 1000 words: if you want to import only cities from France, USA and Belgium you could do as such:

import cities_light

def filter_city_import(sender, items, **kwargs):
    if items[8] not in ('FR', 'US', 'BE'):
        raise cities_light.InvalidItems()


Note: this signal gets a list rather than a City instance for performance reasons.


Same as city_items_pre_import.


Same as region_items_pre_import and cities_light.signals.city_items_pre_import.


Emited by city_import() in the cities_light command for each row parsed in the data file, right before saving City object. Along with City instance it pass items with geonames data. Will be useful, if you define custom cities models with settings.CITIES_LIGHT_APP_NAME.


import cities_light

def process_city_import(sender, instance, items, **kwargs):
    instance.timezone = items[17]


Same as city_items_post_import.


Same as region_items_post_import and cities_light.signals.city_items_post_import.

exception cities_light.exceptions.CitiesLightException[source]

Base exception class for this app’s exceptions.

exception cities_light.exceptions.InvalidItems[source]

The cities_light command will skip item if a city_items_pre_import signal reciever raises this exception.

exception cities_light.exceptions.SourceFileDoesNotExist(source)[source]

A source file could not be found.

Configure logging

This command is made to be compatible with background usage like from cron, to keep the database fresh. So it doesn’t do direct output. To get output from this command, simply configure a handler and formatter for cities_light logger. For example:

    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'simple': {
            'format': '%(levelname)s %(message)s'
    'handlers': {
            'formatter': 'simple'
    'loggers': {
        'cities_light': {
            'propagate': True,
        # also use this one to see SQL queries
        'django': {
            'propagate': True,