# 3.8.11. Source stamps connector

class buildbot.db.sourcestamps.SourceStampsConnectorComponent

  This class manages source stamps, as stored in the database. A source stamp uniquely identifies a particular version of a single codebase. Source stamps are identified by their ID. It is safe to use sourcestamp ID equality as a proxy for source stamp equality. For example, all builds of a particular version of a codebase will share the same sourcestamp ID. This equality does not extend to patches: two sourcestamps generated with exactly the same patch will have different IDs.

  Relative source stamps have a `revision` of None, meaning “whatever the latest is when this sourcestamp is interpreted”. While such source stamps may correspond to a wide array of revisions over the lifetime of a Buildbot installation, they will only ever have one ID.

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

  Sourcestamps are represented by a `SourceStampModel` dataclass with the following fields:

  - `ssid`

  - `branch` (branch, or `None` for default branch)

  - `revision` (revision, or `None` to indicate the latest revision, in

      which case this is a relative source stamp)

  - `repository` (repository containing the source; never `None`)

  - `created_at` (timestamp when this stamp was first created)

  - `codebase` (codebase this stamp is in; never `None`)

  - `project` (project this source is for; never `None`)

  - `patch` (a `PatchModel` or `None`, see below)

  `PatchModel`

  - `patchid` (ID of the patch)

  - `body` (body of the patch, or `None`)

  - `level` (directory stripping level of the patch, or `None`)

  - `subdir` (subdirectory in which to apply the patch, or `None`)

  - `author` (author of the patch, or `None`)

  - `comment` (comment for the patch, or `None`)

  Note that the patch body is a bytestring, not a unicode string.

  findSourceStampId(branch=None, revision=Node, repository=None, project=None, patch_body=None, patch_level=None, patch_author=None, patch_comment=None, patch_subdir=None)
    Parameters:

      - branch (unicode string or None)

      - revision (unicode string or None)

      - repository (unicode string or None)

      - project (unicode string or None)

      - codebase (unicode string (required))

      - patch_body (bytes or unicode string or None) – patch body

      - patch_level (integer or None) – patch level

      - patch_author (unicode string or None) – patch author

      - patch_comment (unicode string or None) – patch comment

      - patch_subdir (unicode string or None) – patch subdir

    Returns:

      ssid, via Deferred

    Create a new SourceStamp instance with the given attributes, or find an existing one. In either case, return its ssid. The arguments all have the same meaning as in an `SourceStampModel`.

    If a new SourceStamp is created, its `created_at` is set to the current time.

  getSourceStamp(ssid)
    Parameters:

      - ssid – sourcestamp to get

      - no_cache (boolean) – bypass cache and always fetch from database

    Returns:

      `SourceStampModel`, or `None`, via Deferred

    Get an `SourceStampModel` representing the given source stamp, or `None` if no such source stamp exists.

  getSourceStamps()
    Returns:

      list of `SourceStampModel`, via Deferred

    Get all sourcestamps in the database. You probably don’t want to do this! This method will be extended to allow appropriate filtering.

  get_sourcestamps_for_buildset(buildsetid)
    Parameters:

      buildsetid – buildset ID

    Returns:

      list of `SourceStampModel`, via Deferred

    Get sourcestamps related to a buildset.

  getSourceStampsForBuild(buildid)
    Parameters:

      buildid – build ID

    Returns:

      list of `SourceStampModel`, via Deferred

    Get sourcestamps related to a build.