Project

General

Profile

Actions

Story #19791

open

Write Python SDK overview

Added by Brett Smith 11 days ago. Updated 3 days ago.

Status:
In Progress
Priority:
Normal
Assigned To:
Category:
SDKs
Target version:
Start date:
11/25/2022
Due date:
% Done:

0%

Estimated time:
(Total: 0.00 h)
Story points:
-

Description

Write a document that explains:

  • The Python SDK dynamically implements interfaces from the Arvados API.
  • Every resource type has a corresponding class.
  • API methods can be called as instance methods.
  • Arguments to methods are passed as keyword arguments.
  • Explain some of the abstractions like calling .execute().
  • Link to documentation for the Arvados API and google-api-python-client for further reading as appropriate.

The goal is for this to be a single document that helps people understand the patterns that the API client follows and how it relates to the Arvados API.

IMO you can implement this by building out the current "Examples" page of the documentation. The orientation should be high-level enough to stay useful even after we have full reference documentation from issue #18799.


Subtasks 1 (1 open0 closed)

Task #19800: Review 19791-python-api-overviewIn ProgressPeter Amstutz11/25/2022

Actions
Actions #1

Updated by Peter Amstutz 9 days ago

  • Target version set to 2022-12-07 Sprint
Actions #2

Updated by Peter Amstutz 9 days ago

  • Assigned To set to Brett Smith
Actions #3

Updated by Brett Smith 4 days ago

  • Status changed from New to In Progress
Actions #4

Updated by Peter Amstutz 3 days ago

  • In the get section, I would split the 1st and 2nd examples into two code blocks.
  • In the list section, it would be better to direct people to use arvados.util.keyset_list_all to handle paging instead of doing it manually.
  • I think an additional section that describes using group().contents() to get project contents would be a good idea.
  • For create it's better to have the object contents in a field corresponding to the object type, so instead of this:
project = arv_client.groups().create(
    body={
        'name': 'Python SDK Test Project',
        'group_class': 'project',
    },
    ensure_unique_name=True,
).execute()

Do this:

project = arv_client.groups().create(
    body={
        'group': {
            'name': 'Python SDK Test Project',
            'group_class': 'project'
        }
    },
    ensure_unique_name=True,
).execute()

(background here is that the second one is more correct to the API definition, the 1st one works because the Rails API does a fixup that moves fields from the top level into the object, but runs a small risk of confusion between top level parameters like 'limit' and 'select' and the object contents).

To modify an existing Arvados object, call the delete method for that resource type.

I think you meant "remove an existing Arvados object"

I don't think you want to go into the weeds of setting trash_at here. It would probably be simpler to just explain that some object types go into the trash and can be recovered, and some are deleted immediately. The ones that can be removed from the trash have an untrash method.

Actions #5

Updated by Brett Smith 3 days ago

All addressed @ 7abef669c except:

Peter Amstutz wrote in #note-4:

  • I think an additional section that describes using group().contents() to get project contents would be a good idea.

I think it would provide the best organization to leave this for the planned cookbook update. Right now this page covers just the API's common resource methods, and then mentions multiple times that you can use the same patterns to call other API methods. If we start covering those other methods, I don't know how we draw the line of which are worth including and which aren't. The cookbook already covers that subjective space of "stuff people ask about a lot," so let's just cover it there. (We might consider adding users/current too: that was covered in the old "Examples" page and I took it out for the same reasons.)

Actions

Also available in: Atom PDF