# 3.8.6. Steps connector

class buildbot.db.steps.StepsConnectorComponent

  This class handles the steps performed within the context of a build. Within a build, each step has a unique name and a unique 0-based number.

  An instance of this class is available at `master.db.steps`.

  Steps are indexed by stepid and are represented by a `StepModel` dataclass with the following fields:

  - `id` (the step ID, globally unique)

  - `number` (the step number, unique only within the build)

  - `name` (the step name, an 50-character identifier unique only within the build)

  - `buildid` (the ID of the build containing this step)

  - `started_at` (datetime at which this step began)

  - `locks_atquired_at` (datetime at which this step acquired or None if the step has not yet acquired locks)

  - `complete_at` (datetime at which this step finished, or None if it is ongoing)

  - `state_string` (short string describing the step’s state)

  - `results` (results of this step; see Build Result Codes)

  - `urls` (list of URLs produced by this step. Each urls is stored as a `UrlModel` dataclass)

  - `hidden` (true if the step should be hidden in status displays)

  Urls are represented by a `UrlModel` dataclass with the following fields:

  - `name`

  - `url`

  getStep(stepid=None, buildid=None, number=None, name=None)
    Parameters:

      - stepid (integer) – the step id to retrieve

      - buildid (integer) – the build from which to get the step

      - number (integer) – the step number

      - name (50-character identifier) – the step name

    Returns:

      `StepModel` or `None` via Deferred

    Get a single step. The step can be specified by:

    > - `stepid` alone

    > - `buildid` and `number`, the step number within that build

    > - `buildid` and `name`, the unique step name within that build

  getSteps(buildid)
    Parameters:

      buildid (integer) – the build from which to get the step

    Returns:

      list of `StepModel`, sorted by number, via Deferred

    Get all steps in the given build, ordered by number.

  addStep(self, buildid, name, state_string)
    Parameters:

      - buildid (integer) – the build to which to add the step

      - name (50-character identifier) – the step name

      - state_string (unicode) – the initial state of the step

    Returns:

      tuple of step ID, step number, and step name, via Deferred

    Add a new step to a build. The given name will be used if it is unique; otherwise, a unique numerical suffix will be appended.

  setStepStateString(stepid, state_string):
    Parameters:

      - stepid (integer) – step ID

      - state_string (unicode) – updated state of the step

    Returns:

      Deferred

    Update the state string for the given step.

  finishStep(stepid, results, hidden)
    Parameters:

      - stepid (integer) – step ID

      - results (integer) – step result

      - hidden (bool) – true if the step should be hidden

    Returns:

      Deferred

    Mark the given step as finished, with `complete_at` set to the current time.

    Note

    This update is done unconditionally, even if the steps are already finished.

  addURL(self, stepid, name, url)
    Parameters:

      - stepid (integer) – the stepid to add the url.

      - name (string) – the url name

      - url (string) – the actual url

    Returns:

      None via deferred

    Add a new url to a step. The new url is added to the list of urls.