➕📝 Added validation of tokens and updated readme.md

Author: benjhar

README.md

@@ -10,8 +10,6 @@ while also maintaining a readable codebase.
 
 You can install jokeapi through [pip](https://pypi.org/project/pip/) by using `pip install jokeapi`
 
-So far there are no build from source instructions.
-
 ---
 
 # get_joke
@@ -29,7 +27,8 @@ interact with one function. This function is `get_joke()`
   from jokeapi import Jokes # Import the Jokes class
 
   j = Jokes()  # Initialise the class
-  j.get_joke()  # Retrieve a random joke
+  joke = j.get_joke(type="single", response_format="txt")  # Retrieve a random joke
+  print(joke)
 ```
 
 ### Parameters
@@ -129,15 +128,66 @@ If left blank it will default to `None`
 
 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.
+should be minimum 0. Maximum value can be determined [here](https://sv443.net/jokeapi/v2/info)
 
 If left blank it will default to the maximum range.
 
 
 #### Example
 
 ```python
-  joke = get_joke(id_range=[10,100])  # Will return a joke with the ID between 10 and 100
+  joke = 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
+
+```python
+  joke = 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
+
+```python
+  joke = 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
+
+```python
+  response = 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}")
 ```
 
 ---
@@ -237,7 +287,7 @@ If not, feel free to ask me through one of the channels provided below.
 
 Developer contact:
 
-[Discord](https://discord.gg/mB989eP)
+![Discord](https://discord.com/assets/07dca80a102d4149e9736d4b162cff6f.ico)[**Discord**](https://discord.gg/mB989eP)
 
 [Issue Tracker](https://github.com/thenamesweretakenalready/Sv443s-JokeAPI-Python-Wrapper/issues)
 

jokeapi/main.py

@@ -131,26 +131,24 @@ def build_request(
         return r
 
     def send_request(self, request, response_format, return_headers, auth_token, user_agent):
+        returns = []
+
         if auth_token:
             r = self.http.request('GET', request, headers={'Authorization': str(
                 auth_token), 'user-agent': str(user_agent)})
         else:
             r = self.http.request('GET', request, headers={'user-agent': str(user_agent)})
 
+        headers = r.headers
+        returns.append(r.data)
+
         if return_headers:
-            if response_format == "json":
-                return r.data, r.headers
-            elif response_format == "xml":
-                return r.data, r.headers
-            else:
-                return r.data, r.headers
-        else:
-            if response_format == "json":
-                return r.data
-            elif response_format == "xml":
-                return r.data
-            else:
-                return r.data
+            returns.append(headers)
+
+        if not headers["Token-Valid"]:
+            returns.append({"Token-Valid": False})
+
+        return returns
 
     def get_joke(
         self,

setup.py

@@ -6,15 +6,15 @@
 setuptools.setup(
     name="jokeapi",
     packages=["jokeapi"],
-    version="0.2.1",
+    version="0.2.2",
     license="GNU General Public License v3 (GPLv3)",
     description="An API Wrapper for Sv443's JokeAPI",
     long_description=long_description,
     long_description_content_type="text/markdown",
     author="thenamesweretakenalready",
     author_email="[email protected]",
     url="""https://github.com/thenamesweretakenalready/Sv443s-JokeAPI-Python-Wrapper""",
-    download_url="https://github.com/user/Sv443s-JokeAPI-Python-Wrapper/archive/v0.1.5.tar.gz",
+    download_url="https://github.com/user/Sv443s-JokeAPI-Python-Wrapper/archive/v0.2.2.tar.gz",
     keywords=["api wrapper", "wrapper", "api", "jokes", "python", "joke api"],
     install_requires=setuptools.find_packages(),
     classifiers=[