Documentation / type hinting for `Future.status`

[bcbnz]

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:

https://github.com/dask/distributed/blob/1a1953d7a5ddca21ed9fc032e6d83039c7d191af/distributed/client.py#L360-L372

This inner state variable is set to a FutureState instance during _bind_late:

https://github.com/dask/distributed/blob/1a1953d7a5ddca21ed9fc032e6d83039c7d191af/distributed/client.py#L328-L331

The definition of FutureState does not include any typehinting or documentation of its status options:

https://github.com/dask/distributed/blob/1a1953d7a5ddca21ed9fc032e6d83039c7d191af/distributed/client.py#L636-L732

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.

[jacobtomlinson]

That sounds about right to me. I expect if there are other states then mypy will complain when you try to add the Literal hint anyway. Feel free to ping me for review on the PR.

[bcbnz]

@jacobtomlinson PR added. mypy didn't find any other states, the state transitions are done by FutureState methods so that makes sense.