Package: django-fias
Приложение для работы с базой данных ФИАС в 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=========================После установки данного обновления лучше выполнить полный импорт БД, т. к. из-за ошибки в предыдущих версияхчасть данных (коды ИФНС, ОКАТО, ОКТМО) была импортирована некорректно.Выполните::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 --fakepython 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-fias2. Добавьте `fias` и `django_select2` в ваш список `INSTALLED_APPS`.3. Добавьте `url(r'^fias/', include('fias.urls', namespace='fias')),` в ваш urlpatterns4. Любым доступным способом подключите к админке приложения, в котором будете использовать поле 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 migrate6. Выполните::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 --rotate5. Запустите 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# orpython 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# orpython 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 <https://github.com/EagerBeager/django-fias/commit/ed375c2e1cafdc04f0c9612091eb040ef8f9f4fe>`_Благодаря этому коммиту до меня наконец дошло, почему импорт отжирал память.