core-https 2.0.2__tar.gz → 3.0.0__tar.gz

{core_https-2.0.2 → core_https-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-https
-Version: 2.0.2
+Version: 3.0.0
 Summary: This project/library contains common elements related to HTTP & API services...
 Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
 Maintainer: Alejandro Cora González
@@ -21,17 +21,22 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: aiohttp<4.0.0,>=3.12.0; python_version >= "3.9"
-Requires-Dist: core-mixins>=2.2.2
-Requires-Dist: requests<3.0.0,>=2.32.3; python_version >= "3.9"
-Requires-Dist: urllib3<3.0.0,>=2.2.3; python_version >= "3.9"
+Requires-Dist: aiohttp<4.0.0,>=3.12.0
+Requires-Dist: core-mixins>=3.0.1
+Requires-Dist: requests<3.0.0,>=2.32.3
+Requires-Dist: urllib3<3.0.0,>=2.2.3
 Provides-Extra: dev
-Requires-Dist: core-dev-tools>=1.0.1; extra == "dev"
-Requires-Dist: core-tests>=2.0.2; extra == "dev"
+Requires-Dist: aiolimiter<2.0.0,>=1.2.1; extra == "dev"
+Requires-Dist: core-dev-tools>=1.2.1; extra == "dev"
+Requires-Dist: core-tests>=2.0.5; extra == "dev"
 Requires-Dist: types-requests>=2.32.0.20250602; extra == "dev"
+Provides-Extra: extras
+Requires-Dist: aiolimiter<2.0.0,>=1.2.1; extra == "extras"
 Dynamic: license-file
 
 core-https
@@ -134,7 +139,13 @@ Check tests and coverage
 
 .. code-block:: shell
 
+    # Unit tests (mocked, no network):
     python manager.py run-tests
+
+    # Functional tests (real HTTP requests — requires network):
+    python manager.py run-tests --test-type functional --pattern "*.py"
+
+    # Coverage:
     python manager.py run-coverage
 
 

{core_https-2.0.2 → core_https-3.0.0}/README.rst

@@ -98,7 +98,13 @@ Check tests and coverage
 
 .. code-block:: shell
 
+    # Unit tests (mocked, no network):
     python manager.py run-tests
+
+    # Functional tests (real HTTP requests — requires network):
+    python manager.py run-tests --test-type functional --pattern "*.py"
+
+    # Coverage:
     python manager.py run-coverage
 
 

{core_https-2.0.2 → core_https-3.0.0}/core_https/__init__.py

@@ -1,12 +1,14 @@
 # -*- coding: utf-8 -*-
 
+"""Public API for the core_https package: HTTP status codes and status info enum."""
+
 from core_mixins import StrEnum
 
 try:
     from http import HTTPStatus as _HTTPStatus
 
 except ImportError:
-    from .utils import HTTPStatus as _HTTPStatus  # type: ignore
+    from .utils import HTTPStatus as _HTTPStatus
 
 
 __all__ = [

{core_https-2.0.2 → core_https-3.0.0}/core_https/exceptions.py

@@ -49,7 +49,14 @@ See Also:
     - HTTP status codes: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
 """
 
-from typing import Dict
+from typing import TypedDict
+
+
+class ErrorInfo(TypedDict):
+    """Structured error payload returned by :meth:`InternalServerError.get_error_info`."""
+
+    type: str
+    details: str
 
 
 class InternalServerError(Exception):
@@ -75,7 +82,7 @@ class InternalServerError(Exception):
         self.status_code = status_code
         self.details = details
 
-    def get_error_info(self) -> Dict[str, str]:
+    def get_error_info(self) -> ErrorInfo:
         """
         Get structured error information for logging or serialization.
         :returns: Dictionary containing error type and details.

{core_https-2.0.2 → core_https-3.0.0}/core_https/requesters/aiohttp_.py

@@ -1,8 +1,11 @@
 # -*- coding: utf-8 -*-
 
+"""Asynchronous HTTP requester implementation backed by aiohttp."""
+
 from __future__ import annotations
 
 import asyncio
+from contextlib import suppress
 from typing import Any
 from typing import Dict
 from typing import Optional
@@ -16,6 +19,7 @@ from aiohttp import (
 )
 from core_mixins import Self
 
+from core_https.exceptions import RetryableException
 from .base import HTTPMethod
 from .base import IRequester
 
@@ -106,7 +110,7 @@ class AioHttpRequester(IRequester):
         super().__init__(**kwargs)
 
         self._session = session
-        self._session_lock = asyncio.Lock()
+        self._session_lock: Optional[asyncio.Lock] = None
         self._owns_session = session is None
         self._timeout = ClientTimeout(total=self.timeout)
         self.retries = retries
@@ -144,6 +148,9 @@ class AioHttpRequester(IRequester):
         """
 
         if self._session is None:
+            if self._session_lock is None:
+                self._session_lock = asyncio.Lock()
+
             async with self._session_lock:
                 if self._session is None:  # Double-check after acquiring lock...
                     self._session = ClientSession(
@@ -265,10 +272,17 @@ class AioHttpRequester(IRequester):
                 return response
 
             except ClientResponseError as error:
-                if attempts > retries:
+                if error.status not in self.RETRYABLE_ERRORS or attempts > retries:
                     self.raise_custom_exception(error.status, error.message)
 
-                await asyncio.sleep(backoff_factor * attempts)
+                with suppress(RetryableException):
+                    self.raise_custom_exception(
+                        error.status,
+                        error.message,
+                        within_retry=True,
+                    )
+
+            await asyncio.sleep(backoff_factor * (2 ** (attempts - 1)))
 
     async def close(self) -> None:
         """
@@ -279,8 +293,9 @@ class AioHttpRequester(IRequester):
         in the constructor, it will not be closed as the caller is responsible
         for managing its lifecycle.
 
-        The session reference is always cleared after calling this method,
-        regardless of whether it was closed or not.
+        The session reference is cleared only when the session was created
+        internally. External sessions retain their reference so the requester
+        remains usable after close() without silently creating a new session.
 
         Note:
             This method is automatically called when using the async context
@@ -290,4 +305,5 @@ class AioHttpRequester(IRequester):
 
         if self._session and self._owns_session:
             await self._session.close()
-        self._session = None
+            self._session = None
+            self._session_lock = None

core_https-3.0.0/core_https/requesters/aiohttp_rate_limit.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+
+"""Rate-limited aiohttp requester using aiolimiter.AsyncLimiter."""
+
+from aiohttp import ClientResponse
+from aiolimiter import AsyncLimiter
+
+from core_https.requesters.aiohttp_ import AioHttpRequester
+
+
+class AioHttpRateLimitRequester(AioHttpRequester):
+    """
+    An HTTP requester that enforces a simple *rate limit* using
+    :class:`aiolimiter.AsyncLimiter`. This class restricts how many
+    requests may be *started* within a given time window. It does **not**
+    limit concurrency; multiple requests may still run in parallel
+    if they acquire permission within the same window.
+    """
+
+    def __init__(
+        self,
+        max_rate: int,
+        time_period: float,
+        **kwargs
+    ) -> None:
+        """
+        Initialize the rate-limited requester.
+
+        :param max_rate: Maximum number of requests allowed within the time window.
+        :param time_period: Duration (in seconds) of the rate-limiting window.
+        :param kwargs: Additional keyword arguments passed to :class:`AioHttpRequester`.
+        """
+
+        if max_rate <= 0:
+            raise ValueError("`max_rate` must be positive!")
+
+        if time_period <= 0:
+            raise ValueError("`time_period` must be positive!")
+
+        super().__init__(**kwargs)
+
+        self.max_rate = max_rate
+        self.time_period = time_period
+
+        self._limiter = AsyncLimiter(
+            max_rate=self.max_rate,
+            time_period=self.time_period,
+        )
+
+    @classmethod
+    def engine(cls) -> str:
+        return "aiohttp_rate_limit"
+
+    async def request(self, *args, **kwargs) -> ClientResponse:
+        """
+        Execute an HTTP request subject to the configured rate limit. The
+        coroutine will wait (non-blocking) until a rate slot becomes available,
+        and then delegate the call to the base :class:`AioHttpRequester`.
+
+        :return: The HTTP response object.
+        :raises Exception: Any exception raised by the underlying HTTP client.
+        """
+
+        async with self._limiter:
+            return await super().request(*args, **kwargs)

core_https-3.0.0/core_https/requesters/aiohttp_throttle.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+
+"""Concurrency-throttled aiohttp requester using asyncio.Semaphore."""
+
+import asyncio
+from typing import Optional
+
+from aiohttp import ClientResponse
+
+from core_https.requesters.aiohttp_ import AioHttpRequester
+
+
+class AioHttpThrottleRequester(AioHttpRequester):
+    """
+    An `AioHttpRequester` implementation that limits the number of
+    concurrent in-flight HTTP requests using an `asyncio.Semaphore`. This
+    throttler enforces *max_concurrency* at the coroutine level within a
+    single event loop. Each call to :meth:`request` must acquire a semaphore
+    permit before dispatching the actual HTTP request.
+
+    **Notes:**
+
+    - The throttling mechanism limits only concurrent *coroutine execution*. It
+      does not enforce rate limiting (requests per second).
+    - If you override :meth:`request` in a subclass, be aware that
+      `await super().request(...)` calls the parent implementation (so the parent
+      semaphore *will* be used for the actual HTTP call). However, any code you
+      run **before** or **after** that `super()` call executes outside the parent's
+      semaphore (and therefore is not throttled).
+    """
+
+    def __init__(self, max_concurrency: int, **kwargs) -> None:
+        """
+        :param max_concurrency: Maximum number of concurrent requests allowed.
+        :param kwargs: Passed through to :class:`AioHttpRequester`.
+        """
+
+        super().__init__(**kwargs)
+        self.max_concurrency = max_concurrency
+        self._semaphore: Optional[asyncio.Semaphore] = None
+
+    @classmethod
+    def engine(cls) -> str:
+        return "aiohttp_throttle"
+
+    async def request(self, *args, **kwargs) -> ClientResponse:
+        """
+        Execute an HTTP request with concurrency throttling. It acquires
+        a semaphore permit before delegating the actual request to the
+        underlying :class:`AioHttpRequester` implementation.
+
+        :returns: The aiohttp response object.
+        :raises: Any exception raised by the underlying session.
+        """
+
+        if self._semaphore is None:
+            self._semaphore = asyncio.Semaphore(self.max_concurrency)
+
+        async with self._semaphore:
+            return await super().request(*args, **kwargs)
+
+    async def close(self) -> None:
+        await super().close()
+        self._semaphore = None

{core_https-2.0.2 → core_https-3.0.0}/core_https/requesters/base.py

@@ -1,9 +1,11 @@
 # -*- coding: utf-8 -*-
 
+"""Abstract base class and shared utilities for all HTTP requester implementations."""
+
 import re
 from abc import ABC
 from abc import abstractmethod
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Mapping, Optional
 
 from core_mixins.interfaces.factory import IFactory
 
@@ -19,7 +21,7 @@ from core_https.exceptions import (
 try:
     from http import HTTPMethod as _HTTPMethod
 except ImportError:
-    from core_https.utils import HTTPMethod as _HTTPMethod  # type: ignore
+    from core_https.utils import HTTPMethod as _HTTPMethod
 
 
 # Type alias that works with both standard library
@@ -77,6 +79,8 @@ class IRequester(IFactory, ABC):
         - :class:`core_mixins.interfaces.factory.IFactory`: Base factory interface
     """
 
+    RETRYABLE_ERRORS = (429, 502, 503, 504)
+
     def __init__(
         self,
         encoding: str = "utf-8",
@@ -255,7 +259,7 @@ class IRequester(IFactory, ABC):
 
     def _get_response_encoding(
         self,
-        headers: Dict[str, str],
+        headers: Mapping[str, str],
         default: str = "utf-8",
     ) -> str:
         """
@@ -312,8 +316,8 @@ class IRequester(IFactory, ABC):
 
         return self.encoding or default
 
-    @staticmethod
     def raise_custom_exception(
+        self,
         status_code: int,
         details: str,
         within_retry: bool = False,
@@ -379,7 +383,7 @@ class IRequester(IFactory, ABC):
             # next condition.
             error_cls = RateLimitException
 
-        elif status_code in (429, 502, 503, 504) and within_retry:
+        elif status_code in self.RETRYABLE_ERRORS and within_retry:
             error_cls = RetryableException
 
         elif 400 <= status_code < 500:

{core_https-2.0.2 → core_https-3.0.0}/core_https/requesters/requests_.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+"""Synchronous HTTP requester implementation backed by the requests library."""
+
 from typing import Dict, Optional
 
 import requests
@@ -44,7 +46,7 @@ class RequestsRequester(IRequester):
         :param retries: Retry strategy to apply. Pass zero (0) to avoid retries.
         """
 
-        super().__init__(**kwargs)
+        super().__init__(backoff_factor=backoff_factor, **kwargs)
         self.retries = retries
 
         backoff_factor = (
@@ -57,7 +59,7 @@ class RequestsRequester(IRequester):
 
         if self.retries is None:
             self.retries = urllib3.Retry(
-                status_forcelist=[429, 502, 503, 504],
+                status_forcelist=IRequester.RETRYABLE_ERRORS,
                 backoff_factor=backoff_factor,
                 total=3,
             )
@@ -70,8 +72,9 @@ class RequestsRequester(IRequester):
 
         if session is None:
             session = requests.Session()
-            session.mount("https://", adapter)
-            session.mount("http://", adapter)
+
+        session.mount("https://", adapter)
+        session.mount("http://", adapter)
 
         self._session = session
 
@@ -79,7 +82,7 @@ class RequestsRequester(IRequester):
     def engine(cls) -> str:
         return "requests"
 
-    def request(  # type: ignore[override]
+    def request(
         self,
         url: str,
         method: HTTPMethod = HTTPMethod.GET,
@@ -99,15 +102,13 @@ class RequestsRequester(IRequester):
         """
 
         session_ = session or self._session
-        if params is None:
-            params = {}
 
         response = session_.request(
             method=str(method.value),
             url=url,
             headers=headers,
             params=params,
-            timeout=timeout,
+            timeout=timeout if timeout is not None else self.timeout,
             **kwargs,
         )
 

{core_https-2.0.2 → core_https-3.0.0}/core_https/requesters/urllib3_.py

@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+"""Low-level synchronous HTTP requester implementation backed by urllib3."""
+
 import json
 from contextlib import suppress
 from typing import Dict, Optional
@@ -40,7 +42,7 @@ class Urllib3Requester(IRequester):
 
         super().__init__(**kwargs)
 
-        if not pool_manager:
+        if pool_manager is None:
             pool_manager = PoolManager()
 
         self._http: PoolManager = pool_manager
@@ -78,10 +80,10 @@ class Urllib3Requester(IRequester):
             else 0.5
         )
 
-        retries_ = retries or self.retries
+        retries_ = retries if retries is not None else self.retries
         if retries_ is None:
             retries_ = Retry(
-                status_forcelist=[429, 502, 503, 504],
+                status_forcelist=self.RETRYABLE_ERRORS,
                 backoff_factor=backoff_factor,
                 total=3,
             )
@@ -91,7 +93,7 @@ class Urllib3Requester(IRequester):
             url=url,
             headers=headers,
             fields=fields,
-            timeout=timeout or self.timeout,
+            timeout=timeout if timeout is not None else self.timeout,
             retries=retries_,
             **kwargs,
         )
@@ -99,7 +101,7 @@ class Urllib3Requester(IRequester):
         status_code = response.status
 
         if status_code >= 400 and self.raise_for_status:
-            info = response.data.decode(self._get_response_encoding(response.headers))  # type: ignore[arg-type]
+            info = response.data.decode(self._get_response_encoding(response.headers))
             headers_ = {k.lower(): v for k, v in response.headers.items()}
 
             if "application/json" in headers_.get("content-type", ""):
@@ -110,6 +112,9 @@ class Urllib3Requester(IRequester):
                     with suppress(json.JSONDecodeError):
                         info = json.loads(info)
 
-            self.raise_custom_exception(status_code, info)
+            self.raise_custom_exception(
+                status_code,
+                info if isinstance(info, str) else json.dumps(info),
+            )
 
         return response

{core_https-2.0.2 → core_https-3.0.0}/core_https/tests/decorators.py

@@ -57,11 +57,14 @@ def patch_aiohttp(
     Args:
         url: The URL that the mock should respond to. Defaults to "https://example.com".
         method: HTTP method for the mock request. Defaults to "GET".
-        json_response: JSON data to return in the response body. Mutually exclusive with text_response and content.
+        json_response: JSON data to return in the response body.
+            Mutually exclusive with text_response and content.
         status: HTTP status code for the mock response. Defaults to 200.
         headers: Dictionary of response headers.
-        text_response: Plain text data to return. Mutually exclusive with json_response and content.
-        content: Raw bytes to return as response content. Mutually exclusive with json_response and text_response.
+        text_response: Plain text data to return.
+            Mutually exclusive with json_response and content.
+        content: Raw bytes to return as response content.
+            Mutually exclusive with json_response and text_response.
         content_type: MIME type of the response. Defaults to "application/json".
         charset: Character encoding for the response. Defaults to "utf-8".
         raise_for_status_exception: Exception to raise when response.raise_for_status() is called.
@@ -142,10 +145,13 @@ def patch_requests(
         url: The URL that the mock should respond to. Defaults to "https://example.com".
         encoding: Character encoding for the response. Defaults to "utf-8".
         headers: Dictionary of response headers.
-        json_response: JSON data to return in the response body. Mutually exclusive with text_response and content.
-        text_response: Plain text data to return. Mutually exclusive with json_response and content.
+        json_response: JSON data to return in the response body.
+            Mutually exclusive with text_response and content.
+        text_response: Plain text data to return.
+            Mutually exclusive with json_response and content.
         status_code: HTTP status code for the mock response. Defaults to 200.
-        content: Raw bytes to return as response content. Mutually exclusive with json_response and text_response.
+        content: Raw bytes to return as response content.
+            Mutually exclusive with json_response and text_response.
         raise_for_status_exception: Exception to raise when response.raise_for_status() is called.
 
     Returns:

{core_https-2.0.2 → core_https-3.0.0}/core_https/tests/requests_.py

@@ -123,7 +123,8 @@ class BaseRequestsTestCases(BaseHttpTestCases):
             url: The URL that the mock response represents. Defaults to "https://example.com".
             encoding: Character encoding for text content. Defaults to "utf-8".
             headers: Dictionary of response headers. Auto-generated if not provided.
-            json_response: JSON data to return from the .json() method. Mutually exclusive with text_response.
+            json_response: JSON data to return from the .json() method.
+                Mutually exclusive with text_response.
             text_response: Plain text content. Auto-generated from json_response if not provided.
             status_code: HTTP status code for the response. Defaults to 200.
             content: Raw bytes content. Auto-generated from text_response if not provided.

{core_https-2.0.2 → core_https-3.0.0}/core_https/tests/urllib3_.py

@@ -269,10 +269,9 @@ class BaseUrllib3TestCases(BaseHttpTestCases):
             """Mock read method."""
             if preload_content:
                 return data.decode() if decode_content else data
-            else:
-                # Simulate streaming read...
-                res = data[:amt] if amt else data
-                return res.decode() if decode_content else res
+            # Simulate streaming read...
+            res = data[:amt] if amt else data
+            return res.decode() if decode_content else res
 
         def mock_read1(amt=None):
             """Mock read1 method (reads up to amt bytes)."""
@@ -289,7 +288,7 @@ class BaseUrllib3TestCases(BaseHttpTestCases):
             line = lines[0] + b"\n" if len(lines) > 1 else lines[0]
             return line[:size] if size > 0 else line
 
-        def mock_readlines(hint=-1):
+        def mock_readlines(_hint=-1):
             return data.split(b"\n")
 
         # Assign read methods...
@@ -300,7 +299,7 @@ class BaseUrllib3TestCases(BaseHttpTestCases):
         mock.readlines = mock_readlines
 
         # Stream methods
-        def mock_stream(amt=2**16, decode_content=None):
+        def mock_stream(amt=2**16, _decode_content=None):
             if not data:
                 return
 
@@ -337,7 +336,7 @@ class BaseUrllib3TestCases(BaseHttpTestCases):
         mock.__exit__ = Mock(side_effect=mock_close())
 
         # Iterator support
-        def mock_iter(self):
+        def mock_iter(_self):
             """Support for iteration over response."""
             yield from data.split(b"\n")
 

{core_https-2.0.2 → core_https-3.0.0}/core_https/utils.py

@@ -50,8 +50,6 @@ See Also:
 from enum import Enum
 from typing import Dict
 
-from core_mixins import Self
-
 
 class HTTPStatus(Enum):
     """
@@ -163,7 +161,7 @@ class HTTPStatus(Enum):
 
     def __repr__(self):
         """Return string representation for debugging."""
-        return f"<{self.__class__.__name__}.{self._value_}>"
+        return f"<{self.__class__.__name__}.{self.name}: {self._value_}>"
 
     def __str__(self):
         """Return string representation of the status code."""
@@ -204,7 +202,7 @@ class HTTPStatus(Enum):
         return self.is_client_error() or self.is_server_error()
 
     @classmethod
-    def by_code(cls, code: int) -> Self:
+    def by_code(cls, code: int) -> "HTTPStatus":
         """
         Find HTTP status by numeric code.
 
@@ -222,11 +220,10 @@ class HTTPStatus(Enum):
             print(status.description)  # "Not Found"
         """
 
-        for status in cls:
-            if status.value == code:
-                return status
-
-        raise ValueError(f"No HTTPStatus found for code: {code}")
+        try:
+            return _HTTP_STATUS_BY_CODE[code]
+        except KeyError as exc:
+            raise ValueError(f"No HTTPStatus found for code: {code}") from exc
 
     @classmethod
     def as_dict(cls) -> Dict[int, str]:
@@ -247,6 +244,9 @@ class HTTPStatus(Enum):
         }
 
 
+_HTTP_STATUS_BY_CODE: Dict[int, HTTPStatus] = {m.value: m for m in HTTPStatus}
+
+
 class HTTPMethod(Enum):
     """
     HTTP method enumeration with backward compatibility.
@@ -332,7 +332,7 @@ class HTTPMethod(Enum):
         return self in (HTTPMethod.GET, HTTPMethod.HEAD, HTTPMethod.POST)
 
     @classmethod
-    def by_name(cls, name: str) -> Self:
+    def by_name(cls, name: str) -> "HTTPMethod":
         """
         Find HTTP method by name (case-insensitive).
 
@@ -352,8 +352,10 @@ class HTTPMethod(Enum):
 
         name = name.upper()
 
-        for http_method in cls:
-            if http_method.value == name:
-                return http_method
+        try:
+            return _HTTP_METHOD_BY_NAME[name]
+        except KeyError as exc:
+            raise ValueError(f"No HTTPMethod found for name: {name}") from exc
+
 
-        raise ValueError(f"No HTTPMethod found for name: {name}")
+_HTTP_METHOD_BY_NAME: Dict[str, HTTPMethod] = {m.value: m for m in HTTPMethod}

{core_https-2.0.2 → core_https-3.0.0}/core_https.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-https
-Version: 2.0.2
+Version: 3.0.0
 Summary: This project/library contains common elements related to HTTP & API services...
 Author-email: Alejandro Cora González <alek.cora.glez@gmail.com>
 Maintainer: Alejandro Cora González
@@ -21,17 +21,22 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE
-Requires-Dist: aiohttp<4.0.0,>=3.12.0; python_version >= "3.9"
-Requires-Dist: core-mixins>=2.2.2
-Requires-Dist: requests<3.0.0,>=2.32.3; python_version >= "3.9"
-Requires-Dist: urllib3<3.0.0,>=2.2.3; python_version >= "3.9"
+Requires-Dist: aiohttp<4.0.0,>=3.12.0
+Requires-Dist: core-mixins>=3.0.1
+Requires-Dist: requests<3.0.0,>=2.32.3
+Requires-Dist: urllib3<3.0.0,>=2.2.3
 Provides-Extra: dev
-Requires-Dist: core-dev-tools>=1.0.1; extra == "dev"
-Requires-Dist: core-tests>=2.0.2; extra == "dev"
+Requires-Dist: aiolimiter<2.0.0,>=1.2.1; extra == "dev"
+Requires-Dist: core-dev-tools>=1.2.1; extra == "dev"
+Requires-Dist: core-tests>=2.0.5; extra == "dev"
 Requires-Dist: types-requests>=2.32.0.20250602; extra == "dev"
+Provides-Extra: extras
+Requires-Dist: aiolimiter<2.0.0,>=1.2.1; extra == "extras"
 Dynamic: license-file
 
 core-https
@@ -134,7 +139,13 @@ Check tests and coverage
 
 .. code-block:: shell
 
+    # Unit tests (mocked, no network):
     python manager.py run-tests
+
+    # Functional tests (real HTTP requests — requires network):
+    python manager.py run-tests --test-type functional --pattern "*.py"
+
+    # Coverage:
     python manager.py run-coverage
 
 

{core_https-2.0.2 → core_https-3.0.0}/core_https.egg-info/SOURCES.txt

@@ -13,6 +13,8 @@ core_https.egg-info/requires.txt
 core_https.egg-info/top_level.txt
 core_https/requesters/__init__.py
 core_https/requesters/aiohttp_.py
+core_https/requesters/aiohttp_rate_limit.py
+core_https/requesters/aiohttp_throttle.py
 core_https/requesters/base.py
 core_https/requesters/requests_.py
 core_https/requesters/urllib3_.py

core_https-3.0.0/core_https.egg-info/requires.txt

@@ -0,0 +1,13 @@
+aiohttp<4.0.0,>=3.12.0
+core-mixins>=3.0.1
+requests<3.0.0,>=2.32.3
+urllib3<3.0.0,>=2.2.3
+
+[dev]
+aiolimiter<2.0.0,>=1.2.1
+core-dev-tools>=1.2.1
+core-tests>=2.0.5
+types-requests>=2.32.0.20250602
+
+[extras]
+aiolimiter<2.0.0,>=1.2.1

core_https-3.0.0/pyproject.toml

@@ -0,0 +1,133 @@
+# Other project metadata fields as specified in:
+# https://packaging.python.org/en/latest/specifications/declaring-project-metadata/
+# https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html
+
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "core-https"
+description = "This project/library contains common elements related to HTTP & API services..."
+version = "3.0.0"
+
+authors = [
+    {name = "Alejandro Cora González", email = "alek.cora.glez@gmail.com"}
+]
+
+maintainers = [
+    {name = "Alejandro Cora González"}
+]
+
+requires-python = ">=3.9"
+license = "MIT"
+readme = "README.rst"
+
+classifiers = [
+    # Classifiers -> https://pypi.org/classifiers/
+    "Intended Audience :: Developers",
+    "Development Status :: 5 - Production/Stable",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Utilities",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: PyPy",
+]
+
+dependencies = [
+    "aiohttp>=3.12.0,<4.0.0",
+    "core-mixins>=3.0.1",
+    "requests>=2.32.3,<3.0.0",
+    "urllib3>=2.2.3,<3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "aiolimiter>=1.2.1,<2.0.0",
+    "core-dev-tools>=1.2.1",
+    "core-tests>=2.0.5",
+    "types-requests>=2.32.0.20250602",
+]
+
+extras = [
+    "aiolimiter>=1.2.1,<2.0.0",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/bytecode-solutions/core/core-https"
+Repository = "https://gitlab.com/bytecode-solutions/core/core-https"
+Documentation = "https://core-https.readthedocs.io/en/latest/"
+Issues = "https://gitlab.com/bytecode-solutions/core/core-https/-/issues"
+Changelog = "https://gitlab.com/bytecode-solutions/core/core-https/-/blob/master/CHANGELOG.md"
+
+[tool.setuptools.package-data]
+"core_https" = ["py.typed"]
+
+[tool.pyright]
+pythonVersion = "3.11"
+# core_mixins ships no stubs; pyright cannot prove StrEnum is a class and
+# raises reportGeneralTypeIssues on `class StatusInfo(StrEnum)`.
+# __init__.py is a thin re-export/enum file — ignoring it is safe.
+ignore = ["core_https/__init__.py"]
+
+[tool.mypy]
+python_version = "3.11"
+
+# The try/except ImportError compatibility shims assign either the stdlib
+# symbol (e.g. http.HTTPStatus) or the backport from core_https.utils to the
+# same name.  mypy sees the two types as incompatible; this is a known
+# false-positive for the try/except compat pattern.
+[[tool.mypy.overrides]]
+module = ["core_https", "core_https.requesters.base"]
+disable_error_code = ["assignment"]
+
+# urllib3.HTTPHeaderDict is a MutableMapping[str, str], not a plain dict.
+# _get_response_encoding only needs Mapping semantics (.get / .items); the
+# annotation is intentionally wide in the implementation, but mypy flags the
+# call site because it cannot see through the urllib3 stub.
+[[tool.mypy.overrides]]
+module = "core_https.requesters.urllib3_"
+disable_error_code = ["arg-type"]
+
+[tool.pylint.messages_control]
+disable = [
+    # HTTP API methods intentionally have many parameters (url, method,
+    # headers, timeout, retries, …).  Splitting them would harm usability.
+    "too-many-arguments",        # R0913
+    "too-many-positional-arguments",  # R0917
+
+    # get_urllib3_mock builds a comprehensive mock object; it genuinely
+    # needs many local variables and statements.
+    "too-many-locals",           # R0914
+    "too-many-statements",       # R0915
+
+    # Test helpers intentionally access private urllib3/aiohttp internals
+    # (e.g. _request_url, _connection) to set up realistic mocks.
+    "protected-access",          # W0212
+
+    # Async requesters (aiohttp_*.py) override abstract sync `request()`
+    # with `async def request()`.  The override is intentional.
+    "invalid-overridden-method", # W0236
+
+    # The backoff_factor resolution pattern is intentionally repeated
+    # across Urllib3Requester and RequestsRequester.
+    "duplicate-code",            # R0801
+]
+
+[tool.ty.src]
+# core_mixins ships no stubs; ty cannot prove StrEnum is a class and raises
+# unsupported-base on `class StatusInfo(StrEnum)`.  __init__.py is a thin
+# re-export/enum file — ignoring it is safe.
+exclude = ["core_https/__init__.py"]
+
+[tool.ty.environment]
+# Check against Python 3.11 so that stdlib symbols introduced in 3.11
+# (http.HTTPMethod, typing.Self, enum.StrEnum) are available, avoiding
+# false-positive unresolved-import errors in the try/except compat shims.
+python-version = "3.11"

core_https-2.0.2/core_https.egg-info/requires.txt

@@ -1,11 +0,0 @@
-core-mixins>=2.2.2
-
-[:python_version >= "3.9"]
-aiohttp<4.0.0,>=3.12.0
-requests<3.0.0,>=2.32.3
-urllib3<3.0.0,>=2.2.3
-
-[dev]
-core-dev-tools>=1.0.1
-core-tests>=2.0.2
-types-requests>=2.32.0.20250602

core_https-2.0.2/pyproject.toml

@@ -1,63 +0,0 @@
-# Other project metadata fields as specified in:
-# https://packaging.python.org/en/latest/specifications/declaring-project-metadata/
-# https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html
-
-[build-system]
-requires = ["setuptools>=61.0.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "core-https"
-description = "This project/library contains common elements related to HTTP & API services..."
-version = "2.0.2"
-
-authors = [
-    {name = "Alejandro Cora González", email = "alek.cora.glez@gmail.com"}
-]
-
-maintainers = [
-    {name = "Alejandro Cora González"}
-]
-
-requires-python = ">=3.9"
-license = "MIT"
-readme = "README.rst"
-
-classifiers = [
-    # Classifiers -> https://pypi.org/classifiers/
-    "Intended Audience :: Developers",
-    "Development Status :: 5 - Production/Stable",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-    "Topic :: Utilities",
-    "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.9",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
-    "Programming Language :: Python :: 3.13",
-]
-
-dependencies = [
-    "aiohttp>=3.12.0,<4.0.0; python_version >= '3.9'",
-    "core-mixins>=2.2.2",
-    "requests>=2.32.3,<3.0.0; python_version >= '3.9'",
-    "urllib3>=2.2.3,<3.0.0; python_version >= '3.9'",
-]
-
-[project.optional-dependencies]
-dev = [
-    "core-dev-tools>=1.0.1",
-    "core-tests>=2.0.2",
-    "types-requests>=2.32.0.20250602",
-]
-
-[project.urls]
-Homepage = "https://gitlab.com/bytecode-solutions/core/core-https"
-Repository = "https://gitlab.com/bytecode-solutions/core/core-https"
-Documentation = "https://core-https.readthedocs.io/en/latest/"
-Issues = "https://gitlab.com/bytecode-solutions/core/core-https/-/issues"
-Changelog = "https://gitlab.com/bytecode-solutions/core/core-https/-/blob/master/CHANGELOG.md"
-
-[tool.setuptools.package-data]
-"core_https" = ["py.typed"]