Trixy7/.claude/project-knowledge/conventions.md

Code-Konventionen

Revision: r1 Source: CLAUDE.md Last updated: 2026-01-31 12:35

---

Sprache

• Kommentare und Dokumentation: Deutsch
• Variablen- und Funktionsnamen: Englisch (snake_case)
• Klassennamen: Englisch (PascalCase)

Debug-Ausgaben

from trixy_core.utils.debug import pinfo, pdebug, perror, pwarn

pinfo("Informative Nachricht")      # Grün [INFO]
pdebug("Debug-Details")             # Cyan [DEBUG]
pwarn("Warnung aufgetreten")        # Gelb [WARN]
perror("Fehler: %s", error_msg)     # Rot [ERROR]

Wichtig: --debug Flag aktiviert stdout-Ausgabe, sonst wird Logging verwendet.

Type Hints

Python 3.10+ Syntax verwenden:

# Richtig
def process(items: list[str]) -> dict[str, int]:
    pass

def get_value(key: str) -> str | None:
    pass

# Falsch (veraltet)
from typing import List, Dict, Optional
def process(items: List[str]) -> Dict[str, int]:
    pass

Konfiguration

• Format: JSON
• Typisierung: Dataclasses mit Standardwerten
• Laden: ConfigManager mit optionalem File-Watching

from trixy_core.config import ConfigManager, ServerConfig

config_manager = ConfigManager()
config = config_manager.load(
    "config/server_config.json",
    ServerConfig,
    name="server",
    auto_reload=True
)

Dateistruktur

Ordner	Inhalt
config/	JSON-Konfigurationsdateien
plugins/	Plugin-Unterverzeichnisse
models/	ML-Modelle (wakeword/, voice_recognition/)
assets/{profile}/	Audio-Dateien, "default" als Fallback
satellites/	Registrierte Satellites (JSON nach MAC)
certs/	SSL/Encryption Keys
logs/	Anwendungslogs

Service-Implementierung

from trixy_core.service import IService, ServicePriority, ServiceGroup

class MeinService(IService):
    PRIORITY = ServicePriority.MANAGER
    GROUP = ServiceGroup.UTILITY
    DEPENDENCIES = ["EventManager", "ConfigManager"]
    NAME = "MeinService"

    async def start(self):
        # Initialisierung
        pass

    async def stop(self):
        # Cleanup
        pass

Event-Handler

from trixy_core.events import TrixyEvent, EventPriority
from trixy_core.events.event_data import WakewordReceived

class MeineKlasse:
    @TrixyEvent(["wakeword_received"], priority=EventPriority.NORMAL)
    def on_wakeword(self, event_name: str, event_data: WakewordReceived):
        if event_data.confidence > 0.8:
            # Verarbeitung
            pass

Async/Await

• Event-Handler können async sein
• Service-Lifecycle-Methoden sind async
• Verwende asyncio für parallele Operationen

async def on_load(self):
    await self.setup_resources()
    await asyncio.gather(
        self.task1(),
        self.task2()
    )

Fehlerbehandlung

from trixy_core.utils.debug import perror

try:
    result = dangerous_operation()
except SpecificError as e:
    perror("Operation fehlgeschlagen: %s", e)
    # Graceful degradation
except Exception as e:
    perror("Unerwarteter Fehler: %s", e)
    raise  # Nur bei kritischen Fehlern

---

See also: modules.md, apis.md