djblets.webapi.managers¶

Managers for API-related database models.

class WebAPITokenManager(*args, **kwargs)¶

Bases: Manager

Manages WebAPIToken models.

generate_token(user, max_attempts=20, note=None, policy={}, auto_generated=False, expires=None, token_generator_id=None, token_info=None, **kwargs)¶

Generate a WebAPIToken for a user.

This will attempt to construct a unique WebAPIToken for a user.

Since a collision is possible, it will try up to a certain number of times. If it cannot create a unique token, a WebAPITokenGenerationError will be raised.

Changed in version 3.0:

• Added the token_generator_id and token_info parameters. These are used to specify what type of token to generate. These parameters are currently optional but will be required in Djblets 4.0.

• Added the optional expires parameter. This can be used to set an expiration date for the token.

Parameters:

• user (django.contrib.auth.models.User) – The user who will own the token.

• max_attempts (int, optional) – The maximum number of attempts to try to find a non-conflicting token. Defaults to 20.

• note (unicode, optional) – A note describing the token.

• policy (dict, optional) – The policy document describing what this token can access in the API. By default, this provides full access.

• auto_generated (bool, optional) –

  Whether or not the token is being automatically generated.

  This parameter does not affect token generation. It’s value will solely be used in the webapi_token_created signal.

• expires (datetime.datetime, optional) –

  The date and time that the token will expire. By default the token will never expire.

  New in version 3.0.

• token_generator_id (str, optional) –

  The ID of the token generator to use for generating the token. If not set, this will default to :py:class: djblets.secrets.token_generators.legacy_sha1 .LegacySHA1TokenGenerator’s ID.

  This parameter will be required in Djblets 4.0.

  New in version 3.0.

• token_info (dict, optional) –

  A dictionary that contains information needed for token generation. If not set, this will default to a dictionary that contains necessary information for the :py:class: djblets.secrets.token_generators.legacy_sha1 .LegacySHA1TokenGenerator.

  See djblets.secrets.token_generators for further details on what is required here for each token generator.

  This parameter will be required in Djblets 4.0.

  New in version 3.0.

• **kwargs (dict) – Additional keyword arguments representing fields in the token. These will be set on the token object.

Returns:

The generated API token.

Return type:

djblets.webapi.models.BaseWebAPIToken

Raises:

• djblets.webapi.errors.WebAPITokenGenerationError – The token was not able to be generated after max_attempts number of collisions were hit.

• KeyError – The token_info dictionary is missing a required key.

invalidate_tokens(users=None, extra_query=None, invalid_reason='')¶

Invalidate a set of tokens.

New in version 3.0.

Parameters:

• users (list of int, optional) – The list of user IDs whose tokens will be invalidated. By default this is set to None, in which case the tokens for all users will be invalidated. The set of tokens to invalidate can be further filtered down using :py:param`extra_query`.

• extra_query (django.db.models.Q, optional) – Additional query parameters to filter the set of tokens that will be invalidated.

• invalid_reason (str, optional) – A message indicating why the tokens are invalid. This defaults to an empty string.

invalidate_token(token, invalid_reason='')¶

Invalidate the given token.

New in version 3.0.

Parameters:

• token (str) – The token value of the token to invalidate.

• invalid_reason (str, optional) – A message indicating why the token is invalid. This defaults to an empty string.