django-esi 8.1.0__py3-none-any.whl

esi/decorators.py

@@ -0,0 +1,271 @@
+import logging
+import time
+from functools import wraps
+from typing import Any
+from collections.abc import Callable
+
+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) -> 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)
+        request.session.create()
+
+    # clean up callback redirect, pass token if new requested
+    try:
+        model = CallbackRedirect.objects.get(session_key=request.session.session_key)
+        token = Token.objects.get(pk=model.token.pk)
+        model.delete()
+        logger.debug(
+            "Retrieved new token from callback for %s session %s",
+            request.user,
+            request.session.session_key[:5])
+        return token
+
+    except (CallbackRedirect.DoesNotExist, Token.DoesNotExist, AttributeError):
+        logger.debug(
+            "No callback for %s session %s",
+            request.user,
+            request.session.session_key[:5],
+            exc_info=True
+        )
+        return None
+
+
+def tokens_required(scopes='', new=False):
+    """
+    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.
+    """
+
+    def decorator(view_func):
+        @wraps(view_func)
+        def _wrapped_view(request, *args, **kwargs):
+
+            # if we're coming back from SSO with a new token, return it
+            token = _check_callback(request)
+            if token:
+                tokens = Token.objects.filter(pk=token.pk)
+                logger.debug("Returning new token.")
+                return view_func(request, tokens, *args, **kwargs)
+
+            if not new:
+                # ensure user logged in to check existing tokens
+                if not request.user.is_authenticated:
+                    logger.debug(
+                        "Session %s is not logged in. Redirecting to login.",
+                        request.session.session_key[:5]
+                    )
+                    from django.contrib.auth.views import redirect_to_login
+                    return redirect_to_login(request.get_full_path())
+
+                # collect tokens in db, check if still valid, return if any
+                tokens = (
+                    Token.objects
+                    .filter(user__pk=request.user.pk)
+                    .require_scopes(scopes)
+                    .require_valid()
+                )
+                if tokens.exists():
+                    logger.debug(
+                        "Retrieved %s tokens for %s session %s",
+                        tokens.count(),
+                        request.user,
+                        request.session.session_key[:5]
+                    )
+                    return view_func(request, tokens, *args, **kwargs)
+
+            # trigger creation of new token via sso
+            logger.debug(
+                "No tokens identified for %s session %s. Redirecting to SSO.",
+                request.user,
+                request.session.session_key[:5]
+            )
+            from esi.views import sso_redirect
+            return sso_redirect(request, scopes=scopes)
+
+        return _wrapped_view
+
+    return decorator
+
+
+def token_required(scopes='', new=False):
+    """
+    Decorator for views which supplies a single,
+    user-selected token for the view to process.
+    Same parameters as tokens_required.
+    """
+
+    def decorator(view_func):
+        @wraps(view_func)
+        def _wrapped_view(request, *args, **kwargs):
+
+            # if we're coming back from SSO with a new token, return it
+            token = _check_callback(request)
+            if token:
+                logger.debug(
+                    "Got new token from %s session %s. Returning to view.",
+                    request.user,
+                    request.session.session_key[:5]
+                )
+                return view_func(request, token, *args, **kwargs)
+
+            # if we're selecting a token, return it
+            if request.method == 'POST':
+                if request.POST.get("_add", False):
+                    logger.debug(
+                        "%s has selected to add new token. Redirecting to SSO.",
+                        request.user
+                    )
+                    # user has selected to add a new token
+                    from esi.views import sso_redirect
+                    return sso_redirect(request, scopes=scopes)
+
+                token_pk = request.POST.get('_token', None)
+                if token_pk:
+                    logger.debug(
+                        "%s has selected token %s", request.user, token_pk
+                    )
+                    try:
+                        token = Token.objects.get(pk=token_pk)
+                        # ensure token belongs to this user and has required scopes
+                        if (
+                            (
+                                (token.user and token.user == request.user)
+                                or not token.user
+                            )
+                            and Token.objects
+                            .filter(pk=token_pk)
+                            .require_scopes(scopes)
+                            .require_valid()
+                            .exists()
+                        ):
+                            logger.debug(
+                                "Selected token fulfills requirements of view. "
+                                "Returning."
+                            )
+                            return view_func(request, token, *args, **kwargs)
+
+                    except Token.DoesNotExist:
+                        logger.debug("Token %s not found.", token_pk)
+
+            if not new:
+                # present the user with token choices
+                tokens = (
+                    Token.objects
+                    .filter(user__pk=request.user.pk)
+                    .require_scopes(scopes)
+                    .require_valid()
+                )
+                if tokens.exists():
+                    logger.debug(
+                        "Returning list of available tokens for %s.", request.user
+                    )
+                    from esi.views import select_token
+                    return select_token(request, scopes=scopes, new=new)
+                else:
+                    logger.debug(
+                        "No tokens found for %s session %s with scopes %s",
+                        request.user,
+                        request.session.session_key[:5],
+                        scopes
+                    )
+
+            # prompt the user to add a new token
+            logger.debug(
+                "Redirecting %s session %s to SSO.",
+                request.user,
+                request.session.session_key[:5]
+            )
+            from esi.views import sso_redirect
+            return sso_redirect(request, scopes=scopes)
+
+        return _wrapped_view
+
+    return decorator
+
+
+def single_use_token(scopes='', new=False):
+    """
+    Decorator for views which supplies a single use token granted via sso login
+    regardless of login state.
+    Same parameters as tokens_required.
+    """
+
+    def decorator(view_func):
+        @wraps(view_func)
+        def _wrapped_view(request, *args, **kwargs):
+
+            # if we're coming back from SSO for a new token, return it
+            token = _check_callback(request)
+            if token:
+                logger.debug(
+                    "Got new token from session %s. Returning to view.",
+                    request.session.session_key[:5]
+                )
+                return view_func(request, token, *args, **kwargs)
+
+            # prompt the user to login for a new token
+            logger.debug(
+                "Redirecting session %s to SSO.", request.session.session_key[:5]
+            )
+            from esi.views import sso_redirect
+            return sso_redirect(request, scopes=scopes)
+
+        return _wrapped_view
+
+    return decorator
+
+
+def wait_for_esi_errorlimit_reset(cache_key="esi_error_limit_reset", poll_interval=1) -> Callable[..., Callable[..., Any]]:
+    """
+    Decorator to apply a polling sleep while the ESI Server/Client is in an Error Limit state
+    The preferred non-blocking method is to retry your tasks after the limit reset time has passed
+
+    Args:
+        cache_key (str, optional):  NOT USUALLY CHANGED. Defaults to "esi_error_limit_reset".
+        poll_interval (int, optional): Interval in seconds to poll redis. Defaults to 1.
+    """
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            reset = cache.get(cache_key)
+            if reset is not None:
+                logger.error(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):
+    """
+    Decorator for custom manual rate limits on some endpoints to apply a polling sleep while the bucket is exhausted.
+    MARKET_DATA_HISTORY
+    CHARACTER_CORPORATION_HISTORY
+    The preferred non-blocking method is to retry your tasks after the limit reset time has passed
+
+
+    Args:
+        bucket (ESIRateLimitBucket): The Bucket to rate limit against
+        raise_on_limit (bool, optional): Whether to raise an Exception when the limit is reached. Defaults to True.
+    """
+    # TODO Investigate esi cache hits.
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            ESIRateLimits.check_decr_bucket(bucket, raise_on_limit)
+            return func(*args, **kwargs)
+        return wrapper
+    return decorator

esi/errors.py

@@ -0,0 +1,22 @@
+class DjangoEsiException(Exception):
+    pass
+
+
+class TokenError(DjangoEsiException):
+    pass
+
+
+class TokenInvalidError(TokenError):
+    pass
+
+
+class TokenExpiredError(TokenError):
+    pass
+
+
+class NotRefreshableTokenError(TokenError):
+    pass
+
+
+class IncompleteResponseError(DjangoEsiException):
+    pass

esi/exceptions.py

@@ -0,0 +1,51 @@
+import dataclasses
+
+from aiopenapi3.errors import HTTPServerError as base_HTTPServerError
+from aiopenapi3.errors import HTTPClientError as base_HTTPClientError
+from aiopenapi3.errors import HTTPError
+
+
+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, reset: float = 0, *args, **kwargs) -> None:
+        self.bucket = bucket
+        self.reset = reset
+        msg = kwargs.get("message") or f"ESI bucket limit reached for {bucket}."
+        super().__init__(msg, *args)
+
+
+@dataclasses.dataclass(repr=False)
+class HTTPNotModified(HTTPError):
+    """The HTTP Status is 304"""
+
+    status_code: int
+    headers: dict[str, str]
+
+    def __str__(self):
+        return f"""<{self.__class__.__name__} {self.status_code} {self.headers}>"""
+
+
+@dataclasses.dataclass(repr=False)
+class HTTPClientError(base_HTTPClientError):
+    """HTTP Response Code 4xx"""
+    pass
+
+
+@dataclasses.dataclass(repr=False)
+class HTTPServerError(base_HTTPServerError):
+    """HTTP Response Code 5xx"""
+    pass

esi/helpers.py

@@ -0,0 +1,63 @@
+from esi.models import Token
+from string import capwords
+
+
+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
+
+
+def pascal_case_string(string: str) -> str:
+    """
+    Convert a string to PascalCase by capitalizing the first letter of each word and removing spaces,
+    but only if the string contains spaces or hyphens.
+
+    This function checks if the input string contains spaces or hyphens. If so, it replaces hyphens with spaces,
+    capitalizes the first letter of each word, removes the spaces, and returns the resulting PascalCase string.
+    If the input string does not contain spaces or hyphens, it is returned unchanged.
+
+    Behaviour:
+    Any string containing spaces or hyphens will be converted to PascalCase.
+    Strings without spaces or hyphens will be returned unchanged.
+    This gives you the opportunity to use already formatted strings as needed.
+
+    Examples:
+    - "app name" -> "AppName"
+    - "app-name" -> "AppName"
+    - "appname" -> "appname"
+    - "AppName" -> "AppName"
+    - "appName" -> "appName"
+    - "app_name" -> "app_name"
+
+    :param string: The input string to be converted to PascalCase.
+    :type string: str
+    :return: The PascalCase formatted string, or the original string if no spaces or hyphens are present.
+    :rtype: str
+    """
+
+    # Check if the string contains spaces or hyphens
+    if any(c in string for c in (" ", "-")):
+        # Replace hyphens with spaces, capitalize each word, and remove spaces
+        return capwords(string.replace("-", " ")).replace(" ", "")
+
+    # Return the original string if no spaces or hyphens are present
+    return string

esi/locale/cs_CZ/LC_MESSAGES/django.po

@@ -0,0 +1,53 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: Django ESI 8.1.0\n"
+"Report-Msgid-Bugs-To: https://gitlab.com/allianceauth/django-esi/-/issues\n"
+"POT-Creation-Date: 2025-11-19 16:22+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"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+#: esi/models.py:66
+msgid "Character"
+msgstr ""
+
+#: esi/models.py:67
+msgid "Corporation"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:13
+msgid "ESI Token Selection"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:44
+msgid "Select Character"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:48
+msgid "Scopes Requested"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:61
+#: esi/templates/esi/select_token.html:98
+msgid "New Character"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:71
+#: esi/templates/esi/select_token.html:107
+msgid "Add Token"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:88
+#: esi/templates/esi/select_token.html:89
+msgid "Select"
+msgstr ""

esi/locale/de/LC_MESSAGES/django.po

@@ -0,0 +1,58 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+# Translators:
+# Peter Pfeufer, 2023
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: Django ESI 8.1.0\n"
+"Report-Msgid-Bugs-To: https://gitlab.com/allianceauth/django-esi/-/issues\n"
+"POT-Creation-Date: 2025-11-19 16:22+1000\n"
+"PO-Revision-Date: 2023-10-25 11:04+0000\n"
+"Last-Translator: Peter Pfeufer, 2023\n"
+"Language-Team: German (https://app.transifex.com/alliance-auth/teams/107430/"
+"de/)\n"
+"Language: de\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+
+#: esi/models.py:66
+msgid "Character"
+msgstr "Charakter"
+
+#: esi/models.py:67
+msgid "Corporation"
+msgstr "Corporation"
+
+#: esi/templates/esi/select_token.html:13
+msgid "ESI Token Selection"
+msgstr "ESI Token Auswahl"
+
+#: esi/templates/esi/select_token.html:44
+msgid "Select Character"
+msgstr "Charakter Auswahl"
+
+#: esi/templates/esi/select_token.html:48
+msgid "Scopes Requested"
+msgstr "Bereiche angefordert"
+
+#: esi/templates/esi/select_token.html:61
+#: esi/templates/esi/select_token.html:98
+msgid "New Character"
+msgstr "Neuer Charakter"
+
+#: esi/templates/esi/select_token.html:71
+#: esi/templates/esi/select_token.html:107
+msgid "Add Token"
+msgstr "Token hinzufügen"
+
+#: esi/templates/esi/select_token.html:88
+#: esi/templates/esi/select_token.html:89
+msgid "Select"
+msgstr "Auswählen"

esi/locale/en/LC_MESSAGES/django.po

@@ -0,0 +1,54 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: Django ESI 8.1.0\n"
+"Report-Msgid-Bugs-To: https://gitlab.com/allianceauth/django-esi/-/issues\n"
+"POT-Creation-Date: 2025-11-19 16:22+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"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+
+#: esi/models.py:66
+msgid "Character"
+msgstr ""
+
+#: esi/models.py:67
+msgid "Corporation"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:13
+msgid "ESI Token Selection"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:44
+msgid "Select Character"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:48
+msgid "Scopes Requested"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:61
+#: esi/templates/esi/select_token.html:98
+msgid "New Character"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:71
+#: esi/templates/esi/select_token.html:107
+msgid "Add Token"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:88
+#: esi/templates/esi/select_token.html:89
+msgid "Select"
+msgstr ""

esi/locale/es/LC_MESSAGES/django.po

@@ -0,0 +1,59 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+# Translators:
+# trenus, 2023
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: Django ESI 8.1.0\n"
+"Report-Msgid-Bugs-To: https://gitlab.com/allianceauth/django-esi/-/issues\n"
+"POT-Creation-Date: 2025-11-19 16:22+1000\n"
+"PO-Revision-Date: 2023-10-25 11:04+0000\n"
+"Last-Translator: trenus, 2023\n"
+"Language-Team: Spanish (https://app.transifex.com/alliance-auth/teams/107430/"
+"es/)\n"
+"Language: es\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=3; plural=n == 1 ? 0 : n != 0 && n % 1000000 == 0 ? "
+"1 : 2;\n"
+
+#: esi/models.py:66
+msgid "Character"
+msgstr ""
+
+#: esi/models.py:67
+msgid "Corporation"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:13
+msgid "ESI Token Selection"
+msgstr "Selección de tokens ESI"
+
+#: esi/templates/esi/select_token.html:44
+msgid "Select Character"
+msgstr "Seleccionar personaje"
+
+#: esi/templates/esi/select_token.html:48
+msgid "Scopes Requested"
+msgstr "Ámbitos solicitados"
+
+#: esi/templates/esi/select_token.html:61
+#: esi/templates/esi/select_token.html:98
+msgid "New Character"
+msgstr "Nuevo personaje"
+
+#: esi/templates/esi/select_token.html:71
+#: esi/templates/esi/select_token.html:107
+msgid "Add Token"
+msgstr ""
+
+#: esi/templates/esi/select_token.html:88
+#: esi/templates/esi/select_token.html:89
+msgid "Select"
+msgstr "Seleccionar"