dankmemer.py 0.1.0a0__py3-none-any.whl

dankmemer/__init__.py

@@ -0,0 +1,7 @@
+__version__ = "0.1.0a0"
+
+from .client import DankMemerClient
+from .routes.items import Item, ItemsFilter
+from .utils import Fuzzy
+
+__all__ = ["DankMemerClient", "Fuzzy", "ItemsFilter", "Item"]

dankmemer/client.py

@@ -0,0 +1,100 @@
+import asyncio
+import time
+from datetime import timedelta
+from typing import Optional
+
+import aiohttp
+
+from .routes import items
+
+
+class DankMemerClient:
+    """
+    An asynchronous client for accessing the DankAlert API.
+
+    This client manages and provides access to various API endpoints
+    (e.g. items, npcs, skills, tools) along with built-in caching. In addition, it supports
+    anti-rate-limit behavior: when 'useAntirateLimit' is enabled (the default), the client
+    ensures that no more than 60 requests are made every 60 seconds.
+
+    Recommended usage:
+      As a context manager:
+        async with DankMemerClient(cache_ttl_hours=24) as client:
+            items = await client.items.query()
+
+      Without a context manager:
+        client = DankMemerClient(cache_ttl_hours=24)
+        items = await client.items.query()
+        await client.session.close()
+    """
+
+    def __init__(
+        self,
+        *,
+        useAntirateLimit: bool = True,
+        base_url="https://api.dankalert.xyz/dank",
+        session: Optional[aiohttp.ClientSession] = None,
+        cache_ttl_hours: int = 24,
+    ):
+        self.use_anti_ratelimit = useAntirateLimit
+        self.base_url = base_url.rstrip("/")
+        self.session = session or aiohttp.ClientSession()
+        if cache_ttl_hours < 1:
+            raise ValueError("cache_ttl_hours must be at least 1 hour")
+        self.cache_ttl = timedelta(hours=cache_ttl_hours)
+
+        # Rate-limiting (current API: 60 requests per 60 seconds)
+        self._rate_limit_lock = asyncio.Lock()
+        self.max_requests: int = 60
+        self.request_period: float = 60.0
+        self._request_times: list[float] = []
+
+        self.items = items.ItemsRoute(self, self.cache_ttl)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb):
+        if self.session:
+            await self.session.close()
+
+    async def request(self, route: str, params: dict = None):
+        """
+        Makes an HTTP GET request to the specified route with the given query parameters,
+        while enforcing the API's rate limiting if useAntirateLimit is enabled.
+
+        :param route: The API route to request (appended to the base URL).
+        :param params: Optional dictionary of query parameters.
+        :return: The parsed JSON response.
+        """
+
+        # Rate-limiting check:
+        # We perform a single check on the _request_times list and sleep if needed.
+        # Because all access to _request_times is serialized using an asyncio lock,
+        # and our expected usage pattern doesn't involve huge bursts of concurrent requests,
+        # a single check is sufficient to enforce the rate limit.
+        # If the system were to experience significant bursts, a while loop could be added
+        # to continuously re-check the condition after sleeping. However, given our design,
+        # the one-time check and sleep approach provides a simpler and maintainable solution.
+
+        if self.use_anti_ratelimit:
+            async with self._rate_limit_lock:
+                now: float = time.monotonic()
+                self._request_times = [
+                    t for t in self._request_times if now - t < self.request_period
+                ]
+                if len(self._request_times) >= self.max_requests:
+                    wait_time: float = self.request_period - (
+                        now - self._request_times[0]
+                    )
+                    await asyncio.sleep(wait_time)
+                    now = time.monotonic()
+                    self._request_times = [
+                        t for t in self._request_times if now - t < self.request_period
+                    ]
+                self._request_times.append(now)
+
+        url = f"{self.base_url}/{route}"
+        async with self.session.get(url, params=params) as response:
+            response.raise_for_status()
+            return await response.json()

dankmemer/utils.py

@@ -0,0 +1,15 @@
+class Fuzzy:
+    """
+    Represents a fuzzy match criterion.
+
+    :param value: The string value to match.
+    :param cutoff: The minimum matching ratio (0-100) required for a successful fuzzy match.
+                   Defaults to 80.
+    """
+
+    def __init__(self, value: str, cutoff: int = 80) -> None:
+        self.value: str = value
+        self.cutoff: int = cutoff
+
+    def __repr__(self) -> str:
+        return f"Fuzzy({self.value!r}, cutoff={self.cutoff})"

dankmemer_py-0.1.0a0.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: dankmemer.py
+Version: 0.1.0a0
+Summary: A lightweight async wrapper for the DankAlert API.
+Home-page: https://github.com/RayyanW786/dankmemer.py
+Author: RayyanW786
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.7.4
+Requires-Dist: rapidfuzz>=1.6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.14.0; extra == "dev"
+Dynamic: license-file

dankmemer_py-0.1.0a0.dist-info/RECORD

@@ -0,0 +1,8 @@
+dankmemer/__init__.py,sha256=gWN5UgfQV1UEiyvWpD8YPXHG0bD4aBlL6ItfinLTar8,200
+dankmemer/client.py,sha256=uGf4ZGL4e23oFCpZ362tGlPmEeEjoBbKxHFQDBFQEds,4039
+dankmemer/utils.py,sha256=CW8B5STAYJ_8Y1QJdx76CtrPgjqIHmwxIwQalYP_ZyY,481
+dankmemer_py-0.1.0a0.dist-info/licenses/LICENSE,sha256=G6ElBv8aqRO3YwXQk6_7OfGcO2IFY5Nyi0PZBCWK9Ig,1084
+dankmemer_py-0.1.0a0.dist-info/METADATA,sha256=IFFO4VC-wuX0C5n-43q7bNVwn3OvPE9vOlzu9CYGIa0,706
+dankmemer_py-0.1.0a0.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+dankmemer_py-0.1.0a0.dist-info/top_level.txt,sha256=ctC8iNcUp-0WbPZI7Oi_054klfpWhS4LgxAUtIPYgqM,10
+dankmemer_py-0.1.0a0.dist-info/RECORD,,

dankmemer_py-0.1.0a0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dankmemer_py-0.1.0a0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rayyan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dankmemer_py-0.1.0a0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dankmemer