dankmemer.py 0.1.0a0__tar.gz

dankmemer_py-0.1.0a0/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/MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include dankmemer *.py 
+include README.rst
+include LICENSE

dankmemer_py-0.1.0a0/PKG-INFO

@@ -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/README.rst

@@ -0,0 +1,83 @@
+dankmemer.py
+============
+
+**Alpha Release Notice:**
+-------------------------
+
+**dankmemer.py** is currently in alpha. At this stage, only the items route is implemented. Future releases will include additional routes and enhanced features.
+
+**dankmemer.py** is a simple and powerful asynchronous Python wrapper for the `DankAlert API <https://api.dankalert.xyz>`_ — giving you easy access to Dank Memer-related data like items, NPCs, skills, tools, and more.
+
+----
+
+🚀 Features
+-----------
+
+- Built-in caching with configurable TTL
+- Powerful filtering with support for exact, fuzzy, and numeric range queries
+
+----
+
+📦 Installation
+---------------
+
+You can install the project using any of the following aliases:
+
+.. code-block:: bash
+
+    pip install dankmemer
+    pip install dankmemer.py
+----
+
+Items Route
+-----------
+
+The Items Route provides access to the ``/items`` endpoint from the DankAlert API. It automatically caches responses for a configurable period, converts raw JSON into ``Item`` objects, and allows easy filtering via the ``ItemsFilter`` class and the ``Fuzzy`` helper.
+
+Basic Example
+~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    import asyncio
+    from dankmemer import DankMemerClient, ItemsFilter, Fuzzy
+
+    async def main():
+        async with DankMemerClient() as client:
+            # Retrieve all items without filtering.
+            all_items = await client.items.query()
+            print("All items:", all_items)
+
+            # Example: Filtering items using various criteria:
+            # - Fuzzy matching on the 'name' field (e.g. items with names similar to "trash")
+            # - Boolean filtering for 'hasUse' flag
+            # - Numeric range filtering for 'marketValue'
+            filter_obj = ItemsFilter(
+                name=Fuzzy("trash", cutoff=80),  # Fuzzy match on name with a cutoff of 80%
+                hasUse=False,                    # Only items that are not usable
+                marketValue=(5000, 10000000)     # Market value between 5,000 and 10,000,000
+            )
+
+            filtered_items = await client.items.query(filter_obj)
+            print("Filtered items:", filtered_items)
+
+    asyncio.run(main())
+
+This basic example demonstrates:
+
+- **Exact vs. Fuzzy Matching:** Use a plain string for exact matches (e.g. ``name="Trash"``) or wrap your string with the ``Fuzzy`` helper (e.g. ``name=Fuzzy("trash", cutoff=80)``) for fuzzy matching.
+- **Numeric Range Filtering:** Supply a tuple ``(min, max)`` to filter numeric fields such as ``marketValue``.
+- **Boolean Filtering:** Directly pass boolean values (e.g. ``hasUse=True``).
+
+----
+
+Documentation
+-------------
+
+Full documentation for dankmemer.py can be found at:
+
+https://dankmemer-py.readthedocs.io
+
+----
+
+Feel free to test, report issues, and contribute to this alpha release!

dankmemer_py-0.1.0a0/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_py-0.1.0a0/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_py-0.1.0a0/dankmemer/routes/items.py

@@ -0,0 +1,282 @@
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
+
+from rapidfuzz import fuzz
+
+from dankmemer.utils import Fuzzy
+
+if TYPE_CHECKING:
+    from dankmemer.client import DankMemerClient
+
+
+@dataclass(frozen=True)
+class Item:
+    """
+    Represents an individual item obtained from the DankAlert API.
+
+    This immutable class encapsulates all relevant attributes that describe an item,
+    such as its identifier, name, details, and various numeric properties. It is designed
+    to allow users to interact with item data in a Pythonic way.
+
+    Attributes:
+        id (int): The unique identifier of the item.
+        name (str): The name of the item.
+        details (str): Additional details or description of the item.
+        emoji (str): An emoji representation associated with the item.
+        flavor (str): A short flavor text providing context or description for the item.
+        hasUse (bool): Indicates whether the item has a usable function.
+        imageURL (str): The URL pointing to the item's image.
+        itemKey (str): A unique string key for the item (e.g. "trash").
+        marketValue (int): The market value of the item.
+        netValue (int): The net value of the item.
+        rarity (str): The rarity classification of the item (e.g. "Common", "Rare").
+        skins (Dict[str, Any]): A dictionary of available skins for the item.
+        tags (Dict[str, Any]): A dictionary of tags associated with the item.
+        type (str): The type or category of the item (e.g. "Sellable", "Loot Box").
+        value (int): The intrinsic value or base price of the item.
+    """
+
+    id: int
+    name: str
+    details: str
+    emoji: str
+    flavor: str
+    hasUse: bool
+    imageURL: str
+    itemKey: str
+    marketValue: int
+    netValue: int
+    rarity: str
+    skins: Dict[str, Any]
+    tags: Dict[str, Any]
+    type: str
+    value: int
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Item":
+        return cls(
+            id=data.get("id"),
+            name=data.get("name"),
+            details=data.get("details"),
+            emoji=data.get("emoji"),
+            flavor=data.get("flavor"),
+            hasUse=data.get("hasUse"),
+            imageURL=data.get("imageURL"),
+            itemKey=data.get("itemKey"),
+            marketValue=data.get("marketValue"),
+            netValue=data.get("netValue"),
+            rarity=data.get("rarity"),
+            skins=data.get("skins", {}),
+            tags=data.get("tags", {}),
+            type=data.get("type"),
+            value=data.get("value"),
+        )
+
+
+class ItemsFilter:
+    """
+    Filter for /items data.
+    For string fields, supply a raw string for an exact match or wrap the string in Fuzzy
+    for fuzzy matching. Numeric fields accept a single number for exact matching or a tuple
+    (min, max) for range filtering.
+
+    Supported filterable attributes:
+      - id: Filter by item ID.
+      - name: Filter by item name.
+      - details: Filter by details.
+      - emoji: Filter by emoji.
+      - flavor: Filter by flavor.
+      - hasUse: Filter by use flag.
+      - imageURL: Filter by image URL.
+      - itemKey: Filter by item key.
+      - marketValue: Filter by market value.
+      - netValue: Filter by net value.
+      - rarity: Filter by rarity.
+      - skins: Filter by skins (exact match).
+      - tags: Filter by tags (exact match).
+      - type: Filter by type.
+      - value: Filter by value.
+      - limit: Maximum number of results returned.
+
+    Examples:
+        .. code-block:: python
+
+            from dankmemer import Fuzzy, ItemsFilter
+
+            # Fuzzy matching example for the 'name' field: match items with a name similar
+            # to "trash" with a cutoff of 80.
+            filter_fuzzy = ItemsFilter(name=Fuzzy("trash", cutoff=80))
+
+            # Exact string matching for the 'name' field.
+            filter_exact = ItemsFilter(name="Trash")
+
+            # Numeric filtering: filtering 'marketValue' to be within a range.
+            filter_range = ItemsFilter(marketValue=(5000, 10000000))
+
+            # Numeric filtering: filtering 'netValue' for an exact match.
+            filter_numeric = ItemsFilter(netValue=100)
+
+            # Boolean filtering: filtering by the 'hasUse' flag.
+            filter_bool = ItemsFilter(hasUse=True)
+    """
+
+    def __init__(
+        self,
+        id: Optional[int] = None,
+        name: Optional[Union[str, Fuzzy]] = None,
+        details: Optional[Union[str, Fuzzy]] = None,
+        emoji: Optional[Union[str, Fuzzy]] = None,
+        flavor: Optional[Union[str, Fuzzy]] = None,
+        hasUse: Optional[bool] = None,
+        imageURL: Optional[Union[str, Fuzzy]] = None,
+        itemKey: Optional[Union[str, Fuzzy]] = None,
+        marketValue: Optional[Union[int, Tuple[int, int]]] = None,
+        netValue: Optional[Union[int, Tuple[int, int]]] = None,
+        rarity: Optional[Union[str, Fuzzy]] = None,
+        skins: Optional[Dict[str, Any]] = None,
+        tags: Optional[Dict[str, Any]] = None,
+        type: Optional[Union[str, Fuzzy]] = None,
+        value: Optional[Union[int, Tuple[int, int]]] = None,
+        limit: Optional[int] = None,
+    ) -> None:
+        self.id: Optional[int] = id
+        self.name: Optional[Union[str, Fuzzy]] = name
+        self.details: Optional[Union[str, Fuzzy]] = details
+        self.emoji: Optional[Union[str, Fuzzy]] = emoji
+        self.flavor: Optional[Union[str, Fuzzy]] = flavor
+        self.hasUse: Optional[bool] = hasUse
+        self.imageURL: Optional[Union[str, Fuzzy]] = imageURL
+        self.itemKey: Optional[Union[str, Fuzzy]] = itemKey
+        self.marketValue: Optional[Union[int, Tuple[int, int]]] = marketValue
+        self.netValue: Optional[Union[int, Tuple[int, int]]] = netValue
+        self.rarity: Optional[Union[str, Fuzzy]] = rarity
+        self.skins: Optional[Dict[str, Any]] = skins
+        self.tags: Optional[Dict[str, Any]] = tags
+        self.type: Optional[Union[str, Fuzzy]] = type
+        self.value: Optional[Union[int, Tuple[int, int]]] = value
+        self.limit: Optional[int] = limit
+
+    def apply(self, data: List[Item]) -> List[Item]:
+        results: List[Item] = []
+        for item in data:
+            if self.id is not None and item.id != self.id:
+                continue
+            if self.name is not None and not self._matches_field(item.name, self.name):
+                continue
+            if self.details is not None and not self._matches_field(
+                item.details, self.details
+            ):
+                continue
+            if self.emoji is not None and not self._matches_field(
+                item.emoji, self.emoji
+            ):
+                continue
+            if self.flavor is not None and not self._matches_field(
+                item.flavor, self.flavor
+            ):
+                continue
+            if self.hasUse is not None and item.hasUse != self.hasUse:
+                continue
+            if self.imageURL is not None and not self._matches_field(
+                item.imageURL, self.imageURL
+            ):
+                continue
+            if self.itemKey is not None and not self._matches_field(
+                item.itemKey, self.itemKey
+            ):
+                continue
+            if self.marketValue is not None and not self._matches_numeric(
+                item.marketValue, self.marketValue
+            ):
+                continue
+            if self.netValue is not None and not self._matches_numeric(
+                item.netValue, self.netValue
+            ):
+                continue
+            if self.rarity is not None and not self._matches_field(
+                item.rarity, self.rarity
+            ):
+                continue
+            if self.skins is not None and item.skins != self.skins:
+                continue
+            if self.tags is not None and item.tags != self.tags:
+                continue
+            if self.type is not None and not self._matches_field(item.type, self.type):
+                continue
+            if self.value is not None and not self._matches_numeric(
+                item.value, self.value
+            ):
+                continue
+            results.append(item)
+        if self.limit is not None:
+            results = results[: self.limit]
+        return results
+
+    def _matches_field(self, field_value: str, filter_val: Union[str, Fuzzy]) -> bool:
+        if not field_value:
+            return False
+        if isinstance(filter_val, Fuzzy):
+            score: float = fuzz.ratio(field_value.lower(), filter_val.value.lower())
+            return score >= filter_val.cutoff
+        return field_value.lower() == filter_val.lower()  # type: ignore
+
+    def _matches_numeric(
+        self, field_value: Union[int, float], filter_val: Union[int, Tuple[int, int]]
+    ) -> bool:
+        if isinstance(filter_val, tuple):
+            low, high = filter_val
+            return low <= field_value <= high
+        return field_value == filter_val
+
+
+class ItemsRoute:
+    """
+    Represents the /items endpoint, converting raw API data into python objects and
+    providing route-specific filtering.
+    """
+
+    def __init__(self, client: "DankMemerClient", cache_ttl: timedelta) -> None:
+        self.client: "DankMemerClient" = client
+        self.cache_ttl: timedelta = cache_ttl
+        self._cache: Optional[Dict[int, Item]] = None
+        self._last_update: Optional[datetime] = None
+        self._lock: asyncio.Lock = asyncio.Lock()
+
+    async def _fetch(self) -> Dict[int, Item]:
+        raw_data: Dict[str, Any] = await self.client.request("items")
+        processed: Dict[int, Item] = {}
+        for key, value in raw_data.items():
+            try:
+                item_id: int = int(key)
+            except ValueError:
+                continue
+            processed[item_id] = Item.from_dict(value)
+        self._cache = processed
+        self._last_update = datetime.now(timezone.utc)
+        return processed
+
+    async def _get_data(self) -> Dict[int, Item]:
+        async with self._lock:
+            if (self._cache is None) or (
+                datetime.now(timezone.utc) - self._last_update > self.cache_ttl
+            ):
+                return await self._fetch()
+            return self._cache
+
+    async def query(self, item_filter: Optional[ItemsFilter] = None) -> List[Item]:
+        """
+        Retrieve the list of Items from the /items endpoint.
+
+        If no filter is provided, all cached items are returned. Otherwise, the provided
+        ItemsFilter is applied and only items matching the filter criteria are returned.
+
+        :param item_filter: Optional ItemsFilter instance containing filtering criteria.
+        :return: A list of Item objects.
+        """
+        raw_dict: Dict[int, Item] = await self._get_data()
+        items_list: List[Item] = list(raw_dict.values())
+        if item_filter is None:
+            return items_list
+        return item_filter.apply(items_list)

dankmemer_py-0.1.0a0/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/dankmemer.py.egg-info/PKG-INFO

@@ -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/dankmemer.py.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+MANIFEST.in
+README.rst
+pyproject.toml
+setup.cfg
+setup.py
+dankmemer/__init__.py
+dankmemer/client.py
+dankmemer/utils.py
+dankmemer.py.egg-info/PKG-INFO
+dankmemer.py.egg-info/SOURCES.txt
+dankmemer.py.egg-info/dependency_links.txt
+dankmemer.py.egg-info/requires.txt
+dankmemer.py.egg-info/top_level.txt
+dankmemer/routes/items.py

dankmemer_py-0.1.0a0/dankmemer.py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dankmemer_py-0.1.0a0/dankmemer.py.egg-info/requires.txt

@@ -0,0 +1,6 @@
+aiohttp>=3.7.4
+rapidfuzz>=1.6.0
+
+[dev]
+pytest>=6.0
+pytest-asyncio>=0.14.0

dankmemer_py-0.1.0a0/dankmemer.py.egg-info/top_level.txt

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

dankmemer_py-0.1.0a0/pyproject.toml

@@ -0,0 +1,6 @@
+[build-system]
+requires = [
+    "setuptools>=42",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"

dankmemer_py-0.1.0a0/setup.cfg

@@ -0,0 +1,31 @@
+[metadata]
+name = dankmemer.py
+version = attr: dankmemer.__version__
+author = RayyanW786
+description = A lightweight async wrapper for the DankAlert API.
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/RayyanW786/dankmemer.py
+license = MIT
+classifiers = 
+	Programming Language :: Python :: 3
+	Programming Language :: Python :: 3.7
+	License :: OSI Approved :: MIT License
+	Operating System :: OS Independent
+
+[options]
+packages = find:
+python_requires = >=3.7
+install_requires = 
+	aiohttp>=3.7.4
+	rapidfuzz>=1.6.0
+
+[options.extras_require]
+dev = 
+	pytest>=6.0
+	pytest-asyncio>=0.14.0
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

dankmemer_py-0.1.0a0/setup.py

@@ -0,0 +1,4 @@
+from setuptools import setup
+
+setup()
+