============================
Информация для разработчиков
============================

Общая информация
================

Исходный код pymorphy2 распространяется по лицензии MIT и доступен на github
и bitbucket:

* https://github.com/kmike/pymorphy2
* https://bitbucket.org/kmike/pymorphy2

Баг-трекер - на `гитхабе`_. Для общения можно использовать `гугл-группу`_
(есть какие-то идеи, предложения, замечания - пишите).

Если вы программист и хотите улучшить код pymorphy2 - может быть
полезным ознакомиться с разделами :ref:`internals`, :ref:`testing`
и :ref:`benchmarking`. Код pymorphy2 работает под Python 2.x и 3.x
без использования утилиты 2to3; написание такого кода, по опыту,
не сложнее написания кода просто под 2.х, но требует некоторой
внимательности и осторожности. Пожалуйста, пишите и запускайте тесты,
если что-то меняете.

Улучшать можно не только код - улучшения в документации, например,
не менее ценны.

Если вы разобрались в каком-то аспекте библиотеке или сделали что-то
интересное с ее помощью - пишите про это (в блоге или еще где-то)
и присылайте ссылку (в `баг-трекер`_ или `гугл-группу`_);
можно будет либо ссылку, либо сам текст в документацию добавить.

pymorphy2 основывается на словарях из OpenCorpora_ и использует
наборы текстов оттуда для автоматического тестирования и замеров скорости;
в будущем планируется также использовать размеченный корпус для
снятия неоднозначности разбора. Любая помощь OpenCorpora_ - это вклад
и в pymorphy2.

.. _OpenCorpora: http://opencorpora.org
.. _баг-трекер: https://github.com/kmike/pymorphy2/issues
.. _гитхабе: https://github.com/kmike/pymorphy2/issues
.. _гугл-группу: https://groups.google.com/forum/?fromgroups#!forum/pymorphy

.. _testing:

Тестирование
============

Запуск
------

Тесты лежат в папке :file:`tests`. При написании тестов используется pytest_.
Для их запуска используется утилита tox_, которая позволяет выполнять
тесты для нескольких интерпретаторов питона.

Для запуска тестов установите tox_ через pip::

    pip install tox

и выполните

::

    tox

из папки с исходным кодом.

.. _tox: http://tox.testrun.org
.. _pytest: http://pytest.org

.. _benchmarking:

Замеры скорости работы
======================

Чтобы улучшать скорость работы pymorphy2 (оптимизируя структуры данных,
алгоритмы или реализацию), нужны какие-то надежные средства
для замеров производительность.


На каких данных измерять?
-------------------------

Самый очевидный способ - выполнить интересующую операцию pymorphy2 для
всех слов из какого-то большого текста или корпуса. Это полезная метрика,
которая позволяет оценить среднюю скорость разбора. Минусы - зависимость
от конкретного корпуса, необходимость этот корпус распространять.

В pymorphy2 для замеров этого типа вместо корпуса целиком используются
частотные списки униграмм из `OpenCorpora <http://opencorpora.org/?page=downloads>`__:
для каждого слова разбор можно выполняеть столько раз, сколько оно встречалось
в корпусе.

Для того, чтоб бороться с "эффектом хоббита", выполняется еще одна
проверка  производительности - разбор прогоняется по 1 разу для
каждого слова из top-100k униграмм.

Для оценки производительности поддержки буквы "ё" во всех
словах "ё" заменяется на "е" и после этого опять прогоняется бенчмарк.


Организация замеров производительности в pymorphy2
--------------------------------------------------

Код для бенчмарков лежит в папке :file:`benchmarks`. Для запуска тестов
производительности выполните

::

    tox -c bench.ini

из папки с исходным кодом pymorphy2.

Замеры потребления памяти
-------------------------

Чтобы оптимизировать структуру словаря, нужно отслеживать потребление памяти.
Для этого у :ref:`утилиты командной строки<cli>` pymorphy есть специальная
команда::

    pymorphy dict mem_usage <FILE> [--verbose]

Для ее работы нужно предварительно установить ``psutil``::

    pip install psutil

``<FILE>`` - это папка со словарем; если указана опция ``--verbose``,
будет напечатан более детальный отчет о том, объекты каких типов занимают
сколько памяти.

.. note::

    Для работы ``--verbose`` требуется установить пакет guppy_,
    который на данный момент недоступен для python 3 (+ для работы под 2.7
    трубеутся устанавливать последнюю версию guppy из svn).

.. _guppy: http://pypi.python.org/pypi/guppy/