m3-django-fias 2.0.1

FIAS Django integration for m3

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

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

• Импорт базы ФИАС из:

  • архива XML или DBF

  • каталога с XML или DBF

  • напрямую с сайта http://fias.nalog.ru в формате XML или DBF

• Импорт всех существующих справочников и классификаторов ФИАС (с возможностью выборочного импорта)

• Возможность хранить данные в отдельной БД

• Все справочники и классификаторы доступны для просмотра в админке Django

• Поле модели AddressField, предоставляющее в админке Django ajax-поиск адреса

• Поддержка полнотекстового поиска для поля AddressField (демо) с помощью:

  • Sphinx Search Engine Для Debian, Ubuntu, RHEL, Windows есть пакеты

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

• Несколько абстрактных моделей, немного упрощающих жизнь

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

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

• django_select2 5.3.0+

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

• django_select2 модуль интеграции Select2 с Django.

• dbfread Маленькая библиотека для работы с DBF. Для python3.3+ пока что нужно использовать мой форк

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

• Часть справочников импортируется независимо от настроек: вся статусная информация, типы нормативных документов, типы адресных объектов, таблица 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

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

Выполните:

python manage.py migrate fias

Обновление 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 Для Debian, Ubuntu, RHEL, Windows есть пакеты

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

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

Расшифровка сокращений

• 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, возвращающие соответственно полную и сокращённую строку адреса, включая номер дома/корпуса/квартиры.

Настройка settings.py

FIAS_UNRAR_TOOL - путь до библиотеки UnRAR (по умолчанию unrar - поиск в глобальных переменных)

TODO

• Проверять списки удалённых объектов и все связанные с AddrObj модели мигрировать на правильные записи

Известные проблемы

• Если используется отдельная БД под данные ФИАС, в админке в список list_display нельзя добавлять поля типа ForeignKey

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

Коммит от EagerBeager Благодаря этому коммиту до меня наконец дошло, почему импорт отжирал память.