Simple django app

Settings

Settings for this application. The most important is TRANSLATION_LANGUAGES because it’s probably project specific.

cities_light.settings.TRANSLATION_LANGUAGES

List of language codes. It is used to generate the alternate_names property of cities_light models. You want to keep it as small as possible. By default, it includes the most popular languages according to wikipedia, which use a rather ascii-compatible alphabet. It also contains ‘abbr’ which stands for ‘abbreviation’, you might want to include this one as well.

See:

Example:

CITIES_LIGHT_TRANSLATION_LANGUAGES = ['es', 'en', 'fr', 'abbr']
cities_light.settings.INCLUDE_COUNTRIES

List of country codes to include. It’s None by default which lets all countries in the database. But if you only wanted French and Belgium countries/regions/cities, you could set it as such:

CITIES_LIGHT_INCLUDE_COUNTRIES = ['FR', 'BE']
cities_light.settings.INCLUDE_CITY_TYPES

List of city feature codes to include. They are described at http://www.geonames.org/export/codes.html, section “P city, village”.

CITIES_LIGHT_INCLUDE_CITY_TYPES = [
‘PPL’, ‘PPLA’, ‘PPLA2’, ‘PPLA3’, ‘PPLA4’, ‘PPLC’, ‘PPLF’, ‘PPLG’, ‘PPLL’, ‘PPLR’, ‘PPLS’, ‘STLMT’,

]

cities_light.settings.COUNTRY_SOURCES

A list of urls to download country info from. Default is countryInfo.txt from geonames download server. Overridable in settings.CITIES_LIGHT_COUNTRY_SOURCES.

cities_light.settings.REGION_SOURCES

A list of urls to download region info from. Default is admin1CodesASCII.txt from geonames download server. Overridable in settings.CITIES_LIGHT_REGION_SOURCES.

cities_light.settings.CITY_SOURCES

A list of urls to download city info from. Default is cities15000.zip from geonames download server. Overridable in settings.CITIES_LIGHT_CITY_SOURCES.

cities_light.settings.TRANSLATION_SOURCES

A list of urls to download alternate names info from. Default is alternateNames.zip from geonames download server. Overridable in settings.CITIES_LIGHT_TRANSLATION_SOURCES.

cities_light.settings.SOURCES

A list with all sources, auto-generated.

cities_light.settings.DATA_DIR

Absolute path to download and extract data into. Default is cities_light/data. Overridable in settings.CITIES_LIGHT_DATA_DIR

cities_light.settings.INDEX_SEARCH_NAMES

If your database engine for cities_light supports indexing TextFields (ie. it is not MySQL), then this should be set to True. You might have to override this setting with settings.CITIES_LIGHT_INDEX_SEARCH_NAMES if using several databases for your project.

cities_light.settings.CITIES_LIGHT_APP_NAME

Modify it only if you want to define your custom cities models, that are inherited from abstract models of this package. It must be equal to app name, where custom models are defined. For example, if they are in geo/models.py, then set settings.CITIES_LIGHT_APP_NAME = 'geo'. Note: you can’t define one custom model, you have to define all of cities_light models, even if you want to modify only one.

class cities_light.settings.ICountry[source]

Country field indexes in geonames.

class cities_light.settings.IRegion[source]

Region field indexes in geonames.

class cities_light.settings.ICity[source]

City field indexes in geonames. Description of fields: http://download.geonames.org/export/dump/readme.txt

class cities_light.settings.IAlternate[source]

Alternate names field indexes in geonames. Description of fields: http://download.geonames.org/export/dump/readme.txt

Models

See source for details.

By default, all models are taken from this package. But it is possible to customise these models to add some fields. For such purpose cities_light models are defined as abstract (without customisation they all inherit abstract versions automatically without changes).

Steps to customise cities_light models

  • Define all of cities abstract models in your app:
    # yourapp/models.py
    
    from cities_light.abstract_models import (AbstractCity, AbstractRegion,
        AbstractCountry)
    from cities_light.receivers import connect_default_signals
    
    
    class Country(AbstractCountry):
        pass
    connect_default_signals(Country)
    
    class Region(AbstractRegion):
        pass
    connect_default_signals(Region)
    
    
    class City(AbstractCity):
        timezone = models.CharField(max_length=40)
    connect_default_signals(City)
    
  • Add post import processing to you model [optional]:
    import cities_light
    from cities_light.settings import ICity
    
    def set_city_fields(sender, instance, items, **kwargs):
        instance.timezone = items[ICity.timezone]
    cities_light.signals.city_items_post_import.connect(set_city_fields)
    
  • Define settings.py:
    INSTALLED_APPS = [
        # ...
        'cities_light',
        'yourapp',
    ]
    
    CITIES_LIGHT_APP_NAME = 'yourapp'
    
  • Create tables:
    python manage.py syncdb
    

That’s all!

Notes:
  • model names can’t be modified, i.e. you have to use exactly City, Country, Region names and not MyCity, MyCountry, MyRegion.
  • Connect default signals for every custom model by calling connect_default_signals (or not, if you don’t want to trigger default signals).
  • if in further versions of cities_light abstract models will be updated (some fields will be added/removed), you have to deal with migrations by yourself, as models are on your own now.

Convert a string value into a string that is usable against City.search_names.

For example, ‘Paris Texas’ would become ‘paristexas’.

cities_light.models.filter_non_cities(sender, items, **kwargs)[source]

Exclude any city which feature code must not be included. By default, this receiver is connected to city_items_pre_import(), it raises InvalidItems if the row feature code is not in the INCLUDE_CITY_TYPES setting.

cities_light.models.filter_non_included_countries_country(sender, items, **kwargs)[source]

Exclude any country which country must not be included. This is slot is connected to the country_items_pre_import() signal and does nothing by default. To enable it, set the INCLUDE_COUNTRIES setting.

cities_light.models.filter_non_included_countries_region(sender, items, **kwargs)[source]

Exclude any region which country must not be included. This is slot is connected to the region_items_pre_import() signal and does nothing by default. To enable it, set the INCLUDE_COUNTRIES setting.

cities_light.models.filter_non_included_countries_city(sender, items, **kwargs)[source]

Exclude any city which country must not be included. This is slot is connected to the city_items_pre_import() signal and does nothing by default. To enable it, set the INCLUDE_COUNTRIES setting.

class cities_light.models.Country(id, name_ascii, slug, geoname_id, alternate_names, name, code2, code3, continent, tld, phone)[source]
class cities_light.models.Region(id, name_ascii, slug, geoname_id, alternate_names, name, display_name, geoname_code, country)[source]
class cities_light.models.City(id, name_ascii, slug, geoname_id, alternate_names, name, display_name, search_names, latitude, longitude, region, country, population, feature_code)[source]

Admin

See source for details.

class cities_light.admin.CityAdmin(model, admin_site)[source]

ModelAdmin for City.

form

alias of CityForm

class cities_light.admin.CountryAdmin(model, admin_site)[source]

ModelAdmin for Country.

form

alias of CountryForm

class cities_light.admin.RegionAdmin(model, admin_site)[source]

ModelAdmin for Region.

form

alias of RegionForm