A Future has a status property. The current documentation only says Returns the status and that the output is a string.
The definition of this is a property which returns the status of an inner state variable:
|
@property |
|
def status(self): |
|
"""Returns the status |
|
|
|
Returns |
|
------- |
|
str |
|
The status |
|
""" |
|
if self._state: |
|
return self._state.status |
|
else: |
|
return None |
This inner state variable is set to a FutureState instance during _bind_late:
|
if self.key in self._client.futures: |
|
self._state = self._client.futures[self.key] |
|
else: |
|
self._state = self._client.futures[self.key] = FutureState(self.key) |
The definition of FutureState does not include any typehinting or documentation of its status options:
|
class FutureState: |
|
"""A Future's internal state. |
|
|
|
This is shared between all Futures with the same key and client. |
|
""" |
|
|
|
__slots__ = ("_event", "key", "status", "type", "exception", "traceback") |
|
|
|
def __init__(self, key: str): |
|
self._event = None |
|
self.key = key |
|
self.exception = None |
|
self.status = "pending" |
|
self.traceback = None |
|
self.type = None |
|
|
|
def _get_event(self): |
|
# Can't create Event eagerly in constructor as it can fetch |
|
# its IOLoop from the wrong thread |
|
# (https://github.com/tornadoweb/tornado/issues/2189) |
|
event = self._event |
|
if event is None: |
|
event = self._event = asyncio.Event() |
|
return event |
|
|
|
def cancel(self, reason=None, msg=None): |
|
"""Cancels the operation""" |
|
self.status = "cancelled" |
|
self.exception = FutureCancelledError(key=self.key, reason=reason, msg=msg) |
|
self._get_event().set() |
|
|
|
def finish(self, type=None): |
|
"""Sets the status to 'finished' and sets the event |
|
|
|
Parameters |
|
---------- |
|
type : any |
|
The type |
|
""" |
|
self.status = "finished" |
|
self._get_event().set() |
|
if type is not None: |
|
self.type = type |
|
|
|
def lose(self): |
|
"""Sets the status to 'lost' and clears the event""" |
|
self.status = "lost" |
|
self._get_event().clear() |
|
|
|
def retry(self): |
|
"""Sets the status to 'pending' and clears the event""" |
|
self.status = "pending" |
|
self._get_event().clear() |
|
|
|
def set_error(self, exception, traceback): |
|
"""Sets the error data |
|
|
|
Sets the status to 'error'. Sets the exception, the traceback, |
|
and the event |
|
|
|
Parameters |
|
---------- |
|
exception: Exception |
|
The exception |
|
traceback: Exception |
|
The traceback |
|
""" |
|
_, exception, traceback = clean_exception(exception, traceback) |
|
|
|
self.status = "error" |
|
self.exception = exception |
|
self.traceback = traceback |
|
self._get_event().set() |
|
|
|
def done(self): |
|
"""Returns 'True' if the event is not None and the event is set""" |
|
return self._event is not None and self._event.is_set() |
|
|
|
def reset(self): |
|
"""Sets the status to 'pending' and clears the event""" |
|
self.status = "pending" |
|
if self._event is not None: |
|
self._event.clear() |
|
|
|
async def wait(self, timeout=None): |
|
"""Wait for the awaitable to complete with a timeout. |
|
|
|
Parameters |
|
---------- |
|
timeout : number, optional |
|
Time in seconds after which to raise a |
|
``dask.distributed.TimeoutError`` |
|
""" |
|
await wait_for(self._get_event().wait(), timeout) |
|
|
|
def __repr__(self): |
|
return f"<{self.__class__.__name__}: {self.status}>" |
Looking at the places where the status is set, it appears the possible values are {"pending", "cancelled", "finished", "lost", "error"}. This would be useful to note in the documentation for Future.status. It also seems like this could be type-hinted as Literal (with the possible values).
I am happy to create a pull request for this, but wanted to check I have correctly analysed it before I do so.
A
Futurehas astatusproperty. The current documentation only saysReturns the statusand that the output is a string.The definition of this is a property which returns the status of an inner state variable:
distributed/distributed/client.py
Lines 360 to 372 in 1a1953d
This inner state variable is set to a
FutureStateinstance during_bind_late:distributed/distributed/client.py
Lines 328 to 331 in 1a1953d
The definition of
FutureStatedoes not include any typehinting or documentation of itsstatusoptions:distributed/distributed/client.py
Lines 636 to 732 in 1a1953d
Looking at the places where the status is set, it appears the possible values are {"pending", "cancelled", "finished", "lost", "error"}. This would be useful to note in the documentation for
Future.status. It also seems like this could be type-hinted asLiteral(with the possible values).I am happy to create a pull request for this, but wanted to check I have correctly analysed it before I do so.