20251005

2025-10-05 23:11:19 +03:00
parent 4cbb69181c
commit b20f18788d
24 changed files with 2275 additions and 12 deletions
--- a/help/class_desc/classes/action_state.md
+++ b/help/class_desc/classes/action_state.md
@@ -0,0 +1,379 @@
+# Класс `ActionState`
+
+Класс `ActionState` предназначен для отслеживания состояния выполняемых действий в программе, фиксируя изменения,
+происходящие в процессе выполнения, а также накапливая сообщения о событиях, успехах и ошибках. Он служит контейнером
+для сохранения промежуточных состояний и обеспечивает простой интерфейс взаимодействия с ними.
+
+## Основная информация
+
+- **Имя файла**: anb_python_components\classes\action_state.py
+- **Автор**: Александр Бабаев
+- **Версия**: 1.0.0
+- **Дата начала поддержки**: с версии 1.0
+
+## Атрибуты и методы класса
+
+### Атрибуты
+
+- **`value: T`**: Хранит основное значение состояния (может быть любым объектом).
+- **`__messages: list[ActionStateMessage]`**: Внутренний список сообщений, накопленных в процессе выполнения действия.
+
+### Конструктор (`__init__`)
+
+Принимает необязательное значение по умолчанию, которое устанавливается в качестве основного значения состояния.
+
+**Параметры**:
+
+- `default: T | None = None`: Значение по умолчанию.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState
+
+state = ActionState[bool](False)
+```
+
+### Основные методы
+
+#### Метод `add_message`
+
+Добавляет новое сообщение в список сообщений.
+
+**Параметры**:
+
+- `message: ActionStateMessage`: Модель сообщения.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState, ActionStateMessage, MessageType
+
+state = ActionState[bool](False)
+state.add_message(ActionStateMessage(MessageType.INFO, "Процесс запущен."))
+```
+
+---
+
+#### Метод `add`
+
+Удобный способ добавления сообщений, принимающий непосредственно тип сообщения и его текст.
+
+**Параметры**:
+
+- `message_type: MessageType`: Тип сообщения.
+- `message: str`: Сообщение.
+- `flags: dict[str, bool] | None = None`: Флаги сообщения (необязательны).
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState, MessageType
+
+state = ActionState[bool](False)
+state.add(MessageType.WARNING, "Скорость низкая.")
+```
+
+---
+
+### Метод `add_info`
+
+Добавляет информационное сообщение в список состояний.
+
+**Параметры**:
+
+- `message: str`: Текст самого информационного сообщения.
+- `flags: dict[str, bool] | None = None`: Дополнительные мета-данные или признаки сообщения (например, отметка о
+  важности или срочности).
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState
+
+state = ActionState[bool](False)
+state.add_info("Начали загрузку данных.")
+```
+
+---
+
+### Метод `add_warning`
+
+Добавляет предупреждение в список состояний.
+
+**Параметры**:
+
+- `message: str`: Текст предупреждения.
+- `flags: dict[str, bool] | None = None`: Дополнительные флаги для конкретного предупреждения.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState
+
+state = ActionState[bool](False)
+state.add_warning("Не хватает оперативной памяти.")
+```
+
+---
+
+### Метод `add_error`
+
+Добавляет сообщение об ошибке в список состояний.
+
+**Параметры**:
+
+- `message: str`: Текст сообщения об ошибке.
+- `flags: dict[str, bool] | None = None`: Дополнительные флаги для конкретной ошибки.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState
+
+state = ActionState[bool](False)
+state.add_error("Не удалось установить соединение с базой данных.")
+```
+
+---
+
+#### Метод `add_state`
+
+Объединяет текущее состояние с другим состоянием, перенося его сообщения.
+
+**Параметры**:
+
+- `state: ActionState`: Другое сообщение о состоянии.
+- `clear_all_before: bool = False`: Очистить список перед добавлением (по умолчанию - False).
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState
+
+state = ActionState[bool](False)
+another_state = ActionState()
+another_state.add_info("Дополнительная информация.")
+state.add_state(another_state)
+```
+
+---
+
+#### Метод `get_messages`
+
+Возвращает список сообщений, возможно применяя фильтр по условию.
+
+**Параметры**:
+
+- `predicate: Callable[[ActionStateMessage], bool] | None = None`: Условие выборки.
+
+**Метод возвращает** `list[ActionStateMessage]`: список сообщений.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState, MessageType
+
+state = ActionState[bool](False)
+errors = state.get_messages(lambda m: m.message_type == MessageType.ERROR)
+```
+
+---
+
+### Метод `get_string_messages`
+
+Возвращает объединённую строку сообщений, фильтруя их по определённому критерию (предикат). Полезен для визуализации
+сообщений в логах или отчётах.
+
+**Параметры**:
+
+- `predicate: Callable[[ActionStateMessage], bool] | None = None`: Функциональный предикат для фильтрации сообщений
+  (например, показывать только ошибки или предупреждения).
+- `separator: str = "\n"`: Разделитель между сообщениями (по умолчанию новая строка).
+
+**Метод возвращает** `str`: строка сообщений.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState, MessageType
+
+state = ActionState[bool](False)
+state.add_error("Ошибка в сети.")
+state.add_warning("Медленная скорость загрузки.")
+
+filtered_messages = state.get_string_messages(predicate = lambda msg: msg.message_type == MessageType.ERROR)
+print(filtered_messages)  # "Ошибка в сети."
+```
+
+---
+
+### Метод `has_infos`
+
+Проверяет, имеются ли в списке сообщения информационного типа (`INFO`).
+
+**Метод возвращает** `bool`: True, если есть, иначе False.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState
+
+state = ActionState[bool](False)
+state.add_info("Процесс завершён.")
+
+if state.has_infos():
+    print("Имеются информационные сообщения.")  # Будет выведено
+```
+
+---
+
+### Метод `has_warnings`
+
+Проверяет, присутствуют ли в списке предупреждающие сообщения (`WARNING`).
+
+**Метод возвращает** `bool`: True, если есть, иначе False.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState
+
+state = ActionState[bool](False)
+state.add_warning("Недостаточно памяти.")
+
+if state.has_warnings():
+    print("Есть предупреждающие сообщения.")  # Будет выведено
+```
+
+---
+
+### Метод `has_errors`
+
+Проверяет, существуют ли в списке сообщения об ошибках (`ERROR`).
+
+**Метод возвращает** `bool`: True, если есть, иначе False.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState
+
+state = ActionState[bool](False)
+state.add_error("Время ожидания истекло.")
+
+if state.has_errors():
+    print("Присутствуют сообщения об ошибках.")  # Будет выведено
+```
+
+---
+
+### Метод `clear`
+
+Очищает список сообщений, возможно применяя условие фильтрации.
+
+**Параметры**:
+
+- `predicate: Callable[[ActionStateMessage], bool] | None = None`: Функциональный предикат для фильтрации сообщений.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState, MessageType
+
+state = ActionState[bool](False)
+state.clear(lambda m: m.message_type == MessageType.INFO)
+```
+
+---
+
+### Метод `is_success`
+
+Проверяет, было ли состояние успешным, основываясь на наличии ошибок и предупреждений.
+
+**Параметры**:
+
+- `ignore_warnings: bool = False`: Игнорировать предупреждения (по умолчанию - False).
+
+**Метод возвращает** `bool`: True, если успешно, иначе False.
+
+**Пример использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState
+
+state = ActionState[bool](False)
+if state.is_success():
+    print("Операция прошла успешно.")
+```
+
+---
+
+### Метод `count`
+
+Метод `count` позволяет получать количество сообщений в списке, потенциально применяя дополнительное условие
+фильтрации (предикат). Таким образом, можно точно подсчитать число нужных сообщений (например, ошибок, предупреждений
+или общих записей).
+
+**Параметры**:
+
+- **`predicate: Callable[[ActionStateMessage], bool] | None = None`**: Опциональный предикат-функция, которая получает
+  каждое сообщение и решает, включать ли его в итоговый счётчик. Если предикат не указан, учитываются все сообщения.
+
+**Метод возвращает** `int`: количество сообщений.
+
+**Пример использования**:
+
+Предположим, мы хотим посчитать количество сообщений каждого типа:
+
+```python
+from anb_python_components.classes.action_state import ActionState, MessageType
+
+state = ActionState[bool](False)
+state.add_info("Данные получены.")
+state.add_warning("Память почти заполнена.")
+state.add_error("Не удаётся подключиться к серверу.")
+
+# Посчитать общее количество сообщений
+total_messages = state.count()
+print(total_messages)  # Вывод: 3
+
+# Посчитать количество ошибок
+error_count = state.count(predicate = lambda msg: msg.message_type == MessageType.ERROR)
+print(error_count)  # Вывод: 1
+
+# Посчитать количество информационных сообщений
+info_count = state.count(predicate = lambda msg: msg.message_type == MessageType.INFO)
+print(info_count)  # Вывод: 1
+```
+
+### Вспомогательные статичные методы для фильтрации сообщений
+
+Эти методы предоставляют готовые предикаты для извлечения конкретных типов сообщений.
+
+- `get_string_error_only() -> Callable[[ActionStateMessage], bool]`: Возвращает предикат для фильтрации только сообщений
+  об ошибках.
+- `get_string_error_and_warning() -> Callable[[ActionStateMessage], bool]`: Возвращает предикат для фильтрации сообщений
+  об ошибках и предупреждениях.
+- `get_string_all() -> Callable[[ActionStateMessage], bool]`: Возвращает предикат, включающий все сообщения (без
+  фильтрации).
+
+**Примеры использования**:
+
+```python
+from anb_python_components.classes.action_state import ActionState
+
+state = ActionState[bool](False)
+# Получить только ошибки
+only_errors = state.get_string_messages(predicate = ActionState.get_string_error_only(), separator = ", ")
+
+# Все сообщения
+all_messages = state.get_string_messages(predicate = ActionState.get_string_all())
+```
+
+## Заключение
+
+Класс `ActionState` играет ключевую роль в мониторинге и управлении состояниями в приложениях, позволяя контролировать
+ход выполнения операций и оперативно реагировать на возникающие события и ошибки.
+
+[На главную](../../index.md)