API

This chapter contains the developer reference documentation of the public API for django-esi.

clients

class ESIClientProvider(compatibility_date: str | date, ua_appname: str, ua_version: str, ua_url: str | None = None, spec_file: None | str = None, tenant: str = 'tranquility', operations: list[str] = [], tags: list[str] = [], additional_spec_headers: dict = {}, **kwargs)

Class for providing a single ESI client instance for a whole app * Note that one of either tags or operations must be provided to reduce memory footprint of the client * When DEBUG=False, not supplying either will raise an AttributeError. :param compatibility_date: The compatibility date for the ESI client. :type compatibility_date: str | date :param ua_appname: Name of the App for generating a User-Agent, :type ua_appname: str :param ua_version: Version of the App for generating a User-Agent, :type ua_version: str :param ua_url: URL To the Source Code or Documentation for generating a User-Agent, :type ua_url: str, Optional :param spec_file: Absolute path to a OpenApi 3.1 spec file to load. :type spec_file: str, Optional :param tenant: The ESI tenant to use (default: “tranquility”). :type tenant: str, Optional :param operations: List of operations to filter the spec down. :type operations: list[str], Optional* :param tags: List of tags to filter the spec down. :type tags: list[str], Optional*

Functions:

client(): ESIClient client_async(): ESIClientAsync

decorators

esi_rate_limiter_bucketed(bucket: ESIRateLimitBucket, raise_on_limit: bool = True)

Decorator for custom manual rate limits on some endpoints to apply a polling sleep while the bucket is exhausted. MARKET_DATA_HISTORY CHARACTER_CORPORATION_HISTORY The preferred non-blocking method is to retry your tasks after the limit reset time has passed

Parameters:

• bucket (ESIRateLimitBucket) – The Bucket to rate limit against

• raise_on_limit (bool, optional) – Whether to raise an Exception when the limit is reached. Defaults to True.

rate_limit_retry_task(func)

Retry celery task on ESI rate limit exhaustion.

single_use_token(scopes='', new=False)

Decorator for views which supplies a single use token granted via sso login regardless of login state. Same parameters as tokens_required.

token_required(scopes: list[str] | str = '', new=False)

Decorator for views which supplies a single, user-selected token for the view to process. Same parameters as tokens_required.

tokens_required(scopes: list[str] | str = '', new=False)

Decorator for views to request an ESI Token. Accepts required scopes as a space-delimited string or list of strings of scope names. Can require a new token to be retrieved by SSO. Returns a QueryDict of Tokens.

wait_for_esi_errorlimit_reset(cache_key='esi_error_limit_reset', poll_interval=1) → Callable[[...], Callable[[...], Any]]

Decorator to apply a polling sleep while the ESI Server/Client is in an Error Limit state The preferred non-blocking method is to retry your tasks after the limit reset time has passed

Parameters:

• cache_key (str, optional) – NOT USUALLY CHANGED. Defaults to “esi_error_limit_reset”.

• poll_interval (int, optional) – Interval in seconds to poll redis. Defaults to 1.

errors

exception DjangoEsiException

exception IncompleteResponseError

exception NotRefreshableTokenError

exception TokenError

exception TokenExpiredError

exception TokenInvalidError

models

class Token(*args, **kwargs)

EVE Stable Interface Access Token

Contains information about the authenticating character and scopes granted to this token. Contains the access token required for ESI authentication as well as refreshing.

Parameters:

• id (AutoField) – Primary key: ID

• created (DateTimeField) – Created

• access_token (TextField) – Access token. The access token granted by SSO.

• refresh_token (TextField) – Refresh token. A re-usable token to generate new access tokens upon expiry.

• character_id (IntegerField) – Character id. The ID of the EVE character who authenticated by SSO.

• character_name (CharField) – Character name. The name of the EVE character who authenticated by SSO.

• token_type (CharField) – Token type. The applicable range of the token.

• character_owner_hash (CharField) – Character owner hash. The unique string identifying this character and its owning EVE account. Changes if the owning account changes.

• sso_version (IntegerField) – Sso version. EVE SSO Version.

Relationship fields:

Parameters:

• user (ForeignKey to User) – User. The user to whom this token belongs. (related name: token)

• scopes (ManyToManyField to Scope) – Scopes. The access scopes granted by this token. (related name: token)

Reverse relationships:

Parameters:

callbackredirect (Reverse ForeignKey from CallbackRedirect) – All callback redirects of this token (related name of token)

exception NotUpdated

property can_refresh: bool

Determine if this token can be refreshed upon expiry.

property expired: bool

Determines if this token has expired.

property expires: datetime

Determines when this token expires.

Returns:

Date & time when this token expires

classmethod get_token(character_id: int, scopes: list) → Token

Helper method to get a token for a specific character with specific scopes.

Parameters:

• character_id – Character to filter on.

• scopes – array of ESI scope strings to search for.

Returns:

Matching token or False when token is not found

refresh(session: OAuth2Session = None, auth: HTTPBasicAuth = None) → None

Refresh this token.

Parameters:

• session – session for refreshing token with

• auth – ESI authentication

refresh_or_delete() → None

Refresh this token or delete it if it can not be refreshed.

valid_access_token() → str

Refresh and return access token to be used in an authed ESI call.

Example

# fetch medals for a character
medals = esi.client.Character.get_characters_character_id_medals(
    # required parameter for endpoint
    character_id = token.character_id,
    # provide a valid access token, which will be refreshed if required
    token = token.valid_access_token()
).results()

Returns:

Valid access token

Raises:

TokenExpiredError – When token can not be refreshed

managers

class TokenQueryset(model=None, query=None, using=None, hints=None)

bulk_refresh() → TokenQueryset

Refresh all refreshable tokens in the queryset and delete any expired token that fails to refresh or can not be refreshed.

Excludes tokens for which the refresh was incomplete for other reasons.

Returns:

All refreshed tokens

equivalent_to(token) → TokenQueryset

Fetch all tokens which match the character and scopes of given reference token

Parameters:

token – esi.models.Token reference token

get_expired() → TokenQueryset

Get all tokens which have expired.

Returns:

All expired tokens.

require_scopes(scope_string: str | list) → TokenQueryset

Filter tokens which have at least a subset of given scopes.

Parameters:

scope_string – The required scopes.

Returns:

Tokens which have all requested scopes.

require_scopes_exact(scope_string: str | list) → TokenQueryset

Filter tokens which exactly have the given scopes.

Parameters:

scope_string – The required scopes.

Returns:

Tokens which have all requested scopes.

require_valid() → TokenQueryset

Ensure all tokens are still valid and attempt to refresh any which are expired

Deletes those which fail to refresh or cannot be refreshed.

Returns:

All tokens which are still valid.