Idea #21132
closed
Document request objects in arvados.api_resources
Description
In arvados.api_resources, all the API methods are documented as returning an API resource directly. This isn't correct. Instead they return a request object that you must execute() to make the API query and get the response.
Document this object. The very simplest core of it is along the lines of:
T = TypeVar('T', bound=Dict)
class ArvadosAPIRequest(Generic[T]):
def execute(self, num_retries: int=0) -> T: ...
But check googleapiclient to see if there are other methods, or execute arguments, worth documenting for users. (If there's an existing typestub for the library, we might consider using that as a base, if licensing allows it.) This definition can probably just go in the static part of the generated file in discovery2pydoc.py.
Once this is defined, all the API methods need their return type updated from T to ArvadosAPIRequest[T]. That's return_annotation in Method.signature in discovery2pydoc.
Updated by 
Updated by