# Класс `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)