adding type hints

.readthedocs.yaml

@@ -0,0 +1,8 @@
+version: 2
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/requirements.txt

@@ -0,0 +1 @@
+sphinx_autodoc_typehints

docs/source/conf.py

@@ -15,6 +15,7 @@
     'sphinx.ext.duration',
     'sphinx.ext.doctest',
     'sphinx.ext.autodoc',
+    'sphinx_autodoc_typehints',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
 ]
@@ -29,7 +30,12 @@
 
 add_module_names = False
 
-# -- Options for HTML output
+# autodoc_typehints="none"
+# typehints_document_rtype = False
+typehints_use_rtype = False
+typehints_use_signature = True
+#typehints_use_signature_return = True
 
+# -- Options for HTML output
 html_theme = 'sphinx_rtd_theme'
 

setup.py

@@ -17,6 +17,7 @@
     project_urls={
         'Documentation': 'https://slskd-api.readthedocs.io',
         'Source': 'https://github.com/bigoulours/slskd-python-api',
+        'Funding': 'https://liberapay.com/bigoulours/donate'
     },
     author='bigoulours',
     description = 'API Wrapper to interact with slskd',

slskd_api/apis/application.py

@@ -5,7 +5,7 @@ class ApplicationApi(BaseApi):
     This class contains the methods to interact with the Application API.
     """
 
-    def state(self):
+    def state(self) -> dict:
         """
         Gets the current state of the application.
         """
@@ -14,25 +14,27 @@ def state(self):
         return response.json()
 
 
-    def stop(self):
-        """
-        Stops the application.
-        """
-        url = self.api_url + '/application'
-        response = requests.delete(url, headers=self.header)
-        return response.json()
+# Getting Error 'Unauthorized' even with admin API-Key:
+    # def stop(self):
+    #     """
+    #     Stops the application.
+    #     """
+    #     url = self.api_url + '/application'
+    #     response = requests.delete(url, headers=self.header)
+    #     return response.ok
 
 
-    def restart(self):
-        """
-        Restarts the application.
-        """
-        url = self.api_url + '/application'
-        response = requests.put(url, headers=self.header)
-        return response.json()
+# Getting Error 'Unauthorized' even with admin API-Key:
+    # def restart(self):
+    #     """
+    #     Restarts the application.
+    #     """
+    #     url = self.api_url + '/application'
+    #     response = requests.put(url, headers=self.header)
+    #     return response.json()
 
 
-    def version(self):
+    def version(self) -> str:
         """
         Gets the current application version.
         """
@@ -41,7 +43,7 @@ def version(self):
         return response.json()
 
 
-    def check_updates(self, forceCheck=False):
+    def check_updates(self, forceCheck: bool = False) -> dict:
         """
         Checks for updates.
         """
@@ -53,18 +55,20 @@ def check_updates(self, forceCheck=False):
         return response.json()
 
 
-    def gc(self):
+    def gc(self) -> bool:
         """
         Forces garbage collection.
+
+        :return: True if successful.
         """
         url = self.api_url + '/application/gc'
         response = requests.post(url, headers=self.header)
-        return response.json()
+        return response.ok
 
 
-    # def application_dump(self):
+# Getting error 'Could not find file...':
+    # def dump(self):
     #     """
-    #     Returns error 'Could not find file...'
     #     """
     #     url = self.api_url + '/application/dump'
     #     response = requests.get(url, headers=self.header)

slskd_api/apis/conversations.py

@@ -5,34 +5,40 @@ class ConversationsApi(BaseApi):
     This class contains the methods to interact with the Conversations API.
     """
 
-    def acknowledge(self, username, id):
+    def acknowledge(self, username: str, id: int) -> bool:
         """
         Acknowledges the given message id for the given username.
+
+        :return: True if successful.
         """
         url = self.api_url + f'/conversations/{username}/{id}'
         response = requests.put(url, headers=self.header)
-        return response.json()
+        return response.ok
 
 
-    def acknowledge_all(self, username):
+    def acknowledge_all(self, username: str) -> bool:
         """
         Acknowledges all messages from the given username.
+
+        :return: True if successful.
         """
         url = self.api_url + f'/conversations/{username}'
         response = requests.put(url, headers=self.header)
-        return response.json()
+        return response.ok
 
 
-    def delete(self, username):
+    def delete(self, username: str) -> bool:
         """
         Closes the conversation associated with the given username.
+
+        :return: True if successful.
         """
         url = self.api_url + f'/conversations/{username}'
         response = requests.delete(url, headers=self.header)
-        return response.json()
+        return response.ok
 
 
-    def get(self, username, includeMessages=True):
+    def get(self, username: str, includeMessages: bool = True) -> dict:
         """
         Gets the conversation associated with the specified username.
         """
@@ -44,16 +50,18 @@ def get(self, username, includeMessages=True):
         return response.json()
 
 
-    def send(self, username, message):
+    def send(self, username: str, message: str) -> bool:
         """
         Sends a private message to the specified username.
+
+        :return: True if successful.
         """
         url = self.api_url + f'/conversations/{username}'
         response = requests.post(url, headers=self.header, json=message)
-        return response
+        return response.ok
 
 
-    def get_all(self, includeInactive=False, unAcknowledgedOnly=False):
+    def get_all(self, includeInactive: bool = False, unAcknowledgedOnly : bool = False) -> list:
         """
         Gets all active conversations.
         """
@@ -66,7 +74,7 @@ def get_all(self, includeInactive=False, unAcknowledgedOnly=False):
         return response.json()
 
 
-    def get_messages(self, username, unAcknowledgedOnly=False):
+    def get_messages(self, username: str, unAcknowledgedOnly : bool = False) -> list:
         """
         Gets all messages associated with the specified username.
         """

slskd_api/apis/logs.py

@@ -5,7 +5,7 @@ class LogsApi(BaseApi):
     This class contains the methods to interact with the Logs API.
     """
 
-    def get(self):
+    def get(self) -> list:
         """
         Gets the last few application logs.
         """

slskd_api/apis/options.py

@@ -5,7 +5,7 @@ class OptionsApi(BaseApi):
     This class contains the methods to interact with the Options API.
     """
 
-    def get(self):
+    def get(self) -> dict:
         """
         Gets the current application options.
         """
@@ -14,20 +14,21 @@ def get(self):
         return response.json()
 
 
-    def startup(self):
+    def get_startup(self) -> dict:
         """
         Gets the application options provided at startup.
         """
         url = self.api_url + '/options/startup'
         response = requests.get(url, headers=self.header)
         return response.json()
-
 
-    def debug(self):
-        """
-        Gets the debug view of the current application options.
-        """
-        url = self.api_url + '/options/debug'
-        response = requests.get(url, headers=self.header)
-        return response.json()
+
+# Getting error 'Unauthorized':
+    # def get_debug(self) -> dict:
+    #     """
+    #     Gets the debug view of the current application options.
+    #     """
+    #     url = self.api_url + '/options/debug'
+    #     response = requests.get(url, headers=self.header)
+    #     return response.json()
 

slskd_api/apis/public_chat.py

@@ -5,18 +5,22 @@ class PublicChatApi(BaseApi):
     [UNTESTED] This class contains the methods to interact with the PublicChat API.
     """
 
-    def start(self):
+    def start(self) -> bool:
         """
         Starts public chat.
+
+        :return: True if successful.
         """
         url = self.api_url + '/publicchat'
         response = requests.post(url, headers=self.header)
         return response.ok
 
 
-    def stop(self):
+    def stop(self) -> bool:
         """
         Stops public chat.
+
+        :return: True if successful.
         """
         url = self.api_url + '/publicchat'
         response = requests.delete(url, headers=self.header)

slskd_api/apis/relay.py

@@ -5,45 +5,55 @@ class RelayApi(BaseApi):
     [UNTESTED] This class contains the methods to interact with the Relay API.
     """
 
-    def connect(self):
+    def connect(self) -> bool:
         """
         Connects to the configured controller.
+
+        :return: True if successful.
         """
         url = self.api_url + '/relay/agent'
         response = requests.put(url, headers=self.header)
         return response.ok
 
 
-    def disconnect(self):
+    def disconnect(self) -> bool:
         """
         Disconnects from the connected controller.
+
+        :return: True if successful.
         """
         url = self.api_url + '/relay/agent'
         response = requests.delete(url, headers=self.header)
         return response.ok
 
 
-    def download_file(self, token):
+    def download_file(self, token: str) -> bool:
         """
         Downloads a file from the connected controller.
+
+        :return: True if successful.
         """
         url = self.api_url + f'/relay/controller/downloads/{token}'
         response = requests.get(url, headers=self.header)
         return response.ok
 
 
-    def upload_file(self, token):
+    def upload_file(self, token: str) -> bool:
         """
         Uploads a file from the connected controller.
+
+        :return: True if successful.
         """
         url = self.api_url + f'/relay/controller/files/{token}'
         response = requests.post(url, headers=self.header)
         return response.ok
 
 
-    def upload_share_info(self, token):
+    def upload_share_info(self, token: str) -> bool:
         """
         Uploads share information to the connected controller.
+
+        :return: True if successful.
         """
         url = self.api_url + f'/relay/controller/shares/{token}'
         response = requests.post(url, headers=self.header)