Add basic docs for python client
Now a user can more easily find out how to update StoryBoard via the python client. Story: 2000710 Task: 3190 Change-Id: Ie59933344c24bca59477d75fa589a063d8866c6f
This commit is contained in:
Zara
parent
58d9f14af5
commit
3decaa7452
28
README.rst
28
README.rst
|
|
@ -17,5 +17,29 @@ Features
|
|||
Notes
|
||||
-----
|
||||
|
||||
There is no command to run this; rather it can be imported into other
|
||||
scripts.
|
||||
This is the StoryBoard python client! It lets you interact with
|
||||
StoryBoard from the comfort of your own terminal! There is no
|
||||
command to run this; instead you can import it into scripts. This
|
||||
lets you perform complex actions on things in StoryBoard, eg: add an
|
||||
helpful comment on all stories with 'cannot store contact information'
|
||||
in the description, pointing users at the relevant docs, but only
|
||||
if there is no comment to this effect already. (There is an example
|
||||
of such a script in :doc:`usage`)
|
||||
|
||||
Some sample commands are given in usage.rst. In general, most
|
||||
resources (ie: stories, tasks, projects, and so on)
|
||||
have a ``get_all()`` and ``get()`` method. The latter takes
|
||||
the resource's id as a parameter, thought it can also take
|
||||
other attributes (eg: tag name).
|
||||
|
||||
To create a new resource, use the ``create()`` method. The
|
||||
necessary parameters depend on the resource, and if not
|
||||
documented, can be worked out from the relevant .py
|
||||
file in the code for the StoryBoard API.
|
||||
|
||||
The ``update()`` method will update mutable fields of the resource (again,
|
||||
these vary depending on the resource).
|
||||
|
||||
Finally, ``delete()`` will delete things.
|
||||
|
||||
Happy task-tracking!
|
||||
|
|
|
|||
|
|
@ -4,4 +4,96 @@ Usage
|
|||
|
||||
To use python-storyboardclient in a project::
|
||||
|
||||
TBD
|
||||
from storyboardclient.v1 import client
|
||||
api_url="http://storyboard-dev.openstack.org/api/v1"
|
||||
access_token="$MY_ACCESS_TOKEN"
|
||||
storyboard = client.Client(api_url, access_token)
|
||||
|
||||
That will not work with storyboard-dev because of certificates, but that demos the syntax.
|
||||
|
||||
Some sample commands to get things::
|
||||
|
||||
get_stories = storyboard.stories.get_all()
|
||||
get_comments_on_one_story = storyboard.stories.get(1).comments.list()
|
||||
get_tags_on_one_story = storyboard.stories.get(1).tags()
|
||||
get_all_story_timeline_events = storyboard.stories.get(1).events.get_all()
|
||||
get_worklists = storyboard.worklists.get_all()
|
||||
get_worklists_in_board = storyboard.worklists.board_id.get(2)
|
||||
get_due_dates = storyboard.due_dates.get_all()
|
||||
get_due_dates_for_board = storyboard.due_dates.get_all(board_id=2)
|
||||
get_users_in_team = storyboard.teams.get(1).users.get_all()
|
||||
get_subscriptions = storyboard.subscriptions.get_all()
|
||||
get_preferences_for_one_user = storyboard.users.get(1).user_preferences.get_all()
|
||||
get_subscription_events = storyboard.subscription_events.get_all()
|
||||
get_tokens_for_one_user = storyboard.users.get(1).user_tokens.list()
|
||||
get_milestones = storyboard.milestones.get_all()
|
||||
get_branches = storyboard.branches.get_all()
|
||||
get_system_info = storyboard.system_info.get(None)
|
||||
|
||||
|
||||
|
||||
|
||||
Some sample commands to create things::
|
||||
|
||||
|
||||
create_story = storyboard.stories.create(title="brand new invalid story with no tasks")
|
||||
create_task = storyboard.tasks.create(title="new task with default settings", project_id=2, story_id=3)
|
||||
create_branch = storyboard.branches.create(project_id=21, name='newbranch')
|
||||
create_worklist = storyboard.worklists.create(title='new worklist', automatic=False)
|
||||
create_board = storyboard.boards.create(title="new board", lanes='')
|
||||
|
||||
|
||||
|
||||
|
||||
Some sample commands to update things::
|
||||
|
||||
update_branch_title = storyboard.branches.update(id=21, name='new name')
|
||||
update_worklist = storyboard.worklists.update(id=296, automatic=True)
|
||||
update_board = storyboard.boards.update(id=3, title="new title")
|
||||
|
||||
|
||||
|
||||
Note: there is currently no single endpoint for permissions of the form
|
||||
api/v1/permissions. There are endpoints specific to some resources, eg:
|
||||
api/v1/worklists/1/permissions . The python client does not support
|
||||
these yet (patches welcome!).
|
||||
|
||||
|
||||
Misc example script-snippets::
|
||||
|
||||
|
||||
get_stories = storyboard.stories.get_all()
|
||||
for story in get_stories:
|
||||
if "blah" in story.description:
|
||||
print story
|
||||
|
||||
for i in range (981277, 2000690):
|
||||
try:
|
||||
story = storyboard.stories.get(i)
|
||||
print story
|
||||
except Exception as e:
|
||||
print e
|
||||
|
||||
Longer sample script::
|
||||
|
||||
from storyboardclient.v1 import client
|
||||
|
||||
storyboard = client.Client(api_url="http://storyboard-dev.openstack.org/api/v1", access_token="$MY_ACCESS_TOKEN")
|
||||
|
||||
stories = storyboard.stories.get_all()
|
||||
|
||||
for story in stories:
|
||||
try:
|
||||
if 'Cannot store contact information' in story.description and 'Friendlybot' not in story.description:
|
||||
story.comments.create(content="This needs your gerrit preferred e-mail address to match a primary e-mail address for a foundation individual member account.\n \n If you already followed the instructions at http://docs.openstack.org/infra/manual/developers.html#account-setup - in the specified order! - and still get that, see https://ask.openstack.org/question/56720 for additional troubleshooting tips.")
|
||||
storyboard.stories.update(id=story.id, description=story.description + '\n \n Friendlybot was here!')
|
||||
except:
|
||||
pass
|
||||
|
||||
|
||||
TODO:
|
||||
|
||||
Some examples of `delete` commands
|
||||
Sections on updating board and worklist items need filling in.
|
||||
Timeline events for boards and worklists need adding.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue