3.10.7. 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 changesonlyImportant (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 to include in the buildset, in addition to those in the scheduler configurationbuilderNames (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 to include in the buildset, in addition to those in the scheduler configurationbuilderNames (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 to include in the buildset, in addition to those in the scheduler configuration
- 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.