Metadata-Version: 1.1
Name: django-fias
Version: 1.2.1
Summary: FIAS Django integration
Home-page: https://github.com/Yuego/django-fias
Author: Artem Vlasov
Author-email: root@proscript.ru
License: MIT license
Download-URL: https://github.com/Yuego/django-fias/archive/1.2.1.tar.gz
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>`_
        Благодаря этому коммиту до меня наконец дошло, почему импорт отжирал память.
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Russian
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Libraries :: Python Modules
