Differential D98

docs: convert various modules to sphinx
ClosedPublic
Actions

Authored by kparal on May 14 2014, 5:03 PM.

Details

Reviewers
roshi
tflink
Maniphest Tasks
T164: convert docstrings to sphinx format
Commits
rLTRN1af4d1ccff72: docs: convert libtaskotron docstrings to sphinx
Summary

Also fix some links in index.

Test Plan

Docs look better.

Diff Detail

Lint
Lint Skipped
Unit
Unit Tests Skipped
roshi accepted this revision.May 15 2014, 12:42 AM

All the included changes look fine to me. It's a good place to work from moving forward.

tflink requested changes to this revision.May 15 2014, 2:56 AM

Overall, it looks really good. Just 2 little things that I think could be improved

libtaskotron/check.py
89–90

The docstring here is appended to the rendered docs in sphinx and is rather confusing. If nothing substantive is being added here, I think it should be removed.

114–115

I'd like to see this docstring changed slightly to make it more clear that this is setting the outcome. The values can stay with the constructor but the param should be listed

kparal added inline comments.May 15 2014, 9:12 AM
libtaskotron/check.py
89–90

We will have to tweak Sphinx rendering, I'd like it to display __init__() method header as well. But in this case, yes, I'll remove it. I was afraid that if you use an IDE capable of displaying docstrings, you wouldn't see any documentation when creating new CheckDetail instance. But at least with Spyder, it displays combined class+init documentation, so it's fine.

114–115

Sphinx solved this for us - it does not include property setter documentation into the generated docs at all:
http://stackoverflow.com/questions/17478040/how-can-i-generate-documentation-for-a-python-property-setter-using-sphinx

So we can either document the property fully in the getter, or in the class docstring. Since all of our other attributes are documented in the class docstring, I think it's more consistent to put it there. So I removed these See class documentation strings, and outcome is no longer visible in the generated docs as a standalone item.

kparal updated this revision.May 15 2014, 9:14 AM
  • address review concerns, add libtaskotron.exceptions docs
kparal updated this revision.May 15 2014, 10:24 AM
  • convert config and config_defaults to sphinx
kparal updated this revision.May 15 2014, 12:34 PM
  • convert file_utils to sphinx
  • convert python_utils to sphinx
  • convert rpm_utils to sphinx
  • convert logger to sphinx
  • convert koji_utils to sphinx
  • convert bodhi_utils to sphinx
tflink added inline comments.May 15 2014, 1:10 PM
libtaskotron/check.py
114–115

is the intent of the outcome() method pair to not be used much? It seems somewhat unwise to not document them at all, otherwise

kparal added inline comments.May 15 2014, 1:25 PM
libtaskotron/check.py
114–115

It's not a method, it's a property, therefore it externally looks and behaves as an attribute. And as all other attributes, it's documented in the class docstring. Do you think it's hard to find?

tflink accepted this revision.May 15 2014, 6:47 PM

Looks good to me, thanks for taking care of this

libtaskotron/check.py
114–115

nvm, I was reading this incorrectly :-/

kparal closed this revision.May 16 2014, 7:12 AM

Closed by commit rLTRN1af4d1ccff72 (authored by @kparal).

Revision Contents

Diff 279

View Options

conf/taskotron.yaml.example

Show First 20 Lines • Show All 61 Lines • ▼ Show 20 Line(s)
62 62​
63## ==== BODHI EMAIL section ==== 63​## ==== BODHI EMAIL section ====
64## These configuration options affect how Taskotron decideds to send emails 64​## These configuration options affect how Taskotron decideds to send emails
65## through Bodhi in specific situations. 65​## through Bodhi in specific situations.
66 66​
67## How long (in minutes) should we wait before allowing consequent test to 67​## How long (in minutes) should we wait before allowing consequent test to
68## re-post a 'FAILED' comment into Bodhi once again. 68​## re-post a 'FAILED' comment into Bodhi once again.
69## By default 3 days (3*24*60 = 4320). 69​## By default 3 days (3*24*60 = 4320).
70#bodhi_email_failed_span: 4320 70​#bodhi_posting_comments_span: 4320
71 71​
72 72​
73## ==== PATHS section ==== 73​## ==== PATHS section ====
74## Location of various pieces of the project. 74​## Location of various pieces of the project.
75 75​
76## The location of log files for Taskotron 76​## The location of log files for Taskotron
77#logdir: /var/log/taskotron 77​#logdir: /var/log/taskotron
78 78​
79​## The location of temporary files for Taskotron
80​#tmpdir: /var/tmp/taskotron
81​
79 82​
80## ==== SECRETS section ==== 83​## ==== SECRETS section ====
81## All login credentials and other secrets are here. If you add some secret 84​## All login credentials and other secrets are here. If you add some secret
82## here, make sure you make this file readable just for the right user accounts. 85​## here, make sure you make this file readable just for the right user accounts.
83 86​
84## FAS (Fedora Accounts System) credentials 87​## FAS (Fedora Accounts System) credentials
85## These credentials are used when reporting results into Bodhi. 88​## These credentials are used when reporting results into Bodhi.
86#fas_username: taskotron 89​#fas_username: taskotron
87#fas_password: '' 90​#fas_password: ''
88 91​
View Options

docs/source/index.rst

1========================== 1​==========================
2Libtaskotron Documentation 2​Libtaskotron Documentation
3========================== 3​==========================
4 4​
5What is libtaskotron? 5​What is libtaskotron?
6===================== 6​=====================
7 7​
8Libtaskotron is one of the core components which make up the `taskotron`_ 8​Libtaskotron is one of the core components which make up the `Taskotron`_
9system. Libtaskotron is responsible for running tasks written in the 9​system. Libtaskotron is responsible for running tasks described in the
10:ref:`taskyaml_section`. 10​:doc:`taskyaml` section.
11 11​
12While libtaskotron was designed for use with `Fedora <http://fedoraproject.org>`_, 12​While libtaskotron was designed for use with `Fedora <http://fedoraproject.org>`_,
13the Fedora specific parts are isolated and the core should be usable with any 13​the Fedora specific parts are isolated and the core should be usable with any
14recent Linux distribution. 14​recent Linux distribution.
15 15​
16Libtaskotron and Taskotron should be considered Alpha software. They are 16​Libtaskotron and Taskotron should be considered Alpha software. They are
17currently under very heavy development and will likely change until we stabilize 17​currently under very heavy development and will likely change until we stabilize
18the interfaces. 18​the interfaces.
19 19​
20Support 20​Support
21======= 21​=======
22Please direct questions and comments to either the `Fedora QA Devel List 22​Please direct questions and comments to either the `Fedora QA Devel List
23<https://admin.fedoraproject.org/mailman/listinfo/qa-devel>`_ or the `#fedora-qa` 23​<https://admin.fedoraproject.org/mailman/listinfo/qa-devel>`_ or the *#fedora-qa*
24IRC channel on `Freenode <http://freenode.net/>`_. 24​IRC channel on `Freenode <http://freenode.net/>`_.
25 25​
26 26​
27 27​
28.. _taskotron: https://fedoraproject.org/wiki/Taskotron 28​.. _Taskotron: https://fedoraproject.org/wiki/Taskotron
29 29​
30Contents 30​Contents
31======== 31​========
32 32​
33.. toctree:: 33​.. toctree::
34 :maxdepth: 1 34​ :maxdepth: 1
35 35​
36 devguide 36​ devguide
37 writing_tasks ​
38 library 37​ library
39 taskyaml 38​ taskyaml
40 39​
41 40​
42Indices and tables 41​Indices and tables
43================== 42​==================
44 43​
45* :ref:`genindex` 44​* :ref:`genindex`
46* :ref:`modindex` 45​* :ref:`modindex`
47* :ref:`search` 46​* :ref:`search`
48 47​
View Options

docs/source/library.rst

1===================== 1​=====================
2libtaskotron API docs 2​libtaskotron API docs
3===================== 3​=====================
4 4​
5This isn't final API documentation, more of an example of how we can do API docs. 5​This isn't final API documentation, more of an example of how we can do API docs.
6 6​
7Once more of our code is using sphinx-style docs, we can start finalizing the 7​Once more of our code is using sphinx-style docs, we can start finalizing the
8format for this page. 8​format for this page.
9 9​
10Note that the docs here are for libtaskotron library functions and don't 10​Note that the docs here are for libtaskotron library functions and don't
11include directives or task yaml details. 11​include directives or task yaml details.
12 12​
13 13​
14runner (one function with sphinx-style docstrings) 14​bodhi_utils
15================================================== 15​===========
16 16​
17.. automodule:: libtaskotron.runner 17​.. automodule:: libtaskotron.bodhi_utils
18 :members: 18​ :members:
19 19​
20check (no sphinx-style docstrings) 20​check
21================================== 21​=====
22 22​
23.. automodule:: libtaskotron.check 23​.. automodule:: libtaskotron.check
24 :members: 24​ :members:
25 25​
26​config
27​======
28​
29​.. automodule:: libtaskotron.config
30​ :members:
31​
32​config_defaults
33​===============
34​
35​.. automodule:: libtaskotron.config_defaults
36​ :members:
37​
38​exceptions
39​==========
40​
41​.. automodule:: libtaskotron.exceptions
42​ :members:
43​
44​file_utils
45​==========
46​
47​.. automodule:: libtaskotron.file_utils
48​ :members:
49​
50​koji_utils
51​==========
52​
53​.. automodule:: libtaskotron.koji_utils
54​ :members:
55​
56​logger
57​======
58​
59​.. automodule:: libtaskotron.logger
60​ :members:
61​
62​python_utils
63​============
64​
65​.. automodule:: libtaskotron.python_utils
66​ :members:
67​
68​rpm_utils
69​=========
70​
71​.. automodule:: libtaskotron.rpm_utils
72​ :members:
73​
74​runner
75​======
76​
77​.. automodule:: libtaskotron.runner
78​ :members:
79​
26yumrepoinfo 80​yumrepoinfo
27=========== 81​===========
28 82​
29.. automodule:: libtaskotron.yumrepoinfo 83​.. automodule:: libtaskotron.yumrepoinfo
30 :members: 84​ :members:
View Options

libtaskotron/bodhi_utils.py

Show All 9 Lines
10from . import rpm_utils 10​from . import rpm_utils
11from . import python_utils 11​from . import python_utils
12from . import exceptions as exc 12​from . import exceptions as exc
13from . import config 13​from . import config
14 14​
15class BodhiUtils(object): 15​class BodhiUtils(object):
16 '''Helper Bodhi methods. 16​ '''Helper Bodhi methods.
17 17​
18 Note: You can access the standard BodhiClient as self.client. 18​ :ivar fedora.client.BodhiClient client: Bodhi client instance
19 ''' 19​ '''
20 20​
21 def __init__(self, client=None): 21​ def __init__(self, client=None):
22 '''Create a new BodhiUtils instance. 22​ '''Create a new BodhiUtils instance.
23 @param client custom BodhiClient instance. If None, a default 23​
24 BodhiClient instance is used. 24​ :param client: custom :class:`BodhiClient` instance. If ``None``, a
25​ default BodhiClient instance is used.
25 ''' 26​ '''
26 27​
27 taskotron_config = config.get_config() 28​ taskotron_config = config.get_config()
28 username = taskotron_config.fas_username 29​ username = taskotron_config.fas_username
29 password = taskotron_config.fas_password 30​ password = taskotron_config.fas_password
30 bodhi_url = taskotron_config.bodhi_server 31​ bodhi_url = taskotron_config.bodhi_server
31 32​
32 if not client: 33​ if not client:
33 log.debug('creating bodhi client to %s' % bodhi_url) 34​ log.debug('creating bodhi client to %s' % bodhi_url)
34 self.client = fedora.client.bodhi.BodhiClient(username=username, 35​ self.client = fedora.client.bodhi.BodhiClient(username=username,
35 password=password, 36​ password=password,
36 base_url=bodhi_url) 37​ base_url=bodhi_url)
37 else: 38​ else:
38 self.client = client 39​ self.client = client
39 40​
40 41​
41 def query_update(self, package): 42​ def query_update(self, package):
42 '''Get the last Bodhi update matching criteria. 43​ '''Get the last Bodhi update matching criteria.
43 44​
44 @param package package NVR or package name or update title or 45​ :param str package: package NVR or package name or update title or
45 update ID 46​ update ID
46 Note: Only NVR allowed, not NEVR. See 47​
47 https://fedorahosted.org/bodhi/ticket/592. 48​ .. note::
48 @return most recent Bodhi update object matching criteria, or None 49​ Only NVR allowed, not NEVR. See
49 when no update is found. 50​ https://fedorahosted.org/bodhi/ticket/592.
51​ :return: most recent Bodhi update object matching criteria, or
52​ ``None`` when no update is found.
53​ :rtype: :class:`bunch.Bunch`
50 ''' 54​ '''
51 log.debug('Searching Bodhi updates for: %s', package) 55​ log.debug('Searching Bodhi updates for: %s', package)
52 res = self.client.query(package=package, limit=1) 56​ res = self.client.query(package=package, limit=1)
53 if res['updates']: 57​ if res['updates']:
54 return res['updates'][0] 58​ return res['updates'][0]
55 else: 59​ else:
56 return None 60​ return None
57 61​
58 62​
59 def build2update(self, builds, strict=False): 63​ def build2update(self, builds, strict=False):
60 '''Find matching Bodhi updates for provided builds. 64​ '''Find matching Bodhi updates for provided builds.
61 65​
62 @param builds builds to search for; iterable of strings in N(E)VR 66​ :param builds: builds to search for in N(E)VR format (``foo-1.2-3.fc20``
63 format (foo-1.2-3.fc20 or foo-4:1.2-3.fc20) 67​ or ``foo-4:1.2-3.fc20``)
64 @param strict if False, incomplete Bodhi updates are allowed. 68​ :type builds: iterable of str
65 If True, every Bodhi update will be compared with the set 69​ :param bool strict: if ``False``, incomplete Bodhi updates are allowed.
66 of provided builds. If there is an Bodhi update which 70​ If ``True``, every Bodhi update will be compared
67 contains builds not provided in @param builds, that update 71​ with the set of provided builds. If there is an
68 is marked as incomplete and removed from the result - i.e. 72​ Bodhi update which contains builds not provided in
69 all builds from @param builds that were part of this 73​ ``builds``, that update is marked as incomplete and
70 incomplete update are placed in the second dictionary of 74​ removed from the result - i.e. all builds from
71 the result tuple. 75​ ``builds`` that were part of this incomplete update
72 @return tuple of two dictionaries: 76​ are placed in the second dictionary of the result
73 * The first dict provides mapping between builds and their 77​ tuple.
74 updates where no error occured. 78​ :return: a tuple of two dictionaries:
75 {build (string): Bodhi update (Bunch)} 79​
76 * The second dict provides mapping between builds and their 80​ * The first dict provides mapping between ``builds`` and their
77 updates where some error occured. 81​ updates where no error occured.
78 {build (string): Bodhi update (Bunch) or None} 82​
79 The value is None if the matching Bodhi update could not be 83​ ``{build (string): Bodhi update (Bunch)}``
80 found (the only possible cause of failure if 84​ * The second dict provides mapping between ``builds`` and their
81 @param strict=False). Or the value is a Bodhi update that was 85​ updates where some error occured. The value is ``None`` if
82 incomplete (happens only if @param strict=True). 86​ the matching Bodhi update could not be found (the only
83 @raise TaskotronValueError if @param builds type is incorrect 87​ possible cause of failure if ``strict=False``). Or the value
88​ is a Bodhi update that was incomplete (happens only if
89​ ``strict=True``).
90​
91​ ``{build (string): Bodhi update (Bunch) or None}``
92​ :raise TaskotronValueError: if ``builds`` type is incorrect
84 ''' 93​ '''
85 # validate input params 94​ # validate input params
86 if not python_utils.listlike(builds): 95​ if not python_utils.listlike(builds):
87 raise exc.TaskotronValueError("Param 'builds' must be iterable, " 96​ raise exc.TaskotronValueError("Param 'builds' must be iterable, "
88 "and yours was: %s" % type(builds)) 97​ "and yours was: %s" % type(builds))
89 98​
90 build2update = {} 99​ build2update = {}
91 failures = {} 100​ failures = {}
▲ Show 20 Lines • Show All 49 Lines • Show Last 20 Lines
View Options

libtaskotron/check.py

Show All 25 Lines22class CheckDetail(object):
26 26​
27 For some checks, it's trivial to parse its output at the end of its 27​ For some checks, it's trivial to parse its output at the end of its
28 execution and evaluate the results. For some, however, it's much easier 28​ execution and evaluate the results. For some, however, it's much easier
29 to do this continuously during check execution. This is especially true 29​ to do this continuously during check execution. This is especially true
30 for multi-item checks (a single check providing results for many items - 30​ for multi-item checks (a single check providing results for many items -
31 builds, updates, etc). That's when this class comes very handy (it can be 31​ builds, updates, etc). That's when this class comes very handy (it can be
32 used even for the simple use cases, of course). 32​ used even for the simple use cases, of course).
33 33​
34 @classattr outcome_priority a tuple of outcome keywords sorted by priority 34​ :cvar outcome_priority: a tuple of :attr:`outcome` keywords sorted by
35 from the least important to the most important 35​ priority from the least important to the most
36 @attr item a string describing the item being tested; for example a build 36​ important
37 NVR ('vpnc-0.5-1.fc20'), update ID ('FEDORA-2014-3309') or a 37​ :ivar str item: a description the item being tested; for example a build NVR
38 repository name ('f20-updates') 38​ (``vpnc-0.5-1.fc20``), update ID (``FEDORA-2014-3309``) or a
39 @attr report_type a definition of the type of the object being checked; for 39​ repository name (``f20-updates``)
40 example 'a Koji build', 'a Bodhi update' or 'a yum 40​ :ivar str report_type: a definition of the type of the object being checked;
41 repository name'. The allowed values are attributes in 41​ for example 'a Koji build', 'a Bodhi update' or 'a
42 @class ReportType. You don't have to fill this in (or you 42​ yum repository name'. The allowed values are
43 can provide a custom string value), but the reporting 43​ attributes in :class:`ReportType`. You don't have to
44 directives react only to the known types (you can still 44​ fill this in (or you can provide a custom string
45 find it in ResultsDB, though). 45​ value), but the reporting directives react only to
46 @attr outcome a keyword specifying the final outcome of the check. Available 46​ the known types (you can always find it in ResultsDB,
47 outcome keywords: 47​ though).
48 * PASSED - everything went well 48​ :ivar str outcome: a keyword specifying the final outcome of the check.
49 * INFO - everything went well, but there is some important 49​ Available outcome keywords:
50 information that needs to be pointed out 50​
51 * FAILED - the item in question fails the check 51​ * PASSED - everything went well
52 * NEEDS_INSPECTION - the outcome can't be determined and a 52​ * INFO - everything went well, but there is some
53 manual inspection is needed 53​ important information that needs to be pointed out
54 * ABORTED - the check aborted itself because of some 54​ * FAILED - the item in question fails the check
55 unexpected problems, i.e. a necessary network 55​ * NEEDS_INSPECTION - the outcome can't be determined and
56 server is not reachable. Running this check with 56​ a manual inspection is needed
57 the same arguments later can help to mitigate 57​ * ABORTED - the check aborted itself because of some
58 this problem. 58​ unexpected problems, i.e. a necessary network server is
59 * CRASHED - the check crashed and did not provide usable 59​ not reachable. Running this check with the same
60 results 60​ arguments later can help to mitigate this problem.
61 If no outcome is set, this attribute returns NEEDS_INSPECTION. 61​ * CRASHED - the check crashed and did not provide usable
62 @attr summary a few words or one-sentence summary about the result of the 62​ results
63 check run (e.g. '5 WARNINGS, 1 ERROR' for an rpmlint result). 63​
64 Should not unnecessarily duplicate self.item or self.outcome, 64​ If no outcome has been set, this attribute returns
65 if possible. 65​ NEEDS_INSPECTION.
66 @attr output output from the check run (a list of strings). You can easily 66​
67 populate this by using @method store(), or you can modify it 67​ Raises :class:`TaskotronValueError` if you try to assign
68 directly (for example filter out some messages you don't want 68​ an unknown keyword.
69 to see in the check output). 69​ :ivar str summary: a few words or one-sentence summary about the result of
70 @attr keyvals all key-value pairs in this dictionary are stored in ResultsDB 70​ the check run (e.g. ``5 WARNINGS, 1 ERROR`` for an
71 as 'extra data'. This can be used to store e.g. a compose id 71​ rpmlint result). Should not unnecessarily duplicate
72 or a kernel version, if that information is important for 72​ :attr:`item` or :attr:`outcome`, if possible.
73 querying the results. Keep it as short as possible. 73​ :ivar output: output from the check run (a list of strings). You can easily
74​ populate this by using @method store(), or you can modify it
75​ directly (for example filter out some messages you don't want
76​ to see in the check output).
77​ :ivar dict keyvals: all key-value pairs in this dictionary are stored in
78​ ResultsDB as 'extra data'. This can be used to store
79​ e.g. a compose id or a kernel version, if that
80​ information is important for querying the results. Keep
81​ it as short as possible.
74 ''' 82​ '''
75 83​
76 outcome_priority = ('PASSED', 'INFO', 'FAILED', 'NEEDS_INSPECTION', 84​ outcome_priority = ('PASSED', 'INFO', 'FAILED', 'NEEDS_INSPECTION',
77 'ABORTED', 'CRASHED') 85​ 'ABORTED', 'CRASHED')
78 86​
79 87​
80 def __init__(self, item, report_type=None, outcome=None, summary='', 88​ def __init__(self, item, report_type=None, outcome=None, summary='',
81 output=None, keyvals=None): 89​ output=None, keyvals=None):
82 '''Create new CheckDetail. ​
83 For param descriptions see class docstring.''' ​
84 ​
85 # validate input 90​ # validate input
tflinkUnsubmitted
Not Done

The docstring here is appended to the rendered docs in sphinx and is rather confusing. If nothing substantive is being added here, I think it should be removed.

kparalAuthorUnsubmitted
Not Done

We will have to tweak Sphinx rendering, I'd like it to display __init__() method header as well. But in this case, yes, I'll remove it. I was afraid that if you use an IDE capable of displaying docstrings, you wouldn't see any documentation when creating new CheckDetail instance. But at least with Spyder, it displays combined class+init documentation, so it's fine.

86 if output is not None and not python_utils.listlike(output): 91​ if output is not None and not python_utils.listlike(output):
87 raise exc.TaskotronValueError("'output' parameter must be a list. " 92​ raise exc.TaskotronValueError("'output' parameter must be a list. "
88 "Yours was: %s" % type(output)) 93​ "Yours was: %s" % type(output))
89 if keyvals is not None and not isinstance(keyvals, collections.Mapping): 94​ if keyvals is not None and not isinstance(keyvals, collections.Mapping):
90 raise exc.TaskotronValueError("'keyvals' parameter must behave like" 95​ raise exc.TaskotronValueError("'keyvals' parameter must behave like"
91 " a dictionary. Yours was: %s" % type(keyvals)) 96​ " a dictionary. Yours was: %s" % type(keyvals))
92 97​
93 self.item = item 98​ self.item = item
94 self.report_type = report_type 99​ self.report_type = report_type
95 self._outcome = None 100​ self._outcome = None
96 if outcome: 101​ if outcome:
97 self.outcome = outcome 102​ self.outcome = outcome
98 self.summary = summary 103​ self.summary = summary
99 self.output = output or [] 104​ self.output = output or []
100 self.keyvals = keyvals or {} 105​ self.keyvals = keyvals or {}
101 106​
102 107​
103 @property 108​ @property
104 def outcome(self): 109​ def outcome(self):
105 '''See class documentation.''' ​
106 return self._outcome or 'NEEDS_INSPECTION' 110​ return self._outcome or 'NEEDS_INSPECTION'
107 111​
108 112​
109 @outcome.setter 113​ @outcome.setter
110 def outcome(self, value): 114​ def outcome(self, value):
111 '''See class documentation.''' ​
112 if value not in self.outcome_priority: 115​ if value not in self.outcome_priority:
tflinkUnsubmitted
Not Done

I'd like to see this docstring changed slightly to make it more clear that this is setting the outcome. The values can stay with the constructor but the param should be listed

kparalAuthorUnsubmitted
Not Done

Sphinx solved this for us - it does not include property setter documentation into the generated docs at all:
http://stackoverflow.com/questions/17478040/how-can-i-generate-documentation-for-a-python-property-setter-using-sphinx

So we can either document the property fully in the getter, or in the class docstring. Since all of our other attributes are documented in the class docstring, I think it's more consistent to put it there. So I removed these See class documentation strings, and outcome is no longer visible in the generated docs as a standalone item.

tflinkUnsubmitted
Not Done

is the intent of the outcome() method pair to not be used much? It seems somewhat unwise to not document them at all, otherwise

kparalAuthorUnsubmitted
Not Done

It's not a method, it's a property, therefore it externally looks and behaves as an attribute. And as all other attributes, it's documented in the class docstring. Do you think it's hard to find?

tflinkUnsubmitted
Not Done

nvm, I was reading this incorrectly :-/

113 raise exc.TaskotronValueError('Unknown outcome keyword: %s' % value) 116​ raise exc.TaskotronValueError('Unknown outcome keyword: %s' % value)
114 self._outcome = value 117​ self._outcome = value
115 118​
116 119​
117 def update_outcome(self, outcome): 120​ def update_outcome(self, outcome):
118 '''Update self.outcome with the provided value only and only if it has 121​ '''Update :attr:`outcome` with the provided value only and only if it
119 a higher priority than its current value (according to 122​ has a higher priority than its current value (according to
120 self.outcome_priority). Otherwise this call does nothing. 123​ :attr:`outcome_priority`). Otherwise this call does nothing.
121 124​
122 This is useful if your check performs a number of 'sub-tasks', each 125​ This is useful if your check performs a number of 'sub-tasks', each
123 passing or failing, and you want to final outcome to be the worst/most 126​ passing or failing, and you want to final outcome to be the worst/most
124 serious one of those. You can just keep calling self.update_outcome() 127​ serious one of those. You can just keep calling :meth:`update_outcome`
125 and the highest priority outcome type will be stored at self.outcome at 128​ and the highest priority outcome type will be stored at :attr:`outcome`
126 the end. 129​ at the end.
127 130​
128 @param outcome the outcome value to assign to self.outcome if it has a 131​ :param str outcome: the outcome value to assign to :attr:`outcome` if it
129 higher priority than its current value. Handles None 132​ has a higher priority than its current value.
130 values gracefully (no action). 133​ Handles ``None`` values gracefully (no action).
131 @throw TaskotronValueError if any of the outcome keywords are not 134​ :raise TaskotronValueError: if any of the outcome keywords are not
132 specified in @classatr outcome_priority''' 135​ specified in :attr:`outcome_priority`'''
133 if self.cmp_outcome(outcome, self._outcome) > 0: 136​ if self.cmp_outcome(outcome, self._outcome) > 0:
134 self.outcome = outcome 137​ self.outcome = outcome
135 138​
136 139​
137 def broken(self): 140​ def broken(self):
138 '''Tells whether the check outcome is set to one of the broken states 141​ '''Tells whether the check :attr:`outcome` is set to one of the broken
139 (i.e. ABORTED or CRASHED).''' 142​ states (i.e. ABORTED or CRASHED).'''
140 return self.outcome in ['ABORTED', 'CRASHED'] 143​ return self.outcome in ['ABORTED', 'CRASHED']
141 144​
142 145​
143 def store(self, message, printout=True): 146​ def store(self, message, printout=True):
144 '''Add a string to the CheckDetail output, and print it optionally as 147​ '''Add a string to the :attr:`output`, and print it optionally as well.
145 well. ​
146 148​
147 This is just a convenience method for most common use case, you can 149​ This is just a convenience method for most common use case, you can
148 of course always access and modify self.output directly, and print or 150​ of course always access and modify :attr:`output` directly, and print or
149 use logging facilities directly as well. This combines both into a 151​ use logging facilities directly as well. This combines both into a
150 single call. 152​ single call.
151 153​
152 @param message a string to store in self.output 154​ :param str message: a string to store in :attr:`output`
153 @param printout whether to print to standard output or not 155​ :param bool printout: whether to print to standard output or not
154 ''' 156​ '''
155 157​
156 self.output.append(message) 158​ self.output.append(message)
157 if printout: 159​ if printout:
158 print message 160​ print message
159 161​
160 162​
161 @classmethod 163​ @classmethod
162 def cmp_outcome(cls, outcome1, outcome2): 164​ def cmp_outcome(cls, outcome1, outcome2):
163 '''Compare two outcomes according to self.outcome_priority and return 165​ '''Compare two outcomes according to :attr:`outcome_priority` and return
164 -1/0/1 if outcome1 has lower/equal/higher priority than outcome2. 166​ -1/0/1 if ``outcome1`` has lower/equal/higher priority than ``outcome2``.
165 167​
166 @param outcome1 a outcome keyword to compare 168​ :param str outcome1: an outcome keyword to compare
167 @param outcome2 a outcome keyword to compare 169​ :param str outcome2: an outcome keyword to compare
168 @throw TaskotronValueError if any of the outcome keywords are not 170​ :raise TaskotronValueError: if any of the outcome keywords are not
169 specified in @classatr outcome_priority 171​ specified in :attr:`outcome_priority`
170 ''' 172​ '''
171 173​
172 # validate input 174​ # validate input
173 for outcome in [outcome1, outcome2]: 175​ for outcome in [outcome1, outcome2]:
174 if (outcome not in cls.outcome_priority) and (outcome is not None): 176​ if (outcome not in cls.outcome_priority) and (outcome is not None):
175 raise exc.TaskotronValueError('Unknown outcome keyword: %s' % 177​ raise exc.TaskotronValueError('Unknown outcome keyword: %s' %
176 outcome) 178​ outcome)
177 179​
178 index1 = cls.outcome_priority.index(outcome1) if outcome1 is not None \ 180​ index1 = cls.outcome_priority.index(outcome1) if outcome1 is not None \
179 else -1 181​ else -1
180 index2 = cls.outcome_priority.index(outcome2) if outcome2 is not None \ 182​ index2 = cls.outcome_priority.index(outcome2) if outcome2 is not None \
181 else -1 183​ else -1
182 return cmp(index1, index2) 184​ return cmp(index1, index2)
183 185​
184 186​
185 @classmethod 187​ @classmethod
186 def create_multi_item_summary(cls, outcomes): 188​ def create_multi_item_summary(cls, outcomes):
187 '''Create a string containing a sum of all outcomes, like this: 189​ '''Create a string containing a sum of all outcomes, like this:
188 "3 PASSED, 1 INFO, 2 FAILED" 190​ ``3 PASSED, 1 INFO, 2 FAILED``
189 191​
190 @param outcomes either one CheckDetail instance or an iterable of 192​ :param outcomes: either one :class:`CheckDetail` instance or an iterable
191 CheckDetails or an iterable of outcome strings 193​ of :class:`CheckDetails <CheckDetail>` or an iterable
194​ of :attr:`outcome` strings
192 ''' 195​ '''
193 # validate input 196​ # validate input
194 if isinstance(outcomes, CheckDetail): 197​ if isinstance(outcomes, CheckDetail):
195 outcomes = (outcomes,) 198​ outcomes = (outcomes,)
196 199​
197 if len(outcomes) <= 0: 200​ if len(outcomes) <= 0:
198 return '' 201​ return ''
199 202​
Show All 20 Lines222 def __str__(self):
220 # Make this object more readable when printing 223​ # Make this object more readable when printing
221 # But don't show self.output, because that can be huuge 224​ # But don't show self.output, because that can be huuge
222 attrs = vars(self) 225​ attrs = vars(self)
223 attrs['output'] = '<stripped out>' 226​ attrs['output'] = '<stripped out>'
224 return '<%s: %s>' % (self.__class__.__name__, pprint.pformat(attrs)) 227​ return '<%s: %s>' % (self.__class__.__name__, pprint.pformat(attrs))
225 228​
226 229​
227class ReportType(object): 230​class ReportType(object):
228 ''' Enum for different types of CheckDetail.report_type''' 231​ ''' Enum for different types of :attr:`CheckDetail.report_type`'''
229 # the values are used as identifiers in a TAP export 232​ # the values are used as identifiers in a TAP export
230 KOJI_BUILD = 'koji_build' 233​ KOJI_BUILD = 'koji_build' #:
231 BODHI_UPDATE = 'bodhi_update' 234​ BODHI_UPDATE = 'bodhi_update' #:
232 YUM_REPOSITORY = 'yum_repository' 235​ YUM_REPOSITORY = 'yum_repository' #:
233 236​
234 237​
235def export_TAP(*check_details): 238​def export_TAP(*check_details):
236 '''Generate TAP output used for reporting to ResultsDB. 239​ '''Generate TAP output used for reporting to ResultsDB.
237 240​
238 @param *check_details any number of CheckDetail instances 241​ :param check_details: any number of :class:`CheckDetail` instances
239 @return a string containing TAP output with results for every CheckDetail 242​ :return: TAP output with results for every :class:`CheckDetail` instance
240 instance provided 243​ provided
241 @raise TaskotronValueError if CheckDetail.item is empty for any parameter 244​ :rtype: str
242 provided 245​ :raise TaskotronValueError: if :attr:`CheckDetail.item` is empty for any
243 246​ parameter provided
244 Example output: 247​
245 ~~~~~~~~~~~~~~~~~~~~~~~ 248​ Example output::
246 TAP Version 13 249​
247 1..1 250​ TAP Version 13
248 ok - $CHECKNAME for Koji build xchat-0.5-1.fc20 251​ 1..1
249 --- 252​ ok - $CHECKNAME for Koji build xchat-0.5-1.fc20
250 details: 253​ ---
251 output: |- 254​ details:
252 xchat.x86_64: W: file-not-utf8 /usr/share/doc/xchat/ChangeLog 255​ output: |-
253 xchat.x86_64: W: non-conffile-in-etc /etc/gconf/schemas/apps.schemas 256​ xchat.x86_64: W: file-not-utf8 /usr/share/doc/xchat/ChangeLog
254 xchat.x86_64: W: no-manual-page-for-binary xchat 257​ xchat.x86_64: W: non-conffile-in-etc /etc/gconf/schemas/apps.schemas
255 item: xchat-0.5-1.fc20 258​ xchat.x86_64: W: no-manual-page-for-binary xchat
256 outcome: PASSED 259​ item: xchat-0.5-1.fc20
257 summary: 5 ERRORS, 10 WARNINGS 260​ outcome: PASSED
258 type: koji_build 261​ summary: 5 ERRORS, 10 WARNINGS
259 ... 262​ type: koji_build
260 ~~~~~~~~~~~~~~~~~~~~~~~ 263​ ...
261 ''' 264​ '''
262 265​
263 # validate input 266​ # validate input
264 for detail in check_details: 267​ for detail in check_details:
265 if not detail.item: 268​ if not detail.item:
266 raise exc.TaskotronValueError('CheckDetail.item is empty for: %s' % 269​ raise exc.TaskotronValueError('CheckDetail.item is empty for: %s' %
267 detail) 270​ detail)
268 271​
▲ Show 20 Lines • Show All 43 Lines • ▼ Show 20 Line(s)282 for detail in check_details:
312 315​
313 # generate 316​ # generate
314 output = tapgen.format_TAP_msg(result=tap_outcome, name=name, data=data) 317​ output = tapgen.format_TAP_msg(result=tap_outcome, name=name, data=data)
315 tapout.append(output) 318​ tapout.append(output)
316 319​
317 return '\n'.join(tapout) 320​ return '\n'.join(tapout)
318 321​
319def import_TAP(source): 322​def import_TAP(source):
320 '''Parses the source (string in TAP format), and returns list of 323​ '''Parses TAP and returns a list of :class:`CheckDetails <CheckDetail>`.
321 CheckDetails. 324​
322 @throw TaskotronValueError if TAP syntax is incorrect 325​ :param str source: TAP-formatted text
326​ :raise TaskotronValueError: if TAP syntax is incorrect
323 ''' 327​ '''
324 328​
325 tap = TAP13() 329​ tap = TAP13()
326 try: 330​ try:
327 tap.parse(source) 331​ tap.parse(source)
328 except ValueError as e: 332​ except ValueError as e:
329 raise exc.TaskotronValueError('Failed to parse TAP contents: %s' % e) 333​ raise exc.TaskotronValueError('Failed to parse TAP contents: %s' % e)
330 334​
Show All 22 Lines
View Options

libtaskotron/config.py

Show All 10 Lines
11 11​
12from . import exceptions as exc 12​from . import exceptions as exc
13from .logger import log 13​from .logger import log
14from .config_defaults import (Config, ProductionConfig, TestingConfig, 14​from .config_defaults import (Config, ProductionConfig, TestingConfig,
15 ProfileName) 15​ ProfileName)
16from . import file_utils 16​from . import file_utils
17 17​
18 18​
19# a list of directories where config files are stored 19​CONF_DIRS = [ # local checkout dir first, then system wide dir
20# the config files are loaded from these locations in the specified order, ​
21# and only the first config file found is used (further locations are ignored) ​
22CONF_DIRS = [ ​
23 # local checkout dir ​
24 os.path.abspath(os.path.dirname(libtaskotron.__file__) + '/../conf'), 20​ os.path.abspath(os.path.dirname(libtaskotron.__file__) + '/../conf'),
25 '/etc/taskotron', 21​ '/etc/taskotron']
26 ] 22​'''A list of directories where config files are stored. The config files are
23​loaded from these locations in the specified order, and only the first config
24​file found is used (further locations are ignored). The first location is
25​dynamic, relative to the package location and it reflects the usual config
26​location in a git checkout.'''
27 27​
28# the name of our configuration file ​
29CONF_FILE = 'taskotron.yaml' 28​CONF_FILE = 'taskotron.yaml'
29​'''the name of our configuration file'''
30 30​
31# environment variable name for setting config profile ​
32PROFILE_VAR = 'TASKOTRON_PROFILE' 31​PROFILE_VAR = 'TASKOTRON_PROFILE'
32​'''environment variable name for setting config profile'''
33 33​
34# a singleton instance of Config ​
35_config = None 34​_config = None
35​'''a singleton instance of Config'''
36 36​
37 37​
38def get_config(): 38​def get_config():
39 '''Get Config instance. 39​ '''Get the Config instance. This method is implemented using the singleton
40​ pattern - you will always receive the same instance, which will get
41​ auto-initialized on the first method call.
40 42​
41 @return either @class Config or its subclass, depending on taskotron 43​ :return: either :class:`.Config` or its subclass, depending on taskotron
42 profile used. This method is implemented using the singleton pattern 44​ profile used.
43 - you will always receive the same instance, which will get 45​ :raise TaskotronConfigError: if config file parsing and handling failed
44 auto-initialized on the first method call. ​
45 @throw TaskotronConfigError if file config parsing and handling failed ​
46 ''' 46​ '''
47 47​
48 global _config 48​ global _config
49 if not _config: 49​ if not _config:
50 _config = _get_instance() 50​ _config = _get_instance()
51 return _config 51​ return _config
52 52​
53 53​
54def _get_instance(): 54​def _get_instance():
55 '''Do everything necessary to fully initialize Config instance, update it 55​ '''Do everything necessary to fully initialize Config instance, update it
56 with external configuration, make all final touches. 56​ with external configuration, make all final touches.
57 57​
58 @return Config instance ready to be used 58​ :return: :class:`.Config` instance ready to be used
59 @throw TaskotronConfigError if file config parsing and handling failed 59​ :raise TaskotronConfigError: if file config parsing and handling failed
60 ''' 60​ '''
61 config = _load() 61​ config = _load()
62 log.debug('Using config profile: %s', config.profile) 62​ log.debug('Using config profile: %s', config.profile)
63 63​
64 # make sure required directories exist 64​ # make sure required directories exist
65 _create_dirs(config) 65​ _create_dirs(config)
66 66​
67 return config 67​ return config
68 68​
69 69​
70def _load(): 70​def _load():
71 '''Load the configuration, internal (defaults) and external (config files) 71​ '''Load the configuration, internal (defaults) and external (config files)
72 72​
73 @return Config instance that was updated by external config file contents 73​ :return: :class:`.Config` instance that was updated by external config file
74 @throw TaskotronConfigError if file config parsing and handling failed 74​ contents
75​ :raise TaskotronConfigError: if file config parsing and handling failed
75 ''' 76​ '''
76 77​
77 # first load the defaults and make sure we even want to load config files 78​ # first load the defaults and make sure we even want to load config files
78 env_profile = os.getenv(PROFILE_VAR) 79​ env_profile = os.getenv(PROFILE_VAR)
79 config = _load_defaults(env_profile) 80​ config = _load_defaults(env_profile)
80 if config.profile == ProfileName.TESTING: 81​ if config.profile == ProfileName.TESTING:
81 log.debug('Testing profile, not loading config files from disk') 82​ log.debug('Testing profile, not loading config files from disk')
82 return config 83​ return config
Show All 16 Lines
99 _merge_config(config, file_config) 100​ _merge_config(config, file_config)
100 101​
101 return config 102​ return config
102 103​
103 104​
104def _load_defaults(profile): 105​def _load_defaults(profile):
105 '''Load and return Config (or its subclass) based on chosen profile. 106​ '''Load and return Config (or its subclass) based on chosen profile.
106 107​
107 @param profile profile name as defined in config_defaults.ProfileName 108​ :param str profile: profile name as defined in :class:`.ProfileName`
108 @return config_defaults.Config instance or its subclass 109​ :return: :class:`.Config` instance or its subclass
109 ''' 110​ '''
110 111​
111 if profile == ProfileName.PRODUCTION: 112​ if profile == ProfileName.PRODUCTION:
112 return ProductionConfig() 113​ return ProductionConfig()
113 elif profile == ProfileName.TESTING: 114​ elif profile == ProfileName.TESTING:
114 return TestingConfig() 115​ return TestingConfig()
115 else: 116​ else:
116 if profile and profile != ProfileName.DEVELOPMENT: 117​ if profile and profile != ProfileName.DEVELOPMENT:
117 log.warn('Unknown profile "%s", selecting "%s"', profile, 118​ log.warn('Unknown profile "%s", selecting "%s"', profile,
118 ProfileName.DEVELOPMENT) 119​ ProfileName.DEVELOPMENT)
119 # the default is the development profile 120​ # the default is the development profile
120 return Config() 121​ return Config()
121 122​
122 123​
123def _search_dirs(conf_dirs, conf_file): 124​def _search_dirs(conf_dirs, conf_file):
124 '''Find the configuration file in a set of directories. The first match 125​ '''Find the configuration file in a set of directories. The first match
125 is returned. 126​ is returned.
126 127​
127 @param conf_dirs a list of directories to search through 128​ :param conf_dirs: a list of directories to search through
128 @param conf_file configuration file name 129​ :type conf_dirs: list of str
129 @return full path to the configuration file or None if not found 130​ :param str conf_file: configuration file name
131​ :return: full path to the configuration file (string) or ``None`` if not
132​ found
130 ''' 133​ '''
131 134​
132 for conf_dir in conf_dirs: 135​ for conf_dir in conf_dirs:
133 filename = os.path.join(conf_dir, conf_file) 136​ filename = os.path.join(conf_dir, conf_file)
134 if os.access(filename, os.R_OK): 137​ if os.access(filename, os.R_OK):
135 return filename 138​ return filename
136 139​
137 140​
138def _load_file(conf_file): 141​def _load_file(conf_file):
139 '''Parse a configuration file and return it as a dictionary. The option 142​ '''Parse a configuration file and return it as a dictionary. The option
140 values are checked for type correctness against a default Config object. 143​ values are checked for type correctness against a default Config object.
141 144​
142 @param conf_file file path or file handler to the configuration file in 145​ :param conf_file: file path (string) or file handler to the configuration
143 YAML syntax 146​ file in YAML syntax
144 @return dictionary parsed from the configuration file 147​ :return: dictionary parsed from the configuration file
145 @throw TaskotronConfigError if any problem occurs during the parsing or some 148​ :raise TaskotronConfigError: if any problem occurs during the parsing or
146 values have incorrect variable type 149​ some values have incorrect variable type
147 ''' 150​ '''
148 151​
149 # convert file path to file handle if needed 152​ # convert file path to file handle if needed
150 if isinstance(conf_file, basestring): 153​ if isinstance(conf_file, basestring):
151 log.debug('Trying to open configuration file: %s', conf_file) 154​ log.debug('Trying to open configuration file: %s', conf_file)
152 try: 155​ try:
153 conf_file = open(conf_file) 156​ conf_file = open(conf_file)
154 except IOError as e: 157​ except IOError as e:
Show All 40 Lines196 raise exc.TaskotronConfigError('Option "%s" in config file %s '
195 % (option, filename, type(default_value), type(value))) 198​ % (option, filename, type(default_value), type(value)))
196 199​
197 return conf_obj 200​ return conf_obj
198 201​
199 202​
200def _merge_config(config, file_config): 203​def _merge_config(config, file_config):
201 '''Merge a Config object and a dictionary parsed from YAML file. 204​ '''Merge a Config object and a dictionary parsed from YAML file.
202 205​
203 @param config a Config instance to merge into 206​ :param config: a :class:`.Config` instance to merge into
204 @param file_config a dictionary parsed from YAML configuration file to merge 207​ :param dict file_config: a dictionary parsed from YAML configuration file to
205 from 208​ merge from
206 @return the same Config instance, but with some attributes overwritten with 209​ :return: the same ``config`` instance, but with some attributes overwritten
207 values from file_config 210​ with values from ``file_config``
208 @throw AttributeError if file_config contains values that config doesn't 211​ :raise AttributeError: if ``file_config`` contains values that ``config``
209 have. But this shouldn't happen, because @function 212​ doesn't have. But this shouldn't happen, because
210 load_file() should already have checked for that. 213​ :func:`_load_file` should already have checked for
214​ that.
211 ''' 215​ '''
212 216​
213 for option, value in file_config.items(): 217​ for option, value in file_config.items():
214 if option == 'profile': 218​ if option == 'profile':
215 # the only option not overridden from file is 'profile', because 219​ # the only option not overridden from file is 'profile', because
216 # that might have been dictated by env variable which has a higher 220​ # that might have been dictated by env variable which has a higher
217 # priority 221​ # priority
218 continue 222​ continue
219 if hasattr(config, option): 223​ if hasattr(config, option):
220 setattr(config, option, value) 224​ setattr(config, option, value)
221 225​
222 226​
223def _create_dirs(config): 227​def _create_dirs(config):
224 '''Create directories in the local file system for appropriate config 228​ '''Create directories in the local file system for appropriate config
225 options - e.g. tmpdir, logdir, etc. 229​ options - e.g. ``tmpdir``, ``logdir``, etc.
226 230​
227 @param config Config instance 231​ :param config: :class:`.Config` instance
228 ''' 232​ '''
229 233​
230 for dir_ in (config.tmpdir, config.logdir): 234​ for dir_ in (config.tmpdir, config.logdir):
231 try: 235​ try:
232 file_utils.makedirs(dir_) 236​ file_utils.makedirs(dir_)
233 except OSError as e: 237​ except OSError as e:
234 # log the problem, but don't raise it. Mostly we can work even 238​ # log the problem, but don't raise it. Mostly we can work even
235 # without these directiories, probably. If not, they will receive 239​ # without these directiories, probably. If not, they will receive
236 # a crash later. (We can re-evaluate this decision then.) 240​ # a crash later. (We can re-evaluate this decision then.)
237 log.warn('Failed to create a required directory, please create it ' 241​ log.warn('Failed to create a required directory, please create it '
238 'manually: %s' % e) 242​ 'manually: %s' % e)
239 243​
View Options

libtaskotron/config_defaults.py

1# -*- coding: utf-8 -*- 1​# -*- coding: utf-8 -*-
2# Copyright 2014, Red Hat, Inc. 2​# Copyright 2014, Red Hat, Inc.
3# License: GNU General Public License version 2 or later 3​# License: GNU General Public License version 2 or later
4 4​
5'''This includes the default values for Taskotron configuration. This is 5​'''This includes the default values for Taskotron configuration. This is
6automatically loaded by config.py and then overridden by values from config 6​automatically loaded by config.py and then overridden by values from config
7files available in system-wide location.''' 7​files available in system-wide location.'''
8 8​
9import pprint 9​import pprint
10 10​
11 11​
12class ProfileName(object): 12​class ProfileName(object):
13 '''Enum of available profile names. These can be specified in the config 13​ '''Enum of available profile names. These can be specified in the config
14 file or as the environment variable.''' 14​ file or as the environment variable.'''
15 15​
16 DEVELOPMENT = 'development' 16​ DEVELOPMENT = 'development' #:
17 PRODUCTION = 'production' 17​ PRODUCTION = 'production' #:
18 TESTING = 'testing' 18​ TESTING = 'testing' #:
19 19​
20 20​
21class Config(object): 21​class Config(object):
22 '''Global configuration for Taskotron (development profile). 22​ '''Global configuration for Taskotron (development profile).
23 23​
24 The documentation for individual options is available in the config 24​ The documentation for individual options is available in the config
25 files (unless they're not present in the config files, then they're 25​ files (unless they're not present in the config files, then they're
26 documented in the code). 26​ documented here).
27 27​
28 Implementation notes: 28​ Implementation notes:
29​
29 * If you want to add a new option, put it here and optionally into the 30​ * If you want to add a new option, put it here and optionally into the
30 config file as well. 31​ config file as well.
31 * If you modify a default value for some option, don't forget to modify 32​ * If you modify a default value for some option, don't forget to modify
32 it in both places - here and in the config file (if present). 33​ it in both places - here and in the config file (if present).
33 * Don't assign None as a default value. We need to know a value type in 34​ * Don't assign ``None`` as a default value. We need to know a value type
34 order to check for correct type of user-provided values. 35​ in order to check for correct type of user-provided values.
35 ''' 36​ '''
36 37​
37 profile = ProfileName.DEVELOPMENT 38​ profile = ProfileName.DEVELOPMENT #:
38 39​
39 reporting_enabled = False 40​ reporting_enabled = False #:
40 report_to_bodhi = True 41​ report_to_bodhi = True #:
41 report_to_resultsdb = True 42​ report_to_resultsdb = True #:
42 43​
43 koji_url = 'http://koji.fedoraproject.org/kojihub' 44​ koji_url = 'http://koji.fedoraproject.org/kojihub' #:
44 pkg_url = 'http://kojipkgs.fedoraproject.org/packages' 45​ pkg_url = 'http://kojipkgs.fedoraproject.org/packages' #:
45 bodhi_server = 'https://admin.fedoraproject.org/updates/' 46​ bodhi_server = 'https://admin.fedoraproject.org/updates/' #:
46 resultsdb_server = \ 47​ resultsdb_server = \
47 'http://resultsdb.qa.fedoraproject.org/resultsdb/api/v1.0/' 48​ 'http://resultsdb.qa.fedoraproject.org/resultsdb/api/v1.0/' #:
48 taskotron_master = 'http://taskotron.qa.fedoraproject.org/taskmaster/' 49​ taskotron_master = 'http://taskotron.qa.fedoraproject.org/taskmaster/' #:
49 buildbot_task_step = 'runtask' 50​ buildbot_task_step = 'runtask' #:
50 51​
51 bodhi_email_failed_span = 4320 52​ bodhi_posting_comments_span = 4320 #:
52 bodhi_posting_comments_span = 4320 53​ # 3 days (3*24*60 = 4320)
53 54​
54 tmpdir = '/var/tmp/taskotron' 55​ tmpdir = '/var/tmp/taskotron' #:
55 logdir = '/var/log/taskotron' 56​ logdir = '/var/log/taskotron' #:
56 main_log_name = 'taskotron.log' 57​ main_log_name = 'taskotron.log'
58​ '''name of the main log file in :attr:`logdir`'''
57 59​
58 fas_username = 'taskotron' 60​ fas_username = 'taskotron' #:
59 fas_password = '' 61​ fas_password = '' #:
60 62​
61 63​
62 def __str__(self): 64​ def __str__(self):
63 # Make this object more readable when printing 65​ ''' Make this object more readable when printing '''
64 return '<%s: %s>' % (self.__class__.__name__, 66​ return '<%s: %s>' % (self.__class__.__name__,
65 pprint.pformat(vars(self))) 67​ pprint.pformat(vars(self)))
66 68​
67 69​
68class ProductionConfig(Config): 70​class ProductionConfig(Config):
69 '''Configuration for production profile. Inherits values from @class Config 71​ '''Configuration for production profile. Inherits values from
70 and overrides some. Read @class Config documentation.''' 72​ :class:`Config` and overrides some. Read Config documentation.'''
71 73​
72 profile = ProfileName.PRODUCTION 74​ profile = ProfileName.PRODUCTION #:
73 reports_enabled = True 75​ reports_enabled = True #:
74 76​
75 77​
76class TestingConfig(Config): 78​class TestingConfig(Config):
77 '''Configuration for testing suite profile. Inherits values from @class 79​ '''Configuration for testing suite profile. Inherits values from
78 Config and overrides some. Read @class Config documentation.''' 80​ :class:`Config` and overrides some. Read Config documentation.'''
79 81​
80 profile = ProfileName.TESTING 82​ profile = ProfileName.TESTING #:
View Options

libtaskotron/exceptions.py

1# -*- coding: utf-8 -*- 1​# -*- coding: utf-8 -*-
2# Copyright 2010-2014, Red Hat, Inc. 2​# Copyright 2010-2014, Red Hat, Inc.
3# License: GNU General Public License version 2 or later 3​# License: GNU General Public License version 2 or later
4 4​
5'''This module contains custom Taskotron exceptions''' 5​'''This module contains custom Taskotron exceptions'''
6 6​
7 7​
8class TaskotronError(Exception): 8​class TaskotronError(Exception):
9 '''Common ancestor for Taskotron related exceptions''' 9​ '''Common ancestor for Taskotron related exceptions'''
10 pass 10​ pass
11 11​
12 12​
13class TaskotronValueError(ValueError, TaskotronError): 13​class TaskotronValueError(ValueError, TaskotronError):
14 '''Taskotron-specific ValueError''' 14​ '''Taskotron-specific :class:`ValueError`'''
15 pass 15​ pass
16 16​
17 17​
18class TaskotronConfigError(TaskotronError): 18​class TaskotronConfigError(TaskotronError):
19 '''All errors related to Taskotron config files''' 19​ '''All errors related to Taskotron config files'''
20 pass 20​ pass
21 21​
22class TaskotronYamlError(TaskotronError): 22​class TaskotronYamlError(TaskotronError):
Show All 12 Lines
View Options

libtaskotron/file_utils.py

1import os 1​import os
2import sys 2​import sys
3import urlgrabber.grabber 3​import urlgrabber.grabber
4import urlgrabber.progress 4​import urlgrabber.progress
5from libtaskotron.logger import log 5​from libtaskotron.logger import log
6from libtaskotron.exceptions import TaskotronRemoteError 6​from libtaskotron.exceptions import TaskotronRemoteError
7 7​
8 8​
9def makedirs(fullpath): 9​def makedirs(fullpath):
10 '''This is the same as @method os.makedirs(), but does not throw an 10​ '''This is the same as :meth:`os.makedirs`, but does not raise an exception
11 exception when the destination directory already exists. 11​ when the destination directory already exists.
12 @raise OSError if directory can't be created 12​
13​ :raise OSError: if directory doesn't exist and can't be created
13 ''' 14​ '''
14 try: 15​ try:
15 os.makedirs(fullpath) 16​ os.makedirs(fullpath)
16 assert os.path.isdir(fullpath) 17​ assert os.path.isdir(fullpath)
17 except OSError, e: 18​ except OSError, e:
18 if e.errno == 17: # "[Errno 17] File exists" 19​ if e.errno == 17: # "[Errno 17] File exists"
19 # if it is a directory everything is ok 20​ # if it is a directory everything is ok
20 if os.path.isdir(fullpath): 21​ if os.path.isdir(fullpath):
21 return 22​ return
22 # otherwise it is a file/socket/etc and it is an error 23​ # otherwise it is a file/socket/etc and it is an error
23 else: 24​ else:
24 raise 25​ raise
25 else: 26​ else:
26 raise 27​ raise
27 28​
28def get_urlgrabber(**kwargs): 29​def get_urlgrabber(**kwargs):
29 '''Get a new instance of URLGrabber that is reasonably set (progress 30​ '''Get a new instance of :class:`URLGrabber` that is reasonably configured
30 bar when in terminal, automatic retries, connection timeout, etc) 31​ (progress bar when in terminal, automatic retries, connection timeout,
31 @kwargs additional kwargs to add to the URLGrabber constructor 32​ etc)
32 @return URLGrabber instance 33​
34​ :param kwargs: additional kwargs to add to the URLGrabber constructor
35​ :return: :class:`urlgrabber.grabber.URLGrabber` instance
33 ''' 36​ '''
34 grabber_args = {'retry': 3, 'timeout': 120} 37​ grabber_args = {'retry': 3, 'timeout': 120}
35 grabber_args.update(kwargs) 38​ grabber_args.update(kwargs)
36 39​
37 grabber = urlgrabber.grabber.URLGrabber(**grabber_args) 40​ grabber = urlgrabber.grabber.URLGrabber(**grabber_args)
38 41​
39 # progress bar when in terminal 42​ # progress bar when in terminal
40 if hasattr(sys.stdout, "fileno") and os.isatty(sys.stdout.fileno()): 43​ if hasattr(sys.stdout, "fileno") and os.isatty(sys.stdout.fileno()):
41 grabber.opts.progress_obj = urlgrabber.progress.TextMeter() 44​ grabber.opts.progress_obj = urlgrabber.progress.TextMeter()
42 45​
43 # retry on socket timeout 46​ # retry on socket timeout
44 if 12 not in grabber.opts.retrycodes: 47​ if 12 not in grabber.opts.retrycodes:
45 grabber.opts.retrycodes.append(12) 48​ grabber.opts.retrycodes.append(12)
46 49​
47 return grabber 50​ return grabber
48 51​
49 52​
50def download(url, dest, overwrite=False, grabber=None): 53​def download(url, dest, overwrite=False, grabber=None):
51 '''Download a file. 54​ '''Download a file.
52 55​
53 @param url file URL to download 56​ :param str url: file URL to download
54 @param dest either an existing directory (string) or a file path (string). 57​ :param str dest: either an existing directory or a file path. In the latter
55 In the latter case all parent directories will be created if 58​ case all parent directories will be created if necessary
56 necessary and the last fraction of the path will be used as the 59​ and the last fraction of the path will be used as the
57 file name. 60​ file name.
58 @param overwrite if the destination file already exists, whether to 61​ :param bool overwrite: if the destination file already exists, whether to
59 overwrite or not. If False, a simple check is performed 62​ overwrite or not. If ``False``, a simple check is
60 whether the remote file is the same as the local file and 63​ performed whether the remote file is the same as the
61 re-downloads it anyway if they are not the same. 64​ local file and re-downloads it anyway if they are not
62 @param grabber custom urlgrabber.grabber.URLGrabber object 65​ the same.
63 @return file path of the downloaded file (string) 66​ :param grabber: custom :class:`urlgrabber.grabber.URLGrabber` instance to be
64 @raise TaskotronRemoteError if download fails or directory can't be created 67​ used for actual downloading
68​ :return: file path of the downloaded file
69​ :rtype: str
70​ :raise TaskotronRemoteError: if download fails or directory can't be created
65 ''' 71​ '''
66 72​
67 if not grabber: 73​ if not grabber:
68 grabber = get_urlgrabber() 74​ grabber = get_urlgrabber()
69 75​
70 # get destination file, create dirs if needed 76​ # get destination file, create dirs if needed
71 if os.path.isdir(dest): 77​ if os.path.isdir(dest):
72 dest = os.path.join(dest, os.path.basename(url)) 78​ dest = os.path.join(dest, os.path.basename(url))
Show All 30 Lines
View Options

libtaskotron/koji_utils.py

Show All 12 Lines
13from libtaskotron import exceptions as exc 13​from libtaskotron import exceptions as exc
14from libtaskotron import rpm_utils 14​from libtaskotron import rpm_utils
15from libtaskotron import config 15​from libtaskotron import config
16 16​
17 17​
18class KojiClient(object): 18​class KojiClient(object):
19 '''Helper Koji methods. 19​ '''Helper Koji methods.
20 20​
21 Note: You can access the standard Koji client (from @module koji) as 21​ :ivar koji.ClientSession session: Koji client session
22 self.session. ​
23 ''' 22​ '''
24 def __init__(self, koji_session=None): 23​ def __init__(self, koji_session=None):
25 '''Create a new KojiClient 24​ '''Create a new KojiClient
26 @param koji_session an existing Koji session (koji.ClientSession), 25​
27 or None if you want a new default session to be 26​ :param koji_session: an existing Koji session instance or ``None`` if
28 created 27​ you want a new default session to be created
28​ :type koji_session: :class:`koji.ClientSession`
29 ''' 29​ '''
30 self.session = (koji_session or 30​ self.session = (koji_session or
31 koji.ClientSession(config.get_config().koji_url)) 31​ koji.ClientSession(config.get_config().koji_url))
32 32​
33 33​
34 def nvr_to_urls(self, nvr, arches=None, debuginfo=False, src=True): 34​ def nvr_to_urls(self, nvr, arches=None, debuginfo=False, src=True):
35 '''Get list of URLs for RPMs corresponding to a build. 35​ '''Get list of URLs for RPMs corresponding to a build.
36 @param nvr build NVR 36​
37 @param arches restrict the arches of builds to provide URLs for. If 37​ :param str nvr: build NVR
38 basearch i386 is in the list, i686 arch is automatically 38​ :param arches: restrict the arches of builds to provide URLs for. Note:
39 added (since that's the arch Koji API uses). 39​ If basearch ``i386`` is in the list, ``i686`` arch is
40​ automatically added (since that's the arch Koji API uses).
40 ''' 41​ '''
41 log.info('Querying Koji for a list of RPMS for: %s', nvr) 42​ log.info('Querying Koji for a list of RPMS for: %s', nvr)
42 43​
43 # add i686 arch if i386 is present in arches 44​ # add i686 arch if i386 is present in arches
44 if arches and 'i386' in arches and 'i686' not in arches: 45​ if arches and 'i386' in arches and 'i686' not in arches:
45 arches.append('i686') 46​ arches.append('i686')
46 47​
47 info = self.session.getBuild(nvr) 48​ info = self.session.getBuild(nvr)
Show All 17 Lines
65 return sorted(urls) 66​ return sorted(urls)
66 67​
67 68​
68 def get_nvr_rpms(self, nvr, rpm_dir, arches=None, debuginfo=False, 69​ def get_nvr_rpms(self, nvr, rpm_dir, arches=None, debuginfo=False,
69 src=False): 70​ src=False):
70 '''Retrieve the RPMs associated with a build NVR into the specified 71​ '''Retrieve the RPMs associated with a build NVR into the specified
71 directory. 72​ directory.
72 73​
73 @param nvr build NVR 74​ :param str nvr build: NVR
74 @param rpm_dir location where to store the RPMs 75​ :param str rpm_dir: location where to store the RPMs
75 @return list of local filenames of the grabbed RPMs 76​ :return: list of local filenames of the grabbed RPMs
76 @raise TaskotronRemoteError if downloading failed 77​ :rtype: list of str
78​ :raise TaskotronRemoteError: if downloading failed
77 ''' 79​ '''
78 rpm_urls = self.nvr_to_urls(nvr, 80​ rpm_urls = self.nvr_to_urls(nvr,
79 arches=arches, 81​ arches=arches,
80 debuginfo=debuginfo, 82​ debuginfo=debuginfo,
81 src=src) 83​ src=src)
82 rpm_files = [] 84​ rpm_files = []
83 log.info('Fetching RPMs for: %s', nvr) 85​ log.info('Fetching RPMs for: %s', nvr)
84 for url in rpm_urls: 86​ for url in rpm_urls:
85 log.info(' fetching %s', url) 87​ log.info(' fetching %s', url)
86 rpm_file = file_utils.download(url, rpm_dir) 88​ rpm_file = file_utils.download(url, rpm_dir)
87 rpm_files.append(rpm_file) 89​ rpm_files.append(rpm_file)
88 90​
89 return rpm_files 91​ return rpm_files
90 92​
91 93​
92 def get_tagged_rpms(self, tag, dest, arches): 94​ def get_tagged_rpms(self, tag, dest, arches):
93 '''Downloads all RPMs of all NVRs tagged by a specific Koji tag. 95​ '''Downloads all RPMs of all NVRs tagged by a specific Koji tag.
94 @dest destination directory 96​
95 @arches list of architectures 97​ :param str dest: destination directory
96 @raise TaskotronRemoteError if downloading failed 98​ :param arches: list of architectures
99​ :type arches: list of str
100​ :raise TaskotronRemoteError: if downloading failed
97 ''' 101​ '''
98 tag_data = self.session.listTagged(tag) 102​ tag_data = self.session.listTagged(tag)
99 nvrs = ["%(nvr)s" % x for x in tag_data] 103​ nvrs = ["%(nvr)s" % x for x in tag_data]
100 rpms = [] 104​ rpms = []
101 for nvr in nvrs: 105​ for nvr in nvrs:
102 rpms.append(self.get_nvr_rpms(nvr, dest, arches)) 106​ rpms.append(self.get_nvr_rpms(nvr, dest, arches))
103 107​
104 return rpms 108​ return rpms
105 109​
106 110​
107def getNEVR(build): 111​def getNEVR(build):
108 '''Extract RPM version identifier in NEVR format from Koji build object 112​ '''Extract RPM version identifier in NEVR format from Koji build object
109 113​
110 @param build Koji buildinfo dictionary (as returned from @module koji 114​ :param dict build: Koji buildinfo dictionary (as returned e.g. from
111 methods like getBuild()) 115​ :meth:`koji.getBuild`)
112 @return NEVR string; epoch is included when non-zero, otherwise omitted 116​ :return: NEVR string; epoch is included when non-zero, otherwise omitted
113 @raise TaskotronValueError if @param build is of incorrect type 117​ :raise TaskotronValueError: if ``build`` is of incorrect type
114 ''' 118​ '''
115 # validate input 119​ # validate input
116 if (not isinstance(build, collections.Mapping) or 'nvr' not in build or 120​ if (not isinstance(build, collections.Mapping) or 'nvr' not in build or
117 'epoch' not in build): 121​ 'epoch' not in build):
118 raise exc.TaskotronValueError("Input argument doesn't look like " 122​ raise exc.TaskotronValueError("Input argument doesn't look like "
119 "a Koji build object: %s" % build) 123​ "a Koji build object: %s" % build)
120 124​
121 rpmver = hawkey.split_nevra(build['nvr'] + '.noarch') 125​ rpmver = hawkey.split_nevra(build['nvr'] + '.noarch')
122 rpmver.epoch = build['epoch'] or 0 126​ rpmver.epoch = build['epoch'] or 0
123 nevr = '%s-%s' % (rpmver.name, rpmver.evr()) 127​ nevr = '%s-%s' % (rpmver.name, rpmver.evr())
124 # supress 0 epoch (evr() method always includes epoch, even if 0) 128​ # supress 0 epoch (evr() method always includes epoch, even if 0)
125 nevr = rpm_utils.rpmformat(nevr, fmt='nevr') 129​ nevr = rpm_utils.rpmformat(nevr, fmt='nevr')
126 130​
127 return nevr 131​ return nevr
View Options

libtaskotron/logger.py

Show All 31 Lines
32def _log_excepthook(*exc_info): 32​def _log_excepthook(*exc_info):
33 '''Called when an exception is not caught''' 33​ '''Called when an exception is not caught'''
34 log.critical(''.join(traceback.format_exception(*exc_info))) 34​ log.critical(''.join(traceback.format_exception(*exc_info)))
35 35​
36 36​
37def init(name='libtaskotron', level=logging.INFO, stream=True, syslog=False, 37​def init(name='libtaskotron', level=logging.INFO, stream=True, syslog=False,
38 filelog=None): 38​ filelog=None):
39 """Setup a logger 39​ """Setup a logger
40 @param name name of the logger, 'libtaskotron' is default 40​
41 @param level level of logging 41​ :param str name: name of the logger, 'libtaskotron' is default
42 @param stream enables logging to stderr 42​ :param level: level of logging
43 @param syslog enables logging to syslog 43​ :type level: level definitions from :mod:`logging`
44 @param filelog enables logging to a file, the value is the file name 44​ :param bool stream: enables logging to stderr
45​ :param bool syslog: enables logging to syslog
46​ :param str filelog: enables logging to a file, the value is the file name
45 """ 47​ """
46 48​
47 # overwrite default except hook 49​ # overwrite default except hook
48 sys.excepthook = _log_excepthook 50​ sys.excepthook = _log_excepthook
49 51​
50 logger = logging.getLogger(name) 52​ logger = logging.getLogger(name)
51 logger.setLevel(level) 53​ logger.setLevel(level)
52 logger.addHandler(logging.NullHandler()) 54​ logger.addHandler(logging.NullHandler())
Show All 27 Lines
View Options

libtaskotron/python_utils.py

1# -*- coding: utf-8 -*- 1​# -*- coding: utf-8 -*-
2# Copyright 2014, Red Hat, Inc. 2​# Copyright 2014, Red Hat, Inc.
3# License: GNU General Public License version 2 or later 3​# License: GNU General Public License version 2 or later
4 4​
5'''A collection of convenience methods related to Python base libraries.''' 5​'''A collection of convenience methods related to Python base libraries.'''
6 6​
7import collections 7​import collections
8 8​
9 9​
10def listlike(obj): 10​def listlike(value):
11 '''Return whether the object is iterable (list, tuple, set, etc), but not 11​ '''Return whether ``value`` is iterable (``list``, ``tuple``, ``set``,
12 string (which is iterable, but we don't often want to consider it as such). 12​ etc), but not ``str`` (which is iterable, but we don't often want to
13 This method is useful e.g. if you want to check that a variable contains 13​ consider it as such). This method is useful e.g. if you want to check that a
14 a list/set/etc of strings. 14​ variable contains a list/set/etc of strings.
15​
16​ :param any value: any object or literal you want to check
17​ :return: whether ``value`` is iterable but not string
18​ :rtype: bool
15 ''' 19​ '''
16 return isinstance(obj, collections.Iterable) and not isinstance(obj, 20​ return (isinstance(value, collections.Iterable) and
17 basestring) 21​ not isinstance(value, basestring))
View Options

libtaskotron/rpm_utils.py

1# -*- coding: utf-8 -*- 1​# -*- coding: utf-8 -*-
2# Copyright 2014, Red Hat, Inc. 2​# Copyright 2014, Red Hat, Inc.
3# License: GNU General Public License version 2 or later 3​# License: GNU General Public License version 2 or later
4 4​
5''' Utility methods related to RPM ''' 5​''' Utility methods related to RPM '''
6 6​
7import os 7​import os
8import hawkey 8​import hawkey
9 9​
10from libtaskotron import exceptions as exc 10​from libtaskotron import exceptions as exc
11 11​
12 12​
13def basearch(arch=None): 13​def basearch(arch=None):
14 ''' 14​ '''
15 This returns the 'base' architecture identifier for a specified architecture 15​ This returns the 'base' architecture identifier for a specified architecture
16 (e.g. i386 for i[3-6]86), to be used by YUM etc. 16​ (e.g. ``i386`` for ``i[3-6]86``), to be used by YUM etc.
17 17​
18 @param arch an arch (string) to be converted to a basearch. If None, then 18​ :param str arch: an architecture to be converted to a basearch. If ``None``,
19 the arch of the current machine is used. 19​ then the arch of the current machine is used.
20 @return basearch, or @param arch if no basearch was found for it 20​ :return: basearch, or ``arch`` if no basearch was found for it
21​ :rtype: str
21 ''' 22​ '''
22 if arch == None: 23​ if arch == None:
23 arch = os.uname()[4] 24​ arch = os.uname()[4]
24 if arch in ('i486', 'i586', 'i686'): 25​ if arch in ('i486', 'i586', 'i686'):
25 arch = 'i386' 26​ arch = 'i386'
26 return arch 27​ return arch
27 28​
28 29​
29def rpmformat(rpmstr, fmt='nvr', end_arch=False): 30​def rpmformat(rpmstr, fmt='nvr', end_arch=False):
30 ''' 31​ '''
31 Parse and convert an RPM package version string into a different format. 32​ Parse and convert an RPM package version string into a different format.
32 String identifiers: N - name, E - epoch, V - version, R - release, A - 33​ String identifiers: N - name, E - epoch, V - version, R - release, A -
33 architecture. 34​ architecture.
34 35​
35 @param rpmstr string to be manipulated in a format of N(E)VR (foo-1.2-3.fc20 36​ :param str rpmstr: string to be manipulated in a format of N(E)VR
36 or bar-4:1.2-3.fc20) or N(E)VRA (foo-1.2-3.fc20.x86_64 or 37​ (``foo-1.2-3.fc20`` or ``bar-4:1.2-3.fc20``) or N(E)VRA
37 bar-4:1.2-3.fc20.i686) 38​ (``foo-1.2-3.fc20.x86_64`` or ``bar-4:1.2-3.fc20.i686``)
38 @param fmt desired format of the string to be returned. Allowed options are: 39​ :param str fmt: desired format of the string to be returned. Allowed options
39 nvr, nevr, nvra, nevra, n, e, v, r, a. If arch is not present in 40​ are: ``nvr``, ``nevr``, ``nvra``, ``nevra``, ``n``, ``e``,
40 rpmstr but requested in fmt, 'noarch' is used. Epoch is provided 41​ ``v``, ``r``, ``a``. If arch is not present in ``rpmstr``
41 only when specifically requested (e.g. fmt='nevr') *and* being 42​ but requested in ``fmt``, ``noarch`` is used. Epoch is
42 non-zero; otherwise it's supressed (the only exception is 43​ provided only when specifically requested (e.g.
43 fmt='e', where you receive 0 for zero epoch). 44​ ``fmt='nevr'``) **and** being non-zero; otherwise it's
44 @param end_arch set this to True if rpmstr ends with an architecture 45​ supressed (the only exception is ``fmt='e'``, where you
45 identifier (foo-1.2-3.fc20.x86_64). It's not possible to 46​ receive ``0`` for zero epoch).
46 reliably distinguish that case automatically. 47​ :param bool end_arch: set this to ``True`` if ``rpmstr`` ends with an
47 @return string based on the specified format, or integer if fmt='e' 48​ architecture identifier (``foo-1.2-3.fc20.x86_64``).
48 @raise TaskotronValueError in @param fmt value is not supported 49​ It's not possible to reliably distinguish that case
50​ automatically.
51​ :return: string based on the specified format, or integer if ``fmt='e'``
52​ :raise TaskotronValueError: if ``fmt`` value is not supported
49 ''' 53​ '''
50 fmt = fmt.lower() 54​ fmt = fmt.lower()
51 supported_formats = ['nvr', 'nevr', 'nvra', 'nevra', 55​ supported_formats = ['nvr', 'nevr', 'nvra', 'nevra',
52 'n', 'e', 'v', 'r', 'a'] 56​ 'n', 'e', 'v', 'r', 'a']
53 if fmt not in supported_formats: 57​ if fmt not in supported_formats:
54 raise exc.TaskotronValueError("Format '%s' not in supported formats " 58​ raise exc.TaskotronValueError("Format '%s' not in supported formats "
55 "(%s)" % (fmt, ', '.join(supported_formats))) 59​ "(%s)" % (fmt, ', '.join(supported_formats)))
56 60​
Show All 25 Lines85 if 'a' in fmt:
82 result += '.' + nevra.arch 86​ result += '.' + nevra.arch
83 87​
84 return result 88​ return result
85 89​
86 90​
87def cmpNEVR(nevr1, nevr2): 91​def cmpNEVR(nevr1, nevr2):
88 '''Compare two RPM version identifiers in NEVR format. 92​ '''Compare two RPM version identifiers in NEVR format.
89 93​
90 @param nevr1 a string in N(E)VR format 94​ :param str nevr1: RPM identifier in N(E)VR format
91 @param nevr2 a string in N(E)VR format 95​ :param str nevr2: RPM identifier in N(E)VR format
92 @return -1/0/1 if nevr1 < nevr2 / nevr1 == nevr2 / nevr1 > nevr2 96​ :return: ``-1``/``0``/``1`` if ``nevr1 < nevr2`` / ``nevr1 == nevr2`` /
93 @raise TaskotronValueError if name in nevr1 doesn't match name in nevr2 97​ ``nevr1 > nevr2``
98​ :rtype: int
99​ :raise TaskotronValueError: if name in ``nevr1`` doesn't match name in
100​ ``nevr2``
94 ''' 101​ '''
95 rpmver1 = hawkey.split_nevra(nevr1 + '.noarch') 102​ rpmver1 = hawkey.split_nevra(nevr1 + '.noarch')
96 rpmver2 = hawkey.split_nevra(nevr2 + '.noarch') 103​ rpmver2 = hawkey.split_nevra(nevr2 + '.noarch')
97 104​
98 if rpmver1.name != rpmver2.name: 105​ if rpmver1.name != rpmver2.name:
99 raise exc.TaskotronValueError("Name in nevr1 doesn't match name in " 106​ raise exc.TaskotronValueError("Name in nevr1 doesn't match name in "
100 "nevr2: %s, %s" % (nevr1, nevr2)) 107​ "nevr2: %s, %s" % (nevr1, nevr2))
101 108​
102 # sack is needed for the comparison, because it can be influence the 109​ # sack is needed for the comparison, because it can be influence the
103 # comparison (for example epoch can be set to be ignored). A default empty 110​ # comparison (for example epoch can be set to be ignored). A default empty
104 # sack should match Fedora customs 111​ # sack should match Fedora customs
105 sack = hawkey.Sack() 112​ sack = hawkey.Sack()
106 113​
107 return rpmver1.evr_cmp(rpmver2, sack) 114​ return rpmver1.evr_cmp(rpmver2, sack)