> ## Documentation Index > Fetch the complete documentation index at: https://developers.strawberryfoundations.org/llms.txt > Use this file to discover all available pages before exploring further. # Verwendung > Wie man SCAPI verwendet # Scapi installieren Unsere Scapi Hauptdatei kann [hier](https://raw.githubusercontent.com/Strawberry-Foundations/strawberry-chat/main/bot/scapi.py) gefunden werden. Platziere diese Datei einfach in dem Ordner, wo du den Bot programmieren willst. Du kannst herausfinden wie du Scapi in deinem Code einbinden kannst indem du dir den Code unten anschaust. Wir empfehlen dir das du außerdem mal einen Blick in unserem [Scapi Bot Ordner](https://github.com/Strawberry-Foundations/strawberry-chat/tree/main/bot) verschaffst um zu verstehen wie ein Bot aufgebaut ist und funktioniert. # Verwendung von scapi in deinem Code Scapi wird mit jedem Update einfacher. Um Scapi in deinem Code einzubinden, verwende Python's `import` Statement. ```python theme={null} import scapi # Importiere die Scapi Funktionsdate from scapi import Scapi # Importiere Scapi's Bot Klasse ``` Wir empfehlen YAML für die Konfigurationsdateien zu verwenden. Du kannst YAML mithilfe von `pip` installieren. (`pip install pyyaml`) # Schreibe deinen ersten Bot ([stbmv1](/german/stbchat/stbm)) Dieser Dokumentationsteil gilt nur für Scapi Legacy v1.0.0 (stbmv1) oder höher ### Die ersten Schritte Um die Basics deines Bots aufzubauen, benötigst du ein Bot-Objekt. Dieses kannst du mithilfe unserer Bot-Objektklasse erstellen: ```python theme={null} Bot = Scapi.Bot(username="username", token="bottoken", host="1.2.3.4", port=1234) ``` In dieser Tabelle siehst du alle verfügbaren Argumente mit ihrer Bedeutung | Flag | Erklärung | | ------------------- | ------------------------------------------------------------------------------------ | | `username` | Der Nutzername des Bots | | `token` | Der Token (Passwort) des Bots | | `host` | Remote-Server, wo der Bot sich mit verbinden soll | | `port` | Der Port des Remote-Servers | | `enable_user_input` | Aktiviere die Nachrichteneingabe innerhalb der Konsole (Auch als Flag verfügbar) | | `print_recv_msg` | Gebe empfangende Nachrichten in die Bot-Logs aus (Konsole) (Auch als Flag verfügbar) | Damit der Bot sich im Server auch einloggt, musst du noch eine wichtige Funktion hinzufügen ```python theme={null} Bot.login() ``` ### Flags Flags sind ein wichtiger Teil beim Programmieren deines Scapi-Bots. Du benötigst Flags um z.B. festzulegen ob du Nachrichten von Nutzern in deinen Bot-Logs sehen willst, oder ob du die Nachrichteneingabe innerhalb der Konsole aktivieren willst. Die Definierung deiner Flags könnte so aussehen: ```python theme={null} Bot.flag_handler(print_recv_msg=True, enable_user_input=True) ``` In dieser Tabelle siehst du alle verfügbaren Flags mit ihrer Bedeutung | Flag | Erklärung | | ------------------- | ---------------------------------------------------------- | | `print_recv_msg` | Gebe empfangende Nachrichten in die Bot-Logs aus (Konsole) | | `enable_user_input` | Aktiviere die Nachrichteneingabe innerhalb der Konsole | | `log_msg` | Ändere das Format der Log-Nachrichten | ### Berechtigungen Ein weiterer Teil deines Bots sind Berechtigungen. Diese überprüfen ob der Nutzer, der einen Command ausgeführt hat, auch die nötigen Berechtigungen besitzt. Außerdem kannst du auch festlegen, wer der Bot-Owner ist. In Scapi gibt es eine Funktion, welche benutzerdefinierte Werte für die Berechtigungsverwaltung annimmt. Mithilfe dieser Funktion kannst du den Bot-Owner festlegen, oder eine Custom-Liste erstellen, und diese anschließend auch innerhalb von Commands verwenden. Das festlegen des Owners und einer Custom-Liste kann wie folgt vorgenommen werden: ```python theme={null} Bot.permission_handler(custom_list=["julian"], owner="julian") ``` ### Commands (`@commands` Modul) Damit der Bot auch ein Sinn und Zweck hat, braucht der Bot Commands. Ein einfacher Commands sieht wie folgt aus: Scapi hat 2 verschiedene Methoden um einen Bot zu schreiben. Eine Methode ist neuer und sauberer ist allerdings noch nicht vollständig entwickelt. Diese Methode heißt `Commands`. Dieser Teil erklärt wie du einen Command mithilfe des Command-Modules schreiben kannst. Für die andere Methode kannst du dir [diesen](/german/scapi/usage#commands-originale-methode) Dokumentationsteil anschauen ```python theme={null} @Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM) def test_command(username: str, args: list): Bot.send_message(f""" Username: {username} Args: {args}""" ) ``` Um klarzustellen, wofür was steht, ist hier nun eine detalierte Erklärung: | Code | Erklärung | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Steht für den Command-Namen, welcher anschließend in der Registry eingefügt wird. Du kannst den Command dann mithilfe des Prefixes und dann den Namen aufrufen (z.B. `!test`) | | `arg_count` | Anzahl der Argumente, die der Befehl annimmt und mindestens benötigt. Es kann auch eine niedrigere Zahl angegeben werden und mehr Argumente trotzdem angenommen werden | | `required_permissions` | Benötigte Berechtigung für den Command. Hier muss ein Wert der Scapi-Klasse übergeben werden. `Scapi.Bot.PermissionLevel.CUSTOM` für die Custom-Liste, die du [hier](/german/scapi/usage#berechtigungen) definiert hast | | `username` | Der Nutzername, des Benutzers, der den Command ausgeführt hat | | `args` | Die Argumente, die beim Ausführen des Commands übergeben wurden. Wird in einer Liste gespeichert (`["first", "second", "third"]`) | | `send_message(...)` | Funktion um eine Nachricht zu senden | ### Commands (Originale Methode) Wie du [hier](/german/scapi/usage#commands-commands-modul) erfahren hast, besitzt Scapi 2 verschiedene Methoden um ein Bot-Command zu schreiben. Dieser Teil zeigt dir, wie du die andere Methode verwendest. Diese ist etwas mehr schwierig, kann aber mehr angepasst werden. Diese Methode wird weiterhin für reine `on_message` Events verwendet um reine Nachrichten zu akzeptieren & zu verarbeiten. Wir empfehlen die Verwendung der Commands-Methode da diese mehr Features besitzt & mehr Support bietet als die Originale Methode (z.B. Berechtigungen) ```python theme={null} def Commands(): while True: try: message = Bot.recv_message(raw=True) if message.startswith("!hello"): Bot.send_message(f"Hello, world!") except: Bot.logger( f"{scapi.RED}An unknown exception occured{scapi.RESET}", type=Scapi.LogLevel.ERROR ) break ``` | Code | Erklärung | | --------------------------------- | --------------------------------------------------------------------------------------------- | | `Commands()` | Erstellt eine Funktion für das allgemeine verarbeiten der empfangenden Nachrichten & Commands | | `while True` | Eine Schleife die nie endet, um immer die Nachrichten zu empfangen | | `Bot.recv_message(raw=True)` | Empfängt die Nachrichten in einem rohen Format (Ohne Farben) | | `if message.startswith("!hello")` | Kontrolliert, ob die empfangende Nachricht mit `!hello` startet | | `send_message(...)` | Funktion um eine Nachricht zu senden | ### Events Es gibt bestimmte Events, die der Bot bei etwas bestimmten aufrufen kann. Einer dieser Events heißt `on_ready`. Dieses Event wird aufgerufen, wenn du den Bot startest. Du musst nur bei der `Bot.run()` Funktion als Argument die `on_ready` Funktion übergeben. Ein `on_ready` Event kann so aussehen: ```python theme={null} @Bot.event def on_ready(): Bot.logger( f"{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}", type=Scapi.LogLevel.INFO ) ``` ### Den Bot starten Um den Bot zu starten musst du zuerst darauf achten, welche Command Methode du verwendest. ```python @commands theme={null} Bot.run(on_ready) ``` ```python Originale Methode theme={null} BotThread = threading.Thread(target=Bot.run, args=(on_ready,)) CommandThread = threading.Thread(target=Commands) BotThread.start() CommandThread.start() ``` ### Beispielbot (Stable v1.0) Dieser Beispielbot gilt nur für Scapi Legacy v1.0.0 (stbmv1) ```python Command Methode theme={null} import scapi # Dies importiert Scapi from scapi import Scapi import yaml # Importiere YAML für die Konfiguration from yaml import SafeLoader with open("default.yml", encoding="utf-8") as config_file: config = yaml.load(config_file, Loader=SafeLoader) # Lade die Konfigurationsdatei # Definiere einige wichtige Variablen für die Reibungslose Verwendung des Bots username = config["bot"]["username"] token = config["bot"]["token"] host = config["server"]["host"] port = config["server"]["port"] prefix = config["bot"]["prefix"] Bot = Scapi.Bot(username=username, token=token, host=host, port=port) # Definiere den Bot Bot.login() # Anmelden ins System Bot.flag_handler(print_recv_msg=True, enable_user_input=True) # Setze ein paar nützliche Flags Bot.permission_handler(custom_list=["your_name"], owner="your_name") # Verwalte deine Bot Berechtigungen # Standard Bot Command @Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM) def test_command(username: str, args: list): Bot.send_message(f""" Username: {username} Args: {args}""" ) # Bot on_ready Event @Bot.event def on_ready(): print(f"{Bot.log_msg}{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}") # Starte den Bot Bot.run(on_ready) ``` ```python Originale Methode theme={null} import scapi from scapi import Scapi import yaml from yaml import SafeLoader import threading with open("default.yml", encoding="utf-8") as config: conf = yaml.load(config, Loader=SafeLoader) username = conf["bot"]["username"] token = conf["bot"]["token"] host = conf["server"]["host"] port = conf["server"]["port"] prefix = conf["bot"]["prefix"] Bot = Scapi.Bot(username=username, token=token, host=host, port=port) Bot.login() Bot.flag_handler(print_recv_msg=True, enable_user_input=True) def Commands(): while True: try: message = Bot.recv_message(raw=True) if message.startswith("!hello"): Bot.send_message(f"Hello, world!") except: Bot.logger(f"{scapi.RED}An unknown exception occured{scapi.RESET}", type=Scapi.LogLevel.ERROR) break @Bot.event def on_ready(): print(f"{Bot.log_msg}{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}") BotThread = threading.Thread(target=Bot.run, args=(on_ready,)) CommandThread = threading.Thread(target=Commands) BotThread.start() CommandThread.start() ``` Dies ist ein Beispiel wie eine Konfiguration in YAML aussehen könnte: ```yaml theme={null} bot: id: 12345678 username: "username" token: "token" prefix: "!" server: host: "1.2.3.4" port: 1234 flags: enableUserInput: true printReceivedMessagesToTerminal: true ``` *** # Schreibe deinen ersten Bot ([stbmv2](/german/stbchat/stbm)) Dieser Dokumentationsteil gilt nur für Scapi v0.12.0 (stbmv2) oder höher ### Die ersten Schritte Um die Basics deines Bots aufzubauen, benötigst du ein Bot-Objekt. Dieses kannst du mithilfe unserer Bot-Objektklasse erstellen: ```python theme={null} Bot = Scapi.Bot(username="username", token="bottoken", host="1.2.3.4", port=1234) ``` In dieser Tabelle siehst du alle verfügbaren Argumente mit ihrer Bedeutung | Flag | Erklärung | | ------------------- | ------------------------------------------------------------------------------------ | | `username` | Der Nutzername des Bots | | `token` | Der Token (Passwort) des Bots | | `host` | Remote-Server, wo der Bot sich mit verbinden soll | | `prefix` | Der Prefix des Bots, worauf er hören soll (z.B. `!help`) | | `port` | Der Port des Remote-Servers | | `enable_user_input` | Aktiviere die Nachrichteneingabe innerhalb der Konsole (Auch als Flag verfügbar) | | `print_recv_msg` | Gebe empfangende Nachrichten in die Bot-Logs aus (Konsole) (Auch als Flag verfügbar) | | `json` | Aktiviert oder deaktiviert den Kompatiblitätsmodus für alte Server | Das Argument `json` ist erst seit Scapi v0.12.1 verfügbar Das Argument `prefix` ist erst seit Scapi v0.13.1b2 verfügbar Damit der Bot sich im Server auch einloggt, musst du noch eine wichtige Funktion hinzufügen ```python theme={null} Bot.login() ``` ### Flags Flags sind ein wichtiger Teil beim Programmieren deines Scapi-Bots. Du benötigst Flags um z.B. festzulegen ob du Nachrichten von Nutzern in deinen Bot-Logs sehen willst, oder ob du die Nachrichteneingabe innerhalb der Konsole aktivieren willst. Die Definierung deiner Flags könnte so aussehen: ```python theme={null} Bot.flag_handler(print_recv_msg=True, enable_user_input=True) ``` In dieser Tabelle siehst du alle verfügbaren Flags mit ihrer Bedeutung | Flag | Erklärung | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `print_recv_msg` | Gebe empfangende Nachrichten in die Bot-Logs aus (Konsole) | | `enable_user_input` | Aktiviere die Nachrichteneingabe innerhalb der Konsole | | `log_msg` | Ändere das Format der Log-Nachrichten | | `ignore_capitalization` | Aktiviert oder deaktiviert das ignorieren von Großbuchstaben für die `on_message` Methode (**Nur verfügbar ab Scapi v0.13**) | ### Berechtigungen Ein weiterer Teil deines Bots sind Berechtigungen. Diese überprüfen ob der Nutzer, der einen Command ausgeführt hat, auch die nötigen Berechtigungen besitzt. Außerdem kannst du auch festlegen, wer der Bot-Owner ist. In Scapi gibt es eine Funktion, welche benutzerdefinierte Werte für die Berechtigungsverwaltung annimmt. Mithilfe dieser Funktion kannst du den Bot-Owner festlegen, oder eine Custom-Liste erstellen, und diese anschließend auch innerhalb von Commands verwenden. Das festlegen des Owners und einer Custom-Liste kann wie folgt vorgenommen werden: ```python theme={null} Bot.permission_handler(custom_list=["julian"], owner="julian") ``` ### Commands (Commands Modul) Damit der Bot auch ein Sinn und Zweck hat, braucht der Bot Commands. Ein einfacher Commands sieht wie folgt aus: Scapi hat 2 verschiedene Methoden um einen Bot zu schreiben. Eine Methode ist neuer und sauberer ist allerdings noch nicht vollständig entwickelt. Diese Methode heißt `Commands`. Dieser Teil erklärt wie du einen Command mithilfe des Command-Modules schreiben kannst. Die ältere Methode ist seit Scapi v0.12.1 veraltet und sollte daher auch nicht mehr verwendet werden ```python theme={null} @Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM) def test_command(username: str, args: list): Bot.send_message(f""" Username: {username} Args: {args}""" ) ``` Um klarzustellen, wofür was steht, ist hier nun eine detalierte Erklärung: | Code | Erklärung | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Steht für den Command-Namen, welcher anschließend in der Registry eingefügt wird. Du kannst den Command dann mithilfe des Prefixes und dann den Namen aufrufen (z.B. `!test`) | | `arg_count` | Anzahl der Argumente, die der Befehl annimmt und mindestens benötigt. Es kann auch eine niedrigere Zahl angegeben werden und mehr Argumente trotzdem angenommen werden | | `required_permissions` | Benötigte Berechtigung für den Command. Hier muss ein Wert der Scapi-Klasse übergeben werden. `Scapi.Bot.PermissionLevel.CUSTOM` für die Custom-Liste, die du [hier](/german/scapi/usage#berechtigungen-2) definiert hast | | `username` | Der Nutzername, des Benutzers, der den Command ausgeführt hat | | `args` | Die Argumente, die beim Ausführen des Commands übergeben wurden. Wird in einer Liste gespeichert (`["first", "second", "third"]`) | | `send_message(...)` | Funktion um eine Nachricht zu senden | Hier findest du noch weitere Commands ```python theme={null} @Bot.command(name="dm", arg_count=1) def send_dm_command(username: str, args: list): Bot.send_direct_message(username, " ".join(args)) ``` ```python theme={null} @Bot.command(name="exit", required_permissions=Scapi.Bot.PermissionLevel.OWNER) def exit_command(username: str, args: list): Bot.exit() ``` ### Commands (Originale Methode) Die Offizielle Unterstützung für die [Originale Methode](/german/scapi/usage#commands-originale-methode) wurde seit Scapi 0.12.1 abgeschafft. Zur Weiterverwendung der Originalen Methode empfehlen wir die neue `@on_message` Methode (Seit v0.13). Bei fehlender Funktionalität bitte ein [Issue](https://github.com/Strawberry-Foundations/strawberry-chat/issues) auf unserem [GitHub](https://github.com/Strawberry-Foundations/strawberry-chat/) öffnen Falls du trotzdem aus was auch immer welchen Gründen diese Methode verwenden möchtest, schaue dir bitte [diesen](/german/scapi/usage#commands-originale-methode) Teil der Dokumentation an ### Events Es gibt bestimmte Events, die der Bot bei etwas bestimmten aufrufen kann. #### @on\_message Event Ab Scapi v0.13 haben wir eine verbesserte Version der Originalen Message-Methode hinzugefügt. Diese verwendet unseren modernen Python-Standard und Python-Dekoratoren. Die Implementierung in deinem Bot-Code ist sehr einfach. Du benötigst nur mindestens Scapi v0.13 oder höher. Ein Bot-Message-Event kann so aussehen: ```python theme={null} # Python-Dekorator zum definieren des Nachrichtenevents @Bot.on_message(message="Hello") # Definierung der Funktion, um sie nachher automatisch auszuführen def on_hello_message(username: str): # Der Code der Funktion, also das was ausgeführt werden soll [...] Bot.send_message(f"Hello {username}!") ``` Nicht alle Funktionen der alten Originalen Methode konnten übernommen werden, daher ist die `@on_message` Methode mehr eingeschränkt. Folgende Funktionen konnten bis jetzt nicht implementiert werden (Aber könnten in Zukunft in einer anderen Form auftreten): * Nutzung von .startswith() * Das erkennen von spezifischen Wörtern innerhalb der Nachricht **Dieses Feature dient aktuell nur dazu, um z.B. ein normales Wort eines Nutzers zu verarbeiten, und darauf zu antworten.** #### @on\_ready Event Dieses Event wird aufgerufen, wenn du den Bot startest. Du musst nur bei der `Bot.run()` Funktion als Argument die `on_ready` Funktion übergeben. Ein `on_ready` Event kann so aussehen: ```python theme={null} @Bot.event def on_ready(): Bot.logger( f"{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}", type=Scapi.LogLevel.INFO ) ``` ### Den Bot starten Um den Bot zu starten musst du zuerst darauf achten, welche Command Methode du verwendest. ```python @commands theme={null} Bot.run(on_ready) ``` ```python Originale Methode theme={null} BotThread = threading.Thread(target=Bot.run, args=(on_ready,)) CommandThread = threading.Thread(target=Commands) BotThread.start() CommandThread.start() ``` ### Beispielbot (v0.12.0 oder höher) Dieser Beispielbot gilt nur für Scapi v0.12.0 (stbmv2) oder höher Die Offizielle Unterstützung für die [Originale Methode](/german/scapi/usage#commands-originale-methode) wurde seit Scapi v0.12.1 abgeschafft. Du kannst [hier](/german/scapi/usage#commands-originale-methode-2) mehr darüber lesen Du kannst Scapi (`@json-communication`/`@main`) [hier](https://raw.githubusercontent.com/Strawberry-Foundations/strawberry-chat/main/bot/scapi.py) erhalten. Die folgenden Code-Stücke zeigen dir wie du einen einfachen Bot mit Scapi (stbmv2) erstellen kannst. ```python @commands theme={null} import scapi from scapi import Scapi import yaml from yaml import SafeLoader with open("default.yml", encoding="utf-8") as config_file: config = yaml.load(config_file, Loader=SafeLoader) username = config["bot"]["username"] token = config["bot"]["token"] host = config["server"]["host"] port = config["server"]["port"] prefix = config["bot"]["prefix"] Bot = Scapi.Bot(username=username, token=token, host=host, port=port, json=True) Bot.login() Bot.flag_handler(print_recv_msg=True, enable_user_input=True) Bot.permission_handler(custom_list=["julian"], owner="julian") @Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM) def test_command(username: str, args: list): Bot.send_message(f""" Username: {username} Args: {args}""" ) @Bot.event def on_ready(): Bot.logger(f"{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}", type=Scapi.LogLevel.INFO) Bot.run(on_ready) ``` ```python @commands + @on_message (seit v0.13) theme={null} import scapi from scapi import Scapi import yaml from yaml import SafeLoader with open("default.yml", encoding="utf-8") as config_file: config = yaml.load(config_file, Loader=SafeLoader) username = config["bot"]["username"] token = config["bot"]["token"] host = config["server"]["host"] port = config["server"]["port"] prefix = config["bot"]["prefix"] Bot = Scapi.Bot(username=username, token=token, host=host, port=port, json=True) Bot.login() Bot.flag_handler(print_recv_msg=True, enable_user_input=True) Bot.permission_handler(custom_list=["julian"], owner="julian") # Neue on_message Methode, um "Plain" Nachrichten vom Nutzer zu verarbeiten @Bot.on_message(message="Hello") def on_hello_message(username: str): Bot.send_message(f"Hello {username}!") # Commands Methode @Bot.command(name="test", arg_count=1, required_permissions=Scapi.Bot.PermissionLevel.CUSTOM) def test_command(username: str, args: list): Bot.send_message(f""" Username: {username} Args: {args}""" ) @Bot.event def on_ready(): Bot.logger(f"{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}", type=Scapi.LogLevel.INFO) Bot.run(on_ready) ``` ```python Originale Methode (Veraltet seit v0.12.1) theme={null} # WARNUNG: Diese Methode ist veraltet # WIR ARBEITEN AN EINER BESSEREN VERSION DIESER METHODE import scapi from scapi import Scapi import yaml from yaml import SafeLoader import threading with open("default.yml", encoding="utf-8") as config: conf = yaml.load(config, Loader=SafeLoader) username = conf["bot"]["username"] token = conf["bot"]["token"] host = conf["server"]["host"] port = conf["server"]["port"] prefix = conf["bot"]["prefix"] Bot = Scapi.Bot(username=username, token=token, host=host, port=port) Bot.login() Bot.flag_handler(print_recv_msg=True, enable_user_input=True) def Commands(): while True: try: message = Bot.recv_message(raw=True) if message.startswith("!hello"): Bot.send_message(f"Hello, world!") except: Bot.logger(f"{scapi.RED}An unknown exception occured{scapi.RESET}", type=Scapi.LogLevel.ERROR) break @Bot.event def on_ready(): print(f"{Bot.log_msg}{scapi.BLUE}{Bot.username} started successfully!{scapi.RESET}") BotThread = threading.Thread(target=Bot.run, args=(on_ready,)) CommandThread = threading.Thread(target=Commands) BotThread.start() CommandThread.start() ``` Das Ändern des zugewiesenen Wertes von `json` zu `False` aktiviert den Kompatiblitätsmodus. Beachte das dies noch nicht vollständig entwickelt wurde.