Changes connector
~~~~~~~~~~~~~~~~~

.. py:module:: buildbot.db.changes

.. index:: double: Changes; DB Connector Component

.. py:class:: ChangesConnectorComponent

    This class handles changes in the Buildbot database, including pulling
    information from the changes sub-tables.

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

    .. index:: chdict, changeid

    Changes are indexed by *changeid*, and are represented by a :class:`ChangeModel` dataclass, which
    has the following fields:

    * ``changeid`` (the ID of this change)
    * ``parent_changeids`` (list of ID; change's parents)
    * ``author`` (unicode; the author of the change)
    * ``committer`` (unicode; the committer of the change)
    * ``files`` (list of unicode; source-code filenames changed)
    * ``comments`` (unicode; user comments)
    * ``is_dir`` (deprecated)
    * ``links`` (list of unicode; links for this change, e.g., to web views,
      review)
    * ``revision`` (unicode string; revision for this change, or ``None`` if
      unknown)
    * ``when_timestamp`` (datetime instance; time of the change)
    * ``branch`` (unicode string; branch on which the change took place, or
      ``None`` for the "default branch", whatever that might mean)
    * ``category`` (unicode string; user-defined category of this change, or
      ``None``)
    * ``revlink`` (unicode string; link to a web view of this change)
    * ``properties`` (user-specified properties for this change, represented as
      a dictionary mapping keys to (value, source))
    * ``repository`` (unicode string; repository where this change occurred)
    * ``project`` (unicode string; user-defined project to which this change
      corresponds)

    .. py:method:: getParentChangeIds(branch, repository, project, codebase)

        :param branch: the branch of the change
        :type branch: unicode string
        :param repository: the repository in which this change took place
        :type repository: unicode string
        :param project: the project this change is a part of
        :type project: unicode string
        :param codebase:
        :type codebase: unicode string

        :returns: the last changeID that matches the branch, repository, project, or codebase

    .. py:method:: addChange(author=None, committer=None, files=None, comments=None, is_dir=0, links=None, revision=None, when_timestamp=None, branch=None, category=None, revlink='', properties={}, repository='', project='', uid=None)

        :param author: the author of this change
        :type author: unicode string
        :param committer: the committer of this change
        :type committer: unicode string
        :param files: a list of filenames that were changed
        :type branch: list of unicode strings
        :param comments: user comments on the change
        :type branch: unicode string
        :param is_dir: deprecated
        :param links: a list of links related to this change, e.g., to web
            viewers or review pages
        :type links: list of unicode strings
        :param revision: the revision identifier for this change
        :type revision: unicode string
        :param when_timestamp: when this change occurred, or the current time
            if None
        :type when_timestamp: datetime instance or None
        :param branch: the branch on which this change took place
        :type branch: unicode string
        :param category: category for this change (arbitrary use by Buildbot
            users)
        :type category: unicode string
        :param revlink: link to a web view of this revision
        :type revlink: unicode string
        :param properties: properties to set on this change, where values are
            tuples of (value, source).  At the moment, the source must be
            ``'Change'``, although this may be relaxed in later versions
        :type properties: dictionary
        :param repository: the repository in which this change took place
        :type repository: unicode string
        :param project: the project this change is a part of
        :type project: unicode string
        :param uid: uid generated for the change author
        :type uid: integer
        :returns: new change's ID via Deferred

        Add a Change with the given attributes to the database, returning the
        changeid via a Deferred.  All arguments should be given as keyword
        arguments.

        The ``project`` and ``repository`` arguments must be strings; ``None``
        is not allowed.

    .. py:method:: getChange(changeid, no_cache=False)

        :param changeid: the id of the change instance to fetch
        :param no_cache: bypass cache and always fetch from database
        :type no_cache: boolean
        :returns: :class:`ChangeModel` or None, via Deferred

        Get a :class:`ChangeModel` for the given changeid, or ``None`` if no such
        change exists.

    .. py:method:: getChangeUids(changeid)

        :param changeid: the id of the change instance to fetch
        :returns: list of uids via Deferred

        Get the userids associated with the given changeid.

    .. py:method:: getChanges(resultSpec=None)

        :param resultSpec: result spec containing filters sorting and paging requests from data/REST API.
            If possible, the db layer can optimize the SQL query using this information.
        :returns: list of :class:`ChangeModel` via Deferred

        Get a list of the changes, represented as :class:`ChangeModel`, matching the given
        criteria. if ``resultSpec`` is not provided, changes are sorted, and paged
        using generic data query options.

    .. py:method:: getChangesCount()

        :returns: list of dictionaries via Deferred

        Get the number of changes that the query option would return if no paging option was set.


    .. py:method:: getLatestChangeid()

        :returns: changeid via Deferred

        Get the most-recently-assigned changeid, or ``None`` if there are no changes at all.


    .. py:method:: getChangesForBuild(buildid)

        :param buildid: ID of the build
        :returns: list of :class:`ChangeModel` via Deferred

        Get the "blame" list of changes for a build.

    .. py:method:: getBuildsForChange(changeid)

        :param changeid: ID of the change
        :returns: list of :class:`ChangeModel` via Deferred

        Get builds related to a change.

    .. py:method:: getChangeFromSSid(sourcestampid)

        :param sourcestampid: ID of the sourcestampid
        :returns: :class:`ChangeModel` via Deferred

        Returns the :class:`ChangeModel` related to the sourcestamp ID.
