Metadata-Version: 1.1
Name: django-fias
Version: 0.3.2
Summary: FIAS Django integration
Home-page: https://github.com/Yuego/django-fias
Author: Artem Vlasov
Author-email: root@proscript.ru
License: MIT license
Download-URL: https://github.com/Yuego/django-fias/archive/v0.3.2.tar.gz
Description: Приложение для работы с базой данных ФИАС в Django
        
        Основные возможности
        ====================
        
        * Импорт базы ФИАС из скачанного архива XML или напрямую с сайта http://fias.nalog.ru
        * Возможность хранить данные в отдельной БД
        * Поле модели AddressField, предоставляющее в админке Django ajax-поиск адреса
        * Поддержка полнотекстового поиска для поля AddressField (`демо <http://youtu.be/ZVVrxg9-o_4>`_)
        * Связанное поле модели для выбора района внутри выбранного в AddressField города (районы никак не привязаны к улицам, соответственно, их нужно выбирать отдельно, если это требуется)
        * Несколько абстрактных моделей, немного упрощающих жизнь
        
        Установка
        ============
        
        1. Установите `django-fias`::
        
                pip install django-fias
        
        2. Добавьте `fias` и `django_select2` в ваш список `INSTALLED_APPS`.
        3. Добавьте `url(r'^fias/', include('fias.urls', namespace='fias')),` в ваш urlpatterns
        4. Любым доступным способом подключите к админке приложения, в котором будете использовать поле FiasAddress свежую версию jQuery::
        
            # например так:
            class ItemAdmin(admin.ModelAdmin):
                class Media:
                    js = ['//ajax.googleapis.com/ajax/libs/jquery/1.10.1/jquery.js']
            admin.site.register(Item, ItemAdmin)
        
        5. Если вы желаете использовать отдельную БД под данные ФИАС, выполните следующее
        
        * Создайте БД и подключите её к Джанго обычным способом
        * Добавьте в ваш `settings.py` параметр::
        
                FIAS_DATABASE_ALIAS = 'fias'
        
        где `fias` - имя БД
        
        * Добавьте в список `DATABASE_ROUTERS`::
        
                fias.routers.FIASRouter
        
        * Выполните::
        
                # для South
                python manage.py migrate --database=fias
                # без South
                python manage.py syncdb --database=fias
        где `fias` - имя БД ФИАС
        
        5. Выполните::
        
                # для South
                python manage.py migrate
                # без South
                python manage.py syncdb
        
        6. Выполните::
        
                python manage.py collectstatic
        
        Обновление до версии 0.3
        ========================
        
        Обязательно наличие South.
        Выполните::
        
                # Если данные ФИАС хранятся в основной БД
                python manage.py migrate
                # Если данные ФИАС хранятся в другой БД
                python manage.py migrate --database=fias
        где `fias` - имя БД ФИАС
        
        Настройка полнотекстового поиска
        ================================
        AddressField поддерживает 2 метода поиска адреса: последовательный (sequence) и полнотекстовый (sphinx).
        
        **NOTE**: поддерживаются только 2 СУБД: PostgreSQL и MySQL.
        **NOTE2**: для индексации базы в MySQL может потребоваться до 2-2.5ГБ свободного места во временном каталоге MySQL.
        **NOTE3**: нет необходимости слишком часто пересоздавать поисковый индекс базы ФИАС. Это требуется делать только после обновления базы.
        
        По-умолчанию используется последовательный метод, т. к. не требует дополнительных настроек.
        Для активации полнотекстового поиска необходимо выполнить несколько дополнительных шагов:
        
        1. Добавьте в ваш `settings.py` параметр::
        
            FIAS_SEARCH_ENGINE='sphinx'
        
        2. Установите:
        
        * `sphinxit <https://github.com/semirook/sphinxit>`_
        * `Sphinx Search Engine <http://sphinxsearch.com>`_ Для Debian, Ubuntu, RHEL, Windows есть `пакеты <http://sphinxsearch.com/downloads/release/>`_
        
        
        3. Сгенерируйте конфигурацию `sphinx`:
        
        Если у вы уже используете `sphinx` в проекте, то вам нужен только конфиг индекса. Выполните::
        
            python manage.py fias_sphinx --path=PATH > sphinx.conf
        
        где `PATH` - путь до каталога с индексами sphinx.
        
        Иначе выполните::
        
            python manage.py fias_sphinx --path=PATH --full > sphinx.conf
        
        чтобы получить полный конфиг sphinx.
        
        Замените конфиг sphinx полученными настройками (для **Gentoo** это файл `/etc/sphinx/sphinx.conf`, для **Ubuntu**: `/etc/sphinxsearch/sphinx.conf`)
        
        4. Псоле того, как данные **импортированы** и обновлены выполните::
        
            indexer -c /etc/sphinx/sphinx.conf --all
        
        *NOTE*: для повторной переиндексации при запущенном Sphinx следует выполнять::
        
            indexer -c /etc/sphinx/sphinx.conf --all --rotate
        
        5. Запустите sphinx::
        
            # для Gentoo
            /etc/init.d/searchd start
            # для Ubuntu
            /etc/init.d/sphinxsearch start
        
        **NOTE** Если Sphinx работает на другом хосте или на другом порту, добавьте в `settings.py` словарь соответствующими параметрами::
        
            FIAS_SEARCHD_CONNECTION = {
                'host': '127.0.0.1',
                'port': 9306,
            }
        
        Выбор импортируемых таблиц
        ==========================
        
        Таблицы NORMDOC, SOCRBASE и ADDROBJ импортируются всегда. Таблицы LANDMARK, HOUSEINT и HOUSE можно не импортировать.
        
        Добавьте в ваш `settings.py` список названий таблиц, которые вы хотели бы импортировать::
        
            FIAS_TABLES = ('landmark', 'houseint', 'house')
        
        
        Импорт данных
        ==============
        
        Первоначальная загрузка данных
        ------------------------------
        Существует несколько способов импортировать данные в БД ФИАС
        
        Полностью автоматический импорт с сайта ФИАС::
        
                python manage.py fias --remote-file
        
        Такой способ не всегда целесообразен по разным причинам, поэтому лучше самостоятельно скачать полный архив и импортировать уже его::
        
                python manage.py fias --file /path/to/fias_xml.rar
        
        **Но!**
        В случае, если в БД уже есть какие-то данные, скрипт выдаст соответствующее сообщение и прекратит работу.
        Такое поведение связано с тем, что при импорте из файла, если версия файла не совпадает с версией данных в какой-то таблице в БД ФИАС,
        данные в этой таблице будут удалены полностью и заменены новыми, при этом
        ORM Django при наличии связанных таблиц удалит данные так же и оттуда.
        Если вы уверены в том, что делаете, добавьте к предыдущей команде флаг *--really-replace*::
        
                python manage.py fias --file /path/to/fias_xml.rar --really-replace
                # or
                python manage.py fias --remote-file --really-replace
        
        Если по какой-то причине нужно импортировать всю БД ФИАС заново, добавьте флаг *--force-replace*::
        
                python manage.py fias --file /path/to/fias_xml.rar --force-replace --really-replace
                # or
                python manage.py fias --remote-file --force-replace --really-replace
        
        Если скачанный файл не актуален, можно добавить к указанной выше команде флаг *--update* - скрипт сразу после импорта обновит БД до актуальной версии.::
        
                python manage.py fias --file /path/to/fias_xml.rar --update
                # or
                python manage.py fias --remote-file --update
                
        **NOTE**
        Импортируются только актуальные записи. Если данные об объекте менялись, будет загружена самая последняя версия записи об этом объекте.
        Записи из будущего не импортируются.
        
        Обновление существующей БД
        --------------------------
        Для обновления БД выполните::
        
                python manage.py fias --update
        
        Обновление выполняется только с сайта ФИАС. Обновить базу из файла нельзя.
        
        **NOTE**
        Как это ни печально, но мы живём в России. Тут всякое бывает. Вот и сервис ФИАС время от времени подсовывает битые дельта-архивы.
        Чтобы оные пропускать автоматически и обновляться следующими по порядку, используйте флаг *--skip* совместно с *--update*
        
        Использование
        ==============
        
        Вы можете самостоятельно ссылаться на таблицы БД фиас.
        
        Вы так же можете добавить в свои модели поле `fias.fields.address.AddressField`, которое предоставит вам удобный
        поиск адреса по базе и прявязку Один-ко-Многим вашей модели к таблице `AddrObj` базы ФИАС. (см. модель `Item` в тестовом приложении)
        
        Либо вы можете унаследоваться от любой модели из `fias.models.address`, которые добавят несколько дополнительных
        полей к вашим моделям и выполнят за вас кое-какую рутину:
        
        **FIASAddress** (см. модель `CachedAddress` в тестовом приложении)
        
        Помимо поля `address` добавляет еще два: `full_address` и `short_address`. В первом хранится полная запись адреса (но без индекса), во втором - укороченная.
        
        **FIASAddressWithArea** (см. модель `CachedAddressWithArea` в тестовом приложении)
        
        Наследуется от предыдущей модели и добавляет еще поле `area` - позволяет указывать район города, выбранного в поле `address` (если, конечно, таковые имеются в БД ФИАС для данного города)
        
        **FIASHouse** (см. модель `CachedAddressWithHouse` в тестовом приложении)
        
        Миксин, добавляющий 3 поля `house`, `corps` и `apartment` - соответственно номер дома, корпус и квартира.
        
        **FIASFullAddress**
        
        Комбинация моделей  `FIASAddress` и `FIASHouse`.
        
        **FIASFullAddressWithArea**
        
        Комбинация моделей `FIASAddressWithArea` и `FIASHouse`
        
        *NOTE*: в моделях `FIASFullAddress` и `FIASFullAddressWithArea` реализованы методы `_get_full_address` и `_get_short_address`, возвращающие соответственно полную и сокращённую строку адреса, включая номер дома/корпуса/квартиры.
        
        
        TODO
        ==============
        
        * Проверять списки удалённых объектов и все связанные с AddrObj модели мигрировать на правильные записи
        
        Известные проблемы
        ====================
        * Если используется отдельная БД под данные ФИАС, в админке в список `list_display` нельзя добавлять поля типа `ForeignKey`
        * South не умеет работать с несколькими БД
        
        Благодарности
        ====================
        
        `Коммит от EagerBeager <https://github.com/EagerBeager/django-fias/commit/ed375c2e1cafdc04f0c9612091eb040ef8f9f4fe>`_
        Благодаря этому коммиту до меня наконец дошло, почему импорт отжирал память.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Russian
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Topic :: Software Development :: Libraries :: Python Modules
