|
1 | | -# Sv443-s-JokeAPI-Python-Wrapper |
| 1 | +# Sv443's Joke API Wrapper |
2 | 2 |
|
3 | | -Just frickin |
| 3 | +[](https://pepy.tech/downloads/jokeapi) |
| 4 | +[](https://circleci.com/gh/thenamesweretakenalready/Sv443s-JokeAPI-Python-Wrapper) |
| 5 | + |
| 6 | +An API wrapper for Sv443's joke api which provides simple yet versatile functionality, |
| 7 | +while also maintaining a readable codebase. |
| 8 | + |
| 9 | +## Install |
| 10 | + |
| 11 | +You can install jokeapi through [pip](https://pypi.org/project/pip/) by using `pip install jokeapi` |
| 12 | + |
| 13 | +So far there are no build from source instructions. |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +# get_joke |
| 18 | + |
| 19 | +The wrapper is structured in such a way that the end-user should only ever have to |
| 20 | +interact with one function. This function is `get_joke()` |
| 21 | + |
| 22 | +--- |
| 23 | + |
| 24 | +## get_joke |
| 25 | + |
| 26 | +### Example |
| 27 | + |
| 28 | +```python |
| 29 | + from jokeapi import Jokes # Import the Jokes class |
| 30 | + |
| 31 | + j = Jokes() # Initialise the class |
| 32 | + j.get_joke() # Retrieve a random joke |
| 33 | +``` |
| 34 | + |
| 35 | +### Parameters |
| 36 | + |
| 37 | +--- |
| 38 | + |
| 39 | +#### category |
| 40 | + |
| 41 | +A list of categories that the returned joke should fit in. |
| 42 | +Options are: |
| 43 | +`programming`, |
| 44 | +`miscellaneous`, |
| 45 | +`dark` |
| 46 | + |
| 47 | +If left blank it will default to use `Any`. |
| 48 | + |
| 49 | +##### Example |
4 | 50 |
|
5 | 51 | ```python |
6 | | - from jokeapi import Jokes |
| 52 | + joke = get_joke(categories=['programming', 'dark']) # Will return a joke that fits in either the programming or dark category. |
| 53 | +``` |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +#### blacklist |
| 58 | + |
| 59 | +A list of properties that the joke *shouldn't* have. |
| 60 | +Options are: |
| 61 | +`nsfw`, |
| 62 | +`religious`, |
| 63 | +`political`, |
| 64 | +`racist`, |
| 65 | +`sexist` |
| 66 | + |
| 67 | +If left blank it will default to `None`. |
| 68 | + |
| 69 | +##### Example |
| 70 | + |
| 71 | +```python |
| 72 | + joke = get_joke(blacklist=['nsfw', 'racist']) # Will return a joke that does not have either the flag "nsfw" or "racist". |
| 73 | +``` |
| 74 | + |
| 75 | +--- |
7 | 76 |
|
8 | | - j = Jokes() |
9 | | - joke = j.get_joke() |
10 | | - print(joke) |
| 77 | +#### response_format |
| 78 | + |
| 79 | +The format in which the API should respond. |
| 80 | +Options are: |
| 81 | +`json`, |
| 82 | +`yaml`, |
| 83 | +`xml` |
| 84 | + |
| 85 | +If left blank it will default to `json`. |
| 86 | + |
| 87 | +#### Example |
| 88 | + |
| 89 | +```python |
| 90 | + joke = get_joke(response_format="xml") # Will return a joke in xml format. |
11 | 91 | ``` |
12 | | -bam you got yourself a joke |
13 | 92 |
|
14 | | -The `get_joke()` function has multiple optional parameters: |
| 93 | +--- |
15 | 94 |
|
| 95 | +### type |
| 96 | + |
| 97 | +The type of joke returned. |
| 98 | +Options are: |
| 99 | +`single`, |
| 100 | +`twopart` |
| 101 | + |
| 102 | +If left blank it will default to `Any` |
| 103 | + |
| 104 | +#### Example |
| 105 | + |
| 106 | +```python |
| 107 | + joke = get_joke(type="twopart") # Will return a twopart joke; both a setup and a delivery. |
| 108 | +``` |
| 109 | + |
| 110 | +--- |
| 111 | + |
| 112 | +### search_string |
| 113 | + |
| 114 | +A string to search for in jokes. |
| 115 | + |
| 116 | +If left blank it will default to `None` |
| 117 | + |
| 118 | +#### Example |
| 119 | + |
| 120 | +```python |
| 121 | + joke = get_joke(search_string="the") # Will return a joke with the word "the" in it. |
| 122 | + # If there are no jokes then it will return the error from the API. |
| 123 | +``` |
| 124 | + |
| 125 | +--- |
| 126 | + |
| 127 | +### id_range |
| 128 | + |
| 129 | +The range in which the selected joke should fall. ID's are decided by the order in which jokes are submitted. |
| 130 | +The argument passes should be in form of list or tuple, and should not exceed length of 2 items. First item |
| 131 | +should be minimum 0. |
| 132 | + |
| 133 | +If left blank it will default to the maximum range. |
| 134 | + |
| 135 | + |
| 136 | +#### Example |
| 137 | + |
| 138 | +```python |
| 139 | + joke = get_joke(id_range=[10,100]) # Will return a joke with the ID between 10 and 100 |
| 140 | +``` |
| 141 | + |
| 142 | +--- |
| 143 | + |
| 144 | +## Returns |
| 145 | + |
| 146 | +Depending on what format is chosen different things will be returned. |
| 147 | + |
| 148 | + |
| 149 | +### json |
| 150 | + |
| 151 | +A succesful API call will return: |
| 152 | + |
| 153 | +```python |
| 154 | + { |
| 155 | + "category": "Miscellaneous", |
| 156 | + "type": "twopart", |
| 157 | + "setup": "I told my psychiatrist I got suicidal tendencies.", |
| 158 | + "delivery": "He said from now on I have to pay in advance.", |
| 159 | + "flags": { |
| 160 | + "nsfw": false, |
| 161 | + "religious": false, |
| 162 | + "political": false, |
| 163 | + "racist": false, |
| 164 | + "sexist": false |
| 165 | + }, |
| 166 | + "id": 94, |
| 167 | + "error": false |
| 168 | + } |
| 169 | +``` |
| 170 | + |
| 171 | + |
| 172 | +### xml |
| 173 | + |
| 174 | +A succesful API call will return: |
| 175 | + |
| 176 | +```python |
| 177 | +<?xml version='1.0'?> |
| 178 | +<data> |
| 179 | + <category>Dark</category> |
| 180 | + <type>single</type> |
| 181 | + <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> |
| 182 | + <flags> |
| 183 | + <nsfw>false</nsfw> |
| 184 | + <religious>false</religious> |
| 185 | + <political>false</political> |
| 186 | + <racist>false</racist> |
| 187 | + <sexist>false</sexist> |
| 188 | + </flags> |
| 189 | + <id>154</id> |
| 190 | + <error>false</error> |
| 191 | +</data> |
| 192 | +``` |
| 193 | + |
| 194 | + |
| 195 | +### yaml |
| 196 | + |
| 197 | +A succesful API call will return: |
| 198 | + |
| 199 | +```python |
| 200 | +category: "Programming" |
| 201 | +type: "single" |
| 202 | +joke: "Your momma is so fat, you need to switch to NTFS to store a picture of her." |
| 203 | +flags: |
| 204 | + nsfw: false |
| 205 | + religious: false |
| 206 | + political: false |
| 207 | + racist: false |
| 208 | + sexist: false |
| 209 | +id: 56 |
| 210 | +error: false |
| 211 | +``` |
16 | 212 |
|
17 | | -`category` - a list of categories the joke should fit in. Possible entries are "Programming", "Miscellaneous" and "Dark". Leave blank for any. |
| 213 | +--- |
18 | 214 |
|
19 | | -`blacklist` - a list of things you don't *really* want to see. Maybe you're babysitting. Possible entries are "nsfw", "religious", "political", "racist" and "sexist" |
| 215 | +## Errors |
20 | 216 |
|
21 | | -`response_format` - a string which describes what format you want your response in. Default is json, and it will return a dict. Other options are "xml" and "yaml" |
| 217 | +The wrapper can raise multiple different errors depending on what you did wrong. |
22 | 218 |
|
23 | | -`type` - what type of joke it is. Defaults to use either. Possible options are "single" and "twopart" |
| 219 | +### ValueErrors will always be raised with expected errors. |
24 | 220 |
|
25 | | -`search_string` - string to search for in jokes. Defaults to None |
| 221 | +The errors are descriptive enough that you should be able to solve them with the information provided in the error message. |
| 222 | +If not, feel free to ask me through one of the channels provided below. |
26 | 223 |
|
27 | | -`id_range` - a list (which should only contain two items) which describes the range in which to search for jokes, by joke id. |
| 224 | +--- |
28 | 225 |
|
| 226 | +Developer contact: |
| 227 | +[Discord](https://discord.gg/mB989eP) |
| 228 | +[Issue Tracker](https://github.com/thenamesweretakenalready/Sv443s-JokeAPI-Python-Wrapper/issues) |
| 229 | +[e-mail](mailto:leet_haker@cyber-wizard.com) |
| 230 | +[Twitter](https://twitter.com/HakkerLeet) |
0 commit comments