opendev/python-storyboardclient
Code Issues Proposed changes

Add basic docs for python client

Browse Source 
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 2016-08-30 13:41:30 +00:00
parent 58d9f14af5
commit 3decaa7452
2 changed files with 119 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
README.rst
View File

@ -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!

94
doc/source/usage.rst
View File

@ -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.