Skip to main content

FIAS Django integration

Project description

Приложение для работы с базой данных ФИАС в Django

Основные возможности
====================

* Импорт базы ФИАС из:
* архива XML или DBF
* каталога с XML или DBF
* напрямую с сайта http://fias.nalog.ru в формате XML или DBF
* Импорт всех существующих справочников и классификаторов ФИАС (с возможностью выборочного импорта)
* Возможность хранить данные в отдельной БД
* Все справочники и классификаторы доступны для просмотра в админке Django
* Поле модели AddressField, предоставляющее в админке Django ajax-поиск адреса
* Поддержка полнотекстового поиска для поля AddressField (`демо <http://youtu.be/ZVVrxg9-o_4>`_) с помощью:
* `Sphinx Search Engine <http://sphinxsearch.com>`_ Для Debian, Ubuntu, RHEL, Windows есть `пакеты <http://sphinxsearch.com/downloads/release/>`_

* Связанное поле модели для выбора района внутри выбранного в AddressField города (районы никак не привязаны к улицам, соответственно, их нужно выбирать отдельно, если это требуется)
* Несколько абстрактных моделей, немного упрощающих жизнь

Совместимость
=============

* Django 1.7+ (*Для работы с django 1.7 необходимо доустановить django_extensions*)
* django_select2 5.3.0+

Внешние зависимости
===================

* `django_select2<https://github.com/applegrew/django-select2>`_ модуль интеграции Select2 с Django.
* `dbfread <https://github.com/olemb/dbfread>`_ Маленькая библиотека для работы с DBF. Для python3.3+ пока что нужно использовать мой `форк<https://github.com/Yuego/dbfread>`_


Некоторые особенности
=====================

* Часть справочников импортируется независимо от настроек: вся статусная информация, типы нормативных документов, типы адресных объектов, таблица AddrObj
* Все справочники и классификаторы связаны между собой посредством ForeignKey, что требует консистентного состояния БД ФИАС. В реальной жизни такого не бывает, поэтому:
* В случае отсутствия родительского поля для ForeignKey включается механизм регрессивного импорта:
* При возникновении любой ошибки пачка объектов делится на части и каждая часть импортируется отдельно
* При повторном возникновении ошибки часть с ошибкой снова делится и импортируется.
* Так повторяется, пока в пачке не останется один объект, который просто отбрасывается.
Таким образом достигается минимальная просадка производительности импорта при возникновении ошибок.


Описание ключей командной строки (python manage.py fias)
========================================================

--src <path|filename|url|AUTO>
Путь до архива с БД ФИАС, каталога, в который предварительно был распакован архив или URL-адрес, с которого требуется скачать импортируемый архив
Отсутствующее значение или значение AUTO означает автоматическое получение данных с сайта http://fias.nalog.ru

--truncate
Указывает полностью удалять все данные из таблицы перед импортом в неё

--i-know-what-i-do
В случае если в БД уже есть какие-то данные, приложение не даст ничего импортировать, пока не будет указан этот ключ.
На возможность обновления никак не влияет.

--update
Обновляет БД ФИАС до актуальной версии (после или вместо импорта).
Если в БД ничего ещё не импортировалось, будет выдано сообщение об ошибке.

--skip
Используется только вместе с --update. Указывает пропускать повреждённые архивы с обновлениями.

--format <xml|dbf>
Указывает, в каком формате скачивать архивы с данными ФИАС. Допустимоые значения: xml или dbf.

--limit
Устанавливает размер пачки записей, единовременно загружаемой в БД. Чем больше размер, тем быстрее импорт (в теории), но дольше обработка ошибок, если таковые возникнут.
По-умолчанию: 10000.

--tables
Задаёт список таблиц для импорта через запятую.

--update-version-info <yes|no>
Указывает, обновлять ли список версий БД ФИАС.
По-умолчанию: yes

--fill-weights
Обновляет веса типов адресных объектов из FIAS_SB_WEIGHTS. Смотри **Настройка весов** ниже.

--keep-indexes
При первоначальном импорте удаляются все индексы из таблиц (кроме первичного ключа) перед импортом и пересоздаются заново после.
Ключ отключает такое поведение. На процесс обновления никак не влияет.

--tempdir <path>
Путь к каталогу, где будут размещены временные файлы в процессе импорта.
Каталог должен существовать и быть доступен для записи.

Обновление 1.1.x до 1.2.0
=========================

После установки данного обновления лучше выполнить полный импорт БД, т. к. из-за ошибки в предыдущих версиях
часть данных (коды ИФНС, ОКАТО, ОКТМО) была импортирована некорректно.

Обновление 1.0.0 до 1.1.0
=========================

Вполне возможна ситуация, когда миграция прервётся из-за неконсистентности БД.
В этом случае придётся выполнить полный импорт, т. к. искать проблемные записи слишком трудозатратно.

* Перед обновлением **сделайте резервную копию БД ФИАС**!!!
* Перед обновлением убедитесь в наличии доступа в Интернет, т. к. в процессе будет скачана последняя версия ахрива БД ФИАС (полный архив).
* Если БД пуста, ничего качаться не будет.

Выполните::

python manage.py migrate fias


Обновление 0.6.1 до 1.0.0
=========================

Обновите django-fias до версии 0.6.2, а django до версии 1.7 или выше.
Смигрируйте базу данных::

python manage.py migrate fias 0001 --fake
python manage.py migrate fias

Обновите django-fias до версии 1.0.0
Обновите все зависимости до актуальных версий (в частности django-select2 до версии не ниже 5.3.0).
Обновите статические файлы::

python manage.py collectstatic


Обновите настройки django-fias (см. fias/config.py).

Установка
=========

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

* Выполните::


python manage.py migrate --database=fias

где `fias` - имя БД ФИАС

5. Выполните::

python manage.py migrate

6. Выполните::

python manage.py collectstatic

Настройка полнотекстового поиска
================================

**NOTE**: поддерживаются только 2 СУБД: PostgreSQL и MySQL.
**NOTE2**: для индексации базы в MySQL может потребоваться до 2-2.5ГБ свободного места во временном каталоге MySQL.
**NOTE3**: нет необходимости слишком часто пересоздавать поисковый индекс базы ФИАС. Это требуется делать только после обновления базы.

1. Установите:

* `Sphinx Search Engine <http://sphinxsearch.com>`_ Для Debian, Ubuntu, RHEL, Windows есть `пакеты <http://sphinxsearch.com/downloads/release/>`_


3. Сгенерируйте конфигурацию `sphinx`:

Если у вы уже используете `sphinx` в проекте, то вам нужен только конфиг индекса. Выполните::

python manage.py fias_suggest --path=PATH > sphinx.conf

где `PATH` - путь до каталога с индексами sphinx.

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

python manage.py fias_suggest --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.
Но помните, что эти изменения будут **перезаписаны** при следующем вызове упомянутой команды!
После внесения изменений обязательно нужно переиндексировать базу.

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

Таблицы SOCRBASE и ADDROBJ импортируются всегда. Таблицы NORMDOC, LANDMARK, HOUSEINT и HOUSE по-умолчанию не импортируются.

Добавьте в ваш `settings.py` список названий таблиц, которые вы хотели бы импортировать::

FIAS_TABLES = ('normdoc', 'landmark', 'houseint', 'house')


Импорт данных
=============

Расшифровка сокращений
----------------------
T: Table (Таблица) - импортируемая в данный момент таблица
L: Loaded (Загружено) - количество уже загруженных в таблицу строк
U: Updated (Обновлено) - количество обновлённых записей
S: Skipped (Пропущено) - количество пропущенных записей, не удовлетворивших условиям фильтров и валидаторов, из них:
E: Errors (Ошибки) - количество записей, пропущенных из-за ошибок
R: Regression (Регрессия) - статус режима регрессивного импорта.
Первое число - уровень рекурсии. Чем глубже рекурсия, тем на более мелкие части разбита пачка записей.
Числа в скобках обозначают <номер части>:<количество записей в части>. Количество чисел и их позиция соответствуют глубине рекурсии.
FN: Filename (Имя файла) - имя файла импортируемой таблицы

Первоначальная загрузка данных
------------------------------
Существует несколько способов импортировать данные в БД ФИАС

Полностью автоматический импорт с сайта ФИАС::

python manage.py fias --src auto [--format <xml|dbf>]

Здесь ключ `--format` указывает, в каком формате предпочтительно скачивать данные. Доступны значения `xml` или `dbf`.
Такой способ не всегда целесообразен по разным причинам, поэтому лучше самостоятельно скачать полный архив и импортировать уже его::

# Архив с XML-файлами
python manage.py fias --src /path/to/fias_xml.rar
# Архив с DBF-файлами
python manage.py fias --src /path/to/fias_dbf.rar
# Каталог с распакованным содержимым архива
python manage.py fias --src /path/to/fias_data/

**Но!**
В случае, если в БД уже есть какие-то данные, скрипт выдаст соответствующее сообщение и прекратит работу.
Такое поведение связано с тем, что при импорте из файла, если версия файла не совпадает с версией данных в какой-то таблице в БД ФИАС,
данные в этой таблице могут быть удалены полностью и заменены новыми, при этом
ORM Django при наличии связанных таблиц удалит данные так же и оттуда.
Если вы уверены в том, что делаете, добавьте к предыдущей команде флаг *--i-know-what-i-do*::

python manage.py fias --src /path/to/fias_xml.rar --i-know-what-i-do
# or
python manage.py fias --src auto --i-know-what-i-do

Если по какой-то причине нужно импортировать всю БД ФИАС заново, добавьте флаг *--truncate*::

python manage.py fias --src /path/to/fias_xml.rar --truncate --i-know-what-i-do
# or
python manage.py fias --src auto --i-know-what-i-do

Если скачанный файл не актуален, можно добавить к указанной выше команде флаг *--update* - скрипт сразу после импорта обновит БД до актуальной версии.::

python manage.py fias --src /path/to/fias_xml.rar --update

**NOTE**
Импортируются только актуальные записи. Если данные об объекте менялись, будет загружена самая последняя версия записи об этом объекте.
Записи из будущего не импортируются.

Обновление существующей БД
--------------------------
Для обновления БД выполните::

python manage.py fias --update

Обновление выполняется только с сайта ФИАС. Обновить базу из файла нельзя.

**NOTE**
Как это ни печально, но мы живём в России. Тут всякое бывает. Вот и сервис ФИАС время от времени подсовывает битые дельта-архивы.
Чтобы оные пропускать автоматически и обновляться следующими по порядку, используйте флаг *--skip* совместно с *--update*

Для вывода всех возможных параметров импорта выполните::

python manage.py fias --help


Просмотр информации о состоянии БД ФИАС
---------------------------------------

Чтобы узнать, насколько актуальна локальная копия БД ФИАС, выполните::

python manage.py fiasinfo --db-version


Использование
=============

Вы можете самостоятельно ссылаться на таблицы БД фиас.

Вы так же можете добавить в свои модели поле `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`

Благодарности
=============

`Коммит от 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

django-fias-1.2.0.tar.gz (68.2 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