QueuedTask

Bases: Generic[RValue]

Represent a task in the queue.

Attributes:

Name	Type	Description
entry_id	int	The id of the entry into the queue that contains the task description.

Source code in src/alchemical_queues/tasks/main.py

class QueuedTask(Generic[RValue]):
    """Represent a task in the queue.

    Attributes:
        entry_id (int): The id of the entry into the queue that contains the task description.
    """

    def __init__(self, queue: AlchemicalTaskQueue, entry_id: int, name: str):
        self._queue = queue
        self.entry_id = entry_id
        self._name = name

    @property
    def done(self) -> bool:
        """Whether this task has a recorded outcome yet (success or failure).

        `result` returns `None` both when the task hasn't completed yet and
        when it has completed successfully with a return value of `None`, so
        if your task handler's success value can legitimately be `None` (a
        "send this email" task that returns nothing, say), check `done`
        rather than relying on `result`'s truthiness to know whether it's
        finished.

        Returns:
            bool: True once `result` reflects a real outcome.
        """

        return bool(self._queue.responses(self.entry_id))

    @property
    def result(self) -> Union[RValue, TaskException, None]:
        """Obtain the result of a queued task if it is finished,
        an exception if the task failed to run, or None if the task
        has not completed.

        This reads whatever was last recorded with
        [AlchemicalTaskQueue.respond][alchemical_queues.AlchemicalTaskQueue.respond]
        for this task's entry_id. `tasks.Worker` always records
        `{"result": ...}` on success or `{"error": ..., "error_type": ...}`
        on failure, which is what lets this property tell those two apart.
        If you call `respond()` yourself with something else entirely (it's
        a general queue-level API, not Worker-specific), there's no such
        shape to interpret -- you get that data back as-is, same as `RValue`.

        Returns:
            RValue: the value you return from the task handler (or, verbatim,
                whatever was passed to `respond()` if it wasn't a dict with a
                `result`/`error` key).
            TaskException: the task failed to execute.
            None: the task has not completed -- but also what you get if the
                task completed successfully and returned None itself; see `done`.
        """

        responses = self._queue.responses(self.entry_id)

        if not responses:
            return None

        data = responses[0].data

        if not isinstance(data, dict):
            return cast(RValue, data)

        if "error" in data:
            return TaskException(data["error"], data.get("error_type"))

        return cast(RValue, data.get("result"))

done property

Whether this task has a recorded outcome yet (success or failure).

result returns None both when the task hasn't completed yet and when it has completed successfully with a return value of None, so if your task handler's success value can legitimately be None (a "send this email" task that returns nothing, say), check done rather than relying on result's truthiness to know whether it's finished.

Returns:

Name	Type	Description
bool	bool	True once result reflects a real outcome.

result property

Obtain the result of a queued task if it is finished, an exception if the task failed to run, or None if the task has not completed.

This reads whatever was last recorded with AlchemicalTaskQueue.respond for this task's entry_id. tasks.Worker always records {"result": ...} on success or {"error": ..., "error_type": ...} on failure, which is what lets this property tell those two apart. If you call respond() yourself with something else entirely (it's a general queue-level API, not Worker-specific), there's no such shape to interpret -- you get that data back as-is, same as RValue.

Returns:

Name	Type	Description
RValue	Union[RValue, TaskException, None]	the value you return from the task handler (or, verbatim, whatever was passed to respond() if it wasn't a dict with a result/error key).
TaskException	Union[RValue, TaskException, None]	the task failed to execute.
None	Union[RValue, TaskException, None]	the task has not completed -- but also what you get if the task completed successfully and returned None itself; see done.