Metadata-Version: 1.1
Name: django-cities-teryt
Version: 1.0.0
Summary: Polish region and city data for Django.
Home-page: https://github.com/lukaszbanasiak/django-cities-teryt
Author: Łukasz Banasiak
Author-email: lukas.banasiak@gmail.com
License: MIT
Description: ===================
        django-cities-teryt
        ===================
        
        Polish region and city data for Django.
        
        This app provides models, admin integration and commands to import region and city data in your database.
        
        The data is pulled from `TERYT <http://bip.stat.gov.pl/en/teryt/>`_ database
        (National Official Register of the Territorial Division of the Country). TERYT is maintained by
        Polish Central Statistical Office (`GUS <http://stat.gov.pl/en/>`_)
        
        Database contains:
         - provinces
         - counties
         - municipalities
         - villages
         - cities
         - city districts
        
        Installation
        ------------
        
        Install django-cities-teryt
        
        .. code:: bash
        
            pip install django-cities-teryt
        
        Or dev version
        
        .. code:: bash
        
            pip install -e git+git@github.com:lukaszbanasiak/django-cities-teryt.git#egg=cities_teryt
        
        Add ``cities_teryt`` to your ``INSTALLED_APPS``
        
        .. code:: python
        
            INSTALLED_APPS = (
                ...
                'cities_teryt',
            )
        
        Now, run ``syncdb``, it will only create tables for models
        
        .. code:: bash
        
            ./manage.py syncdb
        
        Configuration
        -------------
        
        1. Download ``SIMC`` and ``TERC`` xml files from TERYT website http://www.stat.gov.pl/broker/access/prefile/listPreFiles.jspa and save them to one directory.
        2. Setup in your ``settings.py`` full path to above directory
        
        .. code:: python
        
            # Default directory is `import` dir in `django-cities-teryt` app directory
            CITIES_TERYT_IMPORT_DIR = '/path/to/dir'
        
        Importing data
        --------------
        
        To populate your database with all TERYT data use command
        
        .. code:: bash
        
            ./manage.py cities_teryt --data all --import
        
        To remove data use command
        
        .. code:: bash
        
            ./manage.py cities_teryt --data all --flush
        
        To operate on specific type of data enumerate them after ``--data`` argument
        
        .. code:: bash
        
            ./manage.py cities_teryt --data province, county, municipality --import
            ./manage.py cities_teryt --data city, village, district --flush
        
        Notice
        ^^^^^^
        Data have relations so it's best to import everything.
        Data are large and take time to import (there's no progress display).
        Verbosity is controlled through LOGGING.
        
        Examples
        --------
        
        Get ``City`` by name
        
        .. code:: python
        
            >>> City.objects.get(name='Swarzędz')
            <City: Swarzędz (0971502)>
        
        To get name of ``Municipality`` of this City we can use ``parent`` method or call directly ``municipality`` attrib
        
        .. code:: python
        
            >>> City.objects.get(name='Swarzędz').parent
            <Municipality: Swarzędz (302116)>
            >>> City.objects.get(name='Swarzędz').municipality
            <Municipality: Buk (302103)>
            >>> Municipality.objects.get(city__name='Swarzędz')
            <Municipality: Swarzędz (302116)>
        
        In this way we can get also ``Province`` or ``County``
        
        .. code:: python
        
            >>> City.objects.get(name='Swarzędz').province
            <Province: wielkopolskie (30)>
            >>> Province.objects.get(city__name='Swarzędz')
            <Province: wielkopolskie (30)>
        
        ... or even ``Districts``
        
        .. code:: python
        
            >>> c = City.objects.get(name='Swarzędz')
            >>> c.district_set.all()
            [<District: Nowa Wieś (0971519)>, <District: Zieleniec (0971525)>]
            >>> District.objects.filter(city=c)
            [<District: Nowa Wieś (0971519)>, <District: Zieleniec (0971525)>]
        
        List all ``Cities`` in the same ``County``
        
        .. code:: python
        
            >>> County.objects.get(city__name='Swarzędz').city_set.all()
            [<City: Buk (0970520)>, <City: Murowana Goślina (0971152)>, <City: Kostrzyn (0970885)>, <City: Mosina (0971057)>, <City: Pobiedziska (0971287)>, <City: Puszczykowo (0971376)>, <City: Kórnik (0970922)>, <City: Swarzędz (0971502)>, <City: Luboń (0970974)>, <City: Stęszew (0971494)>]
        
        Get pretty display name
        
        .. code:: python
        
            # Village, Municipality, County, Province
            >>> print Village.objects.get(name='Kaczkowo', province__name='wielkopolskie').get_display_name()
            Kaczkowo, Rydzyna, leszczyński, wielkopolskie
            # `Municipality` and `County` for "Poznań" is the same so we got only `City` and `Province` name
            >>> print City.objects.get(name='Poznań').get_display_name()
            Poznań, wielkopolskie
        
        Requirements
        ------------
        
        See ``requirements.txt``
        
Keywords: django cities teryt gus provinces counties municipalities villages districts
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
