diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..3536b33 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,8 @@ +version: 2 + +sphinx: + configuration: docs/source/conf.py + +python: + install: + - requirements: docs/requirements.txt \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..a386fd4 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +sphinx_autodoc_typehints \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 47b2d0f..e92554e 100644 --- a/docs/source/conf.py +++ b/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' diff --git a/setup.py b/setup.py index ea0f3eb..3b71eee 100644 --- a/setup.py +++ b/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', diff --git a/slskd_api/apis/application.py b/slskd_api/apis/application.py index e85978b..7954859 100644 --- a/slskd_api/apis/application.py +++ b/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) diff --git a/slskd_api/apis/conversations.py b/slskd_api/apis/conversations.py index 5b0b268..4263873 100644 --- a/slskd_api/apis/conversations.py +++ b/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. """ diff --git a/slskd_api/apis/logs.py b/slskd_api/apis/logs.py index 643153b..43f4e68 100644 --- a/slskd_api/apis/logs.py +++ b/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. """ diff --git a/slskd_api/apis/options.py b/slskd_api/apis/options.py index 7edab83..622f480 100644 --- a/slskd_api/apis/options.py +++ b/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() \ No newline at end of file diff --git a/slskd_api/apis/public_chat.py b/slskd_api/apis/public_chat.py index 414f893..aa6c575 100644 --- a/slskd_api/apis/public_chat.py +++ b/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) diff --git a/slskd_api/apis/relay.py b/slskd_api/apis/relay.py index 97ff716..3a00cc5 100644 --- a/slskd_api/apis/relay.py +++ b/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) diff --git a/slskd_api/apis/rooms.py b/slskd_api/apis/rooms.py index a90c324..bf4992c 100644 --- a/slskd_api/apis/rooms.py +++ b/slskd_api/apis/rooms.py @@ -5,52 +5,62 @@ class RoomsApi(BaseApi): This class contains the methods to interact with the Rooms API. """ - def get_all_joined(self): + def get_all_joined(self) -> list: """ Gets all joined rooms. + + :return: Names of the joined rooms. """ url = self.api_url + '/rooms/joined' response = requests.get(url, headers=self.header) return response.json() - def join(self, room): + def join(self, roomName: str) -> dict: """ Joins a room. + + :return: room info: name, isPrivate, users, messages """ url = self.api_url + '/rooms/joined' - response = requests.post(url, headers=self.header, json=room) + response = requests.post(url, headers=self.header, json=roomName) return response.json() - def get_joined(self, roomName): + def get_joined(self, roomName: str) -> dict: """ Gets the specified room. + + :return: room info: name, isPrivate, users, messages """ url = self.api_url + f'/rooms/joined/{roomName}' response = requests.get(url, headers=self.header) return response.json() - def leave(self, roomName): + def leave(self, roomName: str) -> bool: """ Leaves a room. + + :return: True if successful. """ url = self.api_url + f'/rooms/joined/{roomName}' response = requests.delete(url, headers=self.header) return response.ok - def send(self, roomName, message): + def send(self, roomName: str, message: str) -> bool: """ Sends a message to the specified room. + + :return: True if successful. """ url = self.api_url + f'/rooms/joined/{roomName}/messages' response = requests.post(url, headers=self.header, json=message) return response.ok - def get_messages(self, roomName): + def get_messages(self, roomName: str) -> list: """ Gets the current list of messages for the specified room. """ @@ -59,34 +69,38 @@ def get_messages(self, roomName): return response.json() - def set_tocker(self, roomName, ticker): + def set_ticker(self, roomName: str, ticker: str) -> bool: """ Sets a ticker for the specified room. + + :return: True if successful. """ url = self.api_url + f'/rooms/joined/{roomName}/ticker' response = requests.post(url, headers=self.header, json=ticker) return response.ok - def add_member(self, roomName, username): + def add_member(self, roomName: str, username: str) -> bool: """ Adds a member to a private room. + + :return: True if successful. """ url = self.api_url + f'/rooms/joined/{roomName}/members' response = requests.post(url, headers=self.header, json=username) return response.ok - def get_users(self, roomName): + def get_users(self, roomName: str) -> list: """ - Gets the current list of users for the specified room. + Gets the current list of users for the specified joined room. """ url = self.api_url + f'/rooms/joined/{roomName}/users' response = requests.get(url, headers=self.header) return response.json() - def get_all(self): + def get_all(self) -> list: """ Gets a list of rooms from the server. """ diff --git a/slskd_api/client.py b/slskd_api/client.py index c158189..798c06c 100644 --- a/slskd_api/client.py +++ b/slskd_api/client.py @@ -56,7 +56,7 @@ def __init__(self, host, metrics_usr=None, metrics_pwd=None, metrics_url_base='/ 'Authorization': f'Basic {basic_auth.decode()}' } - def get(self): + def get(self) -> str: """ Gets the Prometheus metrics as text. """