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>`_
Благодаря этому коммиту до меня наконец дошло, почему импорт отжирал память.
Основные возможности
====================
* Импорт базы ФИАС из скачанного архива 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
Release history Release notifications | RSS feed
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)