# Task - Пользовательская задача

class axipy.Task

  Пользовательская задача. Если выполнение функции в программе занимает длительное время, графический интерфейс Аксиомы будет неотзывчивым в течении этого времени. Чтобы длительная задача выполнялось в отдельном потоке и не нарушала работу интерфейса Аксиомы, такую функцию следует поместить в задачу, используя класс `axipy.Task`.

  Задачи (объекты класса `axipy.Task`) добавляются в менеджер `axipy.task_manager` при создании конструктором, и удаляются при завершении задачи (успешно или с ошибкой). Еще не запущенную задачу, можно удалить из менеджера, вызвав метод `axipy.Task.cancel`. Одну задачу можно запустить только один раз, завершенную задачу нельзя запустить повторно.

  См.также

  `axipy.run_in_gui()`

  См.также

  Работа с длительными операциями

  Конструктор класса:

  `__init__`(function[, name, description, ...]) | Конструктор класса.

  Свойства:

  `description` | Возвращает описание задачи.
  `id` | Возвращает идентификатор задачи.
  `is_canceled` | Возвращает True, если задача была отменена.
  `max` | Устанавливает или возвращает максимальное значение диапазона прогресса задачи.
  `message` | Устанавливает или возвращает отображаемое описание задачи.
  `min` | Устанавливает или возвращает минимальное значение диапазона прогресса задачи.
  `name` | Возвращает имя задачи.
  `range` | Устанавливает или возвращает диапазон прогресса задачи.
  `result` | Возвращает результат задачи.
  `status` | Возвращает текущее состояние задачи.
  `thread_id` | Возвращает идентификатор потока, в котором выполняется задача.
  `title` | Устанавливает или возвращает отображаемое имя задачи.
  `value` | Устанавливает или возвращает текущее значение прогресса задачи.

  Методы:

  `cancel`() | Уведомляет задачу об отмене.
  `raise_if_canceled`([message]) | Вызывает исключение об отмене задачи `axipy.Task.CanceledException`.
  `run_and_get`(*args, **kwargs) | Запускает задачу и ждет результат.
  `start`(*args, **kwargs) | Запускает задачу без ожидания результата.

  Сигналы:

  `finished` | Возвращает сигнал, испускаемый при завершении задачи.
  `message_changed` | Возвращает сигнал, испускаемый при изменении отображаемого описании задачи.
  `range_changed` | Возвращает сигнал, испускаемый при изменении диапазона прогресса задачи.
  `started` | Возвращает сигнал, испускаемый при старте задачи.
  `title_changed` | Возвращает сигнал, испускаемый при изменении отображаемого имени задачи.
  `value_changed` | Возвращает сигнал, испускаемый при изменении текущего значения прогресса задачи.

  Специальные методы:

  `__repr__`() | Официальное строковое представление объекта при вызове `repr()`.
  `__str__`() | Неформальное строковое представление объекта при вызове `str` или `print()`.

  Исключения:

  `CanceledException` | Исключение при отмене задачи.

  Классы:

  `Range` | Диапазон прогресса задачи.
  `Status` | Состояние задачи.

  exception CanceledException

    Исключение при отмене задачи.

  class Range

    Диапазон прогресса задачи.

    Атрибуты:

    `min` | Минимальное значение прогресса задачи.
    `max` | Максимальное значение прогресса задачи.

    Специальные методы:

    `__repr__`() | Официальное строковое представление объекта при вызове `repr()`.

  class Status

    Состояние задачи.

    Атрибуты:

    `IDLE` | В ожидании.
    `RUNNING` | Запущена.
    `SUCCESS` | Выполнена успешно.
    `CANCELED` | Отменена.
    `ERROR` | Завершилась с ошибкой.

  __init__(function: Callable, name: str = '', description: str = '', title: str = '', message: str = '')

    Конструктор класса.

    Создает экземпляр класса.

    Параметры:

      - function – Функция.

      - name – Имя.

      - description – Описание.

      - title – Отображаемое имя.

      - message – Отображаемое описание.

  __repr__() → str

    Официальное строковое представление объекта при вызове `repr()`.

  __str__() → str

    Неформальное строковое представление объекта при вызове `str` или `print()`.

  cancel()

    Уведомляет задачу об отмене.

    Устанавливает свойство `axipy.Task.is_canceled` на True и меняет состояние задачи `axipy.Task.status` на `axipy.Task.Status.CANCELED`. Вызов метода при статусе `axipy.Task.Status.IDLE` также удалит задачу из `axipy.task_manager`. Метод является слотом, Slot() (`PySide2.QtCore.Slot`).

  property description: str

    Возвращает описание задачи.

  property finished: Signal

    Возвращает сигнал, испускаемый при завершении задачи. Передает ссылку на экземпляр задачи, для получения результата, статуса и других атрибутов задачи.

    Тип результата:

      Signal[`axipy.Task`]

  property id: int

    Возвращает идентификатор задачи.

    Идентификатором задачи является её порядковый номер в менеджере задач `axipy.task_manager`.

  property is_canceled: bool

    Возвращает True, если задача была отменена.

    Чтобы отменить задачу (назначить True для свойства `axipy.Task.is_canceled`), нужно вызвать `axipy.Task.cancel()`.

  property max: float

    Устанавливает или возвращает максимальное значение диапазона прогресса задачи.

  property message: str

    Устанавливает или возвращает отображаемое описание задачи.

  property message_changed: Signal

    Возвращает сигнал, испускаемый при изменении отображаемого описании задачи.

    Тип результата:

      Signal[str]

  property min: float

    Устанавливает или возвращает минимальное значение диапазона прогресса задачи.

  property name: str

    Возвращает имя задачи.

  raise_if_canceled(message: Optional[str] = None)

    Вызывает исключение об отмене задачи `axipy.Task.CanceledException`.

    Параметры:

      message – Сообщение, передаваемое в исключение.

  property range: Range

    Устанавливает или возвращает диапазон прогресса задачи.

  property range_changed: Signal

    Возвращает сигнал, испускаемый при изменении диапазона прогресса задачи.

    Тип результата:

      Signal[axipy.Task.Range]

  property result: Any

    Возвращает результат задачи. (Возвращаемое значение пользовательской функции.) Если во время выполнения задачи, было вызвано исключение, то при получении результата, исключение будет вызвано повторно (За исключением пользовательской отмены `axipy.Task.CanceledException`).

    Исключение:

      Exception – Если во время выполнения задачи, было вызвано исключение.

  run_and_get(*args: Any, **kwargs: Any) → Any

    Запускает задачу и ждет результат. Останавливается лишь выполнение кода python, цикл обработки событий Qt продолжает работу. (Сигналы и события продолжают обрабатываться.) Возвращает результат задачи. (Возвращаемое значение пользовательской функции.) Если во время выполнения задачи, было вызвано исключение, то при получении результата, исключение будет вызвано повторно (За исключением пользовательской отмены `axipy.Task.CanceledException`).

    Параметры:

      - *args – Параметры, передаваемые в пользовательскую функцию.

      - **kwargs – Именованные параметры, передаваемые в пользовательскую функцию.

    Результат:

      Результат выполнения задачи. (Возвращаемое значение пользовательской функции.)

    Исключение:

      Exception – Если во время выполнения задачи, было вызвано исключение.

  start(*args: Any, **kwargs: Any)

    Запускает задачу без ожидания результата. Чтобы получить результат, необходимо подписаться на сигнал `axipy.Task.finished` и обратиться к свойству `axipy.Task.result`.

    Параметры:

      - *args – Параметры, передаваемые в пользовательскую функцию.

      - **kwargs – Именованные параметры, передаваемые в пользовательскую функцию.

  property started: Signal

    Возвращает сигнал, испускаемый при старте задачи.

    Тип результата:

      Signal[]

  property status: Status

    Возвращает текущее состояние задачи.

  property thread_id: Optional[int]

    Возвращает идентификатор потока, в котором выполняется задача.

    Когда задача не выполняется, возвращает None.

  property title: str

    Устанавливает или возвращает отображаемое имя задачи.

  property title_changed: Signal

    Возвращает сигнал, испускаемый при изменении отображаемого имени задачи.

    Тип результата:

      Signal[str]

  property value: float

    Устанавливает или возвращает текущее значение прогресса задачи.

  property value_changed: Signal

    Возвращает сигнал, испускаемый при изменении текущего значения прогресса задачи.

    Тип результата:

      Signal[str]