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)[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) Any | Tuple[Any, 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
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] [source]
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
asresult()
- Returns:
same as
result()
, but for multiple pages
- results_localized(languages: list = None, **kwargs) dict [source]
Executes the request and returns the response from ESI for all default languages and pages (if any).
Accepts same parameters in
kwargs
asresult()
pluslanguages
- 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)[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: str = None, spec_file: str = None, version: str = None, app_info_text: str = None, **kwargs) 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.
errors
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) – 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
toUser
) – User. The user to whom this token belongs. (related name:token
)scopes (
ManyToManyField
toScope
) – Scopes. The access scopes granted by this token. (related name:token
)
Reverse relationships:
- Parameters:
callbackredirect (Reverse
ForeignKey
fromCallbackRedirect
) – All callback redirects of this token (related name oftoken
)
- property expires: datetime
Determines when this token expires.
- Returns:
Date & time when this token expires
- get_esi_client(**kwargs) 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) 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: OAuth2Session = None, 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() 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) QuerySet [source]
Fetch all tokens which match the character and scopes of given reference token
- Parameters:
token –
esi.models.Token
reference token
- require_scopes(scope_string: str | list) 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.