# 3.8.13. Users connector

class buildbot.db.users.UsersConnectorComponent

  This class handles Buildbot’s notion of users. Buildbot tracks the usual information about users – username and password, plus a display name.

  The more complicated task is to recognize each user across multiple interfaces with Buildbot. For example, a user may be identified as ‘djmitche’ in Subversion, ‘dustin@v.igoro.us’ in Git, and ‘dustin’ on IRC. To support this functionality, each user has a set of attributes, keyed by type. The `findUserByAttr` method uses these attributes to match users, adding a new user if no matching user is found.

  Users are identified canonically by uid, and are represented by a `UserModel` dataclass with the following fields:

  - `uid`

  - `identifier` (display name for the user)

  - `bb_username` (buildbot login username)

  - `bb_password` (hashed login password)

  - `attributes` (a dictionary of attributes, keyed by type)

  findUserByAttr(identifier, attr_type, attr_data)
    Parameters:

      - identifier – identifier to use for a new user

      - attr_type – attribute type to search for and/or add

      - attr_data – attribute data to add

    Returns:

      userid via Deferred

    Get an existing user, or add a new one, based on the given attribute.

    This method is intended for use by other components of Buildbot to search for a user with the given attributes.

    Note that `identifier` is not used in the search for an existing user. It is only used when creating a new user. The identifier should be based deterministically on the attributes supplied, in some fashion that will seem natural to users.

    For future compatibility, always use keyword parameters to call this method.

  getUser(uid)
    Parameters:

      - uid – user id to look up

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

    Returns:

      `UserModel` or `None` via Deferred

    Get a `UserModel` for the given user, or `None` if no matching user is found.

  getUserByUsername(username)
    Parameters:

      username (string) – username portion of user credentials

    Returns:

      `UserModel` or None via deferred

    Looks up the user with the bb_username, returning a `UserModel` or `None` if no matching user is found.

  getUsers()
    Returns:

      list of `UserModel` without `attributes` via Deferred

    Get the entire list of users. User attributes are not included, so the `attributes` field of the resulting `UserModel` are `None`.

  updateUser(uid=None, identifier=None, bb_username=None, bb_password=None, attr_type=None, attr_data=None)
    Parameters:

      - uid (int) – the user to change

      - identifier (string) – (optional) new identifier for this user

      - bb_username (string) – (optional) new buildbot username

      - bb_password (string) – (optional) new hashed buildbot password

      - attr_type (string) – (optional) attribute type to update

      - attr_data (string) – (optional) value for `attr_type`

    Returns:

      Deferred

    Update information about the given user. Only the specified attributes are updated. If no user with the given uid exists, the method will return silently.

    Note that `bb_password` must be given if `bb_username` appears; similarly, `attr_type` requires `attr_data`.

  removeUser(uid)
    Parameters:

      uid (int) – the user to remove

    Returns:

      Deferred

    Remove the user with the given uid from the database. This will remove the user from any associated tables as well.

  identifierToUid(identifier)
    Parameters:

      identifier (string) – identifier to search for

    Returns:

      uid or `None`, via Deferred

    Fetch a uid for the given identifier, if one exists.