{"id":8096,"library":"django-esi","title":"Django ESI","description":"Django ESI is a Django app that provides a streamlined interface for interacting with the EVE Stable Interface (ESI), the official API for EVE Online. It facilitates dynamic client generation for public and private ESI endpoints, supports EVE Online Single Sign-On (SSO) for character authentication and token retrieval, and offers control over ESI endpoint versions. As of version 9.2.0, it is actively maintained by the Alliance Auth development team and builds upon the `aiopenapi3` library for OpenAPI 3 support.","status":"active","version":"9.2.0","language":"en","source_language":"en","source_url":"https://gitlab.com/alliance-auth/django-esi","tags":["django","eve online","esi","sso","api client"],"install":[{"cmd":"pip install django-esi","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core framework dependency for a Django application.","package":"Django","optional":false},{"reason":"Underlying OpenAPI 3 client library for ESI interactions.","package":"aiopenapi3","optional":false}],"imports":[{"symbol":"ESIClientProvider","correct":"from esi.openapi_clients import ESIClientProvider"},{"note":"Used for views requiring EVE SSO tokens, often with older tutorials or specific authentication flows.","symbol":"token_required","correct":"from esi.decorators import token_required"}],"quickstart":{"code":"import os\nfrom django.conf import settings\n\n# Minimal Django settings for standalone execution (in a real project, these would be in settings.py)\nif not settings.configured:\n    settings.configure(\n        INSTALLED_APPS=['esi'],\n        SECRET_KEY=os.environ.get('DJANGO_SECRET_KEY', 'a-very-secret-key-for-dev'),\n        # Required for EVE SSO, even if not used in this specific public API example\n        ESI_SSO_CLIENT_ID=os.environ.get('ESI_SSO_CLIENT_ID', 'test-dummy'),\n        ESI_SSO_CLIENT_SECRET=os.environ.get('ESI_SSO_CLIENT_SECRET', 'test-dummy'),\n        ESI_SSO_CALLBACK_URL=os.environ.get('ESI_SSO_CALLBACK_URL', 'http://localhost:8000/sso/callback'),\n        ESI_USER_CONTACT_EMAIL=os.environ.get('ESI_USER_CONTACT_EMAIL', 'your_email@example.com'),\n        DEBUG=True # Useful for development, disables some client filters\n    )\n\nfrom esi.openapi_clients import ESIClientProvider\n\n# Instantiate the ESI client provider\n# It's strongly recommended to re-use this client wherever possible (e.g., as a global or singleton).\n# For best results, use a compatibility_date that you genuinely tested against.\n# ua_appname should be PascalCase and ua_version semantic versioning.\n# For development, you can set DEBUG=True in Django settings to temporarily bypass tag/operation filtering.\nesi_client = ESIClientProvider(\n    compatibility_date=\"2024-07-23\", \n    ua_appname=\"MyDjangoApp\", \n    ua_version=\"0.1.0\",\n    # Filtering is crucial for memory efficiency in production\n    # Example: operations=[\"GetAlliances\"], tags=[\"Universe\"]\n    tags=[\"Universe\"]\n)\n\n# Example: Fetching a EVE Universe type (e.g., for 'Vexor')\ntry:\n    # Using the filtered client to access the Universe tag\n    type_id = 603\n    vexor_info = esi_client.client.Universe.GetUniverseTypesTypeId(type_id=type_id).results()\n    print(f\"Fetched EVE Type (ID: {type_id}): {vexor_info.name}\")\n\n    # Example of localized response\n    vexor_info_ko = esi_client.client.Universe.GetUniverseTypesTypeId(\n        type_id=type_id, Accept_Language='ko'\n    ).results()\n    print(f\"Fetched EVE Type in Korean (ID: {type_id}): {vexor_info_ko.name}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to set up `django-esi` in a minimal Django context, instantiate the `ESIClientProvider`, and make a simple request to a public ESI endpoint (e.g., fetching EVE Universe type information). It highlights the importance of `compatibility_date`, User-Agent information, and optional tag/operation filtering for memory optimization. Note that `ESI_SSO_CLIENT_ID`, `ESI_SSO_CLIENT_SECRET`, and `ESI_SSO_CALLBACK_URL` are generally required settings even if not directly used in a public endpoint call."},"warnings":[{"fix":"When creating `ESIClientProvider`, always specify `operations` (list of endpoint names) or `tags` (list of ESI tags, e.g., 'Universe', 'Alliance') to load only the necessary API parts. In `settings.DEBUG=True`, this check is bypassed, and a warning is logged instead.","message":"The OpenAPI client introduced in Django-ESI 8.x can consume significantly more memory due to in-memory Pydantic models. Failing to use `operations` or `tags` filters when instantiating `ESIClientProvider` without `DEBUG=True` will result in an `AttributeError`.","severity":"breaking","affected_versions":"8.x and later"},{"fix":"Choose a `compatibility_date` (YYYY-MM-DD format) that corresponds to when you last verified your ESI integration. Updating Django-ESI itself does not require changing this date unless you are re-testing against newer ESI specifications.","message":"The `compatibility_date` parameter for `ESIClientProvider` should be set to a date you genuinely tested your application against, not 'today'. This header dictates ESI's API behavior for your application.","severity":"gotcha","affected_versions":"All versions using `ESIClientProvider`"},{"fix":"Adhere to the default caching and E-Tag behavior. If disabling `ESI_CACHE_RESPONSE` (by setting to `False`) or custom caching, ensure you understand the implications for ESI rate limits and your application's resource consumption.","message":"Django-ESI 8.x and later heavily rely on caching and E-Tags. Disabling this can lead to excessive ESI requests and higher memory usage for your application if not managed carefully.","severity":"gotcha","affected_versions":"8.x and later"},{"fix":"Ensure the following settings are correctly configured in your `settings.py`: `ESI_SSO_CLIENT_ID`, `ESI_SSO_CLIENT_SECRET`, `ESI_SSO_CALLBACK_URL`, and `ESI_USER_CONTACT_EMAIL`. The contact email is included in the `User-Agent` header for all requests.","message":"EVE SSO and User-Agent settings are mandatory for `django-esi` to function correctly and adhere to CCP's developer guidelines.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Modify the `ESIClientProvider` instantiation to include `operations=['OperationName1', 'OperationName2']` or `tags=['Tag1', 'Tag2']` to load only the necessary ESI endpoints. Example: `esi = ESIClientProvider(..., tags=['Universe'])`.","cause":"The `ESIClientProvider` was instantiated without specifying `operations` or `tags` filters in a production environment (where `settings.DEBUG` is `False`). This is a safeguard against high memory usage.","error":"AttributeError(\"No tag/path filtering supplied to ESI Client.\")"},{"fix":"Verify that your EVE SSO application's callback URL matches `ESI_SSO_CALLBACK_URL` in your Django settings. Ensure all necessary scopes are registered with your SSO app. Run `python manage.py migrate` to ensure the `esi` database tables are correctly set up.","cause":"This error typically occurs during the EVE SSO callback process when the `refresh_token` cannot be stored in the database. Common reasons include misconfigured SSO application settings (e.g., incorrect callback URL, missing scopes), or issues with `python manage.py migrate` for `esi` models.","error":"django.db.utils.IntegrityError: NOT NULL constraint failed: esi_token.refresh_token"},{"fix":"First, ensure `pip install django-esi` was run. Then, add `'esi'` to your `INSTALLED_APPS` list in your Django `settings.py` file: `INSTALLED_APPS = [... 'esi', ...]`","cause":"The 'esi' app is not correctly added to `INSTALLED_APPS` in your Django project's settings, or the `django-esi` package is not installed in your active Python environment.","error":"ModuleNotFoundError: No module named 'esi'"}]}