Clients¶

This module contains all the clients for the library. Each client represents a different endpoint of the API.

Client¶

class somerandomapi.Client[source]¶

Client for interacting with the Some Random API.

This class provides access to all endpoints of the Some Random API, including both free and premium features.

Parameters:

session (aiohttp.ClientSession) –
An aiohttp session to use for HTTP requests. If not provided, the client will create and manage its own session.

Changed in version 0.1.0: - If a session is provided, it will not be closed by the client. Otherwise, the client manages its own session. - This parameter can no longer be None. Either pass a session or omit it entirely.
token (str | None) –
The token to use for endpoints that require it.

Added in version 0.1.0.

property animal¶

The Animal endpoint.

Type:: AnimalClient

property animu¶

The Animu endpoint.

Type:: AnimuClient

property canvas¶

The Canvas endpoint.

Type:: CanvasClient

chatbot(message=None)[source]¶

Chatbot endpoint.

Parameters:: message (Optional[str]) – The message to send to the chatbot. If not provided, the Chatbot object will be returned instead which has a send method and supports async with else ChatbotResult will be returned. .response on that is the response from the chatbot.

Example

async with client.chatbot() as bot:
    await bot.send("Hello!")
    print(bot.response)

# or

res = await client.chatbot("Hello!")
print(res.response)

Returns:: The Chatbot object or the ChatbotResult object. ChatbotResult is returned if message is provided and await is used else Chatbot.
Return type:: Union[Chatbot, ChatbotResult]

async close()[source]¶

Close the client session.

Return type:: None

async decode_base64(_input, /)[source]¶

Decode a base64 string.

Parameters:: input (str) – The base64 string to decode.
Returns:: Object representing the result of the decoding.
Return type:: EncodeResult

async decode_binary(_input)[source]¶

Decode a binary string.

Parameters:: input (str) – The binary string to decode.
Returns:: Object representing the result of the decoding.
Return type:: EncodeResult

async encode_base64(_input, /)[source]¶

Encode a string to base64.

Parameters:: input (str) – The string to encode.
Returns:: Object representing the result of the encoding.
Return type:: EncodeResult

async encode_binary(_input, /)[source]¶

Encode a string to binary.

Parameters:: input (str) – The string to encode.
Returns:: Object representing the result of the encoding.
Return type:: EncodeResult

async generate_bot_token()[source]¶

str: Generate a very realistic bot token

Return type:: str

async hex_to_rgb(_hex, /)[source]¶

Converts a hex value to an RGB value.

Parameters:: hex (str) – The hex value to convert. Must be in the format 123456 or #123456.
Returns:: Object containing the RGB values. Use .as_tuple to get a tuple with the RGB values ((r, g, b)).
Return type:: RGB

async lyrics(song_title)[source]¶

Get the lyrics of a song.

Parameters:: song_title (str) – The title of the song to get the lyrics of.
Returns:: Object representing the lyrics result.
Return type:: Lyrics

property pokemon¶

The Pokemon endpoint.

Type:: PokemonClient

property premium¶

The Premium endpoint.

Type:: PremiumClient

async random_joke()[source]¶

Get a random joke.

Returns:: The joke.
Return type:: str

async rgb_to_hex(rgb)[source]¶

Converts an RGB value to a hex value.

Parameters:: rgb (str) – The RGB value to convert. Must be in the format r,g,b.
Returns:: The hex value.
Return type:: str

async welcome_image(obj=..., *, template=..., type=..., background=..., avatar_url=..., username=..., server_name=..., member_count=..., text_color=..., discriminator=..., key=..., font=...)[source]¶

Generate a welcome image.

Parameters:

obj (WelcomeFree) – The object to use. If not passed, the other parameters will be used and a new object will be created.
template (Literal[1, 2, 3, 4, 5, 6, 7, 8]) – The template to use. Required if obj is not passed.
type (WelcomeType) – The type of welcome image to generate. Required if obj is not passed.
background (WelcomeBackground) – The background to use. Required if obj is not passed.
avatar_url (str) – The avatar URL to use. Required if obj is not passed.
username (str) – The username to use. Required if obj is not passed.
discriminator (int) – The discriminator to use.
server_name (str) – The server name to use. Required if obj is not passed.
member_count (int) – The member count to use. Required if obj is not passed.
text_color (WelcomeTextColor) – The text color to use. Required if obj is not passed.
key (str) – The key to use. Required if a key was not passed when creating the client.
font (int) –
The font from a predefined list. Choose a number between 0 and 7.

Changed in version 0.1.0: Now takes a range of 1-7 instead of 1-8.

Return type:

WelcomeFree

AnimalClient¶

class somerandomapi.AnimalClient[source]¶

Represents the “Animal” endpoint.

This class is not meant to be instantiated by you. Instead, access it through the animal attribute of the Client class.

async get_fact(animal)[source]¶

Get a random fact about an animal.

Parameters:: animal (Union[Fact, str]) – The animal to get a fact about.
Returns:: The fact about the animal.
Return type:: str

async get_image(animal)[source]¶

Get a random image of an animal.

Parameters:: animal (Union[Img, str]) – The animal to get an image of.
Returns:: The image URL.
Return type:: str

async get_image_and_fact(animal)[source]¶

Get a random image and fact about an animal.

Parameters:: animal (Union[Animal, str]) – The animal to get an image and fact about.
Returns:: Object representing the requested animal and its image and fact. Use fact and image to get the fact and image url respectively.
Return type:: AnimalImageFact

async get_image_or_fact(animal)[source]¶

A helper method to get either an image or a fact or both about an animal since the API provides different endpoints for each.

Added in version 0.1.0.

This uses the following methods in order to get the image or fact or both:

get_image_and_fact()
get_fact()
get_image()

And returns an AnimalImageOrFact object with the results.

Parameters:

animal (Union[Animal, Img, Fact, str]) – The animal to get an image or fact or both of.

Returns:

Object representing the requested animal and its image or fact or both.

Use fact and image to get the fact and image url respectively.

Return type:

AnimalImageOrFact

AnimuClient¶

class somerandomapi.AnimuClient[source]¶

Represents the “Animu” endpoint.

This class is not meant to be instantiated you. Instead, access it through the animu attribute of the Client class.

cry()[source]¶

Shortcut for get() with Animu.CRY.

Return type:: str

async get(animu_type, /)[source]¶

Get a random animu image.

Parameters:: animu_type (Union[Animu, str]) – The type of animu image to get. Can be one of the Animu enum values or a string representing the action.
Returns:: The URL of the random animu image.
Return type:: str

hug()[source]¶

Shortcut for get() with Animu.HUG.

Return type:: str

kiss()[source]¶

Shortcut for get() with Animu.KISS.

Return type:: str

nom()[source]¶

Shortcut for get() with Animu.NOM.

Return type:: str

pat()[source]¶

Shortcut for get() with Animu.PAT.

Return type:: str

poke()[source]¶

Shortcut for get() with Animu.POKE.

Return type:: str

async random_quote()[source]¶

Get a random quote from a random animu.

Returns:: Object containing the quote and other information. Use the .quote attribute to get the quote string.
Return type:: AnimuQuote

Chatbot¶

class somerandomapi.Chatbot[source]¶

A client for the chatbot endpoint.

This is a context manager that should be used with the async with statement to ensure the session is closed. Sending a message is done by calling the send method.

async with x: Enters the context manager and returns the client.

await x(message): Sends a message to the chatbot and returns the response.

Example

async with Chatbot(...) as chatbot:
    # response = await chatbot.send("Hello") is also valid.
    async with chatbot.send("Hello") as response:
        print(response.response)

But you can also use it with the await keyword.

chatbot = Chatbot(...)
response = await chatbot.send("Hello")
print(response.response)

Or if you don’t want to use the .send() method, you can use await on the instance of this class directly with the message set on the message attribute.

chatbot = Chatbot(message="Hello")
response = await chatbot()

Parameters:

message (Optional[str]) – The message to send to the chatbot. This is only used if you use the await keyword on an instance of this class.
client (Optional[Client]) – The client. This is also used a session if you don’t provide one.
session (Optional[aiohttp.ClientSession]) – The session to use. If this is not provided, a new session will be created. You are responsible for closing the session if you provide one.

chat(message)[source]¶

Alias for send().

Return type:: _ChatbotSendContextManager

property message¶

The message to send to the chatbot.

This is only used if you use the await keyword on an instance of this class.

Type:: Optional[str]

send(message)[source]¶

Sends a message to the chatbot. See Chatbot for more information.

Parameters:: message (str) – The message to send to the chatbot.
Return type:: _ChatbotSendContextManager

PokemonClient¶

class somerandomapi.PokemonClient[source]¶

Represents the “Pokemon” endpoint.

This class is not meant to be instantiated by the user. Instead, access it through the pokemon attribute of the Client class.

async get_ability(ability)[source]¶

Get a pokemon ability’s information.

Parameters:: ability (str) – The ability name or id of a pokemon ability.
Returns:: Object representing the pokemon ability.
Return type:: PokemonAbility

async get_item(item)[source]¶

Get a pokemon item’s information.

Parameters:: item (str) – The Item name or id of a pokemon item.
Returns:: Object representing the pokemon item.
Return type:: PokemonItem

async get_moves(move)[source]¶

Get a pokemon move’s information.

Parameters:: move (str) – The pokemon move name or id of a pokemon move
Returns:: Object representing the pokemon move.
Return type:: PokemonMove

async get_pokedex(pokemon)[source]¶

Get a pokemon’s pokedex entry.

Parameters:: pokemon (str) – The pokemon to get the pokedex entry for.
Returns:: Object representing the pokedex entry.
Return type:: PokeDex

PremiumClient¶

class somerandomapi.PremiumClient[source]¶

Represents the “Premium” endpoint.

This class is not meant to be instantiated by the user. Instead, access it through the premium attribute of the Client class.

async amongus(avatar, username, key=None, custom_text=None)[source]¶

Create a custom AmongUs ejecting animation.

Parameters:

avatar (str) – The avatar URL.
username (str) – The username. Max 30 characters.
key (Optional[str]) – The key. At least tier 2. Required if not keys are passed to the client.
custom_text (Optional[str]) – The custom text to show rather than ejecting the user.

Returns:

Object representing the generated image.

Return type:

Image

async petpet(avatar)[source]¶

Pet an user’s avatar.

Parameters:: avatar (str) – The avatar URL.
Returns:: The petpet image.
Return type:: Image

async rankcard(obj=..., *, template=..., username=..., avatar_url=..., level=..., current_xp=..., needed_xp=..., discriminator=..., background_url=..., background_color=..., text_color=..., current_xp_color=..., xp_bar_color=..., username_color=...)[source]¶

Generate a custom rankcard.

Parameters:

obj (Optional[Rankcard]) – The object to use. If not passed, the other parameters will be used and a new object will be created.
username (Optional[str]) – The username. Max 32 characters. Required if obj is not passed.
avatar_url (Optional[str]) – The avatar URL. Required if obj is not passed.
discriminator (Optional[int]) – The discriminator to use. Required if obj is not passed.
level (Optional[int]) – The level. Required if obj is not passed.
current_xp (Optional[int]) – The current XP. Required if obj is not passed.
needed_xp (Optional[int]) – The needed XP. Required if obj is not passed.
background_url (Optional[str]) – The background URL. Cannot be used with background_color.
background_color (Optional[str]) – The background color hex. Cannot be used with background_url.
text_color (Optional[str]) – The text color hex.
current_xp_color (Optional[str]) – The current XP color hex.
xp_bar_color (Optional[str]) – The XP bar color hex.
username_color (Optional[str]) – The username color hex.

Return type:

Rankcard

async welcome_image(obj=..., *, template=..., type=..., username=..., avatar_url=..., discriminator=..., server_name=..., member_count=..., text_color=..., background_url=..., font=...)[source]¶

Generate a custom welcome image.

Parameters:

obj (Optional[WelcomePremium]) – The object to use. If not passed, the other parameters will be used and a new object will be created.
template (Optional[Literal[1, 2, 3, 4, 5, 6, 7]`) – The template to use. Must be a number between 1 and 7. Required if obj is not passed.
type (Optional[WelcomeType]) – The type of welcome card. Required if obj is not passed.
username (Optional[str]) – The username. Required if obj is not passed.
avatar_url (Optional[str]) – The avatar URL. Required if obj is not passed.
discriminator (Optional[int]) – The discriminator to use.
server_name (Optional[str]) – The server name. Required if obj is not passed.
member_count (Optional[int]) – The member count. Required if obj is not passed.
text_color (Optional[WelcomeTextColor]) – The text color. Required if obj is not passed.
background_url (Optional[str]) – The background URL.
font (Optional[int]) –
The font from a predefined list. Choose a number between 0 and 7.

Changed in version 0.1.0: This takes a range of 0-7 now instead of 0-8.

Return type:

WelcomePremium

Canvas¶

CanvasClient

class somerandomapi.CanvasClient[source]¶

Represents the Canvas endpoint.

This class is not meant to be instantiated by you. Instead, access it through the canvas attribute of the Client.

blue_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.BLUE.

Return type:: Image

blur_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.BLUR.

Return type:: Image

blurple2_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.BLURPLE_2.

Return type:: Image

blurple_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.BLURPLE.

Return type:: Image

async border(avatar_url, border)[source]¶

Add a border to an image.

Parameters:

avatar_url (str) – The avatar URL.
border (Union[CanvasBorder, str]) – The border to add.

Returns:

The filtered image.

Return type:

Image

async brightness_filter(avatar_url, brightness=None)[source]¶

Apply a brightness filter to an image.

Parameters:

avatar_url (str) – The URL of the image to apply the filter to.
brightness (int) – The brightness value. Must be between 0 and 100. Defaults to a random number between 0 and 100.

Returns:

Object representing the filtered image. Use the .url attribute to access the image URL.

Return type:

Image

async color_filter(avatar_url, color=...)[source]¶

Apply a color filter to an image.

Parameters:

avatar_url (str) – The URL of the image to apply the filter to.
color (Union[str, int]) – The color to apply. Can be a hex value (e.g. #FF0000) or an integer (e.g. 16711680). Defaults to a random color.

Returns:

Object representing the filtered image. Use the .url attribute to access the image URL.

Return type:

Image

async color_viewer(color=...)[source]¶

Get a color as an image.

Parameters:: color (str) – The hex value to get. Defaults to a random color.
Returns:: The color as an image. Use the .url attribute to access the image URL.
Return type:: Image

async colour_filter(avatar_url, colour)[source]¶

Alias for color_filter().

Return type:: Image

async colour_viewer(colour=...)[source]¶

Alias for color_viewer().

Return type:: Image

async crop(avatar_url, shape)[source]¶

Crop an image into various shapes.

Parameters:

avatar_url (str) – The avatar URL.
shape (CanvasCrop) – The shape to apply.

Returns:

The filtered image.

Return type:

Image

async filter(avatar_url, filter)[source]¶

Apply a filter to an image.

Parameters:

avatar_url (str) – The URL of the image to apply the filter to.
filter (Union[CanvasFilter, str]) – The filter to apply. Can be a CanvasFilter enum value or a string representing the filter name.

Returns:

Object representing the filtered image. Use the .url attribute to access the image URL.

Return type:

Image

async generate_genshin_namecard(obj=..., *, avatar_url=..., birthday=..., username=..., description=...)[source]¶

Generate a Genshin Impact namecard.

Parameters:

obj (GenshinNamecard) – The object to use. If not provided, a new object will be created with the other parameters.
avatar_url (str) – The avatar URL.
birthday (str) – The birthday. Must be in the format MM/DD/YYYY.
username (str) – The username.
description (Optional[str]) – An optional description.

Raises:

TypeError – If obj is not a GenshinNamecard.
ValueError – If avatar_url, birthday and username``are not provided and ``obj is not passed.

Returns:

An object representing the generated Genshin Impact namecard. Use the .url attribute to access the image URL.

Return type:

GenshinNamecard

async generate_simpcard(avatar_url)[source]¶

Generate a simpcard.

Parameters:: avatar_url (str) – The avatar URL.
Returns:: The simpcard.
Return type:: Image

async generate_tweet(obj=..., *, display_name=..., username=..., avatar_url=..., text=..., replies=..., retweets=..., likes=..., theme=TweetTheme.LIGHT)[source]¶

Generate an image of a tweet (or post …).

Parameters:

obj (Tweet) – The object to use. If not provided, one will be created with the other parameters.
display_name (str) – The display name of the user.
username (str) – The username of the user.
avatar_url (str) – The avatar URL of the user. Must be .png or .jpg.
text (str) – The text of the tweet. Max 1000 characters.
replies (Optional[int]) – The amount of replies the tweet is supposed to have.
retweets (Optional[int]) – The amount of retweets the tweet is supposed to have.
likes (Optional[int]) – The amount of likes the tweet is supposed to have.
theme (TweetTheme) – The theme of the tweet. Can be either light, dark or dim. Defaults to light.

Raises:

TypeError – If obj is not a Tweet.
ValueError – If display_name, username, avatar_url and text are not provided and obj is not passed.

Returns:

An object representing the generated tweet image. Use the .url attribute to access the image URL.

Return type:

Tweet

async generate_youtube_comment(obj=..., *, avatar_url=..., username=..., text=...)[source]¶

Generate a Youtube comment image.

Parameters:

obj (YoutubeComment) – The object to use. If not provided, a new object will be created with the other parameters.
avatar_url (str) – The avatar URL of the user.
username (str) – The username of the user.
text (str) – The text of the comment.

Raises:

TypeError – If obj is not a YoutubeComment.
ValueError – If avatar_url, username and comment are not provided and obj is not passed.

Returns:

An object representing the generated Youtube comment image. Use the .url attribute to access the image URL.

Return type:

YoutubeComment

green_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.GREEN.

Return type:: Image

greyscale_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.GREYSCALE.

Return type:: Image

invert_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.INVERT.

Return type:: Image

invertgreyscale_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.INVERT_GREYSCALE.

Return type:: Image

property memes¶

Returns a subclient for the memes endpoints.

Type:: CanvasMemes

async overlay(avatar_url, overlay)[source]¶

Add an overlay to an image.

Parameters:

avatar_url (str) – The URL of the image to apply the overlay to.
overlay (Union[CanvasOverlay, str]) – The overlay to apply. Can be a CanvasOverlay enum value or a string representing the overlay name.

Returns:

Object representing the image with the overlay applied. Use the .url attribute to access the image URL.

Return type:

Image

pixelate_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.PIXELATE.

Return type:: Image

red_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.RED.

Return type:: Image

sepia_filter(avatar_url, /)[source]¶

Shortcut for filter() with CanvasFilter.SEPIA.

Return type:: Image

async threshold_filter(avatar_url, threshold=None)[source]¶

Apply a threshold filter to an image.

Parameters:

avatar_url (str) – The URL of the image to apply the filter to.
threshold (int) – The threshold value. Must be between 0 and 255. Defaults to a random number between 1 and 255.

Returns:

Object representing the filtered image. Use the .url attribute to access the image URL.

Return type:

Image

CanvasMemes

class somerandomapi.CanvasMemes[source]¶

A class for interacting with the Canvas memes endpoints.

This class is not meant to be instantiated by the user. Instead, access it through the memes attribute of the CanvasClient class.

async horny(avatar_url)[source]¶

Horny meme.

Parameters:: avatar_url (str) – The avatar URL.
Returns:: Object representing the generated image.
Return type:: Image

async its_so_stupid(avatar_url)[source]¶

It’s so stupid meme.

Parameters:: avatar_url (str) – The avatar URL.
Returns:: Object representing the generated image.
Return type:: Image

async lied(avatar_url, username)[source]¶

Lied meme.

Parameters:

avatar_url (str) – The avatar URL.
username (str) – The username.

Returns:

Object representing the generated image.

Return type:

Image

async lolice(avatar_url)[source]¶

Lolice meme.

Parameters:: avatar_url (str) – The avatar URL.
Returns:: Object representing the generated image.
Return type:: Image

async no_bitches(*, avatar_url, no, bottom_text=None)[source]¶

No bitches meme.

Parameters:

avatar_url (str) – The avatar URL.
no (str) – no?
bottom_text (str) –
The text to display at the bottom of the image. Defaults to nothing.

Added in version 0.1.2.

Returns:

Object representing the generated image.

Return type:

Image

async oogway(quote)[source]¶

Get an image of Oogway saying a quote.

Parameters:: quote (str) – The quote to say.
Returns:: Object representing the generated image.
Return type:: Image

async oogway2(quote)[source]¶

Get an image of Oogway saying a quote.

Parameters:: quote (str) – The quote to say.
Returns:: Object representing the generated image.
Return type:: Image

async tonikawa(avatar_url)[source]¶

Tonikawa meme.

Parameters:: avatar_url (str) – The avatar URL.
Returns:: Object representing the generated image.
Return type:: Image