Differential D724

Update "writing tasks for taskotron" in docs
ClosedPublic
Actions

Authored by mkrizek on Jan 14 2016, 3:16 PM.

Tags

None

Subscribers

None

Details

Reviewers

kparal
tflink
jskladan

Maniphest Tasks

T679: update "writing tasks for taskotron" in the libtaskotron documentation

Commits

rLTRN226a55a5f5f2: Update "writing tasks for taskotron" in docs

Summary

Fixes T679

Test Plan

doit builddocs

Diff Detail

Repository

rLTRN libtaskotron

Lint

Automatic diff as part of commit; lint not applicable.

Unit

Automatic diff as part of commit; unit tests not applicable.

mkrizek retitled this revision from to Update "writing tasks for taskotron" in docs.Jan 14 2016, 3:16 PM

mkrizek updated this object.

mkrizek edited the test plan for this revision. (Show Details)

mkrizek added reviewers: tflink, kparal, jskladan.

mkrizek added a task: T679: update "writing tasks for taskotron" in the libtaskotron documentation.

mkrizek added a dependency: D723: Do not crash when a check does not provide result.Jan 14 2016, 3:16 PM

tflink accepted this revision.Jan 14 2016, 3:18 PM

This revision is now accepted and ready to land.Jan 14 2016, 3:18 PM

Note: I also updated examplebodhi check since we mention it as an example. https://bitbucket.org/fedoraqa/task-examplebodhi/commits/d40b5f380bf40ff6222c08348023a14b0e558eb7

Closed by commit rLTRN226a55a5f5f2: Update "writing tasks for taskotron" in docs (authored by mkrizek). · Explain WhyJan 18 2016, 12:00 PM

This revision was automatically updated to reflect the committed changes.

Revision Contents

			Path	Packages
M			docs/source/writingtasks.rst (73 lines)

Diff 1863

docs/source/writingtasks.rst

1	.. _writing-tasks-for-taskotron:	1		.. _writing-tasks-for-taskotron:
2		2
3	===========================	3		===========================
4	Writing Tasks for Taskotron	4		Writing Tasks for Taskotron
5	===========================	5		===========================
6		6
7	While the eventual target for most tasks will be to run in a production system,	7		While the eventual target for most tasks will be to run in a production system,
8	one of libtaskotron's features is that it can be run without the overhead of	8		one of libtaskotron's features is that it can be run without the overhead of
9	a full production-like system.	9		a full production-like system.
10		10
11	To learn more about what can be done with taskotron, see :ref:`what-can-i-do-with-taskotron`.	11		To learn more about what can be done with taskotron, see :ref:`what-can-i-do-with-taskotron`.
12		12
13	.. warning::
14
15	Taskotron is still very young. At the moment, this document is both the
16	direction that we want to take in the near future and features that currently
17	exist in libtaskotron.
18
19	If you follow this tutorial, be aware that things will be changing. Do not
20	expect libtaskotron to have a stable API yet and be aware that the interfaces
21	may change drastically with little notice.
22
23	Once the interfaces stabilize a bit more, this warning will be edited or
24	removed.
25
26	In order to write tasks, you must :ref:`install-libtaskotron` on your local	13		In order to write tasks, you must :ref:`install-libtaskotron` on your local
27	machine if you aren't running from git.	14		machine if you aren't running from git.
28		15
29	Examples	16		Examples
30	========	17		========
31		18
32	examplebodhi	19		examplebodhi
33	------------	20		------------
▲ Show 20 Lines • Show All 93 Lines • ▼ Show 20 Line(s)		113	.. code-block:: yaml
127		114
128	actions:	115		actions:
129	# we can use bodhi_id and arch as variables here because they're defined	116		# we can use bodhi_id and arch as variables here because they're defined
130	# for us by the runner which also verifies that all required input listed	117		# for us by the runner which also verifies that all required input listed
131	# above is present before executing the task	118		# above is present before executing the task
132	- name: download bodhi update	119		- name: download bodhi update
133	bodhi:	120		bodhi:
134	action: download	121		action: download
135	bodhi_id: ${bodhi_id}	122		update_id: ${bodhi_id}
136	arch: ${arch}	123		arch: ${arch}
137	export: bodhi_downloads	124		export: bodhi_downloads
138		125
139		126
140	# notice how the third item under python is 'rpmfiles' and this matches	127		# notice how the third item under python is 'rpmfiles' and this matches
141	# the arg name in mytask.py. Anything outside of 'file' and 'callable'	128		# the arg name in mytask.py. Anything outside of 'file' and 'callable'
142	# are passed in as kwargs to the specified python callable.	129		# are passed in as kwargs to the specified python callable.
143	- name: run mytask	130		- name: run mytask
Show All 10 Lines		140	- name: report mytask results to resultsdb
154	resultsdb:	141		resultsdb:
155	results: ${mytask_output}	142		results: ${mytask_output}
156		143
157	.. this needs to be fixed, this output is doctored since it doesn't actually	144		.. this needs to be fixed, this output is doctored since it doesn't actually
158	work.	145		work.
159		146
160	We can execute this new task using::	147		We can execute this new task using::
161		148
162	$ python runtask.py -i foo-1.2-3.fc99 -t bodhi_id -a x86_64 ../task-mytask/mytask.yml	149		$ python runtask.py -i FEDORA-2016-8760e32d9b -t bodhi_id -a x86_64 ../task-mytask/mytask.yml
163		150
164		151
165	The output from this task should end with::	152		The output from this task should end with::
166		153
167	Running mytask on foo-1.2-3.fc99.x86_64.rpm	154		Running mytask on FEDORA-2016-8760e32d9b
168		155		[libtaskotron] 15:00:40 CRITICAL Traceback (most recent call last):
169	[libtaskotron:logger.py:34] 2014-05-14 21:30:30 CRITICAL Traceback (most recent call last):	156		File "runtask.py", line 10, in <module>
170	File "runtask.py", line 4, in <module>	157		main.main()
171	runner.main()	158		File "/home/mkrizek/devel/libtaskotron/libtaskotron/main.py", line 151, in main
172	File "/home/tflink/code/taskotron/libtaskotron/libtaskotron/runner.py", line 192, in main	159		overlord.start()
173	task_runner.run()	160		File "/home/mkrizek/devel/libtaskotron/libtaskotron/overlord.py", line 95, in start
174	File "/home/tflink/code/taskotron/libtaskotron/libtaskotron/runner.py", line 31, in run	161		runner.execute()
175	self.do_actions()	162		File "/home/mkrizek/devel/libtaskotron/libtaskotron/executor.py", line 56, in execute
176	File "/home/tflink/code/taskotron/libtaskotron/libtaskotron/runner.py", line 105, in do_actions	163		self._run()
177	self.do_single_action(action)	164		File "/home/mkrizek/devel/libtaskotron/libtaskotron/executor.py", line 93, in _run
178	File "/home/tflink/code/taskotron/libtaskotron/libtaskotron/runner.py", line 94, in do_single_action	165		self._do_actions()
179	self.envdata)	166		File "/home/mkrizek/devel/libtaskotron/libtaskotron/executor.py", line 131, in _do_actions
180	File "/home/tflink/code/taskotron/libtaskotron/libtaskotron/directives/resultsdb_directive.py", line 136, in process	167		self._do_single_action(action)
		168		File "/home/mkrizek/devel/libtaskotron/libtaskotron/executor.py", line 152, in _do_single_action
		169		self.arg_data)
		170		File "/home/mkrizek/devel/libtaskotron/libtaskotron/directives/resultsdb_directive.py", line 196, in process
181	raise TaskotronDirectiveError("Failed to load 'results': %s" % e.message)	171		raise TaskotronDirectiveError("Failed to load 'results': %s" % e.message)
182	TaskotronDirectiveError: Failed to load 'results': Failed to parse YAML contents: Missing plan in the YAML source	172		TaskotronDirectiveError: Failed to load 'results': Failed to parse YAML contents: empty input
183		173
184	We're not actually passing result-YAML output from our task, so let's get that fixed.	174		We're not actually passing result-YAML output from our task, so let's get that fixed.
185		175
186	Actually Doing Something	176		Actually Doing Something
187	------------------------	177		------------------------
188		178
189	The Python code for ``mytask.py`` above doesn't really do anything at all, so let's	179		The Python code for ``mytask.py`` above doesn't really do anything at all, so let's
190	make it do something:	180		make it do something:
Show All 26 Lines		206	.. code-block:: python
217		207
218	from libtaskotron import check	208		from libtaskotron import check
219		209
220	def run_mytask(rpmfiles, bodhi_id):	210		def run_mytask(rpmfiles, bodhi_id):
221	"""run through all passed in rpmfiles and emit result-YAML saying they all passed"""	211		"""run through all passed in rpmfiles and emit result-YAML saying they all passed"""
222		212
223	print "Running mytask on %s" % bodhi_id	213		print "Running mytask on %s" % bodhi_id
224		214
225	details = []
226	result = 'PASSED'	215		result = 'PASSED'
227	note = 'from testing-pending to testing'	216		note = 'from testing-pending to testing'
228	detail = check.CheckDetail(bodhi_id, check.ReportType.BODHI_UPDATE,	217		detail = check.CheckDetail(bodhi_id, check.ReportType.BODHI_UPDATE, result, note)
229	result, note)
230	for rpmfile in rpmfiles['downloaded_rpms']:	218		for rpmfile in rpmfiles['downloaded_rpms']:
231	detail.store(rpmfile, printout=False)	219		detail.store(rpmfile, printout=False)
232		220
233	return check.export_YAML(detail)	221		return check.export_YAML(detail)
234		222
235	Now if we run the task we get output that ends with::	223		Now if we run the task we get output that ends with::
236		224
237	[libtaskotron:resultsdb_directive.py:123] 2014-05-15 09:17:44 INFO Reporting to ResultsDB is disabled.	225		[libtaskotron] 10:01:03 INFO Reporting to ResultsDB is disabled. Once enabled, the following would get reported:
238	INFO:libtaskotron:Reporting to ResultsDB is disabled.
239	[libtaskotron:runner.py:198] 2014-05-15 09:17:44 INFO
240	results:	226		results:
241	- item: foo-1.2-3.fc99	227		- item: FEDORA-2016-8760e32d9b
242	type: bodhi_update
243	outcome: PASSED
244	note: from testing-pending to testing	228		note: from testing-pending to testing
		229		outcome: PASSED
		230		type: bodhi_update
245		231
246	Working with CheckDetail Objects	232		Working with CheckDetail Objects
247	--------------------------------	233		--------------------------------
248		234
249	Check can have one of these outcomes (with increasing priority): ``PASSED``,	235		Check can have one of these outcomes (with increasing priority): ``PASSED``,
250	``INFO``, ``FAILED``, ``NEEDS_INSPECTION``, ``ABORTED`` and ``CRASHED``. These	236		``INFO``, ``FAILED``, ``NEEDS_INSPECTION``, ``ABORTED`` and ``CRASHED``. These
251	are available as a list (where higher index means bigger priority) in	237		are available as a list (where higher index means bigger priority) in
252	:py:attr:`CheckDetail.outcome_priority <libtaskotron.check.CheckDetail.outcome_priority>`.	238		:py:attr:`CheckDetail.outcome_priority <libtaskotron.check.CheckDetail.outcome_priority>`.
Show All 13 Lines		249	.. code-block:: python
266	import random	252		import random
267		253
268	from libtaskotron import check	254		from libtaskotron import check
269		255
270	def random_choice(_):	256		def random_choice(_):
271	return random.choice(['PASSED', 'FAILED', 'ABORTED'])	257		return random.choice(['PASSED', 'FAILED', 'ABORTED'])
272		258
273	def run_mytask(rpmfiles, bodhi_id):	259		def run_mytask(rpmfiles, bodhi_id):
274	"""run through all passed in rpmfiles and emit result-YAML. randomly report	260		"""run through all passed in rpmfiles and emit result-YAML. randomly report failure or pass"""
275	failure or pass"""
276		261
277	print "Running mytask on %s" % bodhi_id	262		print "Running mytask on %s" % bodhi_id
278		263
279	seed = random.random()	264		seed = random.random()
280	random.seed(seed)	265		random.seed(seed)
281		266
282	results = [(rpmfile, random_choice(rpmfile)) for rpmfile in rpmfiles['downloaded_rpms']]	267		results = [(rpmfile, random_choice(rpmfile)) for rpmfile in rpmfiles['downloaded_rpms']]
283		268
Show All 36 Lines