Metadata-Version: 1.1
Name: UTG
Version: 0.3.2
Summary: Генератор связанного русского текста
Home-page: https://github.com/Tiendil/utg
Author: Aleksey Yeletsky <Tiendil>
Author-email: a.eletsky@gmail.com
License: BSD
Description: ##########################################
        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-ой буквы
        =================
        
        * ``строч`` — строчная
        * ``загл`` — заглавная
        
        ===
        Род
        ===
        
        * ``мр`` — мужской род
        * ``ср`` — средний род
        * ``жр`` — женский род
        
        =======================
        Степень прилагательного
        =======================
        
        * ``пол`` — положительная степень
        * ``сравн`` — сравнительная степень
        * ``прев`` — превосходная степень
        
        =============
        Форма глагола
        =============
        
        * ``инф`` — инфинитив
        * ``изъяв`` — изъявительное наклонение
        * ``пов`` — повелительное наклонение
        
        ==============
        Форма предлога
        ==============
        
        * ``осн`` — основная форма
        * ``алт`` — альтернативная форма
        * ``спц`` — специальная форма
        
        =====================
        Форма прилагательного
        =====================
        
        * ``полнприл`` — полная форма
        * ``крприл`` — краткая форма
        
        ===============
        Форма причастия
        ===============
        
        * ``полнприч`` — полная форма
        * ``крприч`` — краткая форма
        
        ======================
        Форма существительного
        ======================
        
        * ``нс`` — нормальная форма
        * ``счт`` — счётная форма
        
        ==========
        Часть речи
        ==========
        
        * ``сущ`` — существительное
        * ``прил`` — прилагательное
        * ``мест`` — местоимение
        * ``гл`` — глагол
        * ``прич`` — причастие
        * ``целое`` — целое число
        * ``текст`` — текст
        * ``предл`` — предлог
        
        =====
        Число
        =====
        
        * ``ед`` — единственное число
        * ``мн`` — множественное число
        
Keywords: text generation,генерация текста
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Natural Language :: Russian
