UTG 0.3.2
Генератор связанного русского текста
License: BSD
Keywords: text generation

##########################################
UTG — генератор связанного русского текста
##########################################

Библиотека для генерации русского текста по шаблонам.

Примеры использования можно найти в игре «Сказка»: http://the-tale.org/linguistics/templates/specification

Перечень идентификаторов свойств слов находится в конце страницы (и на сайте игры).

*********
Установка
*********

Требуется Python 3

.. code:: bash

   pip install utg

   python -m unittest discover utg


*************
Использование
*************

Шаблон фразы — это обычный текст, с дополнительной разметкой, выделяющей места вставки переменных (например, имени героя) и слова, зависимые от этих переменных.

Пример::

  Вчера [mob] [укусил|mob] [hero|вн].

В зависимости от значений переменных, такой шаблон может стать как такой фразой::

  Вчера гиена укусила Халлра.

так и такой::

  Вчера светлячки укусили привидение.

Разберём пример подробно:

* ``Вчера`` — обычный текст.
* ``[mob]`` — переменная, вместо которой подставится название монстра.
* ``[укусил|mob]`` — слово, зависимое от перменной, часть его свойств будет изменяться в зависимости от свойств названия монстра (например, число). Генератор текста автоматически распознаёт свойства формы слова и пытается их сохранить (например, будет распознано и сохранено прошедшее время).
* ``[hero|вн]`` — переменная, вместо которой подставится имя героя. Дополнительно указано, что имя должно быть в винительном падеже.

И перменные и зависимые слова в шаблоне выделяются одинаково и имеют следующий формат:

* ``[`` — открывающая квадратная скобка.
* ``слово`` — зависимое слово или идентификатор переменной. Генератор сначала проверяет наличие переменной с таким именем, если такой переменной нет, то слово ищется в словаре.
* ``|`` — вертикальная черта — разделитель, нужен если указываем дополнительные свойства.
* ``имя переменной`` — переменная, от которой зависит форма слова, может отсутствовать.
* ``|`` — вертикальная черта — разделитель, нужен если указываем дополнительные свойства.
* ``свойства слова через запятую`` — описание требуемой формы слова (падеж, род и так далее).
* ``]`` — закрывающая квадратная скобка.

Дополнительных свойств можно указывать сколько угодно, применяться они будут в порядке определения, например::

  [переменная 1|переменная 2|вн,мр|переменная 3|прш,ед,од].

В большинстве случаев хватает следующих форматов:

* ``[переменная]`` — вставить переменную в нормальной форме (например, существительное в именительном падеже единственного времени).
* ``[переменная|свойства]`` — вставить переменную с указанными свойствами.
* ``[слово|переменная]`` — вставить слово, согласовав его с переменной (например, прилагательное «красивый» с существительным по роду и падежу).
* ``[слово|переменная|свойства]`` — вставить слово, согласова его с переменной и указав дополнительные свойства.

Обратите внимание:

* Указание свойств для слов и переменных действует только в месте вставки, поэтому, чтобы получить словосочение «красивого героя» мы должны указать винительный падеж явно для двух слов: ``[красивый|hero|вн] [hero|вн]``.
* Генератор текста умеет «угадывать» свойства слова по его форме, например, во фразе ``[hero] [побежал|hero]`` можно не указывать время глагола.
* Свойства, указанные позже, затирают свойства, указанные ранее. Например, во фразе ``[красивого|hero] [hero|вн]``` не будет установлен винительный падеж прилагательного, так как он заменится именительным падежом переменной hero.

Все свойства слов можно найти тут: http://the-tale.org/linguistics/templates/specification

******
Пример
******

Создан на основе теста ``utg.tests.test_general.GeneralTests.test_full_usage``

.. code:: python

   # coding: utf-8
   from utg import relations as r
   from utg import logic
   from utg import data
   from utg import dictionary
   from utg import words
   from utg import templates
   from utg import constructors

   # описываем существительное для словаря
   coins_word = words.Word(type=r.WORD_TYPE.NOUN,
                           forms=[ u'монета', u'монеты', u'монете', u'монету', u'монетой', u'монете',    # единственнео число
                                   u'монеты', u'монет', u'монетам', u'монеты', u'монетами', u'монетах',  # множественное число
                                   u'монеты', u'монет', u'монетам', u'монеты', u'монетами', u'монетах'], # счётное число (заполнено для пример, может быть заполнено методом autofill_missed_forms)
                           properties=words.Properties(r.ANIMALITY.INANIMATE, r.GENDER.FEMININE)) # свойства: неодушевлённое, женский род

   # описываем глагол для словаря
   action_word = words.Word(type=r.WORD_TYPE.VERB,
                            # описываем только нужны нам формы слова (порядок важен и определён в utg.data.WORDS_CACHES[r.WORD_TYPE.VERB])
                            forms=[u'подарить', u'подарил', u'подарило', u'подарила', u'подарили'] + [u''] * (len(data.WORDS_CACHES[r.WORD_TYPE.VERB]) - 5),
                            properties=words.Properties(r.ASPECT.PERFECTIVE, r.VOICE.DIRECT) )
   action_word.autofill_missed_forms() # заполняем пропущенные формы на основе введённых (выбираются наиболее близкие)

   # создаём словарь для использования в шаблонах
   test_dictionary = dictionary.Dictionary(words=[coins_word, action_word])

   # создаём шаблон
   template = templates.Template()

   # externals — внешние переменные, не обязаны быть в словаре
   template.parse(u'[Npc] [подарил|npc] [hero|дт] [coins] [монета|coins|вн].', externals=('hero', 'npc', 'coins'))

   # описываем внешние переменные
   hero = words.WordForm(words.Word(type=r.WORD_TYPE.NOUN,
                                    forms=[u'герой', u'героя', u'герою', u'героя', u'героем', u'герое',
                                           u'герои', u'героев', u'героям', u'героев', u'героями', u'героях',
                                           u'герои', u'героев', u'героям', u'героев', u'героями', u'героях'],
                                    properties=words.Properties(r.ANIMALITY.ANIMATE, r.GENDER.MASCULINE)))

   npc = words.WordForm(words.Word(type=r.WORD_TYPE.NOUN,
                                   forms=[u'русалка', u'русалки', u'русалке', u'русалку', u'русалкой', u'русалке',
                                          u'русалки', u'русалок', u'русалкам', u'русалок', u'русалками', u'русалках',
                                          u'русалки', u'русалок', u'русалкам', u'русалок', u'русалками', u'русалках'],
                                    properties=words.Properties(r.ANIMALITY.ANIMATE, r.GENDER.FEMININE)))

   # осуществляем подстановку
   result = template.substitute(externals={'hero': hero,
                                           'npc': npc,
                                           'coins': constructors.construct_integer(125)},
                                dictionary=test_dictionary)

   result == u'Русалка подарила герою 125 монет.'


*************
Свойства слов
*************

===
Вид
===

* ``несов`` — несовершенный
* ``сов`` — совершенный

=============================
Вид зависимости между словами
=============================

Вид зависимости определяет как будет изменяться слово, зависимое от другого. Полная зависимость означает, что слово изменит и семантические и морфологические свойства. Семантическая — только семантические. По умолчанию для слова используется полная зависимость.

Для примера, если у вас есть слова, зависимые от числительного, то во фразах:

* «5 красивых хомячков побежали в норку» — необходима полная зависимость, так как числительное употребляется в предложении и необходимо изменять морфологию слова;
* «Красивые хомячки побежали в норку» — необходима только семантическая зависимость, так как нам интересно только количество хомячков (один или много), но не надо согласовывать их с точным значением числительного;</li>
* «Красивые 5 хомячков побежали в норку» — необходима полная зависимость слова «хомячки», но только семантическая зависимость слова «красивые».

свойства:

* ``пзв`` — полная зависимость
* ``сзв`` — семантическая зависимость

================
Виды целых чисел
================

* ``цо`` — один
* ``цд`` — дуальные 2, 3, 4
* ``цсд`` — составные дуальные на 2, 3, 4
* ``цост`` — остальные целые
* ``цмм`` — миллион и миллиард

=====
Время
=====

* ``прш`` — прошедшее время
* ``нст`` — настоящее время
* ``буд`` — будущее время

=====
Залог
=====

* ``прям`` — прямой залог
* ``взв`` — возвратный залог

=====================
Категория местоимения
=====================

* ``личн`` — личное
* ``возвр`` — возвратное
* ``притяж`` — притяжательное
* ``вопр`` — вопросительное
* ``относ`` — относительное
* ``указат`` — указательное
* ``опред`` — определительное
* ``отриц`` — отрицательное
* ``неопр`` — неопределённое
* ``взаимн`` — взаимное

=========================
Категория прилагательного
=========================

* ``кач`` — качественное
* ``отн`` — относительное
* ``прит`` — притяжательное

====
Лицо
====

* ``1л`` — 1-ое лицо
* ``2л`` — 2-ое лицо
* ``3л`` — 3-е лицо

==============
Одушевлённость
==============

* ``од`` — одушевлённое
* ``но`` — неодушевлённое

=====
Падеж
=====

* ``им`` — именительный
* ``рд`` — родительный
* ``дт`` — дательный
* ``вн`` — винительный
* ``тв`` — творительный
* ``пр`` — предложный

=================
Размер 1-ой буквы
=================

* ``строч`` — строчная
* ``загл`` — заглавная

===
Род
===

* ``мр`` — мужской род
* ``ср`` — средний род
* ``жр`` — женский род

=======================
Степень прилагательного
=======================

* ``пол`` — положительная степень
* ``сравн`` — сравнительная степень
* ``прев`` — превосходная степень

=============
Форма глагола
=============

* ``инф`` — инфинитив
* ``изъяв`` — изъявительное наклонение
* ``пов`` — повелительное наклонение

==============
Форма предлога
==============

* ``осн`` — основная форма
* ``алт`` — альтернативная форма
* ``спц`` — специальная форма

=====================
Форма прилагательного
=====================

* ``полнприл`` — полная форма
* ``крприл`` — краткая форма

===============
Форма причастия
===============

* ``полнприч`` — полная форма
* ``крприч`` — краткая форма

======================
Форма существительного
======================

* ``нс`` — нормальная форма
* ``счт`` — счётная форма

==========
Часть речи
==========

* ``сущ`` — существительное
* ``прил`` — прилагательное
* ``мест`` — местоимение
* ``гл`` — глагол
* ``прич`` — причастие
* ``целое`` — целое число
* ``текст`` — текст
* ``предл`` — предлог

=====
Число
=====

* ``ед`` — единственное число
* ``мн`` — множественное число