Package: jokeapi
Sv443's Joke API WrapperAn API wrapper for Sv443's joke api which provides simple yet versatile functionality,
while also maintaining a readable codebase.InstallYou can install jokeapi throughpipby usingpip install jokeapiget_jokeThe 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 isget_joke().Please note that urllib3, the core dependency of this wrapper automatically abides byRetry-Afterheaders, which means you may have to wait a long time for a joke if you
have made a lot of requests recentlysubmit_jokeThe wrapper also provides simple access to the submit endpoint through thesubmit_joke()function.Note that joke submissions are manually checked and you will be ratelimited.get_jokeExamplefromjokeapiimportJokes# Import the Jokes classimportasyncioasyncdefprint_joke():j=awaitJokes()# Initialise the classjoke=awaitj.get_joke()# Retrieve a random jokeifjoke["type"]=="single":# Print the jokeprint(joke["joke"])else:print(joke["setup"])print(joke["delivery"])asyncio.run(print_joke())ParameterscategoryA list of categories that the returned joke should fit in.
Options are:programming,miscellaneous,dark,punIf left blank it will default to useAny.Examplejoke=awaitj.get_joke(category=['programming','dark'])# Will return a joke that fits in either the programming or dark category.blacklistA list of properties that the jokeshouldn'thave.
Options are:nsfw,religious,political,racist,sexistIf left blank it will default toNone.Examplejoke=awaitj.get_joke(blacklist=['nsfw','racist'])# Will return a joke that does not have either the flag "nsfw" or "racist".response_formatThe format in which the API should respond.
Options are:json,yaml,xml,txtIf left blank it will default tojson.Examplejoke=awaitj.get_joke(response_format="xml")# Will return a joke in xml format.joke_typeThe type of joke returned.
Options are:single,twopart,AnyIf left blank it will default toAnyExamplejoke=awaitj.get_joke(joke_type="twopart")# Will return a twopart joke; both a setup and a delivery.search_stringA string to search for in jokes.If left blank it will default toNoneExamplejoke=awaitj.get_joke(search_string="the")# Will return a joke with the word "the" in it.# If there are no jokes then it will return the error from the API.id_rangeThe 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 determinedhereIf left blank it will default to the maximum range.Examplejoke=awaitj.get_joke(id_range=[10,100])# Will return a joke with the ID between 10 and 100.amountThe 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.Examplejoke=awaitj.get_joke(amount=2)# Will return 2 jokes.langThe language that the joke and response should be in. Currently supported languages are in the official api
documentation. Defaults to en.Examplejoke=awaitj.get_joke(lang="de")auth_tokenA 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 NoneExamplejoke=awaitj.get_joke(auth_token="aaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbb")# Will send the token to the api in a header.user_agentA 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 itExamplejoke=awaitj.get_joke(user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:77.0) Gecko/20100101 Firefox/77.0")# 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_headersA 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.Exampleresponse=awaitj.get_joke(return_headers=True)joke=response[0]headers=response[1]print(f"Joke:{joke}")print(f"Headers:{headers}")ReturnsDepending on what format is chosen different things will be returned.jsonA 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}xmlA succesful API call will return:<?xml version='1.0'?><data><category>Dark</category><type>single</type><joke>Myexhadanaccident.Itoldtheparamedicsthewrongbloodtypeforher.She'llfinallyexperiencewhatrejectionisreallylike.</joke><flags><nsfw>false</nsfw><religious>false</religious><political>false</political><racist>false</racist><sexist>false</sexist></flags><id>154</id><error>false</error></data>yamlA succesful API call will return:category:"Programming"type:"single"joke:"Yourmommaissofat,youneedtoswitchtoNTFStostoreapictureofher."flags:nsfw:falsereligious:falsepolitical:falseracist:falsesexist:falseid:56error:falsetxtA succesful API call will return:Why does no one like SQLrillex?

He keeps dropping the database.ErrorsThe 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_jokeExamplefromjokeapiimportJokesimportasyncioasyncdefsubmit_new_joke():j=awaitJokes()awaitj.submit_joke("Miscellaneous","funny haha",{"nsfw":False,"religious":False,"political":False,"racist":False,"sexist":False},lang="de")asyncio.run(submit_new_joke())ParameterscategoryThe category the joke is.
Options are:programming,miscellaneous,dark,punHas no default value.jokeThe 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.flagsThe flags that the joke should have.
Options are:nsfw,religious,political,racist,sexistHas no default value.langThe language code for the language the joke it written in. E.g en for english,
de for german.Defaults toenContributorsThatCopy27994f701b578ckdiri3e20cd13b6a2a6Developer contactDiscordIssue Trackere-mail