_____                   _______                   _____                    _____                    _____
         /\    \                 /::\    \                 /\    \                  /\    \                  /\    \
        /::\    \               /::::\    \               /::\____\                /::\    \                /::\    \
        \:::\    \             /::::::\    \             /:::/    /               /::::\    \              /::::\    \
         \:::\    \           /::::::::\    \           /:::/    /               /::::::\    \            /::::::\    \
          \:::\    \         /:::/~~\:::\    \         /:::/    /               /:::/\:::\    \          /:::/\:::\    \
           \:::\    \       /:::/    \:::\    \       /:::/____/               /:::/__\:::\    \        /:::/__\:::\    \
           /::::\    \     /:::/    / \:::\    \     /::::\    \              /::::\   \:::\    \       \:::\   \:::\    \
  _____   /::::::\    \   /:::/____/   \:::\____\   /::::::\____\________    /::::::\   \:::\    \    ___\:::\   \:::\    \
 /\    \ /:::/\:::\    \ |:::|    |     |:::|    | /:::/\:::::::::::\    \  /:::/\:::\   \:::\    \  /\   \:::\   \:::\    \
/::\    /:::/  \:::\____\|:::|____|     |:::|    |/:::/  |:::::::::::\____\/:::/__\:::\   \:::\____\/::\   \:::\   \:::\____\
/\:::\  /:::/    \::/    / \:::\    \   /:::/    / \::/   |::|~~~|~~~~~     \:::\   \:::\   \::/    /\:::\   \:::\   \::/    /
 \:::\/:::/    / \/____/   \:::\    \ /:::/    /   \/____|::|   |           \:::\   \:::\   \/____/  \:::\   \:::\   \/____/
  \::::::/    /             \:::\    /:::/    /          |::|   |            \:::\   \:::\    \       \:::\   \:::\    \
   \::::/    /               \:::\__/:::/    /           |::|   |             \:::\   \:::\____\       \:::\   \:::\____\
    \::/    /                 \::::::::/    /            |::|   |              \:::\   \::/    /        \:::\  /:::/    /
     \/____/                   \::::::/    /             |::|   |               \:::\   \/____/          \:::\/:::/    /
                                \::::/    /              |::|   |                \:::\    \               \::::::/    /
                                 \::/____/               \::|   |                 \:::\____\               \::::/    /
                                  ~~                      \:|   |                  \::/    /                \::/    /
                                                           \|___|                   \/____/                  \/____/

A small CLI app for fetching and displaying jokes on your terminal 🤡

Jokes are taken from the public JokeAPI. A lot of the jokes on there are VERY dark and likely to be insulting. It is possible to filter out some of the gutter humor (but why tho? gutter humor is the best humor). To filter jokes, see the flag section.

Jokes has three dependencies that will have to be installed prior to running locally.

1. poetry
2. pre-commit
3. just

Once all three have been installed, clone this repo and "cd" your way into the created folder, e.g. cd jokes.

To setup the environment run just setup, and activate the virtual environment created by poetry with poetry shell.

You should now be able to run the jokes command. Try it out by running jokes get.

There are a few arguments you can use when calling jokes.

Example: jokes get -c Any or jokes get --category Any

Default: Any

The category tag will specify which category your joke will be in. Use jokes get --help to see available categories.

Example: jokes get -t Single or jokes get --type Single

Default: Random

Choose the type of joke, either a single oneliner or a two-parter. Use jokes get --help to see available types.

Example: jokes get -f nsfw -f explicit or jokes get --flag nsfw

Default: []

The flag option can be used once, multiple times, or not at all. It is used to try to filter out unwanted jokes. But it isn't an exact science, so don't be surprised if it doesn't filter out everything.

Use jokes get --help to see available flags.

Example: jokes get -l fr or jokes get --lang fr

Default: EN (English)

Choose the language you want your joke to be in. Choice must be in the ISO 639-1 format. Current supported languages are English, French, Portuguese, Czech, Spanish, and German.

Note that the option does not translate the jokes but filters jokes that have been submitted in the desired language.

Example: jokes get --safe or jokes get --unsafe

Default: unsafe

If you use the safe option, the API will attempt to filter out any offensive, dark, or insulting jokes. Be warned that some gutter humor may work its way through the filtering, but it's unlikely.

The ability to submit a joke to the Joke API with this CLI is currently under construction 🛠️. The code has been written but it hasn't been possible to test since the Joke API has temporarily disabled joke submissions at this time.

Example: jokes --debug

Default: Off

Debug is turned off by default but can be turned on using the debug flag.

Errors are typically returned as "An unexpected error occurred." If you wish to see more information about the nature of the error, use the debug flag. This is only intended for development purposes.

Tests are written in pytest and can be called using either just test while the virtual environemnt is activated.