# 3.10.7. BaseScheduler

class buildbot.schedulers.base.ReconfigurableBaseScheduler

  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:

      - 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 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.

class buildbot.schedulers.base.BaseScheduler

  This class is legacy counterpart of `ReconfigurableBaseScheduler`. It does not support reconfiguration.