3.5.8. BaseScheduler¶
-
class
buildbot.schedulers.base.
BaseScheduler
¶ This is the base class for all Buildbot schedulers. See Writing Schedulers for information on writing new schedulers.
-
__init__
(name, builderNames, properties={}, codebases={'':{}})¶ Parameters: - name – (positional) the scheduler name
- builderName – (positional) a list of builders, by name, for which this scheduler can queue builds
- properties – a dictionary of properties to be added to queued builds
- codebases – the codebase configuration for this scheduler (see user documentation)
Initializes a new scheduler.
The scheduler configuration parameters, and a few others, are available as attributes:
-
name
¶ This scheduler’s name.
-
builderNames
¶ Type: list Builders for which this scheduler can queue builds.
-
codebases
¶ Type: dict The codebase configuration for this scheduler.
-
properties
¶ Type: Properties instance Properties that this scheduler will attach to queued builds. This attribute includes the
scheduler
property.
-
schedulerid
¶ Type: integer The ID of this scheduler in the
schedulers
table.
Subclasses can consume changes by implementing
gotChange
and callingstartConsumingChanges
fromstartActivity
.-
startConsumingChanges
(self, fileIsImportant=None, change_filter=None, onlyImportant=False)¶ Parameters: - fileIsImportant (callable) – a callable provided by the user to distinguish important and unimportant changes
- change_filter (
buildbot.changes.filter.ChangeFilter
instance) – a filter to determine which changes are even considered by this scheduler, orNone
to consider all changes - onlyImportant (boolean) – If True, only important changes, as specified by fileIsImportant, will be added to the buildset.
Returns: Deferred
Subclasses should call this method when becoming active in order to receive changes. The parent class will take care of filtering the changes (using
change_filter
) and (iffileIsImportant
is not None) classifying them.
-
gotChange
(change, important)¶ Parameters: - change (buildbot.changes.changes.Change) – the new change
- important (boolean) – true if the change is important
Returns: Deferred
This method is called when a change is received. Schedulers which consume changes should implement this method.
If the
fileIsImportant
parameter tostartConsumingChanges
was None, then all changes are considered important. It is guaranteed that thecodebase
of the change is one of the scheduler’s codebase.Note
The
buildbot.changes.changes.Change
instance will instead be a change resource in later versions.
The following methods are available for subclasses to queue new builds. Each creates a new buildset with a build request for each builder.
-
addBuildsetForSourceStamps
(self, sourcestamps=[], waited_for=False, reason='', external_idstring=None, properties=None, builderNames=None)¶ Parameters: - sourcestamps (list) – a list of full sourcestamp dictionaries or sourcestamp IDs
- waited_for (boolean) – if true, this buildset is being waited for (and thus should continue during a clean shutdown)
- reason (string) – reason for the build set
- external_idstring (string) – external identifier for the buildset
- properties (
Properties
instance) – properties - in addition to those in the scheduler configuration - to include in the buildset - builderNames (list) – a list of builders for the buildset, or None to use the scheduler’s configured
builderNames
Returns: (buildset ID, buildrequest IDs) via Deferred
Add a buildset for the given source stamps. Each source stamp must be specified as a complete source stamp dictionary (with keys
revision
,branch
,project
,repository
, andcodebase
), or an integersourcestampid
.The return value is a tuple. The first tuple element is the ID of the new buildset. The second tuple element is a dictionary mapping builder name to buildrequest ID.
-
addBuildsetForSourceStampsWithDefaults
(reason, sourcestamps, waited_for=False, properties=None, builderNames=None)¶ Parameters: - reason (string) – reason for the build set
- sourcestamps (list) – partial list of source stamps to build
- waited_for (boolean) – if true, this buildset is being waited for (and thus should continue during a clean shutdown)
- properties (
Properties
instance) – properties - in addition to those in the scheduler configuration - to include in the buildset - builderNames (list) – a list of builders for the buildset, or None to use the scheduler’s configured
builderNames
Returns: (buildset ID, buildrequest IDs) via Deferred, as for
addBuildsetForSourceStamps
Create a buildset based on the supplied sourcestamps, with defaults applied from the scheduler’s configuration.
The
sourcestamps
parameter is a list of source stamp dictionaries, giving the required parameters. Any unspecified values, including sourcestamps from unspecified codebases, will be filled in from the scheduler’s configuration. Ifsourcestamps
is None, then only the defaults will be used. Ifsourcestamps
includes sourcestamps for codebases not configured on the scheduler, they will be included anyway, although this is probably a sign of an incorrect configuration.
-
addBuildsetForChanges
(waited_for=False, reason='', external_idstring=None, changeids=[], builderNames=None, properties=None)¶ Parameters: - waited_for (boolean) – if true, this buildset is being waited for (and thus should continue during a clean shutdown)
- reason (string) – reason for the build set
- external_idstring (string) – external identifier for the buildset
- changeids (list) – changes from which to construct the buildset
- builderNames (list) – a list of builders for the buildset, or None to use the scheduler’s configured
builderNames
- properties (
Properties
instance) – properties - in addition to those in the scheduler configuration - to include in the buildset
Returns: (buildset ID, buildrequest IDs) via Deferred, as for
addBuildsetForSourceStamps
Add a buildset for the given changes (
changeids
). This will take sourcestamps from the latest of any changes with the same codebase, and will fill in sourcestamps for any codebases for which no changes are included.
The active state of the scheduler is tracked by the following attribute and methods.
-
active
¶ True if this scheduler is active
-
activate
()¶ Returns: Deferred Subclasses should override this method to initiate any processing that occurs only on active schedulers. This is the method from which to call
startConsumingChanges
, or to set up any timers or message subscriptions.
-
deactivate
()¶ Returns: Deferred Subclasses should override this method to stop any ongoing processing, or wait for it to complete. The method’s returned Deferred should not fire until the processing is complete.
The state-manipulation methods are provided by
buildbot.util.state.StateMixin
. Note that no locking of any sort is performed between these two functions. They should only be called by an active scheduler.-
getState
(name[, default])¶ Parameters: - name – state key to fetch
- default – default value if the key is not present
Returns: Deferred
This calls through to
buildbot.db.state.StateConnectorComponent.getState
, using the scheduler’s objectid.
-
setState
(name, value)¶ Parameters: - name – state key
- value – value to set for the key
Returns: Deferred
This calls through to
buildbot.db.state.StateConnectorComponent.setState
, using the scheduler’s objectid.
-