babaev-an / ANB Python Components
CI/CD
Реестр контейнеров и пакетов

class_desc/classes

Класс ActionState

Класс ActionState предназначен для отслеживания состояния выполняемых действий в программе, фиксируя изменения, происходящие в процессе выполнения, а также накапливая сообщения о событиях, успехах и ошибках. Он служит контейнером для сохранения промежуточных состояний и обеспечивает простой интерфейс взаимодействия с ними.

Основная информация

  • Имя файла: anb_python_components\classes\action_state.py
  • Автор: Александр Бабаев
  • Версия: 1.0.0
  • Дата начала поддержки: с версии 1.0

Атрибуты и методы класса

Атрибуты

  • value: T: Хранит основное значение состояния (может быть любым объектом).
  • __messages: list[ActionStateMessage]: Внутренний список сообщений, накопленных в процессе выполнения действия.

Конструктор (__init__)

Принимает необязательное значение по умолчанию, которое устанавливается в качестве основного значения состояния.

Параметры:

  • default: T | None = None: Значение по умолчанию.

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

from anb_python_components import ActionState

state = ActionState[bool](False)

Основные методы

Метод add_message

Добавляет новое сообщение в список сообщений.

Параметры:

  • message: ActionStateMessage: Модель сообщения.

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

from anb_python_components 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: Флаги сообщения (необязательны).

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

from anb_python_components import ActionState, MessageType

state = ActionState[bool](False)
state.add(MessageType.WARNING, "Скорость низкая.")

Метод add_info

Добавляет информационное сообщение в список состояний.

Параметры:

  • message: str: Текст самого информационного сообщения.
  • flags: dict[str, bool] | None = None: Дополнительные мета-данные или признаки сообщения (например, отметка о важности или срочности).

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

from anb_python_components import ActionState

state = ActionState[bool](False)
state.add_info("Начали загрузку данных.")

Метод add_warning

Добавляет предупреждение в список состояний.

Параметры:

  • message: str: Текст предупреждения.
  • flags: dict[str, bool] | None = None: Дополнительные флаги для конкретного предупреждения.

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

from anb_python_components import ActionState

state = ActionState[bool](False)
state.add_warning("Не хватает оперативной памяти.")

Метод add_error

Добавляет сообщение об ошибке в список состояний.

Параметры:

  • message: str: Текст сообщения об ошибке.
  • flags: dict[str, bool] | None = None: Дополнительные флаги для конкретной ошибки.

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

from anb_python_components import ActionState

state = ActionState[bool](False)
state.add_error("Не удалось установить соединение с базой данных.")

Метод add_state

Объединяет текущее состояние с другим состоянием, перенося его сообщения.

Параметры:

  • state: ActionState: Другое сообщение о состоянии.
  • clear_all_before: bool = False: Очистить список перед добавлением (по умолчанию - False).

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

from anb_python_components 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]: список сообщений.

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

from anb_python_components 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: строка сообщений.

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

from anb_python_components 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.

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

from anb_python_components import ActionState

state = ActionState[bool](False)
state.add_info("Процесс завершён.")

if state.has_infos():
    print("Имеются информационные сообщения.")  # Будет выведено

Метод has_warnings

Проверяет, присутствуют ли в списке предупреждающие сообщения (WARNING).

Метод возвращает bool: True, если есть, иначе False.

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

from anb_python_components import ActionState

state = ActionState[bool](False)
state.add_warning("Недостаточно памяти.")

if state.has_warnings():
    print("Есть предупреждающие сообщения.")  # Будет выведено

Метод has_errors

Проверяет, существуют ли в списке сообщения об ошибках (ERROR).

Метод возвращает bool: True, если есть, иначе False.

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

from anb_python_components import ActionState

state = ActionState[bool](False)
state.add_error("Время ожидания истекло.")

if state.has_errors():
    print("Присутствуют сообщения об ошибках.")  # Будет выведено

Метод clear

Очищает список сообщений, возможно применяя условие фильтрации.

Параметры:

  • predicate: Callable[[ActionStateMessage], bool] | None = None: Функциональный предикат для фильтрации сообщений.

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

from anb_python_components 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.

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

from anb_python_components import ActionState

state = ActionState[bool](False)
if state.is_success():
    print("Операция прошла успешно.")

Метод count

Метод count позволяет получать количество сообщений в списке, потенциально применяя дополнительное условие фильтрации (предикат). Таким образом, можно точно подсчитать число нужных сообщений (например, ошибок, предупреждений или общих записей).

Параметры:

  • predicate: Callable[[ActionStateMessage], bool] | None = None: Опциональный предикат-функция, которая получает каждое сообщение и решает, включать ли его в итоговый счётчик. Если предикат не указан, учитываются все сообщения.

Метод возвращает int: количество сообщений.

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

Предположим, мы хотим посчитать количество сообщений каждого типа:

from anb_python_components 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]: Возвращает предикат, включающий все сообщения (без фильтрации).

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

from anb_python_components 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 играет ключевую роль в мониторинге и управлении состояниями в приложениях, позволяя контролировать ход выполнения операций и оперативно реагировать на возникающие события и ошибки.

На главную

Назад