Skip to main content

Sv443's Joke API Wrapper

Downloads Downloads Downloads CircleCI

An API wrapper for Sv443's joke api which provides simple yet versatile functionality, while also maintaining a readable codebase.

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. 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


get_joke

Example

  from jokeapi import Jokes # Import the Jokes class

  j = Jokes()  # Initialise the class
  joke = j.get_joke()[0]  # Retrieve a random joke
  if joke["type"] == "single": # Print the joke
    print(joke["joke"])
  else:
    print(joke["setup"])
    print(joke["delivery"])

Parameters


category

A list of categories that the returned joke should fit in. Options are: programming, miscellaneous, dark

If left blank it will default to use Any.

Example
  joke = j.get_joke(category=['programming', 'dark'])  # Will return a joke that fits in either the programming or dark category.

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
  joke = j.get_joke(blacklist=['nsfw', 'racist'])  # Will return a joke that does not have either the flag "nsfw" or "racist".

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 = j.get_joke(response_format="xml")  # Will return a joke in xml format.

type

The type of joke returned. Options are: single, twopart

If left blank it will default to Any

Example

  joke = j.get_joke(type="twopart")  # Will return a twopart joke; both a setup and a delivery.

search_string

A string to search for in jokes.

If left blank it will default to None

Example

  joke = j.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_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

  joke = j.get_joke(id_range=[10,100])  # Will return a joke with the ID between 10 and 100.

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

  joke = j.get_joke(auth_token="aaaaaaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbb") # Will send the token to the api in a header.

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

  joke = j.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_headers

A boolean value (True or False) that tells the wrapper if you wish to receive headers in the return from the function. Defaults to False.

Example

  response = j.get_joke(return_headers=True)
  joke = response[0]
  headers = response[1]
  # The function returns the joke and then the headers using the "return x, y" syntax, so you can index it like a list or tuple.

  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:

<?xml version='1.0'?>
<data>
    <category>Dark</category>
    <type>single</type>
    <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>false</nsfw>
        <religious>false</religious>
        <political>false</political>
        <racist>false</racist>
        <sexist>false</sexist>
    </flags>
    <id>154</id>
    <error>false</error>
</data>

yaml

A succesful API call will return:

category: "Programming"
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.


Developer contact:

DiscordDiscord

Issue Tracker

e-mail

Twitter

Metadata

Release files for jokeapi 0.2.5.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jokeapi 0.2.5.2
File Size Uploaded Provenance Actions
jokeapi-0.2.5.2.tar.gz 7.5 kB Without provenance Details for jokeapi-0.2.5.2.tar.gz

Release files / jokeapi-0.2.5.2.tar.gz

Download URL jokeapi-0.2.5.2.tar.gz
Size 7.5 kB
Tags Source
SHA-256 checksum
How to use checksums
f94a94fef8f893075eed4cd795cdf53a78f4ea00d713df83d3e7d3adf424e0d2
BLAKE2b-256 checksum
How to use checksums
846da490f4d84d8825a4511601dece908586054a44a3e2762e8e99bd5aa8e7c5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.0.0 requests-toolbelt/0.9.1 tqdm/4.48.2 CPython/3.8.5

Security for jokeapi 0.2.5.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page