-
-
Notifications
You must be signed in to change notification settings - Fork 750
Description
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:
distributed/distributed/client.py
Lines 360 to 372 in 1a1953d
| @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:
distributed/distributed/client.py
Lines 328 to 331 in 1a1953d
| 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:
distributed/distributed/client.py
Lines 636 to 732 in 1a1953d
| 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.