Skip to main content

FIAS Django integration (fork Ailove)

Project 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` - имя БД ФИАС


Обновление до версии 0.4
========================

Обязательно наличие South.

Если данные ФИАС хранятся в MySQL, выполните::

# Если данные ФИАС хранятся в основной БД
python manage.py migrate fias 0004 --fake
python manage.py migrate fias
# Если данные ФИАС хранятся в другой БД
python manage.py migrate fias 0004 --fake --database=fias
python manage.py migrate fias --database=fias

Иначе выполните::

# Если данные ФИАС хранятся в основной БД
python manage.py migrate
# Если данные ФИАС хранятся в другой БД
python manage.py migrate --database=fias

Затем следует сгенерировать новый конфиг для Sphinx, как описано ниже, и переиндексировать базу.

Настройка полнотекстового поиска
================================
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,
}

Настройка весов
===============
Из-за особенностей организации БД ФИАС, сортировка результатов поиска происходит не так, как хотелось бы.
Поэтому, начиная с версии 0.4 добавлена возможность настроить веса типов адресных объектов по своему усмотрению.
Для этого в `settings.py` добавьте словарь `FIAS_SB_WEIGHTS` вида::

FIAS_SB_WEIGHTS = {
# СОКРАЩЕНИЕ: ВЕС
'г': 128,
'с': 100,
}

где
* СОКРАЩЕНИЕ - сокращённое наименование вида объекта из таблицы SocrBase
* ВЕС - число от 0 до 128

*NOTE*: по-умолчанию вес всех типов равен 64
*NOTE*: пример заполнения можно посмотреть в weights.py - там перечислены предустановленные веса.

Чтобы применить свои изменения, выполните::

python manage.py fias --fill-weights

Кроме того изменить веса можно в панели администрирования Django.
Но помните, что эти изменения будут **перезаписаны** при следующем вызове упомянутой команды!
После внесения изменений обязательно нужно переиндексировать базу.

Выбор импортируемых таблиц
==========================

Таблицы 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>`_
Благодаря этому коммиту до меня наконец дошло, почему импорт отжирал память.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ailove-django-fias-0.5.2.tar.gz (40.8 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page