django-esi 8.0.0a4__py3-none-any.whl → 8.0.0b2__py3-none-any.whl

esi/openapi_clients.py

@@ -1,8 +1,9 @@
 import logging
 import pathlib
 import warnings
-from datetime import datetime, date
+import datetime as dt
 from hashlib import md5
+from timeit import default_timer
 from typing import Any
 
 from aiopenapi3 import OpenAPI, FileSystemLoader
@@ -10,6 +11,7 @@ from aiopenapi3._types import ResponseDataType, ResponseHeadersType
 from aiopenapi3.errors import HTTPServerError as base_HTTPServerError
 from aiopenapi3.errors import HTTPClientError as base_HTTPClientError
 from aiopenapi3.request import OperationIndex, RequestBase
+from esi.rate_limiting import ESIRateLimitBucket, ESIRateLimits, interval_to_seconds
 from httpx import (
     AsyncClient, Client, HTTPStatusError, RequestError, Response, Timeout,
 )
@@ -23,16 +25,21 @@ from django.utils.text import slugify
 
 from esi import app_settings
 from esi.exceptions import HTTPClientError, HTTPServerError, HTTPNotModified
-from esi.aiopenapi3.plugins import Add304ContentType, DjangoESIInit, PatchCompatibilityDatePlugin, Trim204ContentType
+from esi.aiopenapi3.plugins import (
+    Add304ContentType, DjangoESIInit, PatchCompatibilityDatePlugin,
+    Trim204ContentType, MinifySpec
+)
 from esi.exceptions import ESIErrorLimitException
 from esi.models import Token
+from esi.signals import esi_request_statistics
 from esi.stubs import ESIClientStub
 
 from . import __title__, __url__, __version__
+from .helpers import pascal_case_string
 
 logger = logging.getLogger(__name__)
 
-ETAG_EXPIRY = 60*60*24*7  # 7 days
+ETAG_EXPIRY = 60 * 60 * 24 * 7  # 7 days
 
 
 def _time_to_expiry(expires_header: str) -> int:
@@ -43,8 +50,10 @@ def _time_to_expiry(expires_header: str) -> int:
         int: The cache TTL in seconds
     """
     try:
-        expires_dt = datetime.strptime(str(expires_header), '%a, %d %b %Y %H:%M:%S %Z')
-        return max(int((expires_dt - datetime.utcnow()).total_seconds()), 0)
+        expires_dt = dt.datetime.strptime(str(expires_header), '%a, %d %b %Y %H:%M:%S %Z')
+        if expires_dt.tzinfo is None:
+            expires_dt = expires_dt.replace(tzinfo=dt.timezone.utc)
+        return max(int((expires_dt - dt.datetime.now(dt.timezone.utc)).total_seconds()), 0)
     except ValueError:
         return 0
 
@@ -74,7 +83,7 @@ def http_retry_sync() -> Retrying:
     )
 
 
-async def http_retry_async() -> AsyncRetrying:
+async def http_retry_async() -> AsyncRetrying:  # pragma: no cover
     return AsyncRetrying(
         retry=retry_if_exception(_httpx_exceptions),
         wait=wait_combine(
@@ -85,13 +94,19 @@ async def http_retry_async() -> AsyncRetrying:
     )
 
 
-def _load_plugins(app_name):
+def _load_plugins(app_name, tags: list[str] = [], operations: list[str] = []):
     """Load the plugins to make ESI work with this lib.
 
     Args:
         app_name (str): app name to use for internal etags
     """
-    return [PatchCompatibilityDatePlugin(), Trim204ContentType(), Add304ContentType(), DjangoESIInit(app_name)]
+    return [
+        PatchCompatibilityDatePlugin(),
+        Trim204ContentType(),
+        Add304ContentType(),
+        DjangoESIInit(app_name),
+        MinifySpec(tags, operations)
+    ]
 
 
 def _load_aiopenapi_client_sync(
@@ -100,7 +115,9 @@ def _load_aiopenapi_client_sync(
         app_name: str,
         user_agent: str,
         tenant: str,
-        spec_file: str | None = None) -> OpenAPI:
+        spec_file: str | None = None,
+        tags: list[str] = [],
+        operations: list[str] = []) -> OpenAPI:
     """Create an OpenAPI3 Client from Spec
 
     Args:
@@ -140,14 +157,14 @@ def _load_aiopenapi_client_sync(
             session_factory=session_factory,
             loader=FileSystemLoader(pathlib.Path(spec_file)),
             use_operation_tags=True,
-            plugins=_load_plugins(app_name)
+            plugins=_load_plugins(app_name, tags, operations)
         )
     else:
         return OpenAPI.load_sync(
             url=spec_url,
             session_factory=session_factory,
             use_operation_tags=True,
-            plugins=_load_plugins(app_name)
+            plugins=_load_plugins(app_name, tags, operations)
         )
 
 
@@ -157,7 +174,7 @@ async def _load_aiopenapi_client_async(
         app_name: str,
         user_agent: str,
         tenant: str,
-        spec_file: str | None = None) -> OpenAPI:
+        spec_file: str | None = None) -> OpenAPI:  # pragma: no cover
     """Create an OpenAPI3 Client from Spec Async
 
     Args:
@@ -218,10 +235,15 @@ def _build_user_agent(ua_appname: str, ua_version: str, ua_url: str | None = Non
     Returns:
         str: User-Agent string
     """
+
+    # Enforce PascalCase for `ua_appname` and strip whitespace
+    sanitized_ua_appname = pascal_case_string(ua_appname)
+    sanitized_appname = pascal_case_string(__title__)
+
     return (
-        f"{ua_appname}/{ua_version} "
+        f"{sanitized_ua_appname}/{ua_version} "
         f"({app_settings.ESI_USER_CONTACT_EMAIL}{f'; +{ua_url})' if ua_url else ')'} "
-        f"{__title__}/{__version__} (+{__url__})"
+        f"{sanitized_appname}/{__version__} (+{__url__})"
     )
 
 
@@ -234,6 +256,7 @@ def esi_client_factory_sync(
         ua_appname: str, ua_version: str, ua_url: str | None = None,
         spec_file: str | None = None,
         tenant: str = "tranquility",
+        tags: list[str] = [], operations: list[str] = [],
         **kwargs) -> OpenAPI:
     """Generate a new OpenAPI ESI client.
     Args:
@@ -248,7 +271,16 @@ def esi_client_factory_sync(
     """
     user_agent = _build_user_agent(ua_appname, ua_version, ua_url)
     spec_url = _get_spec_url()
-    return _load_aiopenapi_client_sync(spec_url, compatibility_date, ua_appname, user_agent, tenant, spec_file)
+    return _load_aiopenapi_client_sync(
+        spec_url,
+        compatibility_date,
+        ua_appname,
+        user_agent,
+        tenant,
+        spec_file,
+        tags,
+        operations
+    )
 
 
 async def esi_client_factory_async(
@@ -256,7 +288,7 @@ async def esi_client_factory_async(
         ua_appname: str, ua_version: str, ua_url: str | None = None,
         spec_file: str | None = None,
         tenant: str = "tranquility",
-        **kwargs) -> OpenAPI:
+        **kwargs) -> OpenAPI:  # pragma: no cover
     """Generate a new OpenAPI ESI client.
     Args:
         compatibility_date (str): "YYYY-MM-DD" The latest version of ESI your client is tested with
@@ -278,9 +310,13 @@ class BaseEsiOperation():
         self.method, self.url, self.operation, self.extra = operation
         self.api = api
         self.token: Token | None = None
+        self.bucket: ESIRateLimitBucket | None = None
+
         self._args = []
         self._kwargs = {}
 
+        self._set_bucket()
+
     def __call__(self, *args, **kwargs) -> "BaseEsiOperation":
         self._args = args
         self._kwargs = kwargs
@@ -343,7 +379,7 @@ class BaseEsiOperation():
             str: Key
         """
         # ignore the token this will break the cache
-        return f"{slugify(self.api.app_name)}_etag_{self._cache_key()}"
+        return f"{slugify(self.api.app_name)}_etag_{self._cache_key()}"  # type: ignore app_name is added by a plugin
 
     def _cache_key(self) -> str:
         """Generate a key name used to cache responses based on method, url, args, kwargs
@@ -366,7 +402,7 @@ class BaseEsiOperation():
         """
         _body = self._kwargs.pop("body", None)
         if _body and not getattr(self.operation, "requestBody", False):
-            raise ValueError("Request Body provided on endpoint with no request body paramater.")
+            raise ValueError("Request Body provided on endpoint with no request body parameter.")
         return _body
 
     def _extract_token_param(self) -> Token | None:
@@ -393,7 +429,7 @@ class BaseEsiOperation():
         """
         return any(p.name == "before" or p.name == "after" for p in self.operation.parameters)
 
-    def _get_cache(self, cache_key: str, etag: str) -> tuple[ResponseHeadersType | None, Any, Response | None]:
+    def _get_cache(self, cache_key: str, etag: str | None) -> tuple[ResponseHeadersType | None, Any, Response | None]:
         """Retrieve cached response and validate expiry
         Args:
             cache_key (str): The cache key to retrieve
@@ -421,8 +457,13 @@ class BaseEsiOperation():
 
             # check if etag is same before building models from cache
             if etag:
-                if cached_response.headers.get('Expires') == etag:
+                if cached_response.headers.get('ETag') == etag:
                     # refresh/store the etag's TTL
+                    self._send_signal(
+                        status_code=0,  # this is a cached response less a 304
+                        headers=cached_response.headers,
+                        latency=0
+                    )
                     self._store_etag(cached_response.headers)
                     raise HTTPNotModified(
                         status_code=304,
@@ -493,8 +534,40 @@ class BaseEsiOperation():
         )
         return req._process_request(cached_response)
 
+    def _set_bucket(self):
+        """Setup the rate bucket"""
+        _rate_limit = getattr(self.operation, "extensions", {}).get("rate-limit", False)
+        if _rate_limit:
+            _key = _rate_limit["group"]
+            if self.token:
+                _key = f"{_key}:{self.token.character_id}"
+            self.bucket = ESIRateLimitBucket(
+                _key,
+                _rate_limit["max-tokens"],
+                interval_to_seconds(_rate_limit["window-size"])
+            )
+
+    def _send_signal(self, status_code: int, headers: dict = {}, latency: float = 0) -> None:
+        """
+            Dispatch the esi request statistics signal
+        """
+        esi_request_statistics.send(
+            sender=self.__class__,
+            operation=self.operation.operationId,
+            status_code=status_code,
+            headers=headers,
+            latency=latency,
+            bucket=self.bucket.slug if self.bucket else ""
+        )
+
 
 class EsiOperation(BaseEsiOperation):
+    def __skip__process__headers__(
+        self, result, headers: dict[str, str], expected_response
+    ):
+        """Return all headers always"""
+        return headers
+
     def _make_request(
             self,
             parameters: dict[str, Any],
@@ -507,10 +580,20 @@ class EsiOperation(BaseEsiOperation):
             # or handle this by pushing their celery tasks back
             raise ESIErrorLimitException(reset=reset)
 
+        if self.bucket:
+            """Check Rate Limit"""
+            ESIRateLimits.check_bucket(self.bucket)
+
         retry = http_retry_sync()
 
         def __func():
             req = self.api.createRequest(f"{self.operation.tags[0]}.{self.operation.operationId}")
+
+            # We want all headers from ESI
+            # don't check/parse them against the spec and return them all
+            # TODO Investigate if this is a bug with aiopenapi or a spec compliance issue
+            req._process__headers = self.__skip__process__headers__
+
             if self.token:
                 self.api.authenticate(OAuth2=True)  # make the lib happy
                 if isinstance(self.token, str):
@@ -529,7 +612,22 @@ class EsiOperation(BaseEsiOperation):
                     req.req.headers["Authorization"] = f"Bearer {self.token.valid_access_token()}"
             if etag:
                 req.req.headers["If-None-Match"] = etag
-            return req.request(data=self.body, parameters=self._unnormalize_parameters(parameters))
+            _response = req.request(data=self.body, parameters=self._unnormalize_parameters(parameters))
+
+            if self.bucket and "x-ratelimit-remaining" in _response.result.headers:
+                logger.debug(
+                    "ESI Rate-Limit: "
+                    f"'{_response.result.headers.get('x-ratelimit-group')}' - "
+                    f"Used {_response.result.headers.get('x-ratelimit-used')} - "
+                    f"{_response.result.headers.get('x-ratelimit-remaining')} / "
+                    f"({_response.result.headers.get('x-ratelimit-limit')})"
+                )
+                ESIRateLimits.set_bucket(
+                    self.bucket,
+                    _response.result.headers.get("x-ratelimit-remaining")
+                )
+
+            return _response
         return retry(__func)
 
     def result(
@@ -542,11 +640,16 @@ class EsiOperation(BaseEsiOperation):
         """Executes the request and returns the response from ESI for the current operation.
         Raises:
             ESIErrorLimitException: _description_
+            ESIBucketLimitException: _description_
         Returns:
             _type_: _description_
         """
-
+        _t = default_timer()
         self.token = self._extract_token_param()
+
+        if self.token:
+            self._set_bucket()
+
         self.body = self._extract_body_param()
         parameters = self._kwargs | extra
         cache_key = self._cache_key()
@@ -576,13 +679,13 @@ class EsiOperation(BaseEsiOperation):
             logger.debug(f"Cache Miss {self.url}")
             try:
                 headers, data, response = self._make_request(parameters, etag)
-                if response.status_code == 420:
-                    reset = response.headers.get("X-RateLimit-Reset", None)
-                    cache.set("esi_error_limit_reset", reset, timeout=reset)
-                    raise ESIErrorLimitException(reset=reset)
-
             # Shim our exceptions into Django-ESI
             except base_HTTPServerError as e:
+                self._send_signal(
+                    status_code=e.status_code,
+                    headers=e.headers,
+                    latency=default_timer() - _t
+                )
                 raise HTTPServerError(
                     status_code=e.status_code,
                     headers=e.headers,
@@ -590,23 +693,52 @@ class EsiOperation(BaseEsiOperation):
                 )
 
             except base_HTTPClientError as e:
+                self._send_signal(
+                    status_code=e.status_code,
+                    headers=e.headers,
+                    latency=default_timer() - _t
+                )
+
+                if e.status_code == 420:
+                    reset = e.headers.get("X-RateLimit-Reset", None)
+                    if reset:
+                        reset = int(reset)
+                        cache.set("esi_error_limit_reset", reset, timeout=reset)
+                    raise ESIErrorLimitException(reset=reset)
+
                 raise HTTPClientError(
                     status_code=e.status_code,
                     headers=e.headers,
                     data=e.data
                 )
 
+            self._send_signal(
+                status_code=response.status_code,
+                headers=response.headers,
+                latency=default_timer() - _t
+            )
+
+            # store the ETAG in cache
+            self._store_etag(response.headers)
+
             # Throw a 304 exception for catching.
             if response.status_code == 304:
                 # refresh/store the etag's TTL
-                self._store_etag(response.headers)
                 raise HTTPNotModified(
                     status_code=304,
                     headers=response.headers
                 )
 
-        # last step store cache we dont want to catch the 304 `None` resonses
-        self._store_cache(cache_key, response)
+            # last step store cache after 304 logic, we dont want to catch the 304 `None` responses
+            self._store_cache(cache_key, response)
+
+        else:
+            # send signal for cached data too
+            self._send_signal(
+                status_code=0,
+                headers=response.headers,
+                latency=default_timer() - _t
+            )
 
         return (data, response) if return_response else data
 
@@ -724,7 +856,7 @@ class EsiOperation(BaseEsiOperation):
             return []
 
 
-class EsiOperationAsync(BaseEsiOperation):
+class EsiOperationAsync(BaseEsiOperation):  # pragma: no cover
     async def _make_request(
             self,
             parameters: dict[str, Any],
@@ -747,7 +879,7 @@ class EsiOperationAsync(BaseEsiOperation):
                     req.req.headers["Authorization"] = f"Bearer {self.token.valid_access_token()}"
                 if etag:
                     req.req.headers["If-None-Match"] = etag
-                return await req.request(parameters=self._unnormalize_parameters(parameters))
+                return req.request(parameters=self._unnormalize_parameters(parameters))
         # Should never be reached because AsyncRetrying always yields at least once
         raise RuntimeError("Retry loop exited without performing a request")
 
@@ -766,7 +898,7 @@ class EsiOperationAsync(BaseEsiOperation):
         if not etag and app_settings.ESI_CACHE_RESPONSE:
             etag = cache.get(etag_key)
 
-        headers, data, response = self._get_cache(cache_key)
+        headers, data, response = self._get_cache(cache_key, etag)
 
         if response and use_cache:
             expiry = _time_to_expiry(str(headers.get('Expires')))
@@ -868,7 +1000,7 @@ class EsiOperationAsync(BaseEsiOperation):
                 my_languages.append(lang)
 
         return {
-            language: self.results(accept_language=language, **kwargs)
+            language: self.results(accept_language=language, **extra)
             for language in my_languages
         }
 
@@ -906,7 +1038,7 @@ class ESITag:
         return EsiOperation(self._operations[name], self.api)
 
 
-class ESITagAsync():
+class ESITagAsync():  # pragma: no cover
     """
     Async API Tag Wrapper, providing access to Operations within a tag
     Assets, Characters, etc.
@@ -966,9 +1098,9 @@ class ESIClient(ESIClientStub):
             # old lib
             from django.core.cache import caches
             default_cache = caches['default']
-            _client = default_cache.get_master_client()
+            _client = default_cache.get_master_client()  # type: ignore
 
-        keys = _client.keys(f":?:{slugify(self.api.app_name)}_etag_*")
+        keys = _client.keys(f":?:{slugify(self.api.app_name)}_etag_*")  # type: ignore app_name is added by a plugin
         if keys:
             deleted = _client.delete(*keys)
 
@@ -977,7 +1109,7 @@ class ESIClient(ESIClientStub):
         return deleted
 
 
-class ESIClientAsync(ESIClientStub):
+class ESIClientAsync(ESIClientStub):  # pragma: no cover
     """
     Async Base ESI Client, provides access to Tags Assets, Characters, etc.
     or Raw aiopenapi3 via sad smiley ._.
@@ -1007,6 +1139,8 @@ class ESIClientAsync(ESIClientStub):
 
 class ESIClientProvider:
     """Class for providing a single ESI client instance for a whole app
+    * Note that one of either `tags` or `operations` must be provided to reduce memory footprint of the client
+    * When `DEBUG=False`, not supplying either will raise an AttributeError.
     Args:
         compatibility_date (str | date): The compatibility date for the ESI client.
         ua_appname (str): Name of the App for generating a User-Agent,
@@ -1014,6 +1148,8 @@ class ESIClientProvider:
         ua_url (str, Optional): URL To the Source Code or Documentation for generating a User-Agent,
         spec_file (str, Optional): Absolute path to a OpenApi 3.1 spec file to load.
         tenant (str, Optional): The ESI tenant to use (default: "tranquility").
+        operations (list[str], Optional*): List of operations to filter the spec down.
+        tags (list[str], Optional*): List of tags to filter the spec down.
     Functions:
         client(): ESIClient
         client_async(): ESIClientAsync
@@ -1024,24 +1160,28 @@ class ESIClientProvider:
 
     def __init__(
         self,
-        compatibility_date: str | date,
+        compatibility_date: str | dt.date,
         ua_appname: str,
         ua_version: str,
         ua_url: str | None = None,
         spec_file: None | str = None,
         tenant: str = "tranquility",
+        operations: list[str] = [],
+        tags: list[str] = [],
         **kwargs
     ) -> None:
-        if type(compatibility_date) is date:
-            self._compatibility_date = self._date_to_string(compatibility_date)
+        if type(compatibility_date) is dt.date:
+            self._compatibility_date: str = self._date_to_string(compatibility_date)
         else:
-            self._compatibility_date = compatibility_date
+            self._compatibility_date: str = str(compatibility_date)
         self._ua_appname = ua_appname
         self._ua_version = ua_version
         self._ua_url = ua_url
         self._spec_file = spec_file
         self._tenant = tenant
         self._kwargs = kwargs
+        self._operations = operations
+        self._tags = tags
 
     @property
     def client(self) -> ESIClient:
@@ -1053,12 +1193,14 @@ class ESIClientProvider:
                 ua_url=self._ua_url,
                 spec_file=self._spec_file,
                 tenant=self._tenant,
+                operations=self._operations,
+                tags=self._tags,
                 **self._kwargs)
             self._client = ESIClient(api)
         return self._client
 
     @property
-    async def client_async(self) -> ESIClientAsync:
+    async def client_async(self) -> ESIClientAsync:  # pragma: no cover
         if self._client_async is None:
             api = await esi_client_factory_async(
                 compatibility_date=self._compatibility_date,
@@ -1067,12 +1209,14 @@ class ESIClientProvider:
                 ua_url=self._ua_url,
                 spec_file=self._spec_file,
                 tenant=self._tenant,
+                operations=self._operations,
+                tags=self._tags,
                 **self._kwargs)
             self._client_async = ESIClientAsync(api)
         return self._client_async
 
     @classmethod
-    def _date_to_string(cls, compatibility_date: date) -> str:
+    def _date_to_string(cls, compatibility_date: dt.date) -> str:
         """Turns a date object in a compatibility_date string"""
         return f"{compatibility_date.year}-{compatibility_date.month:02}-{compatibility_date.day:02}"
 

esi/rate_limiting.py

@@ -1,7 +1,16 @@
+import logging
 import time
 from django.core.cache import cache
 from esi.exceptions import ESIBucketLimitException
 
+logger = logging.getLogger(__name__)
+
+seconds_per_unit = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+
+
+def interval_to_seconds(s):
+    return int(s[:-1]) * seconds_per_unit[s[-1]]
+
 
 class ESIRateLimitBucket:
     MARKET_DATA_HISTORY = ("market_data_history", 300, 60)
@@ -16,6 +25,9 @@ class ESIRateLimitBucket:
     def choices(cls):
         return [(bucket.slug, bucket.slug.replace("_", " ").title()) for bucket in cls]
 
+    def __str__(self):
+        return f"Rate Limit: {self.slug} - {self.limit} in {self.window}Seconds"
+
 
 class ESIRateLimiter:
     def __init__(self) -> None:
@@ -35,44 +47,61 @@ class ESIRateLimiter:
 
     def get_bucket(self, bucket: ESIRateLimitBucket) -> int:
         # get the value from the bucket
-        return cache.get(
-            self._slug_to_key(bucket.slug),
-            1  # When not found return 1
+        return int(
+            cache.get(
+                self._slug_to_key(bucket.slug),
+                1  # When not found return 1
+            )
         )
 
-    def get_timeout(self, bucket: ESIRateLimitBucket, raise_on_limit: bool = True) -> int:
-        curent_bucket = self.get_bucket(bucket)
-        if curent_bucket <= 0:
+    def get_timeout(self, bucket: ESIRateLimitBucket) -> int:
+        current_bucket = self.get_bucket(bucket)
+        if current_bucket <= 0:
             timeout = cache.ttl(self._slug_to_key(bucket.slug)) + 1
             msg = (
                 f"Rate limit for bucket '{bucket.slug}' exceeded: "
-                f"{curent_bucket}/{bucket.limit} in last {bucket.window}s. "
+                f"{current_bucket}/{bucket.limit} in last {bucket.window}s. "
                 f"Wait {timeout}s."
             )
-            if raise_on_limit:
-                raise ESIBucketLimitException(msg)  # Throw error
-            else:
-                return timeout  # return the time left till reset
+            logger.warning(msg)
+            return timeout  # return the time left till reset
         else:
             return 0  # we are good.
 
-    def decr_bucket(self, bucket: ESIRateLimitBucket) -> int:
-        # decrease the bucket value by 1 from the bucket
+    def decr_bucket(self, bucket: ESIRateLimitBucket, delta: int = 1) -> int:
+        # decrease the bucket value by <delta> from the bucket
         return cache.decr(
-            self._slug_to_key(bucket.slug)
+            self._slug_to_key(bucket.slug),
+            delta
+        )
+
+    def set_bucket(self, bucket: ESIRateLimitBucket, new_limit: int = 1) -> int:
+        # decrease the bucket value by <delta> from the bucket
+        return cache.set(
+            self._slug_to_key(bucket.slug),
+            int(new_limit),
+            timeout=bucket.window
         )
 
-    def check_bucket(self, bucket: ESIRateLimitBucket, raise_on_limit: bool = True):
-        ESIRateLimits.init_bucket(bucket)
+    def check_bucket(self, bucket: ESIRateLimitBucket):
+        self.init_bucket(bucket)
         # get the value
-        bucket_val = ESIRateLimits.get_bucket(bucket)
+        bucket_val = self.get_bucket(bucket)
         if bucket_val <= 0:
-            timeout = ESIRateLimits.get_timeout(bucket, raise_on_limit=raise_on_limit)
+            timeout = self.get_timeout(bucket)
             if timeout > 0:
-                time.sleep(timeout)
+                raise ESIBucketLimitException(bucket, timeout)
             return
-        # reduce our bucket by 1
-        ESIRateLimits.decr_bucket(bucket)
+
+    def check_decr_bucket(self, bucket: ESIRateLimitBucket, raise_on_limit: bool = True):
+        try:
+            self.check_bucket(bucket)
+            self.decr_bucket(bucket)
+        except ESIBucketLimitException as ex:
+            if raise_on_limit:
+                raise ex
+            else:
+                time.sleep(ex.reset)
 
 
 ESIRateLimits = ESIRateLimiter()

esi/signals.py

@@ -0,0 +1,21 @@
+from django.dispatch import Signal
+
+"""
+Basic signal sent after an ESI requests
+    from django.dispatch import receiver
+    from esi.signals import esi_request_statistics
+
+    @receiver(esi_request_statistics)
+    def esi_callback(sender, operation, status_code, headers, latency, bucket, **kwargs):
+        # do stuff
+        pass
+"""
+esi_request_statistics = Signal(
+    # providing_args=[
+    #     "operation",
+    #     "status_code",
+    #     "headers",
+    #     "latency",
+    #     "bucket"
+    # ]
+)