def search(self) -> SearchResults:
"""Perform a search.
If you provide an API key with no extra parameters, search will be performed
with the user's browsing settings and default filters. With no additional
parameters, the search will display the latest SFW wallpapers. See the parameter
list at `https://wallhaven.cc/help/api` to access other listings.
If you provide both an API key and search parameters, `Wallhaven` will merge the
parameters defined in both, but with the search parameters having priority over
the ones in your browsing settings. For example, if you set `purity` to only
display `sketchy` wallpapers in your browsing settings, when providing an API
key, the search will always retrieve `sketchy` wallpapers unless you explicitly
state otherwise in the search parameters.
Also, the only way to retrieve more than 24 results per page is to change the
`Thumbs Per Page` option in your browsing settings and providing an API key
whenever performing a search.
"""
url = API_ENDPOINTS["search"]
# If `self.params` is empty, the search will use the default parameters.
data = handler.get_json(
url, timeout=self.timeout, headers=self.headers, params=self.params
)
return SearchResults.from_dict(data)
def get_tag(self, tag_id: Union[str, int]) -> Tag:
"""Get tag from a given ID.
Args:
tag_id (str | int): An integer or a numeric string representing the Tag id.
Returns:
An instance of a `Tag` object.
"""
url = API_ENDPOINTS["tag"].format(id=tag_id)
response = handler.get_json(url, timeout=self.timeout)
return Tag.from_dict(response["data"])
def get_wallpaper(self, wallpaper_id: str) -> Wallpaper:
"""Get wallpaper from a given ID. An API key is required for NSFW wallpapers.
Args:
wallpaper_id (str): The wallpaper ID, e.g "8oxreo".
Returns:
An instance of a `Wallpaper` object.
"""
url = API_ENDPOINTS["wallpaper"].format(id=wallpaper_id)
response = handler.get_json(url, timeout=self.timeout, headers=self.headers)
return Wallpaper.from_dict(response["data"])
def _get_collection_listing(
self, username: str, collection_id: int, private: bool = False
) -> CollectionListing:
"""Get the listing of wallpapers in a collection.
This is a internal method that is shared between `get_collection_listing` and
`get_private_collection_listing`. It is not supposed to be used on its own, but
through those two methods. This method does NOT check if the API key exists.
Args:
username (str): A string representing the collection's owner.
collection_id (int): An integer representing the collection's ID.
private (bool): Whether the collection is private (True) or public (False).
Returns:
A `CollectionListing` object that provides a list of wallpapers and meta
information that can be used as pagination.
"""
# Same endpoint for both public and private collection listing.
url = API_ENDPOINTS["collection_listing"].format(
username=username, id=collection_id
)
if private:
response = handler.get_json(url, timeout=self.timeout, headers=self.headers)
else:
response = handler.get_json(url, timeout=self.timeout)
# Add the request URL to the meta dict.
# This URL will be later used for pagination, as we only need to append
# "?page=<n>" to the URL.
response["meta"]["request_url"] = url
# Since we also need the `meta` key inside the dictionary, we can't use
# `response["data"]` in here.
return CollectionListing.from_dict(response)
def get_user_settings(self) -> UserSettings:
"""Read an authenticated user's settings from the API key.
Returns:
An instance of a `UserSettings` object.
Raises:
ApiKeyError: For an invalid API key or when one is not provided.
"""
if self.api_key is None:
raise ApiKeyError("An API key is required to read an user's settings.")
url = API_ENDPOINTS["settings"]
response = handler.get_json(url, timeout=self.timeout, headers=self.headers)
return UserSettings.from_dict(response["data"])
def get_all_collections(self) -> List[Collection]:
"""Get all collections (including private ones) from an authenticated user.
This operation requires an API key.
Returns:
A list of `Collection` objects. At least one (1) collection should always be
present.
Raises:
ApiKeyError: For an invalid API key or when one is not provided.
"""
if self.api_key is None:
raise ApiKeyError(
"An API key is required to get collections from an authenticated user."
)
url = API_ENDPOINTS["collection_apikey"]
response = handler.get_json(url, timeout=self.timeout, headers=self.headers)
return self._get_collections_from_response(response)
def get_collections(self, username: str) -> List[Collection]:
"""Get the collections of a given user.
Fetching the collections by username only returns public collections.
If you want to fetch all collections (including private ones), you need to
provide an API key and call `get_all_collections` instead.
Args:
username (str): The collections' owner.
Returns:
A list of `Collection` objects or an empty list if no collections are found.
This will only happen if the user has only one collection and it's marked as
private. In this case, use `get_all_collections` with an API key.
"""
url = API_ENDPOINTS["collection"].format(username=username)
response = handler.get_json(url, timeout=self.timeout)
return self._get_collections_from_response(response)