From 3decaa7452098dc886b31a0cd32dece5ff1b5223 Mon Sep 17 00:00:00 2001 From: Zara Date: Tue, 30 Aug 2016 13:41:30 +0000 Subject: [PATCH] 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 --- README.rst | 28 ++++++++++++- doc/source/usage.rst | 94 +++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 119 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 0c4c0bf..5d5c2d1 100644 --- a/README.rst +++ b/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! diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 43e45fc..a124052 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -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. +