1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
Buildsets connector
~~~~~~~~~~~~~~~~~~~
.. py:module:: buildbot.db.buildsets
.. index:: double: Buildsets; DB Connector Component
.. py:class:: BuildsetsConnectorComponent
This class handles getting buildsets into and out of the database.
Buildsets combine multiple build requests that were triggered together.
An instance of this class is available at ``master.db.buildsets``.
.. index:: bsdict, bsid
Buildsets are indexed by *bsid* and their contents are represented as :class:`BuildSetModel`
dataclass with the following fields:
* ``bsid``
* ``external_idstring`` (arbitrary string for mapping builds externally)
* ``reason`` (string; reason these builds were triggered)
* ``rebuilt_buildid`` (integer; id of a build which was rebuilt or None if there was no rebuild.
In case of repeated rebuilds, only initial build id is tracked)
* ``sourcestamps`` (list of sourcestamps for this buildset, by ID)
* ``submitted_at`` (datetime object; time this buildset was created)
* ``complete`` (boolean; true if all of the builds for this buildset are complete)
* ``complete_at`` (datetime object; time this buildset was completed)
* ``results`` (aggregate result of this buildset; see :ref:`Build-Result-Codes`)
* ``parent_buildid`` (optional build id that is the parent for this buildset)
* ``parent_relationship`` (relationship identifier for the parent)
.. py:method:: addBuildset(sourcestamps, reason, properties, builderids, rebuilt_buildid=None, external_idstring=None, parent_buildid=None, parent_relationship=None)
:param sourcestamps: sourcestamps for the new buildset; see below
:type sourcestamps: list
:param reason: reason for this buildset
:type reason: short unicode string
:param properties: properties for this buildset
:type properties: dictionary, where values are tuples of (value, source)
:param builderids: builderids specified by this buildset
:type builderids: list of int
:param external_idstring: external key to identify this buildset; defaults to None
:type external_idstring: unicode string
:param datetime submitted_at: time this buildset was created; defaults to the current time
:param int parent_buildid: optional build id that is the parent for this buildset
:param unicode parent_relationship: relationship identifier for the parent. This is the
configured relationship between the parent build and the child buildsets
:param int rebuilt_buildid: optional rebuilt build id
:returns: buildset ID and buildrequest IDs, via a Deferred
Add a new buildset to the database, along with build requests for each builder, returning
the resulting bsid via a Deferred. Arguments should be specified by keyword.
Each sourcestamp in the list of sourcestamps can be given either as an integer, assumed to
be a sourcestamp ID, or a dictionary of keyword arguments to be passed to
:py:meth:`~buildbot.db.sourcestamps.SourceStampsConnectorComponent.findSourceStampId`.
The return value is a tuple ``(bsid, brids)`` where ``bsid`` is the inserted buildset ID
and ``brids`` is a dictionary mapping builderids to build request IDs.
.. py:method:: completeBuildset(bsid, results[, complete_at=XX])
:param bsid: buildset ID to complete
:type bsid: integer
:param results: integer result code
:type results: integer
:param datetime complete_at: time the buildset was completed
:returns: Deferred
:raises: :py:exc:`KeyError` if the buildset does not exist or is
already complete
Complete a buildset, marking it with the given ``results`` and setting
its ``completed_at`` to the current time, if the ``complete_at``
argument is omitted.
.. py:method:: getBuildset(bsid)
:param bsid: buildset ID
:returns: :class:`BuildSetModel` or ``None``, via Deferred
Get a :class:`BuildSetModel` representing the given buildset, or ``None``
if no such buildset exists.
Note that buildsets are not cached, as the values in the database are
not fixed.
.. py:method:: getBuildsets(complete=None, resultSpec=None)
:param complete: if true, return only complete buildsets; if false,
return only incomplete buildsets; if ``None`` or omitted, return all
buildsets
:param resultSpec: result spec containing filters sorting and paging requests from data/REST API.
If possible, the db layer can optimize the SQL query using this information.
:returns: list of :class:`BuildSetModel`, via Deferred
Get a list of :class:`BuildSetModel` matching the given criteria.
.. py:method:: getRecentBuildsets(count=None, branch=None, repository=None,
complete=None):
:param count: maximum number of buildsets to retrieve (required)
:type count: integer
:param branch: optional branch name. If specified, only buildsets
affecting such branch will be returned
:type branch: string
:param repository: optional repository name. If specified, only
buildsets affecting such repository will be returned
:type repository: string
:param complete: if true, return only complete buildsets; if false,
return only incomplete buildsets; if ``None`` or omitted, return all
buildsets
:type complete: Boolean
:returns: list of :class:`BuildSetModel`, via Deferred
Get "recent" buildsets, as defined by their ``submitted_at`` times.
.. py:method:: getBuildsetProperties(buildsetid)
:param bsid: buildset ID
:returns: dictionary mapping property name to ``value, source``, via
Deferred
Return the properties for a buildset, in the same format they were
given to :py:meth:`addBuildset`.
Note that this method does not distinguish a nonexistent buildset from
a buildset with no properties, and returns ``{}`` in either case.
|
