Caution

This page documents the latest, unreleased version of Buildbot. For documentation for released versions, see http://docs.buildbot.net/current/.

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 calling startConsumingChanges from startActivity.

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, or None 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 (if fileIsImportant is not None) classifying them.

gotChange(change, important)
Parameters:
Returns:

Deferred

This method is called when a change is received. Schedulers which consume changes should implement this method.

If the fileIsImportant parameter to startConsumingChanges was None, then all changes are considered important. It is guaranteed that the codebase 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 configuration

  • 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, and codebase), or an integer sourcestampid.

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 configuration

  • 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. If sourcestamps is None, then only the defaults will be used. If sourcestamps 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.