From e7ecc0beba23a63ec8dca22a17627de3972cb5fa Mon Sep 17 00:00:00 2001 From: Jan Date: Tue, 28 Mar 2023 10:51:58 +0200 Subject: [PATCH] Finish docstrings --- src/data/files.py | 36 +++++++++++++++++++++++++- src/data/settings.py | 16 +++++++++++- src/language/lang.py | 17 ++++++++++++- src/mqtt.py | 60 ++++++++++++++++++++++++++------------------ 4 files changed, 102 insertions(+), 27 deletions(-) diff --git a/src/data/files.py b/src/data/files.py index 099e01a..efd936a 100644 --- a/src/data/files.py +++ b/src/data/files.py @@ -12,6 +12,12 @@ entries_filename = "entries.json" # region write def write_json_to_files(dict_to_save, filename): + """ + Hilfsmethode zum Schreiben einer JSON-Datei auf dem Geraet. + + :param dict_to_save: ``dict``, das als JSON-Datei gespeichert werden soll. + :param filename: Name der Datei als ``str``. + """ if not FILES_PATH.is_dir(): FILES_PATH.mkdir() @@ -27,9 +33,20 @@ def write_json_to_files(dict_to_save, filename): def write_settings_to_files(settings_dict): + """ + Schreibt Einstellungen in JSON-Datei auf Geraet. + + :param settings_dict: ``dict`` mit entsprechenden Einstellungen. + """ write_json_to_files(settings_dict, settings_filename) def write_entries_to_files(entries_dict): + """ + Schreibt Eintraege der Einkaufsliste in JSON-Datei auf Geraet. + + :param entries_dict: ``dict`` mit entsprechenden Eintraegen. + """ + write_json_to_files(entries_dict, entries_filename) # endregion @@ -37,6 +54,12 @@ def write_entries_to_files(entries_dict): # region read def read_json_from_files(filename) -> dict: + """ + Liest eine JSON-Datei als ``dict`` ein. + + :param filename: Name der auszulesenden Datei als ``str``. + :return: Liefert ``dict`` der JSON-Datei zurueck. + """ path = Path(FILES_PATH, filename) if not os.path.exists(path): @@ -46,9 +69,20 @@ def read_json_from_files(filename) -> dict: return json.load(json_file) def read_settings_from_files() -> dict: + """ + Liest Einstellungen der lokalen JSON-Datei ein. + + :return: Liefert Einstellungen als ``dict`` zurueck. + """ return read_json_from_files(settings_filename) def read_entries_from_files() -> Dict[str, list]: + """ + Liest Eintraege der Einkaufsliste der lokalen JSON-Datei ein. + + :return: Liefert Eintraege als ``dict`` zurueck. + """ + return read_json_from_files(entries_filename) -# endregion \ No newline at end of file +# endregion diff --git a/src/data/settings.py b/src/data/settings.py index 37ae2d8..b8225da 100644 --- a/src/data/settings.py +++ b/src/data/settings.py @@ -5,6 +5,9 @@ from data.files import read_settings_from_files, write_settings_to_files @dataclass class AppSettings: + """ + Stellt Datenklasse zum Halten der aktuellen Einstellungen dar. + """ language: str = "DE" dark_theme: bool = False mqtt_server: str = "broker.hivemq.com" @@ -13,6 +16,9 @@ class AppSettings: mqtt_password: str = "" def to_json_file(self): + """ + Wandelt das Objekt in eine Einstellung-JSON-Datei um und speichert diese auf dem Geraet. + """ settings_dict = {"settings": asdict(self)} try: write_settings_to_files(settings_dict) @@ -22,6 +28,10 @@ class AppSettings: @staticmethod def from_json_file(): + """ + Statische Methode zum Auslesen einer lokalen JSON-Datei und direkten Umwandlung in ein + ``AppSettings``-Objekt. + """ settings_dict = None try: @@ -44,7 +54,11 @@ class AppSettings: return new_settings @staticmethod - def get_or_create(): + def get_or_create(): + """ + Statische Methode, welche entweder initiale Einstellungen anlegt oder diese aus einer + vorhandenen JSON-Datei liest. + """ settings = AppSettings.from_json_file() if settings is None: print("Creating new settings") diff --git a/src/language/lang.py b/src/language/lang.py index 87c030b..5c8e646 100644 --- a/src/language/lang.py +++ b/src/language/lang.py @@ -8,12 +8,21 @@ LANGUAGE_FOLDER = Path("res", "lang") class TranslationProvider: + """ + Dient als statische Hilfsklasse zum Uebersetzen von Texten innerhalb der App. + """ src_dir : Path last_language_key: Optional[str] = None last_language_dict: Optional[Dict[str, str]] = None @classmethod def get_language_file(cls, language: str) -> Dict[str, str]: + """ + Statische Methode zum Auslesen einer Sprach-JSON-Datei. + Laedt die Uebersetzungen anhand der ausgewaehlten Sprache. + + :param language: Sprachschluessel der gewuenschten Sprache als ``str``. + """ if language not in list(LANGUAGES.keys()): raise ValueError('invalid language key: "{language}"') @@ -36,10 +45,16 @@ class TranslationProvider: @classmethod def get_translated(cls, key: str, language: str) -> str: + """ + Diese statische Methide uebersetzt einen Text anhand des Text-Schluessels und der Sprache. + + :param key: Schluessel des zu uebersetzenden Texts als ``str``. + :param language: Sprachschluessel der gewuenschten Sprache als ``str``. + """ lang_dict = cls.get_language_file(language) result = lang_dict.get(key, None) if result: return result - print(f"unsuccesful try to get {key} in language {language}") + print(f"unsuccessful try to get {key} in language {language}") return f'key not found for language: \nkey:"{key}"\nlanguage:"{language}"' diff --git a/src/mqtt.py b/src/mqtt.py index c812d2a..cfd5761 100644 --- a/src/mqtt.py +++ b/src/mqtt.py @@ -7,11 +7,14 @@ import json def _get_broker_and_port(broker: str, port: int) -> tuple[str, int]: """ Teilt die Broker-Adresse in Broker und Port auf. + Wenn der Port in der Broker-Adresse angegeben ist, wird er aus der Broker-Adresse entfernt und + der Port-Parameter ignoriert. - Wenn der Port in der Broker-Adresse angegeben ist, wird er aus der Broker-Adresse entfernt und der Port-Parameter ignoriert. - :param broker: der hostname oder die IP-Adresse des Brokers (kann auch Port enthalten) - :param port: der Port der verwendet wird, wenn der Port nicht in der Broker-Adresse angegeben ist - :return: (broker, port) als Tuple + :param broker: Der Hostname oder die IP-Adresse des Brokers (kann auch Port enthalten) als + ``str``. + :param port: Der Port als ``int`` der verwendet wird, wenn der Port nicht in der Broker-Adresse + angegeben ist. + :return: (broker, port) als Tuple. """ print("getting broker and port", broker, port) @@ -24,7 +27,7 @@ def _get_broker_and_port(broker: str, port: int) -> tuple[str, int]: class MqttClient: """ - Klasse zum Verbinden mit einem MQTT-Broker + Klasse zum Verbinden mit einem MQTT-Broker. """ def __init__( self, @@ -52,13 +55,14 @@ class MqttClient: password: Optional[str] = None, ): """ - Setzt die Verbindungsdaten für den MQTT-Broker + Setzt die Verbindungsdaten für den MQTT-Broker. - :param broker: die Adresse des Brokers - :param topic: die topic die der Client standardmäßig verwendet - :param port: Port des Brokers, kann auch durch : in der Broker-Adresse angegeben werden - :param username: Username zum Verbinden mit dem Broker - :param password: passwort zum Verbinden mit dem Broker + :param broker: Die Adresse des Brokers als ``str``. + :param topic: Die Topic ``str``, die der Client standardmäßig verwendet. + :param port: Port des Brokers als ``int``, kann auch durch : in der Broker-Adresse + angegeben werden. + :param username: Username als ``str`` zum Verbinden mit dem Broker. + :param password: Passwort als ``str`` zum Verbinden mit dem Broker. """ broker, port = _get_broker_and_port(broker, port) self.__broker = broker @@ -69,9 +73,11 @@ class MqttClient: def parse_callback(self, msg, callback: Optional[Callable]): """ - Verarbeitet die empfangenen Nachrichten und ruft die angegebene Callback-Funktion auf - :param msg: die nachricht die empfangen wurde - :param callback: [optional] die Callback-Funktion die aufgerufen werden soll (wenn nicht angegeben wird die Callback-Funktion der Klasse verwendet) + Verarbeitet die empfangenen Nachrichten und ruft die angegebene Callback-Funktion auf. + + :param msg: Die Nachricht als ``str``, die empfangen wurde. + :param callback: [optional] Die Callback-Funktion als ``Callable``, die aufgerufen werden + soll (wenn nicht angegeben wird die Callback-Funktion der Klasse verwendet). """ if callback is None: callback = self.__subscribe_callback @@ -82,9 +88,10 @@ class MqttClient: def on_connect(return_code: int) -> None: """ Wird aufgerufen, wenn eine Verbindung zum MQTT-Broker hergestellt wurde. + Gibt lediglich eine Meldung aus. - Macht selbst nicht viel, außer eine Meldung auszugeben. - :param return_code: anhand dessen wird entschieden ob die Verbindung erfolgreich war + :param return_code: Mitgabe als ``int``, wodurch entschieden wird, ob die Verbindung + erfolgreich war. """ if return_code == 0: print("Connected to MQTT Broker!") @@ -95,10 +102,12 @@ class MqttClient: self, msg: dict, topic: Optional[str] = None, retain: bool = True ) -> None: """ - Sendet eine Nachricht an den MQTT-Broker - :param msg: die zu sendenden Daten als dict (wird automatisch in JSON umgewandelt) - :param topic: [optional] die topic an welche die Nachricht gesendet werden soll (wenn nicht angegeben wird die topic der Klasse verwendet) - :param retain: ob bei der Nachricht die retain-Flag gesetzt werden soll + Sendet eine Nachricht an den MQTT-Broker. + + :param msg: Die zu sendenden Daten als ``dict`` (wird automatisch in JSON umgewandelt). + :param topic: [optional] Die Topic als ``str`` an welche die Nachricht gesendet werden soll + (wenn nicht angegeben wird die topic der Klasse verwendet). + :param retain: Ob bei der Nachricht die retain-Flag gesetzt werden soll, als ``bool``. """ if self.__client is None: print("publish called but mqtt-client is None", self) @@ -116,8 +125,11 @@ class MqttClient: def subscribe(self, callback=None) -> None: """ - Abonniert die topic der Klasse und ruft die angegebene Callback-Funktion auf, wenn eine Nachricht empfangen wird - :param callback: die Callback-Funktion die aufgerufen werden soll (wenn nicht angegeben wird die Callback-Funktion der Klasse verwendet) + Abonniert die Topic der Klasse und ruft die angegebene Callback-Funktion auf, wenn eine + Nachricht empfangen wird. + + :param callback: Die Callback-Funktion als ``Callable``, die aufgerufen werden soll + (wenn nicht angegeben, wird die Callback-Funktion der Klasse verwendet). """ if self.__connection_error: return @@ -155,8 +167,8 @@ class MqttClient: def disconnect(self) -> None: """ Trennt die Verbindung zum MQTT-Broker. - - Muss nicht explizit aufgerufen werden, da die Klasse sich selbst beim Löschen automatisch trennt + Muss nicht explizit aufgerufen werden, da die Klasse sich selbst beim Loeschen automatisch + trennt. """ if self.__client and self.__connection_error is False: print("Disconnecting from MQTT broker...")