Differential D119

convert docstrings of directives to sphinx format
ClosedPublic
Actions

Authored by garretraziel on Jun 4 2014, 12:06 PM.

Details

Reviewers
kparal
tflink
Maniphest Tasks
T164: convert docstrings to sphinx format
Commits
rLTRN8c82af1eea32: convert docstrings of directives to sphinx format
Summary

Convert docstrings of modules in libtaskotron/directives/
directory into sphinx format.

Test Plan

generate sphinx documentation for every module in
directives directory with ":members:", ":undoc-members:" and
":private-members:"

Diff Detail

Repository
rLTRN libtaskotron
Lint
Lint Skipped
Unit
Unit Tests Skipped
garretraziel retitled this revision from to convert docstrings of directives to sphinx format.Jun 4 2014, 12:06 PM
garretraziel updated this object.
garretraziel edited the test plan for this revision. (Show Details)
garretraziel added reviewers: tflink, kparal.
kparal requested changes to this revision.Jun 4 2014, 12:30 PM
kparal added inline comments.
libtaskotron/directives/bodhi_comment_directive.py
142–143

This must be

:param parsed_comments: already existing AutoQA comments for
 the update
:type parsed_comments: list of dict
295–306

You can use a proper reST "bold" here.

299
``noarch``

looks better

303–305

It's nice to use

``True``

and similarly for False. It's not required, but it looks better (denotes the values) in the generated docs. Similarly for the 0 above. And similarly in other docstrings.

369–373

This gets distorted, you need to make it a preformatted block.

374
``checkname`` in ``env_data``
This revision now requires changes to proceed.Jun 4 2014, 12:30 PM
garretraziel updated this revision to Diff 351.Jun 5 2014, 9:13 AM
  • correct sphinx formating in directives
kparal added a comment.EditedJun 5 2014, 9:21 AM

Looks good, no problems spotted.

@tflink: Are the directives expected to be added into library.rst? Because otherwise it's in Sphinx format, but not visible anywhere.

libtaskotron/directives/bodhi_comment_directive.py
142

I guess this should read Taskotron :-)

garretraziel added a comment.Jun 5 2014, 11:10 AM

@tflink: another thing is, from what I understand, classes without "main" docstring (that docstring right after class XY:) won't appear in result at all, even when they have docstrings in some of their methods. And methods/classes with underscore at the beginning of their name won't appear there either. To include both, one must add :undoc-members: and
:private-members: besides :members:. Are we planning to ad these into library.rst too?

garretraziel updated this revision to Diff 364.Jun 6 2014, 7:56 AM
  • AutoQA -> Taskotron
tflink added a subscriber: roshi.Jun 9 2014, 10:50 AM

Are the directives expected to be added into library.rst?

I hadn't been planning on it, no. The plan had been to use the directive documentation stuff that @roshi is working on in D93 instead. Do you think that it would be better to add them to library.rst?

another thing is, from what I understand, classes without "main" docstring (that docstring right after class XY:) won't appear in result at all, even when they have docstrings in some of their methods. And methods/classes with underscore at the beginning of their name won't appear there either. To include both, one must add :undoc-members: and :private-members: besides :members:.

I thought that just using :members: would pull in everything that had a docstring, regardless of whether the class itself had a docstring but I could be wrong on that one.

kparal accepted this revision.Jun 10 2014, 8:22 AM

OK, let's commit this as it is and deal with the rest in D93.

This revision is now accepted and ready to land.Jun 10 2014, 8:22 AM
garretraziel closed this revision.Jun 10 2014, 8:34 AM
garretraziel updated this revision to Diff 372.

Closed by commit rLTRN8c82af1eea32 (authored by Garret Raziel <boloomka@gmail.com>).

Revision Contents

Diff 372

View Options

libtaskotron/directives/bodhi_comment_directive.py

Show First 20 Lines • Show All 64 Lines • ▼ Show 20 Line(s)50class BodhiUpdateState:
65 65​
66 def num_results(self): 66​ def num_results(self):
67 ''' Retrieve the number of results currently held ''' 67​ ''' Retrieve the number of results currently held '''
68 return len(self.result_history) 68​ return len(self.result_history)
69 69​
70 def add_result(self, new_result): 70​ def add_result(self, new_result):
71 ''' Update the current state with a new result. 71​ ''' Update the current state with a new result.
72 72​
73 Args: 73​ :param dict new_result: a dictionary containing the following keys:
74 new_result: a dictionary containing the following keys: 74​ ``time`` (datetime object), ``testname``, ``result``, ``arch``
75 time (datetime object), testname, result, arch ​
76 ''' 75​ '''
77 76​
78 self.result_history.append(new_result) 77​ self.result_history.append(new_result)
79 78​
80 # copy the current test state so that we can compare later 79​ # copy the current test state so that we can compare later
81 old_state = self.test_states.copy() 80​ old_state = self.test_states.copy()
82 81​
83 # for depcheck, we only care about i386 and x86_64 arches 82​ # for depcheck, we only care about i386 and x86_64 arches
▲ Show 20 Lines • Show All 47 Lines • ▼ Show 20 Line(s)129 def did_test_change(self):
131 ''' Determine whether the state of any tests changed with the addition 130​ ''' Determine whether the state of any tests changed with the addition
132 of the last result''' 131​ of the last result'''
133 return self.test_change 132​ return self.test_change
134 133​
135 134​
136def _is_comment_email_needed(update_name, parsed_comments, new_result, 135​def _is_comment_email_needed(update_name, parsed_comments, new_result,
137 kojitag): 136​ kojitag):
138 ''' 137​ '''
139 Determines whether or not to send an email with the comment posted to bodhi. 138​ Determines whether or not to send an email with the comment posted to bodhi.
140 Uses previous comments on update in order to determine current state 139​ Uses previous comments on update in order to determine current state
141 140​
142 Args: 141​ :param str update_name: name of the update to be tested
143 update_name -- name of the update to be tested 142​ :param parsed_comments: already existing Taskotron comments for
kparalUnsubmitted
Not Done

I guess this should read Taskotron :-)

144 parsed_comments -- already existing AutoQA comments for the update 143​ the update
kparalUnsubmitted
Not Done

This must be

:param parsed_comments: already existing AutoQA comments for
 the update
:type parsed_comments: list of dict
145 new_result -- the new result to be posted 144​ :type parsed_comments: list of dict
146 kojitag -- the koji tag being tested (affects the expected tests) 145​ :param dict new_result: the new result to be posted
146​ :param str kojitag: the koji tag being tested (affects the expected tests)
147​ :rtype: bool
147 ''' 148​ '''
148 149​
149 Config = config.get_config() 150​ Config = config.get_config()
150 151​
151 log.info("checking email needed for %s (%s)", update_name, kojitag) 152​ log.info("checking email needed for %s (%s)", update_name, kojitag)
152 # compute current state 153​ # compute current state
153 update_state = BodhiUpdateState(update_name, kojitag=kojitag) 154​ update_state = BodhiUpdateState(update_name, kojitag=kojitag)
154 for result in parsed_comments: 155​ for result in parsed_comments:
Show All 10 Lines
165 166​
166 if new_state is PASS and current_state is not FAIL: 167​ if new_state is PASS and current_state is not FAIL:
167 send_email = False 168​ send_email = False
168 169​
169 return send_email 170​ return send_email
170 171​
171def _parse_result_from_comment(comment): 172​def _parse_result_from_comment(comment):
172 ''' 173​ '''
173 Parses timestamp and results from bodhi comment 174​ Parses timestamp and results from bodhi comment
174 175​
175 Args: 176​ :param dict comment: the ``comment`` part of bodhi update object
176 comment -- the 'comment' part of bodhi update object 177​ :rtype: dict
177 ''' 178​ '''
178 179​
179 comment_time = datetime.datetime.strptime(comment['timestamp'], '%Y-%m-%d %H:%M:%S') 180​ comment_time = datetime.datetime.strptime(comment['timestamp'], '%Y-%m-%d %H:%M:%S')
180 181​
181 # comment form to match: 182​ # comment form to match:
182 # 'Taskotron: %s test %s on %s. Result log: %s' 183​ # 'Taskotron: %s test %s on %s. Result log: %s'
183 # note that it isn't looking for the autoqa user right now, that needs to 184​ # note that it isn't looking for the autoqa user right now, that needs to
184 # be done in any code that calls this 185​ # be done in any code that calls this
Show All 12 Lines
197 198​
198 return {'time':comment_time, 'testname':test_name, 199​ return {'time':comment_time, 'testname':test_name,
199 'result':result, 'arch':arch} 200​ 'result':result, 'arch':arch}
200 201​
201 202​
202def _already_commented(bodhi_api, update, testname, arch): 203​def _already_commented(bodhi_api, update, testname, arch):
203 '''Check if Taskotron comment is already posted. 204​ '''Check if Taskotron comment is already posted.
204 205​
205 Args: 206​ :param update: Bodhi update object --or-- update title --or-- update ID
206 update -- Bodhi update object --or-- update title --or-- update ID --or-- package NVR 207​ --or-- package NVR
207 testname -- the name of the test 208​ :param str testname: the name of the test
208 arch -- tested architecture 209​ :param str arch: tested architecture
209 210​
210 Note: Only NVR allowed, not ENVR. See https://fedorahosted.org/bodhi/ticket/592. 211​ Note: Only NVR allowed, not ENVR. See https://fedorahosted.org/bodhi/ticket/592.
211 212​
212 Returns: 213​ :return: Tuple containing old result and time when the last comment was posted.
213 Tuple containing old result and time when the last comment was posted. 214​ If no comment is posted yet, or it is, but the update
214 If no comment is posted yet, or it is, but the update 215​ has been modified since, tuple will contain two empty strings.
215 has been modified since, tuple will contain two empty strings. ​
216 216​
217 Throws: 217​ :raises TaskotronValueError: if no such update can be found
218 TaskotronValueError -- if no such update can be found ​
219 ''' 218​ '''
220 219​
221 Config = config.get_config() 220​ Config = config.get_config()
222 221​
223 # if we received update title or ID, let's convert it to update object first 222​ # if we received update title or ID, let's convert it to update object first
224 if isinstance(update, basestring): 223​ if isinstance(update, basestring):
225 u = bodhi_api.query_update(update) 224​ u = bodhi_api.query_update(update)
226 if u: 225​ if u:
Show All 16 Lines
243 # check whether update was modified after the last posted comment 242​ # check whether update was modified after the last posted comment
244 if update['date_modified'] > comment_time: 243​ if update['date_modified'] > comment_time:
245 return ('','') 244​ return ('','')
246 return (old_result, comment_time) 245​ return (old_result, comment_time)
247 246​
248def _is_comment_needed(old_result, comment_time, result, time_span = None): 247​def _is_comment_needed(old_result, comment_time, result, time_span = None):
249 '''Check if the comment is meant to be posted. 248​ '''Check if the comment is meant to be posted.
250 249​
251 Args: 250​ :param str old_result: the result of the last test
252 old_result -- the result of the last test 251​ :param str comment_time: the comment time of the last test
253 comment_time -- the comment time of the last test 252​ :param str result: the result of the test
254 result -- the result of the test 253​ :param int time_span: waiting period (in minutes) before posting the same comment
255 time_span -- waiting period (in minutes) before posting the same comment ​
256 254​
257 Returns: 255​ :return: ``True`` if the comment will be posted, ``False`` otherwise.
258 True if the comment will be posted, False otherwise. 256​ :rtype: bool
259 ''' 257​ '''
260 # the first comment or a comment with different result, post it 258​ # the first comment or a comment with different result, post it
261 if not old_result or old_result != result: 259​ if not old_result or old_result != result:
262 return True 260​ return True
263 261​
264 # If we got here, it means that the comment with the same result has been 262​ # If we got here, it means that the comment with the same result has been
265 # already posted, we now need to determine whether we can post the 263​ # already posted, we now need to determine whether we can post the
266 # comment again or not. 264​ # comment again or not.
Show All 22 Lines
289 287​
290 return True 288​ return True
291 289​
292 290​
293def _post_testresult(bodhi_api, update, testname, result, url, 291​def _post_testresult(bodhi_api, update, testname, result, url,
294 arch = 'noarch', karma = 0, doreport='onchange'): 292​ arch = 'noarch', karma = 0, doreport='onchange'):
295 '''Post comment and karma to bodhi 293​ '''Post comment and karma to bodhi
296 294​
297 Args: 295​ :param str update: the **title** of the update comment on
298 update -- the *title* of the update comment on 296​ :param str testname: the name of the test
299 testname -- the name of the test 297​ :param str result: the result of the test
300 result -- the result of the test 298​ :param str url: url of the result of the test
301 url -- url of the result of the test 299​ :param str arch: tested architecture (default ``noarch``)
kparalUnsubmitted
Not Done
``noarch``

looks better

302 arch -- tested architecture (default 'noarch') 300​ :param int karma: karma points (default ``0``)
303 karma -- karma points (default 0) 301​ :param str doreport: set to 'all' to force posting bodhi comment
304 doreport -- set to 'all' to force posting bodhi comment 302​
305 303​ :return: ``True`` if comment was posted successfully or comment wasn't
306 Returns: 304​ meant to be posted (either posting is turned off or comment was
307 True if comment was posted successfully or comment wasn't meant to be 305​ already posted), ``False`` otherwise.
kparalUnsubmitted
Not Done

It's nice to use

``True``

and similarly for False. It's not required, but it looks better (denotes the values) in the generated docs. Similarly for the 0 above. And similarly in other docstrings.

308 posted (either posting is turned off or comment was already posted), 306​ :rtype: bool
kparalUnsubmitted
Not Done

You can use a proper reST "bold" here.

309 False otherwise. ​
310 ''' 307​ '''
311 308​
312 # TODO when new bodhi releases, add update identification by UPDATEID support 309​ # TODO when new bodhi releases, add update identification by UPDATEID support
313 310​
314 Config = config.get_config() 311​ Config = config.get_config()
315 312​
316 if not update or not testname or not result or url == None: 313​ if not update or not testname or not result or url == None:
317 log.error("bodhi_post_testresults() requires non-empty update, "\ 314​ log.error("bodhi_post_testresults() requires non-empty update, "\
▲ Show 20 Lines • Show All 44 Lines • ▼ Show 20 Line(s)357 except Exception as e:
362 return False 359​ return False
363 360​
364 return True 361​ return True
365 362​
366 363​
367 364​
368class BodhiCommentDirective(BaseDirective): 365​class BodhiCommentDirective(BaseDirective):
369 """The bodhi_comment directive interfaces with Bodhi to create 366​ """The bodhi_comment directive interfaces with Bodhi to create
370 a comment in Bodhi 367​ a comment in Bodhi
371 368​
372 format: "bodhi_comment: 369​ Format::
370​
371​ bodhi_comment:
373 results: <TAP13> 372​ results: <TAP13>
374 doreport: [all, onchange]" 373​ doreport: [all, onchange]
kparalUnsubmitted
Not Done

This gets distorted, you need to make it a preformatted block.

375 Also note, that 'checkname' needs to be present in env_data. 374​
kparalUnsubmitted
Not Done
``checkname`` in ``env_data``
375​ Also note, that ``checkname`` needs to be present in ``env_data``.
376 """ 376​ """
377 def __init__(self, bodhi_api=None): 377​ def __init__(self, bodhi_api=None):
378 378​
379 if bodhi_api: 379​ if bodhi_api:
380 self.bodhi_api = bodhi_api 380​ self.bodhi_api = bodhi_api
381 else: 381​ else:
382 self.bodhi_api = bodhi_utils.BodhiUtils() 382​ self.bodhi_api = bodhi_utils.BodhiUtils()
383 383​
▲ Show 20 Lines • Show All 58 Lines • Show Last 20 Lines
View Options

libtaskotron/directives/bodhi_directive.py

Show All 10 Lines
11from libtaskotron.exceptions import TaskotronDirectiveError 11​from libtaskotron.exceptions import TaskotronDirectiveError
12 12​
13directive_class = 'BodhiDirective' 13​directive_class = 'BodhiDirective'
14 14​
15class BodhiDirective(BaseDirective): 15​class BodhiDirective(BaseDirective):
16 """The bodhi directive interfaces with Bodhi to facilitate 16​ """The bodhi directive interfaces with Bodhi to facilitate
17 various bodhi actions. 17​ various bodhi actions.
18 18​
19 format: "bodhi: 19​ Format::
20​
21​ bodhi:
20 action: [download] 22​ action: [download]
21 <command args>" 23​ <command args>
22 24​
23 Valid Commands: 25​ Valid Commands:
24 26​
25 download 27​ download
26 Downloads rpms of builds from update specified by its name or id 28​ Downloads rpms of builds from update specified by its name or id
27 format: "bodhi: 29​
30​ Format::
31​
32​ bodhi:
28 action: download 33​ action: download
29 bodhi_id: <name or id of update> 34​ bodhi_id: <name or id of update>
30 arch=<desired arch>" 35​ arch=<desired arch>
31 """ 36​ """
32 def __init__(self, bodhi_api=None, koji_session=None): 37​ def __init__(self, bodhi_api=None, koji_session=None):
33 38​
34 if bodhi_api: 39​ if bodhi_api:
35 self.bodhi_api = bodhi_api 40​ self.bodhi_api = bodhi_api
36 else: 41​ else:
37 self.bodhi_api = bodhi.BodhiUtils() 42​ self.bodhi_api = bodhi.BodhiUtils()
38 43​
▲ Show 20 Lines • Show All 56 Lines • Show Last 20 Lines
View Options

libtaskotron/directives/createrepo_directive.py

1from __future__ import absolute_import 1​from __future__ import absolute_import
2import subprocess as sub 2​import subprocess as sub
3from libtaskotron.directives import BaseDirective 3​from libtaskotron.directives import BaseDirective
4from libtaskotron.logger import log 4​from libtaskotron.logger import log
5from libtaskotron.exceptions import TaskotronDirectiveError 5​from libtaskotron.exceptions import TaskotronDirectiveError
6 6​
7directive_class = 'CreaterepoDirective' 7​directive_class = 'CreaterepoDirective'
8 8​
9 9​
10class CreaterepoDirective(BaseDirective): 10​class CreaterepoDirective(BaseDirective):
11 def process(self, input_data, env_data): 11​ def process(self, input_data, env_data):
12 """For the createrepo directive, we're expecting a yaml declaration of 12​ """For the createrepo directive, we're expecting a yaml declaration of
13 the form "createrepo: repodir=/path/to/some/dir" 13​ the form ``createrepo: repodir=/path/to/some/dir``
14 """ 14​ """
15 15​
16 repodir = input_data['repodir'] 16​ repodir = input_data['repodir']
17 17​
18 log.info('running createrepo on %s', repodir) 18​ log.info('running createrepo on %s', repodir)
19 19​
20 p = sub.Popen(['createrepo', repodir], stdout=sub.PIPE, stderr=sub.PIPE) 20​ p = sub.Popen(['createrepo', repodir], stdout=sub.PIPE, stderr=sub.PIPE)
21 21​
22 output, errors = p.communicate() 22​ output, errors = p.communicate()
23 23​
24 if p.returncode: 24​ if p.returncode:
25 raise TaskotronDirectiveError(errors) 25​ raise TaskotronDirectiveError(errors)
26 26​
27 log.debug(output) 27​ log.debug(output)
28 28​
29 return output 29​ return output
View Options

libtaskotron/directives/dummy_directive.py

1from __future__ import absolute_import 1​from __future__ import absolute_import
2from libtaskotron.directives import BaseDirective 2​from libtaskotron.directives import BaseDirective
3from libtaskotron.exceptions import TaskotronDirectiveError 3​from libtaskotron.exceptions import TaskotronDirectiveError
4 4​
5directive_class = 'DummyDirective' 5​directive_class = 'DummyDirective'
6 6​
7 7​
8class DummyDirective(BaseDirective): 8​class DummyDirective(BaseDirective):
9 """The dummy directive is just what it sounds like - a directive that 9​ """The dummy directive is just what it sounds like - a directive that
10 doesn't do anything other than return a status and (optionally) a message. 10​ doesn't do anything other than return a status and (optionally) a message.
11 11​
12 It is primarially meant for testing the runner or as a placeholder while 12​ It is primarially meant for testing the runner or as a placeholder while
13 writing new tasks. 13​ writing new tasks.
14 14​
15 format: 15​ Format::
16​
16 dummy: result=<result> [msg=<some string message>] 17​ dummy: result=<result> [msg=<some string message>]
17 required params: result 18​ required params: result
18 optional params: msg 19​ optional params: msg
19 """ 20​ """
20 21​
21 def process(self, input_data, env_data): 22​ def process(self, input_data, env_data):
22 expected_result = input_data['result'] 23​ expected_result = input_data['result']
23 24​
24 if expected_result.lower() == 'fail': 25​ if expected_result.lower() == 'fail':
25 raise TaskotronDirectiveError("This is a dummy directive and " 26​ raise TaskotronDirectiveError("This is a dummy directive and "
26 "configured to fail") 27​ "configured to fail")
27 28​
28 if 'msg' in input_data: 29​ if 'msg' in input_data:
29 return input_data['msg'] 30​ return input_data['msg']
View Options

libtaskotron/directives/koji_directive.py

1from __future__ import absolute_import 1​from __future__ import absolute_import
2 2​
3from libtaskotron.koji_utils import KojiClient 3​from libtaskotron.koji_utils import KojiClient
4from libtaskotron.logger import log 4​from libtaskotron.logger import log
5from libtaskotron.directives import BaseDirective 5​from libtaskotron.directives import BaseDirective
6from libtaskotron.exceptions import TaskotronDirectiveError 6​from libtaskotron.exceptions import TaskotronDirectiveError
7from libtaskotron import rpm_utils 7​from libtaskotron import rpm_utils
8 8​
9directive_class = 'KojiDirective' 9​directive_class = 'KojiDirective'
10 10​
11class KojiDirective(BaseDirective): 11​class KojiDirective(BaseDirective):
12 """The koji directive interfaces with Koji to facilitate various koji 12​ """The koji directive interfaces with Koji to facilitate various koji
13 actions. 13​ actions.
14 14​
15 format: "koji: target_dir=<target_dir> command=[download, download_tag] <command args> 15​ Format::
16​
17​ koji: target_dir=<target_dir> command=[download, download_tag] <command args>
16 18​
17 Valid Commands: 19​ Valid Commands:
18 20​
19 download 21​ download
20 Downloads the koji build specified as "koji_build" 22​ Downloads the koji build specified as ``koji_build``
21 format: 23​
22 "koji: command=download koji_build=<N(E)VR to download> arch=<desired arch> 24​ Format::
25​
26​ koji: command=download koji_build=<N(E)VR to download> arch=<desired arch>
23 download_tag 27​ download_tag
24 Downloads rpms tagged by "koji_tag" 28​ Downloads rpms tagged by ``koji_tag``
25 format: 29​
26 "koji: command=download_tag koji_tag=<koji tag to download> arch=<desired arch> 30​ Format::
31​
32​ koji: command=download_tag koji_tag=<koji tag to download> arch=<desired arch>
27 """ 33​ """
28 34​
29 def __init__(self, koji_session=None): 35​ def __init__(self, koji_session=None):
30 super(KojiDirective, self).__init__() 36​ super(KojiDirective, self).__init__()
31 if koji_session is None: 37​ if koji_session is None:
32 self.koji = KojiClient(koji_session) 38​ self.koji = KojiClient(koji_session)
33 else: 39​ else:
34 self.koji = koji_session 40​ self.koji = koji_session
▲ Show 20 Lines • Show All 59 Lines • Show Last 20 Lines
View Options

libtaskotron/directives/python_directive.py

1from __future__ import absolute_import 1​from __future__ import absolute_import
2import imp 2​import imp
3import os 3​import os
4 4​
5from libtaskotron.directives import BaseDirective 5​from libtaskotron.directives import BaseDirective
6from libtaskotron.exceptions import TaskotronDirectiveError 6​from libtaskotron.exceptions import TaskotronDirectiveError
7 7​
8directive_class = 'PythonDirective' 8​directive_class = 'PythonDirective'
9 9​
10 10​
11class PythonDirective(BaseDirective): 11​class PythonDirective(BaseDirective):
12 """The python directive is designed to execute a piece of python code as 12​ """The python directive is designed to execute a piece of python code as
13 part of task execution. Given a callable name 'dothis_thing', possible 13​ part of task execution. Given a callable name ``dothis_thing``, possible
14 implementations in the loaded code could include: 14​ implementations in the loaded code could include:
15 15​
16​ ::
17​
16 class TaskClass(object): 18​ class TaskClass(object):
17 def my_task(self): 19​ def my_task(self):
18 return "I'm a task class method!" 20​ return "I'm a task class method!"
19 21​
20 _instantiated_class = TaskClass() 22​ _instantiated_class = TaskClass()
21 23​
22 task_class_target = _instantiated_class.my_task 24​ task_class_target = _instantiated_class.my_task
23 25​
24 In this case, you could pass in 'task_class_target' as the callable arg 26​ In this case, you could pass in ``task_class_target`` as the callable arg
27​
28​ ::
25 29​
26 class EmbeddedCallClass(object): 30​ class EmbeddedCallClass(object):
27 def __call__(self): 31​ def __call__(self):
28 return "I'm a __call__ method in a class!" 32​ return "I'm a __call__ method in a class!"
29 33​
30 embedded_task_target = EmbeddedCallClass() 34​ embedded_task_target = EmbeddedCallClass()
31 35​
32 In this case, you could pass in 'embedded_task_target' as the callable arg 36​ In this case, you could pass in ``embedded_task_target`` as the callable arg
37​
38​ ::
33 39​
34 def task_method(): 40​ def task_method():
35 return "I'm a task method!" 41​ return "I'm a task method!"
36 42​
37 And in this third case, you would pass in 'task_method' as the callable arg 43​ And in this third case, you would pass in ``task_method`` as the callable arg
44​
45​ Format::
38 46​
39 format: ​
40 python: 47​ python:
41 file=<python filename> callable=<method name> [<kwargname>=<kwargvalue>' 48​ file=<python filename> callable=<method name> [<kwargname>=<kwargvalue>]
42 required params: <python filename>, callable 49​
43 optional params: farther key/value pairs, to be passed into the callable 50​ * required params: ``<python filename>``, ``callable``
44 as kwargs 51​ * optional params: farther key/value pairs, to be passed into the callable
52​ as kwargs
45 """ 53​ """
46 54​
47 def _do_getattr(self, module, name): 55​ def _do_getattr(self, module, name):
48 """Isolation of getattr to make the code more easily testable 56​ """Isolation of getattr to make the code more easily testable
49 57​
50 @param module module from which to getattr from 58​ :param module module: module from which to getattr from
51 @param name name of object to getattr 59​ :param str name: name of object to getattr
52 @returns object retrieved from module 60​ :returns: object retrieved from module
53 """ 61​ """
54 62​
55 return getattr(module, name) 63​ return getattr(module, name)
56 64​
57 def execute(self, task_module, method_name, kwargs): 65​ def execute(self, task_module, method_name, kwargs):
58 """Execute a callable in the specified module 66​ """Execute a callable in the specified module
59 67​
60 @param task_module module containing the specified callable 68​ :param module task_module: module containing the specified callable
61 @param method_name name of callable to execute 69​ :param str method_name: name of callable to execute
62 @param kwargs kwargs to pass as parameters into the callable 70​ :param dict kwargs: kwargs to pass as parameters into the callable
63 @return output from the executed method 71​ :returns: output from the executed method
64 """ 72​ """
65 73​
66 task_method = self._do_getattr(task_module, method_name) 74​ task_method = self._do_getattr(task_module, method_name)
67 75​
68 output = task_method(**kwargs) 76​ output = task_method(**kwargs)
69 77​
70 if output is not None and not isinstance(output, basestring): 78​ if output is not None and not isinstance(output, basestring):
71 raise TaskotronDirectiveError( 79​ raise TaskotronDirectiveError(
72 "Callable task method must return string or None, actual " 80​ "Callable task method must return string or None, actual "
73 "returned type: %s" % type(output)) 81​ "returned type: %s" % type(output))
74 82​
75 return output 83​ return output
76 84​
77 def load_pyfile(self, filename): 85​ def load_pyfile(self, filename):
78 """Import python code specified 86​ """Import python code specified
79 87​
80 @param filename absolute path to the python file 88​ :param str filename: absolute path to the python file
81 """ 89​ """
82 90​
83 task_importname = 'runtask_%s' % os.path.basename(filename).rstrip( 91​ task_importname = 'runtask_%s' % os.path.basename(filename).rstrip(
84 '.py') 92​ '.py')
85 task = imp.load_source(task_importname, filename) 93​ task = imp.load_source(task_importname, filename)
86 94​
87 return task_importname, task 95​ return task_importname, task
88 96​
89 def checkfile(self, filename): 97​ def checkfile(self, filename):
90 """Check to see if the file exists 98​ """Check to see if the file exists
91 99​
92 @param filename abspath to the filename 100​ :param str filename: abspath to the filename
93 @throws TaskotronDirectiveError if the file does not exist 101​ :raises TaskotronDirectiveError: if the file does not exist
94 """ 102​ """
95 103​
96 if not os.path.exists(filename): 104​ if not os.path.exists(filename):
97 raise TaskotronDirectiveError("The file %s does not exist!" 105​ raise TaskotronDirectiveError("The file %s does not exist!"
98 % filename) 106​ % filename)
99 107​
100 def process(self, input_data, env_data): 108​ def process(self, input_data, env_data):
101 """For the python directive, we're expecting a yaml declaration of the 109​ """For the python directive, we're expecting a yaml declaration of the
102 form 110​ form
103 "python: ​
104 file=<python file> callable=<method name> [kwarg1=something ...]" ​
105 111​
106 @param input_data dictionary of all kwargs from yaml declaration, 112​ ::
113​
114​ python:
115​ file=<python file> callable=<method name> [kwarg1=something ...]
116​
117​ :param dict input_data: dictionary of all kwargs from yaml declaration,
107 including callable and file 118​ including callable and file
108 @param env_data information on the environment in which we're running 119​ :param dict env_data: information on the environment in which we're
109 @return output from the method specified, this is expected to be TAP 120​ running
121​ :returns: output from the method specified, this is expected to be TAP
110 output 122​ output
111 """ 123​ """
112 124​
113 if 'callable' not in input_data or 'file' not in input_data: 125​ if 'callable' not in input_data or 'file' not in input_data:
114 detected_args = ', '.join(input_data.keys()) 126​ detected_args = ', '.join(input_data.keys())
115 raise TaskotronDirectiveError( 127​ raise TaskotronDirectiveError(
116 "The python directive requires both 'callable' and 'file' " 128​ "The python directive requires both 'callable' and 'file' "
117 "arguments. Detected arguments: %s" % detected_args) 129​ "arguments. Detected arguments: %s" % detected_args)
Show All 13 Lines
View Options

libtaskotron/directives/resultsdb_directive.py

Show All 30 Lines
31directive_class = 'ResultsdbDirective' 31​directive_class = 'ResultsdbDirective'
32 32​
33class ResultsdbDirective(BaseDirective): 33​class ResultsdbDirective(BaseDirective):
34 """The resultsdb directive interfaces with ResultsDB to store results. 34​ """The resultsdb directive interfaces with ResultsDB to store results.
35 35​
36 When reporting is disabled, the directive checks whether the input is a valid 36​ When reporting is disabled, the directive checks whether the input is a valid
37 TAP and lists out the details that would have been reported. 37​ TAP and lists out the details that would have been reported.
38 38​
39 format: "resultsdb: results=<TAP13> 39​ Format::
40​
41​ resultsdb: results=<TAP13>
40 """ 42​ """
41 43​
42 def __init__(self, resultsdb = None): 44​ def __init__(self, resultsdb = None):
43 self.resultsdb = resultsdb 45​ self.resultsdb = resultsdb
44 46​
45 conf = config.get_config() 47​ conf = config.get_config()
46 self.masterurl = conf.taskotron_master 48​ self.masterurl = conf.taskotron_master
47 self.task_stepname = conf.buildbot_task_step 49​ self.task_stepname = conf.buildbot_task_step
Show All 36 Lines85 if refurl is not None:
84 url = refurl 86​ url = refurl
85 87​
86 jobdata = self.resultsdb.create_job(url, status='SCHEDULED', name=name) 88​ jobdata = self.resultsdb.create_job(url, status='SCHEDULED', name=name)
87 self.resultsdb.update_job(id=jobdata['id'], status='RUNNING') 89​ self.resultsdb.update_job(id=jobdata['id'], status='RUNNING')
88 90​
89 return jobdata 91​ return jobdata
90 92​
91 def complete_resultsdb_job(self, jobid): 93​ def complete_resultsdb_job(self, jobid):
92 """ Change the resultsdb job to a status of 'COMPLETED', indicating 94​ """ Change the resultsdb job to a status of ``COMPLETED``, indicating
93 that the reporting is complete. 95​ that the reporting is complete.
94 96​
95 :param int jobid: The resultsdb jobid to be modified 97​ :param int jobid: The resultsdb jobid to be modified
96 :returns: json representation of returned data from the resultsdb instance 98​ :returns: json representation of returned data from the resultsdb instance
97 """ 99​ """
98 return self.resultsdb.update_job(jobid, status='COMPLETED') 100​ return self.resultsdb.update_job(jobid, status='COMPLETED')
99 101​
100 def parse_jobid(self, jobid): 102​ def parse_jobid(self, jobid):
101 """ Parse the incoming jobid which should either be '-1' to indicate 103​ """ Parse the incoming jobid which should either be ``-1`` to indicate
102 that dummy values should be used or in the form of <builder>/<buildid>. 104​ that dummy values should be used or in the form of <builder>/<buildid>.
103 105​
104 If the passed in format is invalid, no exceptions will be raised but a 106​ If the passed in format is invalid, no exceptions will be raised but a
105 warning message will be emitted to logs 107​ warning message will be emitted to logs
106 108​
107 :param str jobid: jobid from runner 109​ :param str jobid: jobid from runner
108 :returns: (builder, buildid) 110​ :returns: (builder, buildid)
109 """ 111​ """
▲ Show 20 Lines • Show All 71 Lines • Show Last 20 Lines
View Options

libtaskotron/directives/yumrepoinfo_directive.py

Show All 24 Lines
25 25​
26from libtaskotron.exceptions import TaskotronDirectiveError 26​from libtaskotron.exceptions import TaskotronDirectiveError
27from libtaskotron.logger import log 27​from libtaskotron.logger import log
28 28​
29directive_class = 'YumrepoinfoDirective' 29​directive_class = 'YumrepoinfoDirective'
30 30​
31class YumrepoinfoDirective(BaseDirective): 31​class YumrepoinfoDirective(BaseDirective):
32 """A directive for translating koji tag into a set of yum repos. 32​ """A directive for translating koji tag into a set of yum repos.
33 The directive returns a dictionary having koji_tag as the key, and 33​ The directive returns a dictionary having ``koji_tag`` as the key, and
34 URL for the respective repo as a value. 34​ URL for the respective repo as a value.
35 If the koji tag specified by koji_tag argument has any parent repos 35​ If the koji tag specified by ``koji_tag`` argument has any parent repos
36 (e.g. f20-updates is a child of f20), all the repos from the koji_tag 36​ (e.g. f20-updates is a child of f20), all the repos from the ``koji_tag``
37 and up are returned. 37​ and up are returned.
38 If the koji_tag is '-pending', the '-pending' is stripped (as it is not 38​ If the ``koji_tag`` is ``-pending``, the ``-pending`` is stripped (as it is
39 a repo), and then the code works the same. 39​ not a repo), and then the code works the same.
40 It is also possible to assign koji_tag to 'rawhide'. 40​ It is also possible to assign ``koji_tag`` to ``rawhide``.
41 41​
42 format: "yumrepoinfo: 42​ Format::
43 koji_tag=<tag> 43​
44 arch=<arch> 44​ yumrepoinfo:
45​ koji_tag=<tag>
46​ arch=<arch>
45 """ 47​ """
46 48​
47 def __init__(self, repoinfo = None): 49​ def __init__(self, repoinfo = None):
48 self.repoinfo = repoinfo 50​ self.repoinfo = repoinfo
49 51​
50 def process(self, input_data, env_data): 52​ def process(self, input_data, env_data):
51 53​
52 if 'koji_tag' not in input_data or 'arch' not in input_data: 54​ if 'koji_tag' not in input_data or 'arch' not in input_data:
Show All 29 Lines