rbtools.utils.users¶

Utilities for working with user sessions.

Functions

rbtools.utils.users.credentials_prompt(server_url: str, username: str | None = None, password: str | None = None, is_retry: bool = False) → tuple[str, str][source]¶

Prompt for a username and/or password using the command line.

Added in version 6.0.

Parameters:

• server_url (str) – The Review Board server URL.

• username (str, optional) – The username for authentication, if one has already been provided.

• password (str, optional) – The password for authentication, if one has already been provided.

• is_retry (bool, optional) – Whether credentials have already been prompted for before.

Returns:

A 2-tuple of:

Tuple:

• username (str) – The user-provided username.

• password (str) – The user-provided password.

Return type:

tuple

Raises:

rbtools.api.errors.AuthorizationError – RBTools is unable to prompt for the credentials.

rbtools.utils.users.get_authenticated_session(api_client: RBClient, api_root: RootResource, auth_required: Literal[True], session: SessionResource | None = None, num_retries: int = 3, via_web: bool | None = None, open_browser: bool | None = None, enable_logging: bool | None = None, capabilities: Capabilities | None = None) → SessionResource[source]¶

rbtools.utils.users.get_authenticated_session(api_client: RBClient, api_root: RootResource, auth_required: Literal[False] = False, session: SessionResource | None = None, num_retries: int = 3, via_web: bool | None = None, open_browser: bool | None = None, enable_logging: bool | None = None, capabilities: Capabilities | None = None) → SessionResource | None

rbtools.utils.users.get_authenticated_session(api_client: RBClient, api_root: RootResource, auth_required: bool, session: SessionResource | None = None, num_retries: int = 3, via_web: bool | None = None, open_browser: bool | None = None, enable_logging: bool | None = None, capabilities: Capabilities | None = None) → SessionResource | None

Return an authenticated session.

None will be returned if the user is not authenticated, unless the ‘auth_required’ parameter is True, in which case the user will be prompted to login.

Changed in version 5.0: Added support for authenticating through web-based login. This includes the new arguments: via_web, open_browser, enable_logging and capabilities.

Parameters:

• api_client (rbtools.api.client.RBClient) – The API client of the command that is creating the server.

• api_root (rbtools.api.resource.RootResource) – The root resource for the Review Board server.

• auth_required (bool, optional) – Whether to require authenticating the user. If True, the user will be prompted to log in if they are not currently authenticated.

• session (rbtools.api.resource.SessionResource, optional) – The current session, if available.

• num_retries (int, optional) – The number of times to retry authenticating if it fails.

• via_web (bool, optional) –

  Whether to use web-based login.

  If this is set, it will take precedence over what’s set in rbtools.api.client.RBClient.web_login_options.

  Added in version 5.0.

• open_browser (bool, optional) –

  Whether to automatically open a browser when using web-based login.

  If this is set, it will take precedence over what’s set in rbtools.api.client.RBClient.web_login_options.

  Added in version 5.0.

• enable_logging (bool, optional) –

  Whether to display the logs for the web login server when using web-based login.

  If this is set, it will take precedence over what’s set in rbtools.api.client.RBClient.web_login_options.

  Added in version 5.0.

• capabilities (rbtools.api.capabilities.Capabilities, optional) –

  The Review Board server capabilities.

  Added in version 5.0.

Returns:

The authenticated session resource or None if the user is not authenticated.

Return type:

rbtools.api.resource.SessionResource

rbtools.utils.users.get_user(api_client: RBClient, api_root: RootResource, auth_required: bool = False) → UserItemResource | None[source]¶

Return the user resource for the current session.

Parameters:

• api_client (rbtools.api.client.RBClient) – The API client of the command that is getting the user.

• api_root (rbtools.api.resource.RootResource) – The root resource for the Review Board server.

• auth_required (bool, optional) – Whether to require authenticating the user. If True, the user will be prompted to log in if they are not currently authenticated.

Returns:

The authenticated session resource or None if the user is not authenticated.

Return type:

rbtools.api.resource.UserItemResource

rbtools.utils.users.get_username(api_client: RBClient, api_root: RootResource, auth_required: bool = False) → str | None[source]¶

Return the username for the current session.

Parameters:

• api_client (rbtools.api.client.RBClient) – The API client of the command that is getting the username.

• api_root (rbtools.api.resource.RootResource) – The root resource for the Review Board server.

• auth_required (bool, optional) – Whether to require authenticating the user. If True, the user will be prompted to log in if they are not currently authenticated.

Returns:

The username of the authenticated user, or None if the user is not authenticated.

Return type:

str