OMGeeky/Kivy-Shopping-List
1
0
Fork 0
mirror of https://github.com/OMGeeky/Kivy-Shopping-List.git synced 2026-01-19 01:44:06 +01:00
Code Issues Packages Projects Releases Wiki Activity

Finish docstrings

Browse Source
This commit is contained in:
Jan
2023-03-28 10:51:58 +02:00
parent 037f0a7e58
commit e7ecc0beba
4 changed files with 102 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
src/data/files.py
View File

@@ -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
# endregion

16
src/data/settings.py
View File

@@ -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")

17
src/language/lang.py
View File

@@ -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}"'

60
src/mqtt.py
View File

@@ -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...")