django-esi 7.0.0b1__tar.gz → 8.0.0a1__tar.gz

{django_esi-7.0.0b1 → django_esi-8.0.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-esi
-Version: 7.0.0b1
+Version: 8.0.0a1
 Summary: Django app for accessing the EVE Swagger Interface (ESI).
 Author-email: Alliance Auth <adarnof@gmail.com>
 Requires-Python: >=3.8
@@ -24,14 +24,16 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
 License-File: LICENSE
+Requires-Dist: aiopenapi3
 Requires-Dist: bravado>=10.6,<12
-Requires-Dist: brotli
 Requires-Dist: celery>=4.0.2
 Requires-Dist: django>=4.2,<6
+Requires-Dist: httpx[http2, brotli, zstd]
 Requires-Dist: jsonschema<4
 Requires-Dist: python-jose>=3.3
 Requires-Dist: requests>=2.26
 Requires-Dist: requests-oauthlib>=0.8
+Requires-Dist: tenacity
 Requires-Dist: tqdm>=4.62.3
 Requires-Dist: myst-parser ; extra == "docs"
 Requires-Dist: sphinx ; extra == "docs"

{django_esi-7.0.0b1 → django_esi-8.0.0a1}/esi/__init__.py

@@ -1,5 +1,6 @@
 """Django app for accessing the EVE Swagger Interface (ESI)."""
 
-__version__ = '7.0.0b1'
+__version__ = '8.0.0a1'
 __title__ = 'Django-ESI'
 __url__ = 'https://gitlab.com/allianceauth/django-esi'
+__build_date__ = "2025-08-26"

{django_esi-7.0.0b1 → django_esi-8.0.0a1}/esi/admin.py

@@ -1,7 +1,8 @@
 from django.contrib import admin
 from django.contrib.auth import get_user_model
+from django.db.models import QuerySet
 
-from .models import Token, Scope, CallbackRedirect
+from .models import CallbackRedirect, Scope, Token
 
 admin.site.register(CallbackRedirect)
 
@@ -13,14 +14,14 @@ class ScopeAdmin(admin.ModelAdmin):
 
 @admin.register(Token)
 class TokenAdmin(admin.ModelAdmin):
-    def get_queryset(self, request):
+    def get_queryset(self, request) -> QuerySet["Token"]:
         qs = super().get_queryset(request)
         return qs.select_related('user').prefetch_related('scopes')
 
     @admin.display(
         description='Scopes'
     )
-    def get_scopes(self, obj):
+    def get_scopes(self, obj) -> str:
         return ", ".join([x.name for x in obj.scopes.all()])
 
     User = get_user_model()

django_esi-8.0.0a1/esi/aiopenapi3/plugins.py

@@ -0,0 +1,78 @@
+from aiopenapi3.plugin import Document
+
+
+class RemoveSecurityParameter(Document):
+    """
+    Removes the whole OAuth2 securityScheme
+    """
+    def parsed(self, ctx: Document.Context) -> Document.Context:
+        print("RemoveSecurityParameterPlugin: Removing OAuth2 securityScheme")
+        spec = ctx.document
+        oauth2 = spec.get("components", {}).get("securitySchemes", {}).pop("OAuth2", None)
+        # Patch all paths
+        for path_item in spec.get("paths", {}).values():
+            for method_name in ("get", "post", "put", "delete", "patch", "options", "head"):
+                method = path_item.get(method_name)
+                if not method:
+                    continue
+                method.pop("security", None)
+
+        return ctx
+
+
+class TrimSecurityParameter(Document):
+    """TrimSecurityParameter
+    Trims out of Spec OAuth2 attributes. CCP have fixed this.
+    Leaving in place in case we need a quick reference again.
+    """
+    def parsed(self, ctx: Document.Context) -> Document.Context:
+        print("TrimSecurityParameter: Trimming out of spec attributes")
+        spec = ctx.document
+        oauth2 = spec.get("components", {}).get("securitySchemes", {}).get("OAuth2")
+        if oauth2 and oauth2.get("type") == "oauth2":
+            oauth2.pop("in", None)
+            oauth2.pop("name", None)
+        return ctx
+
+
+class PatchCompatibilityDatePlugin(Document):
+    """
+    Makes the X-Compatibility-Date header optional
+
+    This is because WE specifically add it in the library to the HTTP requests,
+    but without this, it will be a required parameter during request generation before it hits the HTTP library.
+    """
+    def parsed(self, ctx: Document.Context) -> Document.Context:
+        print("PatchCompatibilityDatePlugin: making compatibility date optional")
+        spec = ctx.document
+
+        def patch_param(param):
+            # Follow $ref if present
+            if "$ref" in param:
+                ref = param["$ref"]
+                parts = ref.split("/")
+                if parts[1] == "components" and parts[2] == "parameters":
+                    param_name = parts[-1]
+                    comp_param = spec.get("components", {}).get("parameters", {}).get(param_name)
+                    if comp_param and comp_param.get("name") == "X-Compatibility-Date":
+                        comp_param["required"] = False
+            else:
+                # Inline parameter
+                if (param.get("name") == "X-Compatibility-Date" and param.get("in") == "header"):
+                    param["required"] = False
+
+        # Patch all paths
+        for path_item in spec.get("paths", {}).values():
+            for method_name in ("get", "post", "put", "delete", "patch", "options", "head"):
+                method = path_item.get(method_name)
+                if not method:
+                    continue
+                for param in method.get("parameters", []):
+                    patch_param(param)
+
+        # Patch global parameters in components
+        for param_name, param in spec.get("components", {}).get("parameters", {}).items():
+            if param.get("name") == "X-Compatibility-Date" and param.get("in") == "header":
+                param["required"] = False
+
+        return ctx

{django_esi-7.0.0b1 → django_esi-8.0.0a1}/esi/app_settings.py

@@ -66,8 +66,21 @@ ESI_REQUESTS_CONNECT_TIMEOUT = getattr(settings, 'ESI_REQUESTS_CONNECT_TIMEOUT',
 Can temporarily overwritten with by passing ``timeout`` with ``result()``
 """
 
-ESI_REQUESTS_READ_TIMEOUT = getattr(settings, 'ESI_REQUESTS_READ_TIMEOUT', 30)
+ESI_REQUESTS_READ_TIMEOUT = getattr(settings, 'ESI_REQUESTS_READ_TIMEOUT', 10)
 """Default read timeouts for all requests to ESI.
+This should be a maximum of 10s as ESI cuts all requests to the monolith off @ 10s.
+
+Can temporarily overwritten with by passing ``timeout`` with ``result()``
+"""
+
+ESI_REQUESTS_WRITE_TIMEOUT = getattr(settings, 'ESI_REQUESTS_WRITE_TIMEOUT', 5)
+"""Default write timeouts for all requests to ESI.
+
+Can temporarily overwritten with by passing ``timeout`` with ``result()``
+"""
+
+ESI_REQUESTS_POOL_TIMEOUT = getattr(settings, 'ESI_REQUESTS_POOL_TIMEOUT', 5)
+"""Default pool timeouts for all requests to ESI.
 
 Can temporarily overwritten with by passing ``timeout`` with ``result()``
 """

{django_esi-7.0.0b1 → django_esi-8.0.0a1}/esi/checks.py

@@ -1,5 +1,5 @@
-from django.core.checks import Error, Warning, register, Tags
 from django.conf import settings
+from django.core.checks import Error, Tags, Warning, register
 
 
 @register(Tags.security)

{django_esi-7.0.0b1 → django_esi-8.0.0a1}/esi/clients.py

@@ -1,28 +1,27 @@
-from datetime import datetime
-from hashlib import md5
 import json
 import logging
+import warnings
+from datetime import datetime
+from hashlib import md5
 from time import sleep
+from typing import Any
 from urllib import parse as urlparse
-from typing import Any, Union, Tuple
-import warnings
 
-from bravado.client import SwaggerClient
 from bravado import requests_client
+from bravado.client import SwaggerClient
 from bravado.exception import (
-    HTTPBadGateway, HTTPGatewayTimeout, HTTPServiceUnavailable
+    HTTPBadGateway, HTTPGatewayTimeout, HTTPServiceUnavailable,
 )
-from bravado_core.response import IncomingResponse
-from bravado.swagger_model import Loader
 from bravado.http_future import HttpFuture
-from bravado_core.spec import Spec, CONFIG_DEFAULTS
+from bravado.swagger_model import Loader
+from bravado_core.response import IncomingResponse
+from bravado_core.spec import CONFIG_DEFAULTS, Spec
 from requests.adapters import HTTPAdapter
 
 from django.core.cache import cache
 
+from . import __title__, __url__, __version__, app_settings
 from .errors import TokenExpiredError
-from . import app_settings, __version__, __title__, __url__
-
 
 logger = logging.getLogger(__name__)
 
@@ -75,7 +74,7 @@ class CachingHttpFuture(HttpFuture):
         except ValueError:
             return 0
 
-    def results(self, **kwargs) -> Union[Any, Tuple[Any, IncomingResponse]]:
+    def results(self, **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.
 
@@ -143,7 +142,7 @@ class CachingHttpFuture(HttpFuture):
             for language in my_languages
         }
 
-    def result(self, **kwargs) -> Union[Any, Tuple[Any, IncomingResponse]]:
+    def result(self, **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.
 
@@ -222,7 +221,7 @@ class CachingHttpFuture(HttpFuture):
 
         return super().result(**kwargs)
 
-    def _result_with_retries(self, **kwargs) -> Tuple[Any, IncomingResponse]:
+    def _result_with_retries(self, **kwargs) -> tuple[Any, IncomingResponse]:
         """Execute request and retry on certain HTTP errors.
 
         ``kwargs`` are passed through to super().result()

{django_esi-7.0.0b1 → django_esi-8.0.0a1}/esi/decorators.py

@@ -1,14 +1,18 @@
+import functools
 import logging
+import time
 from functools import wraps
-from typing import Union
 
-from .models import Token, CallbackRedirect
+from django.core.cache import cache
 
+from esi.rate_limiting import ESIRateLimitBucket, ESIRateLimits
+
+from .models import CallbackRedirect, Token
 
 logger = logging.getLogger(__name__)
 
 
-def _check_callback(request) -> Union[Token, None]:
+def _check_callback(request) -> Token | None:
     # ensure session installed in database
     if not request.session.exists(request.session.session_key):
         logger.debug("Creating new session for %s", request.user)
@@ -221,3 +225,31 @@ def single_use_token(scopes='', new=False):
         return _wrapped_view
 
     return decorator
+
+
+def wait_for_esi_errorlimit_reset(cache_key="esi_error_limit_reset", poll_interval=1):
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            reset = cache.get(cache_key)
+            if reset is not None:
+                print(f"ESI Error Limited, waiting {reset}s before retrying...")
+                while cache.get(cache_key):
+                    time.sleep(poll_interval)
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator
+
+
+def esi_rate_limiter_bucketed(
+    bucket: ESIRateLimitBucket,
+    raise_on_limit: bool = True,
+):
+    # TODO Investigate esi cache hits.
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            ESIRateLimits.check_bucket(bucket, raise_on_limit)
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator

django_esi-8.0.0a1/esi/exceptions.py

@@ -0,0 +1,18 @@
+class ESIErrorLimitException(Exception):
+    """ESI Global Error Limit Exceeded
+    https://developers.eveonline.com/docs/services/esi/best-practices/#error-limit
+    """
+    def __init__(self, reset=None, *args, **kwargs) -> None:
+        self.reset = reset
+        msg = kwargs.get("message") or (
+            f"ESI Error limited. Reset in {reset} seconds." if reset else "ESI Error limited."
+        )
+        super().__init__(msg, *args)
+
+
+class ESIBucketLimitException(Exception):
+    """Endpoint (Bucket) Specific Rate Limit Exceeded"""
+    def __init__(self, bucket, *args, **kwargs) -> None:
+        self.bucket = bucket
+        msg = kwargs.get("message") or f"ESI bucket limit reached for {bucket}."
+        super().__init__(msg, *args)

django_esi-8.0.0a1/esi/helpers.py

@@ -0,0 +1,25 @@
+from esi.models import Token
+
+
+def get_token(character_id: int, scopes: list) -> Token:
+    """Helper method to get a valid token for a specific character with specific scopes.
+
+    Args:
+        character_id: Character to filter on.
+        scopes: array of ESI scope strings to search for.
+
+    Returns:
+        Matching Token
+    """
+    qs = (
+        Token.objects
+        .filter(character_id=character_id)
+        .require_scopes(scopes)
+        .require_valid()
+    )
+    token = qs.first()
+    if token is None:
+        raise Token.DoesNotExist(
+            f"No valid token found for character_id={character_id} with required scopes."
+        )
+    return token

{django_esi-7.0.0b1 → django_esi-8.0.0a1}/esi/locale/en/LC_MESSAGES/django.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PACKAGE VERSION\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-10-08 23:42+1000\n"
+"POT-Creation-Date: 2025-06-30 10:57+1000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -18,11 +18,11 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "Plural-Forms: nplurals=2; plural=(n != 1);\n"
 
-#: esi/models.py:72
+#: esi/models.py:73
 msgid "Character"
 msgstr ""
 
-#: esi/models.py:73
+#: esi/models.py:74
 msgid "Corporation"
 msgstr ""
 

django_esi-8.0.0a1/esi/management/commands/generate_esi_stubs.py

@@ -0,0 +1,211 @@
+import os
+import re
+
+from aiopenapi3 import OpenAPI
+from httpx import Client, Timeout
+
+from django.core.management.base import BaseCommand
+
+from esi import __title__, __url__, __version__, app_settings, stubs, __build_date__
+from esi.aiopenapi3.plugins import PatchCompatibilityDatePlugin
+
+# OpenAPI Types to Python
+TYPE_MAP = {
+    "integer": "int",
+    "number": "float",
+    "string": "str",
+    "boolean": "bool",
+    "array": "list[Any]",
+    "object": "dict[str, Any]",
+}
+
+
+def sanitize_class_name(name: str) -> str:
+    """Convert a tag into a valid Python class name."""
+    sanitized = re.sub(r'[^0-9a-zA-Z_]', '_', name.strip())
+    if sanitized and not sanitized[0].isalpha():
+        sanitized = f"_{sanitized}"
+    return sanitized
+
+
+def sanitize_operation_class(name: str) -> str:
+    return re.sub(r'[^0-9a-zA-Z_]', '', name[0].upper() + name[1:] + "Operation")
+
+
+def schema_to_type(schema) -> str:
+    """Convert an OpenAPI schema to a Python type hint."""
+    if not schema:
+        return "Any"
+    schema_type = getattr(schema, "type", None)
+    if schema_type == "array":
+        items_schema = getattr(schema, "items", None)
+        inner = schema_to_type(items_schema)
+        return f"list[{inner}]"
+    if schema_type == "object":
+        return "dict[str, Any]"
+    return TYPE_MAP.get(schema_type, "Any")
+
+
+class Command(BaseCommand):
+    help = "Generate ESI Stubs from the current ESI spec with correct type hints."
+
+    def add_arguments(self, parser):
+        parser.add_argument(
+            "--output",
+            default=None,
+            help="Custom output path for the generated ESI stub file (default: stubs.pyi next to openapi_clients.py).",
+        )
+        parser.add_argument(
+            "--compatibility_date",
+            default=__build_date__,
+            help="Compatibility Date to build ESI Stubs from.",
+        )
+
+    def handle(self, *args, **options):
+        self.stdout.write("Starting ESI stub generation...")
+
+        headers = {
+            "User-Agent": f"{__title__}/{__version__} (+{__url__})",
+            "X-Tenant": "tranquility",
+            "X-Compatibility-Date": options["compatibility_date"]
+        }
+
+        def session_factory(**kwargs) -> Client:
+            kwargs.pop("headers", None)
+            return Client(
+                headers=headers,
+                timeout=Timeout(
+                    connect=app_settings.ESI_REQUESTS_CONNECT_TIMEOUT,
+                    read=app_settings.ESI_REQUESTS_READ_TIMEOUT,
+                    write=app_settings.ESI_REQUESTS_WRITE_TIMEOUT,
+                    pool=app_settings.ESI_REQUESTS_POOL_TIMEOUT
+                ),
+                **kwargs
+            )
+
+        spec_url = f"{app_settings.ESI_API_URL}meta/openapi.json"
+        stub_api = OpenAPI.load_sync(
+            url=spec_url,
+            session_factory=session_factory,
+            use_operation_tags=True,
+            plugins=[PatchCompatibilityDatePlugin()],
+        )
+
+        base_path = os.path.dirname(stubs.__file__)
+        output_path = options["output"] or os.path.join(base_path, "stubs.pyi")
+
+        self.stdout.write(f"Outputting to: {output_path}")
+
+        spec_root = stub_api._root
+        with open(output_path, "w", encoding="utf-8") as f:
+            # File headers
+            f.write("# flake8: noqa=E501\n")
+            f.write("# Auto Generated do not edit\n")
+            # Python Imports
+            f.write("from typing import Any, Optional\n\n")
+            f.write("from esi.openapi_clients import EsiOperation\n")
+            f.write("from esi.models import Token\n\n\n")
+
+            operation_classes = {}
+
+            for tag in sorted(stub_api._operationindex._tags.keys()):
+                # ESI Operation
+                # The various methods called on an ESI Operation
+                # result(), Results(), Results_Localized() etc. all live here
+                ops = stub_api._operationindex._tags[tag]
+                for nm, op in sorted(ops._operations.items()):
+                    op_obj = op[2]
+                    docstring = (op_obj.description or op_obj.summary or "").replace("\n", " ").strip()
+                    op_class_name = sanitize_operation_class(nm)
+
+                    response_type = "Any"
+                    try:
+                        resp_200 = op_obj.responses.get("200")
+                        if resp_200 and "application/json" in resp_200.content:
+                            response_type = schema_to_type(resp_200.content["application/json"].schema_)
+                    except Exception:
+                        response_type = "Any"
+
+                    results_type = response_type if response_type.startswith("list[") else f"list[{response_type}]"
+
+                    if op_class_name not in operation_classes:
+                        f.write(f"class {op_class_name}(EsiOperation):\n")
+                        f.write("    \"\"\"EsiOperation, use result(), results() or results_localized()\"\"\"\n")
+
+                        # result()
+                        f.write(f"    def result(self, etag: str | None = None, return_response: bool = False, use_cache: bool = True, **extra) -> {response_type}:\n")  # noqa: E501
+                        f.write(f"        \"\"\"{docstring}\"\"\"\n") if docstring else None
+                        f.write("        ...\n\n")
+
+                        # results()
+                        f.write(f"    def results(self, etag: str | None = None, return_response: bool = False, use_cache: bool = True, **extra) -> {results_type}:\n")  # noqa: E501
+                        f.write(f"        \"\"\"{docstring}\"\"\"\n") if docstring else None
+                        f.write("        ...\n\n")
+
+                        # results_localized()
+                        f.write(f"    def results_localized(self, languages: str | list[str] = 'en', **kwargs) -> {results_type}:\n")
+                        f.write(f"        \"\"\"{docstring}\"\"\"\n") if docstring else None
+                        f.write("        ...\n\n\n")
+
+                        operation_classes[op_class_name] = True
+
+            f.write("class ESIClientStub:\n")
+            for tag in sorted(stub_api._operationindex._tags.keys()):
+                # ESI ESIClientStub
+                # The various ESI Tags and Operations
+                ops = stub_api._operationindex._tags[tag]
+                class_name = f"_{sanitize_class_name(tag)}"
+                f.write(f"    class {class_name}:\n")
+                for nm, op in sorted(ops._operations.items()):
+                    op_obj = op[2]
+                    effective_security = (
+                        getattr(op_obj, "security", None) or getattr(spec_root, "security", None)
+                    )
+
+                    def _has_oauth2(sec) -> bool:
+                        data = sec if isinstance(sec, dict) else getattr(sec, "root", None)
+                        if not isinstance(data, dict):
+                            return False
+                        return any(k.lower() == "oauth2" for k in data)
+
+                    needs_oauth = any(_has_oauth2(s) for s in (effective_security or []))
+
+                    params = ["self"]
+                    optional_params = []
+                    for p in getattr(op_obj, "parameters", []):
+                        required = getattr(p, "required", False)
+                        schema_type_value = getattr(getattr(p, "schema_", None), "type", None)
+                        if isinstance(schema_type_value, str):
+                            param_type = TYPE_MAP.get(schema_type_value, "Any")
+                        else:
+                            param_type = "Any"
+                        default = ""
+                        if not required:
+                            param_type = f"Optional[{param_type}]"
+                            default = " = ..."
+                        param_name = p.name.replace("-", "_")
+                        if param_name == "authorization" and needs_oauth:
+                            # Skip the Authorization Parameter, we inject this at HTTP Header Level
+                            continue
+                        if required:
+                            params.append(f"{param_name}: {param_type}{default}")
+                        else:
+                            optional_params.append(f"{param_name}: {param_type}{default}")
+                    if needs_oauth:
+                        # Here, we add our own custom param instead of the earlier Authorization
+                        # Our library will pick this up and use it later
+                        params.append("token: Token")
+                    optional_params.append("**kwargs: Any")
+                    params_str = ", ".join(params + optional_params)
+                    op_class_name = sanitize_operation_class(nm)
+                    docstring = (op_obj.description or op_obj.summary or "").replace("\n", " ").strip()
+
+                    if docstring:
+                        f.write(f"        def {nm}({params_str}) -> {op_class_name}:\n")
+                        f.write(f"            \"\"\"{docstring}\"\"\"\n")
+                        f.write("            ...\n\n")
+                    else:
+                        f.write(f"        def {nm}({params_str}) -> {op_class_name}: ...\n")
+                f.write(f"\n    {sanitize_class_name(tag)}: {class_name} = {class_name}()\n\n")
+
+        self.stdout.write(self.style.SUCCESS(f"ESI stubs written to {output_path}"))