Project

General

Profile

Actions

Story #21132

closed

Document request objects in arvados.api_resources

Added by Brett Smith 4 months ago. Updated 3 months ago.

Status:
Resolved
Priority:
Normal
Assigned To:
Category:
Documentation
Start date:
11/18/2023
Due date:
% Done:

100%

Estimated time:
(Total: 0.00 h)
Story points:
0.5
Release relationship:
Auto

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.


Subtasks 1 (0 open1 closed)

Task #21202: Review 21132-api-resources-fixesResolvedPeter Amstutz11/18/2023

Actions
Actions

Also available in: Atom PDF