django-esi 7.0.1__py3-none-any.whl → 8.0.0a2__py3-none-any.whl

esi/management/commands/generate_esi_stubs.py

@@ -0,0 +1,228 @@
+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\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_type = op[0]
+                    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:
+                        match op_type:
+                            case "post":
+                                resp_201 = op_obj.responses.get("201")
+                                if resp_201 and "application/json" in resp_201.content:
+                                    response_type = schema_to_type(resp_201.content["application/json"].schema_)
+                            case "put" | "delete":
+                                response_type = "None"
+                            case _:
+                                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")
+                        if response_type != "None":
+                            f.write("    \"\"\"EsiOperation, use result(), results() or results_localized()\"\"\"\n")
+                        else:
+                            f.write("    \"\"\"EsiOperation, use result()\"\"\"\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")
+                        if response_type != "None":
+                            # We only need the extra utility functions if its actually an endpoint that returns data
+                            # 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: list[str] | str | None = None, **extra) -> dict[str, {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 = []
+                    if getattr(op_obj, "requestBody", None):
+                        params.append(f"body: {schema_to_type(op_obj.requestBody.content['application/json'].schema_)}")
+
+                    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"{param_type} | None"
+                            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}"))

esi/managers.py

@@ -1,21 +1,22 @@
 import logging
 from datetime import timedelta
-from typing import Any, Union
+from typing import Any
 
 import requests
-from django.db import models
-from django.utils import timezone
 from jose import jwt
 from jose.exceptions import ExpiredSignatureError, JWTError
 from requests_oauthlib import OAuth2Session
 
+from django.db import models
+from django.utils import timezone
+
 from . import app_settings
 from .errors import IncompleteResponseError, TokenError
 
 logger = logging.getLogger(__name__)
 
 
-def _process_scopes(scopes):
+def _process_scopes(scopes) -> set[str]:
     if scopes is None:
         # support filtering by no scopes with None passed
         scopes = []
@@ -28,8 +29,8 @@ def _process_scopes(scopes):
     return {str(s) for s in scopes}
 
 
-class TokenQueryset(models.QuerySet):
-    def get_expired(self) -> models.QuerySet:
+class TokenQueryset(models.QuerySet["Token"]):
+    def get_expired(self) -> "TokenQueryset":
         """Get all tokens which have expired.
 
         Returns:
@@ -39,7 +40,7 @@ class TokenQueryset(models.QuerySet):
             timezone.now() - timedelta(seconds=app_settings.ESI_TOKEN_VALID_DURATION)
         return self.filter(created__lte=max_age)
 
-    def bulk_refresh(self) -> models.QuerySet:
+    def bulk_refresh(self) -> "TokenQueryset":
         """Refresh all refreshable tokens in the queryset and delete any expired token
         that fails to refresh or can not be refreshed.
 
@@ -65,7 +66,7 @@ class TokenQueryset(models.QuerySet):
         self.filter(refresh_token__isnull=True).get_expired().delete()
         return self.exclude(pk__in=incomplete)
 
-    def require_valid(self) -> models.QuerySet:
+    def require_valid(self) -> "TokenQueryset":
         """Ensure all tokens are still valid and attempt to refresh any which are expired
 
         Deletes those which fail to refresh or cannot be refreshed.
@@ -80,7 +81,7 @@ class TokenQueryset(models.QuerySet):
         qs = self.filter(pk__in=fresh_pks | refreshed_pks)
         return qs
 
-    def require_scopes(self, scope_string: Union[str, list]) -> models.QuerySet:
+    def require_scopes(self, scope_string: str | list) -> "TokenQueryset":
         """Filter tokens which have at least a subset of given scopes.
 
         Args:
@@ -103,7 +104,7 @@ class TokenQueryset(models.QuerySet):
             tokens = tokens.filter(scopes__pk=pk)
         return tokens
 
-    def require_scopes_exact(self, scope_string: Union[str, list]) -> models.QuerySet:
+    def require_scopes_exact(self, scope_string: str | list) -> "TokenQueryset":
         """Filter tokens which exactly have the given scopes.
 
         Args:
@@ -121,7 +122,7 @@ class TokenQueryset(models.QuerySet):
         pks = [v['pk'] for v in scopes_qs]
         return self.filter(pk__in=pks)
 
-    def equivalent_to(self, token) -> models.QuerySet:
+    def equivalent_to(self, token) -> "TokenQueryset":
         """Fetch all tokens which match the character and scopes of given reference token
 
         Args:
@@ -134,8 +135,8 @@ class TokenQueryset(models.QuerySet):
             .exclude(pk=token.pk)
 
 
-class TokenManager(models.Manager):
-    def get_queryset(self):
+class TokenManager(models.Manager["Token"]):
+    def get_queryset(self) -> TokenQueryset:
         """
         Replace base queryset model with custom TokenQueryset
         :rtype: :class:`esi.managers.TokenQueryset`
@@ -143,7 +144,7 @@ class TokenManager(models.Manager):
         return TokenQueryset(self.model, using=self._db)
 
     @staticmethod
-    def _decode_jwt(jwt_token: dict, jwk_set: dict, issuer: Any):
+    def _decode_jwt(jwt_token: str, jwk_set: dict, issuer: Any) -> dict[str, Any]:
         """
         Helper function to decide the JWT access token supplied by EVE SSO
         """
@@ -162,7 +163,7 @@ class TokenManager(models.Manager):
         return token_data
 
     @staticmethod
-    def validate_access_token(token: str):
+    def validate_access_token(token: str) -> dict[str, Any] | None:
         """
         Validate a JWT token retrieved from the EVE SSO.
         :param token: A JWT token originating from the EVE SSO v2
@@ -200,7 +201,7 @@ class TokenManager(models.Manager):
             logger.warning("The JWT signature was invalid: %s", e)
             return None
 
-    def create_from_code(self, code, user=None):
+    def create_from_code(self, code, user=None) -> "Token":
         """
         Perform OAuth code exchange to retrieve a token.
         :param code: OAuth grant code.
@@ -282,7 +283,7 @@ class TokenManager(models.Manager):
         logger.debug("Successfully created %r for user %s", model, user)
         return model
 
-    def create_from_request(self, request):
+    def create_from_request(self, request) -> "Token":
         """
         Generate a token from the OAuth callback request. Must contain 'code' in GET.
         :param request: OAuth callback request.

esi/managers.pyi

@@ -0,0 +1,82 @@
+from typing import Any
+from django.db.models import QuerySet, Manager
+from .models import Token
+
+
+class TokenQueryset(QuerySet[Token]):
+    def get_expired(self) -> "TokenQueryset":
+        ...
+
+    def bulk_refresh(self) -> "TokenQueryset":
+        ...
+
+    def require_scopes(self, scope_string: str | list) -> "TokenQueryset":
+        ...
+
+    def require_scopes_exact(self, scope_string: str | list) -> "TokenQueryset":
+        ...
+
+    def require_valid(self) -> "TokenQueryset":
+        ...
+
+    def equivalent_to(self, token: Token) -> "TokenQueryset":
+        ...
+
+    def filter(self, *args: Any, **kwargs: Any) -> "TokenQueryset":
+        ...
+
+    def exclude(self, *args: Any, **kwargs: Any) -> "TokenQueryset":
+        ...
+
+    def order_by(self, *field_names: str) -> "TokenQueryset":
+        ...
+
+    def annotate(self, *args: Any, **kwargs: Any) -> "TokenQueryset":
+        ...
+
+    def select_related(self, *fields: str) -> "TokenQueryset":
+        ...
+
+    def prefetch_related(self, *lookups: str) -> "TokenQueryset":
+        ...
+
+    def distinct(self, *field_names: str) -> "TokenQueryset":
+        ...
+
+    def none(self) -> "TokenQueryset":
+        ...
+
+    def all(self) -> "TokenQueryset":
+        ...
+
+
+class TokenManager(Manager[Token]):
+    def get_queryset(self) -> "TokenQueryset":
+        ...
+
+    def filter(self, *args: Any, **kwargs: Any) -> "TokenQueryset":
+        ...
+
+    def exclude(self, *args: Any, **kwargs: Any) -> "TokenQueryset":
+        ...
+
+    def order_by(self, *field_names: str) -> "TokenQueryset":
+        ...
+
+    def annotate(self, *args: Any, **kwargs: Any) -> "TokenQueryset":
+        ...
+
+    def select_related(self, *fields: str) -> "TokenQueryset":
+        ...
+
+    def prefetch_related(self, *lookups: str) -> "TokenQueryset":
+        ...
+
+    def distinct(self, *field_names: str) -> "TokenQueryset":
+        ...
+
+    def none(self) -> "TokenQueryset":
+        ...
+
+    def all(self) -> "TokenQueryset":
+        ...

esi/models.py

@@ -1,36 +1,29 @@
 import datetime
-import re
 import logging
+import re
 from typing import ClassVar
 
 from bravado.client import SwaggerClient
-from requests.auth import HTTPBasicAuth
-from requests_oauthlib import OAuth2Session
 from oauthlib.oauth2.rfc6749.errors import (
-    InvalidClientError,
-    InvalidClientIdError,
-    InvalidGrantError,
-    InvalidTokenError,
-    MissingTokenError,
+    InvalidClientError, InvalidClientIdError, InvalidGrantError,
+    InvalidTokenError, MissingTokenError,
 )
+from requests.auth import HTTPBasicAuth
+from requests_oauthlib import OAuth2Session
 
-from django.core.exceptions import ImproperlyConfigured
 from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
 from django.db import models
 from django.utils import timezone
 from django.utils.translation import gettext_lazy as _
 
 from . import app_settings
 from .clients import esi_client_factory
-from .managers import TokenManager
 from .errors import (
-    IncompleteResponseError,
-    NotRefreshableTokenError,
-    TokenExpiredError,
-    TokenInvalidError,
-    TokenError
+    IncompleteResponseError, NotRefreshableTokenError, TokenError,
+    TokenExpiredError, TokenInvalidError,
 )
-
+from .managers import TokenManager
 
 logger = logging.getLogger(__name__)