API

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

clients

class CachingHttpFuture(future, response_adapter, operation=None, request_config=None)[source]

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) Union[Any, Tuple[Any, bravado_core.response.IncomingResponse]][source]

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

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) Union[Any, Tuple[Any, bravado_core.response.IncomingResponse]][source]

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

Parameters

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

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_localized(languages: Optional[list] = None, **kwargs) dict[source]

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

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

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

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)[source]

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: Optional[str] = None, spec_file: Optional[str] = None, version: Optional[str] = None, app_info_text: Optional[str] = None, **kwargs) bravado.client.SwaggerClient[source]

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)[source]

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)[source]

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)[source]

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[source]
exception IncompleteResponseError[source]
exception NotRefreshableTokenError[source]
exception TokenError[source]
exception TokenExpiredError[source]
exception TokenInvalidError[source]

models

class Token(*args, **kwargs)[source]

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) – 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.

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

  • 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.

  • scopes (ManyToManyField) – Scopes. The access scopes granted by this 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.datetime

Determines when this token expires.

Returns

Date & time when this token expires

get_esi_client(**kwargs) bravado.client.SwaggerClient[source]

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) esi.models.Token[source]

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: Optional[requests_oauthlib.oauth2_session.OAuth2Session] = None, auth: Optional[requests.auth.HTTPBasicAuth] = None) None[source]

Refresh this token.

Parameters
  • session – session for refreshing token with

  • auth – ESI authentication

valid_access_token() str[source]

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)[source]
bulk_refresh() django.db.models.query.QuerySet[source]

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) django.db.models.query.QuerySet[source]

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

Parameters

tokenesi.models.Token reference token

get_expired() django.db.models.query.QuerySet[source]

Get all tokens which have expired.

Returns

All expired tokens.

require_scopes(scope_string: Union[str, list]) django.db.models.query.QuerySet[source]

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: Union[str, list]) django.db.models.query.QuerySet[source]

Filter tokens which exactly have the given scopes.

Parameters

scope_string – The required scopes.

Returns

Tokens which have all requested scopes.

require_valid() django.db.models.query.QuerySet[source]

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.