# alice-py-ycf 

> v 0.2.3
>
> Python >= v 3.8
> 

Фреймворк для разработки навыков Яндекс Алисы на Python

> Адаптирован для работы с Yandex Cloud Function
 
- Минималистичен
- Нет внешних зависимостей
- Достаточно базового уровня Python

----
Пример файла requirements.txt для Yandex Cloud Function
```python
alice-py-ycf==0.2.3
```

Пример возможностей.<br>Файл index.py с функцией handler для Yandex Function Cloud:
```python
def handler(event, context):
    # подключение только базового управления
    from alice_py_ycf import Alice, AddScene

    # создание еще одной сцены
    Alice.red_room = AddScene()

    # выполняется при первом запуске навыка 
    @Alice.start()
    def start_f(ctx):
        return {
            "txt" : 'Это первый запуск приложения',
        }

    # выполняется в основной комнате только если придет "привет" или "хай"
    @Alice.command(['привет','хай'])
    def comm_f(ctx):
        return {
            "txt":'И тебе привет!',
        }

    @Alice.command(['хочу в красную комнату','пошли в красную комнату'])
    def comm_f(ctx):
        ctx['data']['scene'] = 'red_room'
        return {
            "txt": 'Отлично! Переходим в красную комнату'
        }

    # выполняется в основной комнате если это не первый запуск и 
    # не подходит ни под один из command( !! )
    @Alice.any()
    def any_f(ctx):
        return {
            "txt": 'Неизвестная команда',
            'tts': 'Эта команда мне неизвестна'
        }

    # выполняется в дополнительной комнате (red_room) если 
    # пользователь находится в ней и 
    # не подходит ни под один из command( !! ) из этой комнаты
    @Alice.red_room.any()
    def any_f(ctx):
        return {
            "txt": 'Неизвестная команда красная комната',
            'tts': 'Эта команда мне неизвестна'
        }

    # выполняется в только в дополнительной комнате (red_room) 
    # если пользователь в ней и не одна команда 
    # не подходит ни под один из command( !! ) из этой комнаты
    @Alice.red_room.command(['привет','хай'])
    def any_f(ctx):
        return {
            "txt": 'И тебе привет из красной комнаты',
            'tts': 'И тебе прив+ет из кр+асной комнаты'
        }
    
    # команда для возврата в основную комнату
    @Alice.red_room.command(['обратно в основной комнату','назад'])
    def any_f(ctx):
        ctx['data']['scene'] = ''
        return {
            "txt": 'И тебе привет из красной комнаты',
            'tts': 'И тебе прив+ет из кр+асной комнаты'
        }
    
    # выполняется за пределами установленного таймаута
    @Alice.timeout()
    def any_f(ctx):
        return {
            "txt": 'Что-то пошло не так..'
        }

    # работа фреймворка
    # установлен timeout 4сек, за пределами которого 
    # будет отправлено 
    # подготовленное сообщение. 
    # default timeout = 3сек.
    return Alice.run(event, timeout=4)
```

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

**обработка запроса "помощь":**
```python
# Данные функция будет вызвана если 
# пользователь сказал "помощь"
# Обработка данного запроса является 
# рекомендованной для всех навыков
@Alice.help()
    def hlp(ctx):
        return {
            "txt": 'вы находитесь в навыке',
            'tts': 'Вы находитесь в навыке'
        }
```

**обработка запроса "что ты умеешь":**
```python
# Данные функция будет вызвана если 
# пользователь сказал "что ты умеешь"
# Обработка данного запроса является 
# рекомендованной для всех навыков
@Alice.whatcyd()
    def hlp(ctx):
        return {
            "txt": 'вы можете управлять навыком..',
            'tts': 'вы можете управлять навыком.'
        }
```
---
**Особенности работы с фреймворком:**

- Значение "tts" не является обязательным и может отсутствовать. В этом случае подставляется значение из "txt".

- Значение "txt" можно передавать массивом:
```python
choice_response = [
    {'txt':'первый вариант'}
    {'txt':'вариант посложней',
    'tts': 'вариант посложн+ей'},
    {'txt':'третий вариант ответа'}
]
@Alice.any()
    def any_f(ctx, data):
        return {
            "txt":choice_response,
        }
```
Из массива будет взят один случайный вариант ответа.

- Если навык не сможет ответить за отведенное время, можно ответить пользователю подготовленным ответом. 
```python
# (...)

# ответ который последует если навык выйдет за пределы timeout`а
@Alice.timeout()
    def any_f(ctx, data):
        return {
            "txt": 'Что-то пошло не так, но мы обязательно разберемся.. Давай попробуем еще раз.',
        }

    # не обязательный параметр timeout = количество секунд, через которые последует подготовленный ответ
    return Alice.run(event, timeout=4)
```

<font color="#67CDFE">ctx</font> - контекст вызова. По ключу "json" хранится полный json запроса. По ключу "data" хранятся данные сессий и данные сцены (комнаты)<br>

```python
ctx = {
    # полный json request`а
    'json': { ... }
    
    # Данные для быстрого доступа. Данные в них будут отправлены response.
    'data': {
        # название сцены. Пустая строка = основная комната
        'scene': '',

        # хранение состояния сессии
        'us': {},

        # хранение состояния между сессиями
        'ws': {},

        # хранение состояние для экземпляра приложения
        'as': {}
    }
}
```







