add slskd_api @ v0.1.5

lib/slskd_api/__init__.py

@@ -0,0 +1,18 @@
+# Copyright (C) 2023 bigoulours
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+# 
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from .client import SlskdClient, MetricsApi
+
+__all__ = ('SlskdClient', 'MetricsApi')

lib/slskd_api/apis/__init__.py

@@ -0,0 +1,44 @@
+# Copyright (C) 2023 bigoulours
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+# 
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from .application import ApplicationApi
+from .conversations import ConversationsApi
+from .logs import LogsApi
+from .options import OptionsApi
+from .public_chat import PublicChatApi
+from .relay import RelayApi
+from .rooms import RoomsApi
+from .searches import SearchesApi
+from .server import ServerApi
+from .session import SessionApi
+from .shares import SharesApi
+from .transfers import TransfersApi
+from .users import UsersApi
+
+__all__ = (
+    'ApplicationApi',
+    'ConversationsApi',
+    'LogsApi',
+    'OptionsApi',
+    'PublicChatApi',
+    'RelayApi',
+    'RoomsApi',
+    'SearchesApi',
+    'ServerApi',
+    'SessionApi',
+    'SharesApi',
+    'TransfersApi',
+    'UsersApi'
+)

lib/slskd_api/apis/application.py

@@ -0,0 +1,91 @@
+# Copyright (C) 2023 bigoulours
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+# 
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from .base import *
+
+class ApplicationApi(BaseApi):
+    """
+    This class contains the methods to interact with the Application API.
+    """
+
+    def state(self) -> dict:
+        """
+        Gets the current state of the application.
+        """
+        url = self.api_url + '/application'
+        response = self.session.get(url)
+        return response.json()
+
+
+    def stop(self) -> bool:
+        """
+        Stops the application. Only works with token (usr/pwd login). 'Unauthorized' with API-Key.
+        
+        :return: True if successful.
+        """
+        url = self.api_url + '/application'
+        response = self.session.delete(url)
+        return response.ok
+
+
+    def restart(self) -> bool:
+        """
+        Restarts the application. Only works with token (usr/pwd login). 'Unauthorized' with API-Key.
+        
+        :return: True if successful.
+        """
+        url = self.api_url + '/application'
+        response = self.session.put(url)
+        return response.ok
+
+
+    def version(self) -> str:
+        """
+        Gets the current application version.
+        """
+        url = self.api_url + '/application/version'
+        response = self.session.get(url)
+        return response.json()
+
+
+    def check_updates(self, forceCheck: bool = False) -> dict:
+        """
+        Checks for updates.
+        """
+        url = self.api_url + '/application/version/latest'
+        params = dict(
+            forceCheck=forceCheck
+        )
+        response = self.session.get(url, params=params)
+        return response.json()
+
+
+    def gc(self) -> bool:
+        """
+        Forces garbage collection.
+
+        :return: True if successful.
+        """
+        url = self.api_url + '/application/gc'
+        response = self.session.post(url)
+        return response.ok
+
+
+# Not supposed to be part of the external API
+# More info in the Github discussion: https://github.com/slskd/slskd/discussions/910
+    # def dump(self):
+    #     url = self.api_url + '/application/dump'
+    #     response = self.session.get(url)
+    #     return response.json()

lib/slskd_api/apis/base.py

@@ -0,0 +1,26 @@
+# Copyright (C) 2023 bigoulours
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+# 
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+import requests
+from urllib.parse import quote
+
+class BaseApi:
+    """
+    Base class where api-url and headers are set for all requests.
+    """
+
+    def __init__(self, api_url: str, session: requests.Session):
+        self.api_url = api_url
+        self.session = session

lib/slskd_api/apis/conversations.py

@@ -0,0 +1,103 @@
+# Copyright (C) 2023 bigoulours
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+# 
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from .base import *
+
+class ConversationsApi(BaseApi):
+    """
+    This class contains the methods to interact with the Conversations API.
+    """
+
+    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/{quote(username)}/{id}'
+        response = self.session.put(url)
+        return response.ok
+
+
+    def acknowledge_all(self, username: str) -> bool:
+        """
+        Acknowledges all messages from the given username.
+
+        :return: True if successful.
+        """
+        url = self.api_url + f'/conversations/{quote(username)}'
+        response = self.session.put(url)
+        return response.ok
+
+
+    def delete(self, username: str) -> bool:
+        """
+        Closes the conversation associated with the given username.
+
+        :return: True if successful.
+        """
+        url = self.api_url + f'/conversations/{quote(username)}'
+        response = self.session.delete(url)
+        return response.ok
+
+
+    def get(self, username: str, includeMessages: bool = True) -> dict:
+        """
+        Gets the conversation associated with the specified username.
+        """
+        url = self.api_url + f'/conversations/{quote(username)}'
+        params = dict(
+            includeMessages=includeMessages
+        )
+        response = self.session.get(url, params=params)
+        return response.json()
+
+
+    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/{quote(username)}'
+        response = self.session.post(url, json=message)
+        return response.ok
+
+
+    def get_all(self, includeInactive: bool = False, unAcknowledgedOnly : bool = False) -> list:
+        """
+        Gets all active conversations.
+        """
+        url = self.api_url + '/conversations'
+        params = dict(
+            includeInactive=includeInactive,
+            unAcknowledgedOnly=unAcknowledgedOnly
+        )
+        response = self.session.get(url, params=params)
+        return response.json()
+
+
+    def get_messages(self, username: str, unAcknowledgedOnly : bool = False) -> list:
+        """
+        Gets all messages associated with the specified username.
+        """
+        url = self.api_url + f'/conversations/{quote(username)}/messages'
+        params = dict(
+            username=username,
+            unAcknowledgedOnly=unAcknowledgedOnly
+        )
+        response = self.session.get(url, params=params)
+        return response.json()
+

lib/slskd_api/apis/logs.py

@@ -0,0 +1,29 @@
+# Copyright (C) 2023 bigoulours
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+# 
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+from .base import *
+
+class LogsApi(BaseApi):
+    """
+    This class contains the methods to interact with the Logs API.
+    """
+
+    def get(self) -> list:
+        """
+        Gets the last few application logs.
+        """
+        url = self.api_url + '/logs'
+        response = self.session.get(url)
+        return response.json()