DankMemerClient

The DankMemerClient class manages asynchronous access to the Gwapes items API, including caching and rate-limit protection. The default API supports only client.items. Other routes raise dankmemer.exceptions.UnsupportedRouteException before an HTTP request.

An explicit non-Gwapes base_url preserves legacy request behaviour for a compatible custom server, although such servers are not officially supported.

Python 3.11 or newer is required.

Cache Control

Route responses are cached for 24 hours by default. Use cache_ttl_hours=0 or cache_ttl_hours=None to disable caching.

async with DankMemerClient(cache_ttl_hours=0) as client:
    items = await client.items.query()

Each route supports clear_cache() and cache_info(). The client also supports clear_cache(), clear_route_cache("items"), and cache_info() for all routes.

Retries and Logging

DankMemerClient retries HTTP 429 responses and selected temporary server errors by default. Retry-After headers are respected when present.

client = DankMemerClient(
    retry_attempts=2,
    retry_backoff=0.5,
    retry_on_rate_limit=True,
)

Logging is configured when a client is created, not at import time. The default logging_mode="default" installs the package’s coloured console handler on the dankmemer logger and avoids duplicate package-created handlers.

Use logging_mode="null" for silent logging, or logging_mode="inherit" to let parent/root application logging handle output. Pass logger=... to use an application logger directly. Custom loggers are not modified by the client.

default_client = DankMemerClient()
explicit_default = DankMemerClient(logging_mode="default")
silent_client = DankMemerClient(logging_mode="null")
inherited_client = DankMemerClient(logging_mode="inherit")
custom_client = DankMemerClient(logger=my_logger)

Session Ownership

If the client creates its own aiohttp.ClientSession, close() and the async context manager close it. If you pass an existing session, ownership stays with the caller and the client will not close it.

class dankmemer.client.ColoredFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)

format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string uses the time (as determined by a call to usesTime(), formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

Return type:

str

class dankmemer.client.DankMemerClient(*, useAntirateLimit=True, base_url='https://api.gwapes.com', session=None, cache_ttl_hours=24, retry_attempts=5, retry_backoff=1.0, retry_max_sleep=30.0, retry_on_rate_limit=None, retry_on_server_error=True, request_timeout=30.0, logging_mode='default', logger=None)

An asynchronous client for accessing Dank Memer item data through Gwapes.

The default API supports only items. Legacy route objects remain available for callers using an explicit compatible base_url. The client also provides built-in caching and optional client-side rate-limit protection.

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.close()

If a session is passed in, the caller keeps ownership of that session and should close it separately.

cache_info()

Return cache state for all routes.

Return type:

dict[str, dict[str, Any]]

clear_cache()

Clear all route caches for this client.

Return type:

None

clear_route_cache(route_name)

Clear one route cache by client attribute name, such as items.

Return type:

None

async request(route, params=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.

Parameters:

• route (str) – The API route to request (appended to the base URL).

• params (dict[str, Any] | None) – Optional dictionary of query parameters.

Returns:

The parsed JSON response.