"""
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:
.. code:: python
# 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]*:
.. code:: python
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:
.. code:: python
INSTALLED_APPS = [
# ...
'cities_light',
'yourapp',
]
CITIES_LIGHT_APP_NAME = 'yourapp'
- Create tables:
.. code::
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.
"""
# some imports are present for backwards compatibility and migration process
from .abstract_models import (AbstractCountry, AbstractRegion, AbstractCity,
ToSearchTextField, CONTINENT_CHOICES, to_search, to_ascii)
from .signals import *
from .receivers import *
from .settings import *
__all__ = ['CONTINENT_CHOICES', 'to_search', 'to_ascii', 'filter_non_cities',
'filter_non_included_countries_country',
'filter_non_included_countries_region',
'filter_non_included_countries_city']
if CITIES_LIGHT_APP_NAME == DEFAULT_APP_NAME:
[docs] class Country(AbstractCountry):
pass
connect_default_signals(Country)
__all__.append('Country')
[docs] class Region(AbstractRegion):
pass
connect_default_signals(Region)
__all__.append('Region')
[docs] class City(AbstractCity):
pass
connect_default_signals(City)
__all__.append('City')