Sv443's Joke API Wrapper
Install
You can install jokeapi through pip by using pip install jokeapi
get_joke
The wrapper is structured in such a way that the end-user should only ever have to
interact with one function to get a joke. This function is get_joke().
Please note that urllib3, the core dependency of this wrapper automatically abides by
Retry-After headers, which means you may have to wait a long time for a joke if you
have made a lot of requests recently
submit_joke
The wrapper also provides simple access to the submit endpoint through the submit_joke()
function.
Note that joke submissions are manually checked and you will be ratelimited.
get_joke
Example
import asyncio
async def print_joke():
j = await Jokes() # Initialise the class
joke = await j.get_joke() # Retrieve a random joke
if joke["type"] == "single": # Print the joke
print(joke["joke"])
else:
print(joke["setup"])
print(joke["delivery"])
asyncio.run(print_joke())
Parameters
category
A list of categories that the returned joke should fit in.
Options are:
programming,
miscellaneous,
dark,
pun
If left blank it will default to use Any.
Example
blacklist
A list of properties that the joke shouldn't have.
Options are:
nsfw,
religious,
political,
racist,
sexist
If left blank it will default to None.
Example
response_format
The format in which the API should respond.
Options are:
json,
yaml,
xml,
txt
If left blank it will default to json.
Example
joke_type
The type of joke returned.
Options are:
single,
twopart,
Any
If left blank it will default to Any
Example
search_string
A string to search for in jokes.
If left blank it will default to None
Example
# If there are no jokes then it will return the error from the API.
id_range
The range in which the selected joke should fall. ID's are decided by the order in which jokes are submitted. The argument passes should be in form of list or tuple, and should not exceed length of 2 items. First item should be minimum 0. Maximum value can be determined here
If left blank it will default to the maximum range.
Example
amount
The amount of jokes you want the api to return. Will return them in a list. Maximum number is 10 jokes, and the api defaults to 1 if you use a number larger than the maximum. Defaults to 1.
Example
lang
The language that the joke and response should be in. Currently supported languages are in the official api documentation. Defaults to en.
Example
auth_token
A string token provided by the api owner. Using it will mean you are whitelisted by the api and can make more requests than normal users. Defaults to None
Example
user_agent
A string sent the the api that tells the api what browser you are (pretending to be). The default user agent is Mozilla Firefox from Windows 10 and should work fine, but the functionality is provided in case you wish to change it
Example
# This is in fact the default user agent, and tells the API that we are visitng the page from a Firefox 77.0
# browser using Windows 10 64bit.
return_headers
A boolean value (True or False) that tells the wrapper if you wish to receive headers in the return from the function. Will return a list instead of a single value Defaults to False.
Example
joke = response[0]
headers = response[1]
print(f"Joke: {joke}")
print(f"Headers: {headers}")
Returns
Depending on what format is chosen different things will be returned.
json
A succesful API call will return:
"category": "Miscellaneous",
"type": "twopart",
"setup": "I told my psychiatrist I got suicidal tendencies.",
"delivery": "He said from now on I have to pay in advance.",
"flags": {
"nsfw": false,
"religious": false,
"political": false,
"racist": false,
"sexist": false
},
"id": 94,
"error": false
}
xml
A succesful API call will return:
<data>
<category>Darkcategory>
<type>singletype>
<joke>My ex had an accident. I told the paramedics the wrong blood type for her. She'll finally experience what rejection is really like.joke>
<flags>
<nsfw>falsensfw>
<religious>falsereligious>
<political>falsepolitical>
<racist>falseracist>
<sexist>falsesexist>
flags>
<id>154id>
<error>falseerror>
data>
yaml
A succesful API call will return:
type: "single"
joke: "Your momma is so fat, you need to switch to NTFS to store a picture of her."
flags:
nsfw: false
religious: false
political: false
racist: false
sexist: false
id: 56
error: false
txt
A succesful API call will return:
Why does no one like SQLrillex?
He keeps dropping the database.
Errors
The wrapper can raise multiple different errors depending on what you did wrong.
The errors are descriptive enough that you should be able to solve them with the information provided in the error message. If not, feel free to ask me through one of the channels provided below.
submit_joke
Example
import asyncio
async def submit_new_joke():
j = await Jokes()
await j.submit_joke("Miscellaneous", "funny haha", {
"nsfw": False,
"religious": False,
"political": False,
"racist": False,
"sexist": False
}, lang="de")
asyncio.run(submit_new_joke())
Parameters
category
The category the joke is.
Options are:
programming,
miscellaneous,
dark,
pun
Has no default value.
joke
The joke itself. Can either be a single string or a list/tuple, for the setup and delivery. Setup should be at index 0 in the tuple, delivery at 1.
Has no default value.
flags
The flags that the joke should have.
Options are:
nsfw,
religious,
political,
racist,
sexist
Has no default value.
lang
The language code for the language the joke it written in. E.g en for english, de for german.
Defaults to en