Модуль вопросов (questionary)
=============================

.. automodule:: mylife3000.questionary
   :members:
   :undoc-members:
   :show-inheritance:
   :special-members: __init__

Обзор
-----

Модуль ``questionary.py`` реализует паттерн Dependency Injection для изоляции
обработчиков от логики работы с вопросами. Класс Questionary предоставляет
единый интерфейс для доступа к вопросам, разбитым по разделам и темам.

Архитектура данных
------------------

.. mermaid::

   graph TB
       Q[Questionary] --> S1[Самопознание]
       Q --> S2[Вектор]
       Q --> S3[Вызовы]
       Q --> S4[Окружение]
       Q --> S5[Интеграция]
       Q --> S6[Капсула времени]
       
       S1 --> T1[Ядро личности]
       S1 --> T2[Сильные стороны]
       S1 --> T3[Ценности]
       
       T1 --> Q1[Вопрос 1]
       T1 --> Q2[Вопрос 2]

Класс Questionary
-----------------

.. py:class:: Questionary()

   Основной класс для управления вопросами.
   
   **Атрибуты:**
   
   .. py:attribute:: sections
      
      Словарь разделов, тем и списков вопросов
      
      **Тип:** ``Dict[str, Dict[str, List[str]]]``
   
   .. py:attribute:: section_descriptions
      
      Словарь описаний разделов
      
      **Тип:** ``Dict[str, str]``

Методы Questionary
------------------

.. py:method:: Questionary._load_questions()

   Приватный метод загрузки вопросов из модуля questions_data.
   
   **Действия:**
   
   - Инициализирует структуру sections
   - Заполняет section_descriptions
   - Добавляет категорию "Случайный вопрос" в каждый раздел

.. py:method:: Questionary.get_section_questions(section_name: str) -> Optional[Dict[str, List[str]]]

   Возвращает словарь тем и вопросов для указанного раздела.
   
   **Parameters:**
   
   - ``section_name`` - название раздела
   
   **Returns:**
   
   - Словарь {тема: список_вопросов} или None

.. py:method:: Questionary.get_section_description(section_name: str) -> str

   Возвращает описание указанного раздела.
   
   **Returns:**
   
   - Описание раздела или пустую строку

.. py:method:: Questionary.get_random_question(section_name: str, theme: Optional[str] = None) -> Optional[str]

   Возвращает случайный вопрос из указанного раздела и/или темы.
   
   **Логика выбора:**
   
   1. Если указана тема - вопрос из темы
   2. Если нет - вопрос из категории "Случайный вопрос"
   3. Если нет - случайный вопрос из всего раздела
   
   **Returns:**
   
   - Случайный вопрос или None

.. py:method:: Questionary.get_themes(section_name: str) -> List[str]

   Возвращает список тем для указанного раздела.
   
   **Важно:** Исключает категорию "Случайный вопрос"

.. py:method:: Questionary.get_all_sections() -> List[str]

   Возвращает список всех доступных разделов.

Структура разделов
------------------

+-----------------------------------+---------------------------------------------------+
| Раздел                           | Описание                                          |
+===================================+===================================================+
| Самопознание: Кто Я?             | Внутренняя сущность, идентичность                 |
+-----------------------------------+---------------------------------------------------+
| Вектор: Куда я движусь?          | Цели, амбиции, планирование                       |
+-----------------------------------+---------------------------------------------------+
| Вызовы: Что мне мешает?          | Препятствия, страхи, ограничения                  |
+-----------------------------------+---------------------------------------------------+
| Окружение: Мои отношения?        | Социальные связи и отношения                      |
+-----------------------------------+---------------------------------------------------+
| Интеграция: Как я живу?          | Повседневные практики и рутины                    |
+-----------------------------------+---------------------------------------------------+
| Капсула Времени                  | Личная история и наследие                         |
+-----------------------------------+---------------------------------------------------+

Dependency Injection
--------------------

Questionary используется через механизм Dependency Injection:

.. code-block:: python

   # В main.py
   questionary = Questionary()
   application.bot_data['questionary'] = questionary
   
   # В обработчиках
   questionary: Questionary = context.bot_data['questionary']

Пример использования
--------------------

.. code-block:: python

   # Создание экземпляра
   questionary = Questionary()
   
   # Получение всех разделов
   sections = questionary.get_all_sections()
   # ['Самопознание: Кто Я?', 'Вектор: Куда я движусь?', ...]
   
   # Получение тем раздела
   themes = questionary.get_themes('Самопознание: Кто Я?')
   # ['Ядро личности', 'Сильные и слабые стороны', ...]
   
   # Получение случайного вопроса
   question = questionary.get_random_question('Самопознание: Кто Я?', 'Ядро личности')
   # "Если бы тебе нужно было описать свою сущность..."

Статистика вопросов
-------------------

.. list-table:: Количество вопросов по разделам
   :header-rows: 1
   :widths: 50 25 25

   * - Раздел
     - Тем
     - Вопросов
   * - Самопознание: Кто Я?
     - 6
     - 48
   * - Вектор: Куда я движусь?
     - 4
     - 32
   * - Вызовы: Что мне мешает?
     - 4
     - 28
   * - Окружение: Мои отношения?
     - 5
     - 40
   * - Интеграция: Как я живу?
     - 5
     - 40
   * - Капсула Времени
     - 6
     - 48
   * - **Всего**
     - **30**
     - **236**

Смотрите также
--------------

* :doc:`questions_data` - Исходные данные вопросов
* :doc:`handlers` - Использование Questionary в обработчиках
* :doc:`main` - Инициализация Dependency Injection