Reference#

Client#

class waifuim.Client(*, session: ClientSession | None = None, token: str, identifier: str)#

Client for interacting with the API.

Parameters:

session (aiohttp.ClientSession | None) – The session to use for requests. If not provided, a new session will be created.
token (str) – The API token to use for requests. You can get one here.
identifier (str) – Used to identify your application in the User-Agent header. It is recommended to use the name of your application.

await search(*, included_tags: Sequence[Tags | str] | None = None, excluded_tags: Sequence[Tags | str] | None = None, nsfw: bool = False, gif: bool | None = None, order_by: Order = Order.RANDOM, orientation: Orientation | None = None, multiple: Literal[False] = False, included_files: Sequence[str] | None = None, excluded_files: Sequence[str] | None = None, return_raw: Literal[False] = False) → Image#

await search(*, included_tags: Sequence[Tags | str] | None = None, excluded_tags: Sequence[Tags | str] | None = None, nsfw: bool = False, gif: bool | None = None, order_by: Order = Order.RANDOM, orientation: Orientation | None = None, multiple: Literal[True] = False, included_files: Sequence[str] | None = None, excluded_files: Sequence[str] | None = None, return_raw: Literal[False] = False) → list[waifuim.models.Image]

await search(*, included_tags: Sequence[Tags | str] | None = None, excluded_tags: Sequence[Tags | str] | None = None, nsfw: bool = False, gif: bool | None = None, order_by: Order = Order.RANDOM, orientation: Orientation | None = None, multiple: bool = False, included_files: Sequence[str] | None = None, excluded_files: Sequence[str] | None = None, return_raw: bool = True) → ImageResponseData

Search for some images on the API.

Parameters:

included_tags (Sequence[Tag | str] | None) – Will only return images with these tags.
excluded_tags (Sequence[Tag | str] | None) – Will not return images with these tags.
nsfw (bool) – Whether to return NSFW images. Defaults to False.
gif (bool | None) – Whether to return GIFs.
order_by (Order) – How to order the images. Defaults to Order.RANDOM.
orientation (Orientation | None) – The orientation of the images.
multiple (bool) – Whether to return multiple images. Returns 30. Defaults to False.
included_files (Sequence[str] | None) – Only return images with these files.
excluded_files (Sequence[str] | None) – Do not return images with these files.
return_raw (bool | None) – Whether to return the raw response data.

Raises:

NotFound – No images were found matching your search.
HTTPException – An error occurred while requesting.

Returns:

The image(s) returned from the API.

Return type:

Image | list[Image] | ImageResponseData

await favourites(*, user_id: int, included_tags: Sequence[Tags | str] | None = None, excluded_tags: Sequence[Tags | str] | None = None, nsfw: bool = False, gif: bool | None = None, order_by: Order = Order.RANDOM, orientation: Orientation | None = None, multiple: Literal[False] = False, included_files: Sequence[str] | None = None, excluded_files: Sequence[str] | None = None, return_raw: Literal[False] = False) → Image#

await favourites(*, user_id: int, included_tags: Sequence[Tags | str] | None = None, excluded_tags: Sequence[Tags | str] | None = None, nsfw: bool = False, gif: bool | None = None, order_by: Order = Order.RANDOM, orientation: Orientation | None = None, multiple: Literal[True] = False, included_files: Sequence[str] | None = None, excluded_files: Sequence[str] | None = None, return_raw: Literal[False] = False) → list[waifuim.models.Image]

await favourites(*, user_id: int, included_tags: Sequence[Tags | str] | None = None, excluded_tags: Sequence[Tags | str] | None = None, nsfw: bool = False, gif: bool | None = None, order_by: Order = Order.RANDOM, orientation: Orientation | None = None, multiple: bool = False, included_files: Sequence[str] | None = None, excluded_files: Sequence[str] | None = None, return_raw: bool = True) → ImageResponseData

Get a user’s favourites.

Note

The user must have authorized your application to access their favourites. See generate_authorization_link().

Parameters:

user_id (int) – The ID of the user to get the favourites of.
included_tags (Sequence[Tag | str] | None) – Will only return images with these tags.
excluded_tags (Sequence[Tag | str] | None) – Will not return images with these tags.
nsfw (bool) – Whether to return NSFW images. Defaults to False.
gif (bool | None) – Whether to return GIFs.
order_by (Order) – How to order the images. Defaults to Order.RANDOM.
orientation (Orientation | None) – The orientation of the images.
multiple (bool) – Whether to return multiple images. Returns 30. Defaults to False.
included_files (Sequence[str] | None) – Only return images with these files.
excluded_files (Sequence[str] | None) – Do not return images with these files.
return_raw (bool | None) – Whether to return the raw response data.

Raises:

NotFound – No images were found matching your search.
Unauthorized – Your token is invalid.
Forbidden – You do not have permission to access the user’s favorites
HTTPException – An error occurred while requesting.

Returns:

The image(s) returned from the API.

Return type:

Image | list[Image] | ImageResponseData

await favourites_insert(*, user_id: int, image: Image | int) → None#

Insert an image into a user’s favourites.

Note

The user must have authorized your application to edit their favourites. See utils.generate_authorization_link().

Parameters:

user_id (int) – The ID of the user to insert the image into.
image (Image | int) – The Image or Image ID of the image to insert to the user’s favourites.

Raises:

HTTPException – Can occur if: - Image already exists in the user’s favourites. - The image does not exist.
Forbidden – You do not have permission to edit the user’s favorites.
Unauthorized – Your token is invalid.

await favourites_delete(*, user_id: int, image: Image | int) → None#

Remove an image from a user’s favourites.

Note

The user must have authorized your application to edit their favourites. See utils.generate_authorization_link().

Parameters:

user_id (int) – The ID of the user to remove the image from.
image (Image | int) – The Image or Image ID of the image to remove from the user’s favourites.

Raises:

HTTPException – Can occur if: - Image dosen’t exist in the user’s favourites. - The image does not exist.
Forbidden – You do not have permission to edit the user’s favorites.
Unauthorized – Your token is invalid.

await favourites_toggle(*, user_id: int, image: Image | int) → None#

Insert or Reomve an image into a user’s favourites.

Note

The user must have authorized your application to edit their favourites. See utils.generate_authorization_link().

Parameters:

user_id (int) – The ID of the user to remove the image from.
image (Image | int) – The Image or Image ID of the image to insert or remove from the user’s favourites.

Raises:

HTTPException – The image does not exist.
Forbidden – You do not have permission to edit the user’s favorites.
Unauthorized – Your token is invalid.

Get a user’s favourites.

Note

The user must have authorized your application to access their favourites. See generate_authorization_link().

Parameters:

user_id (int) – The ID of the user to get the favourites of.
included_tags (Sequence[Tag | str] | None) – Will only return images with these tags.
excluded_tags (Sequence[Tag | str] | None) – Will not return images with these tags.
nsfw (bool) – Whether to return NSFW images. Defaults to False.
gif (bool | None) – Whether to return GIFs.
order_by (Order) – How to order the images. Defaults to Order.RANDOM.
orientation (Orientation | None) – The orientation of the images.
multiple (bool) – Whether to return multiple images. Returns 30. Defaults to False.
included_files (Sequence[str] | None) – Only return images with these files.
excluded_files (Sequence[str] | None) – Do not return images with these files.
return_raw (bool | None) – Whether to return the raw response data.

Raises:

NotFound – No images were found matching your search.
Unauthorized – Your token is invalid.
Forbidden – You do not have permission to access the user’s favorites
HTTPException – An error occurred while requesting.

Returns:

The image(s) returned from the API.

Return type:

Image | list[Image] | ImageResponseData

await favorites_insert(*, user_id: int, image: Image | int) → None#

Insert an image into a user’s favourites.

Note

The user must have authorized your application to edit their favourites. See utils.generate_authorization_link().

Parameters:

user_id (int) – The ID of the user to insert the image into.
image (Image | int) – The Image or Image ID of the image to insert to the user’s favourites.

Raises:

HTTPException – Can occur if: - Image already exists in the user’s favourites. - The image does not exist.
Forbidden – You do not have permission to edit the user’s favorites.
Unauthorized – Your token is invalid.

await favorites_delete(*, user_id: int, image: Image | int) → None#

Remove an image from a user’s favourites.

Note

The user must have authorized your application to edit their favourites. See utils.generate_authorization_link().

Parameters:

user_id (int) – The ID of the user to remove the image from.
image (Image | int) – The Image or Image ID of the image to remove from the user’s favourites.

Raises:

HTTPException – Can occur if: - Image dosen’t exist in the user’s favourites. - The image does not exist.
Forbidden – You do not have permission to edit the user’s favorites.
Unauthorized – Your token is invalid.

await favorites_toggle(*, user_id: int, image: Image | int) → None#

Insert or Reomve an image into a user’s favourites.

Note

The user must have authorized your application to edit their favourites. See utils.generate_authorization_link().

Parameters:

user_id (int) – The ID of the user to remove the image from.
image (Image | int) – The Image or Image ID of the image to insert or remove from the user’s favourites.

Raises:

HTTPException – The image does not exist.
Forbidden – You do not have permission to edit the user’s favorites.
Unauthorized – Your token is invalid.

await close()#: Closes the aiohttp.ClientSession used by the client.

Caution

If you specified your own ClientSession, this may interrupt what you are doing with the session.

Models#

class waifuim.Tag(tag_id: int, name: str, description: str, is_nsfw: bool)#: Class representing a tag.

class waifuim.Image(signature: str, extension: str, id: int, favourites: int, dominant_color: str, source: str, uploaded_at: datetime | str | None, liked_at: datetime | str | None, is_nsfw: bool, width: int, height: int, url: str, preview_url: str, tags: list[waifuim.models.Tag])#: Class representing an image.

class waifuim.ImageResponseData#: Represents the raw image response data from the API.

class waifuim.Tags(value)#

An enumeration.

classmethod from_str(string: str) → Tags | None#

Get a Tag with its name.

If your input is not found, None will be returned.

class waifuim.Order(value)#: An enumeration.

class waifuim.Orientation(value)#: An enumeration.

Utils#

waifuim.generate_authorization_link(user_id: int, permissions: list[str]) → str#

Generates an authorization link for a user.

Valid permissions are:

manage_favourites
view_favourites

waifuim.generate_deauthorization_link(user_id: int, permissions: list[str]) → str#

Generates an deauthorize link for a user.

Valid permissions are:

manage_favourites
view_favourites

Exceptions#

class waifuim.HTTPException(response: ClientResponse, data: dict[str, Any] | str)#: Exception for HTTP Exceptions.

class waifuim.NotFound(response: ClientResponse, data: dict[str, Any] | str)#: Raised when a 404 error is encountered.

class waifuim.Forbidden(response: ClientResponse, data: dict[str, Any] | str)#: Raised when a 403 error is encountered.

class waifuim.Unauthorized(response: ClientResponse, data: dict[str, Any] | str)#: Raised when a 401 error is encountered.