The Base Class, Functions and Exceptions

Below you can find an information about the base class.

class aiowallhaven.api.WallHavenAPI(api_key)

API key is a key given to you by https://wallhaven.cc.

HTTP Method “GET”

async aiowallhaven.api.WallHavenAPI._get_method(self, url: str, params: Dict | None = None) → Dict

Make an async GET request to https://wallhaven.cc

Parameters:

  • url – URL for the new aiohttp.ClientSession object.

  • params – Additional parameters for get method

Returns:

class:

JSON object

Functions

async aiowallhaven.api.WallHavenAPI.get_wallpaper(self, wallpaper_id: str)

Get the details about wallpaper with given id.

Parameters:

wallpaper_id – A string representing a unique id assigned to the wallpaper.

Returns:

class:

JSON object

async aiowallhaven.api.WallHavenAPI.search(self, q: str | None = None, category: Category | None = None, purity: Purity | None = None, sorting: Sorting | None = None, order: Order | None = None, toprange: TopRange | None = None, atleast: Resolution | None = None, resolutions: list[Resolution] | None = None, ratios: list[Ratio] | None = None, color: Color | None = None, page: int | None = None, seed: str | None = None)

Perform search through Wallhaven. If no additional parameters are set the latest SFW wallpapers will be returned.

Parameters:

  • q – Search query. Your main way of finding what you’re looking for.

  • category – Only wallpapers with specified categories will be returned.

  • purity – Only wallpapers with specified purities will be returned.

  • sorting – (optional) Method of sorting results.

  • order – (optional) Sorting order. Default order is desc.

  • toprange – (optional) Specify toplist sorting options. Sorting MUST be set to ‘toplist’.

  • atleast – (optional) Minimum resolution allowed. (e.g. “1920x1080”)

  • resolutions – (optional) List of exact wallpaper resolutions.

  • ratios – (optional) List of exact ratios.

  • color – (optional) Search by color.

  • page – (optional) Pagination. Not actually infinite.

  • seed – (optional) seed for random results. Example: [a-zA-Z0-9]{6}.

Returns:

class:

JSON object

async aiowallhaven.api.WallHavenAPI.get_tag(self, tag: int)

Return the information about a specific tag.

Parameters:

tag – an integer associated with a tag.

Returns:

class:

JSON object

async aiowallhaven.api.WallHavenAPI.my_settings(self)

Return the user’s settings. API key is required for this method.

Returns:

class:

JSON object

async aiowallhaven.api.WallHavenAPI.get_collections(self, username: str | None = None, collection_id: int | None = None, purity: Purity | None = None, page: int = 1)

Allows a user to see their own or public collection.

Parameters:

  • username – (optional) Specifies a username of user, whose collections you are looking for.

  • collection_id – (optional) Argument to parse through user collection having the indicated ID.

  • purity – (optional) Argument to choose purity of returned results (e.g. [“sfw”, “sketchy”, “nsfw”]).

  • page – Page of the collection you are looking for.

Returns:

class:

JSON object

Exceptions

aiowallhaven.api_exception_reasons.TooManyRequests

alias of Too many requests to the server, please try again later

aiowallhaven.api_exception_reasons.Unauthorized

alias of Invalid API key. Please provide a valid API key. You can regenerate your API key at https://wallhaven.cc/settings/account

aiowallhaven.api_exception_reasons.GeneralError

alias of The request to open {session} failed with the following HTTP code: {status_code}

aiowallhaven.api_exception_reasons.ValueErrorPurity

alias of No valid purity filter found. Only ‘sfw’, ‘sketchy’, and ‘nsfw’ are considered to be valid purity filters.

aiowallhaven.api_exception_reasons.ValueErrorCategory

alias of No valid category filter found. Only ‘general’, ‘anime’, and ‘people’ are considered to be valid category filters.

aiowallhaven.api_exception_reasons.ValueErrorSorting

alias of Invalid parameter was provided. Only “date_added”, “relevance”, “random”, “favorites”, “toplist” are considered to be valid arguments.

aiowallhaven.api_exception_reasons.ValueErrorOrder

alias of Invalid order method was provided. Only ‘desc’ and ‘asc’ are considered to be valid arguments.

aiowallhaven.api_exception_reasons.ValueErrorToprange

alias of Invalid parameter was provided. Only “1d”, “3d”, “1w”, “1M”, “3M”, “6M”, “1y” are considered to be valid arguments.

aiowallhaven.api_exception_reasons.ValueErrorAtleast

alias of Invalid screen resolution was provided. Valid formats: Resolution(1920, 1080), Resolution(3080, 2140)