API

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

clients

class CachingHttpFuture(future: FutureAdapter, response_adapter: Callable[[Any], IncomingResponse], operation: Operation | None = None, request_config: RequestConfig | None = None)

Extended wrapper for a FutureAdapter that returns a HTTP response and also supports caching.

This class contains the response for an ESI request with an ESI client.

result(**kwargs) → Any | Tuple[Any, IncomingResponse]

Executes the request and returns the response from ESI. Response will include the requested / first page only if there are more pages available.

Parameters:

• timeout – (optional) timeout for ESI request in seconds, overwrites default

• retries – (optional) max number of retries, overwrites default

• language – (optional) retrieve result for specific language

• ignore_cache – (optional) set to True to ignore response caching

Returns:

Response from endpoint or a tuple with response from endpoint and an incoming response object containing additional meta data including the HTTP response headers

results(**kwargs) → Any | Tuple[Any, IncomingResponse]

Executes the request and returns the response from ESI for the current route. Response will include all pages if there are more available.

Accepts same parameters in kwargs as result()

Returns:

same as result(), but for multiple pages

results_localized(languages: list = None, **kwargs) → dict

Executes the request and returns the response from ESI for all default languages and pages (if any).

Accepts same parameters in kwargs as result() plus languages

Parameters:

languages – (optional) list of languages to return instead of default languages

Returns:

Dict of all responses with the language code as keys.

class EsiClientProvider(datasource=None, spec_file=None, version=None, app_info_text=None, **kwargs)

Class for providing a single ESI client instance for the whole app

Parameters:

• datasource – Name of the ESI datasource to access.

• spec_file – Absolute path to a swagger spec file to load.

• version – Base ESI API version. Accepted values are ‘legacy’, ‘latest’,

• app_info_text – Text identifying the application using ESI which will be included in the User-Agent header. Should contain name and version of the application using ESI. e.g. “my-app v1.0.0”. Note that spaces are used as delimiter.

• kwargs – Explicit resource versions to build, in the form Character=’v4’. Same values accepted as version.

If a spec_file is specified, specific versioning is not available. Meaning the version and resource version kwargs are ignored in favour of the versions available in the spec_file.

esi_client_factory(token=None, datasource: str = None, spec_file: str = None, version: str = None, app_info_text: str = None, **kwargs) → SwaggerClient

Generate a new ESI client.

Parameters:

• token (esi.models.Token) – used to access authenticated endpoints.

• datasource – Name of the ESI datasource to access.

• spec_file – Absolute path to a swagger spec file to load.

• version – Base ESI API version. Accepted values are ‘legacy’, ‘latest’,

• app_info_text – Text identifying the application using ESI which will be included in the User-Agent header. Should contain name and version of the application using ESI. e.g. “my-app v1.0.0”. Note that spaces are used as delimiter.

• kwargs – Explicit resource versions to build, in the form Character=’v4’. Same values accepted as version.

If a spec_file is specified, specific versioning is not available. Meaning the version and resource version kwargs are ignored in favour of the versions available in the spec_file.

Returns:

New ESI client

decorators

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='', 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='', 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.

errors

exception DjangoEsiException

exception IncompleteResponseError

exception NotRefreshableTokenError

exception TokenError

exception TokenExpiredError

exception TokenInvalidError

models

class Token(*args, **kwargs)

EVE Swagger 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)

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

get_esi_client(**kwargs) → SwaggerClient

Creates an authenticated ESI client with this token.

Parameters:

**kwargs – Extra spec versioning as per esi.clients.esi_client_factory

Returns:

New ESI client

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()

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() → QuerySet

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) → QuerySet

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

Parameters:

token – esi.models.Token reference token

get_expired() → QuerySet

Get all tokens which have expired.

Returns:

All expired tokens.

require_scopes(scope_string: str | list) → QuerySet

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) → QuerySet

Filter tokens which exactly have the given scopes.

Parameters:

scope_string – The required scopes.

Returns:

Tokens which have all requested scopes.

require_valid() → QuerySet

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.