Trixy7/docs/api

Trixy Core API Documentation

Vollständige API-Referenz für das Trixy Core Framework.

Module-Übersicht

Modul	Beschreibung	Dokumentation
trixy_core.utils	Utilities, Logging, Decorators, Validation	utils.md
trixy_core.service	Service Container, Lifecycle, Circuit Breaker	service.md
trixy_core.events	Event-System, Middleware, Persistence	events.md
trixy_core.config	Konfiguration, Secrets, Migration	config.md
trixy_core.network	Protokoll, Verschlüsselung, TLS, Security, Retry, KeepAlive, Compression, RPC	network.md
trixy_core.satellite	Satellite-Management, Load-Balancing, Capability Discovery, Metrics	satellite.md
trixy_core.plugins	Plugin-System, Hooks, Hot-Reload	plugins.md
trixy_core.arbitration	Wakeword-Arbitration, Multi-Satellite	arbitration.md

Architektur-Übersicht

┌─────────────────────────────────────────────────────────────────┐
│                     Application Layer                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Server    │  │   Client    │  │ Standalone  │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
├─────────────────────────────────────────────────────────────────┤
│                      Plugin System                               │
│  ┌─────────┐  ┌──────────┐  ┌───────┐  ┌──────────┐            │
│  │ Hooks   │  │ Registry │  │ Deps  │  │ HotReload│            │
│  └─────────┘  └──────────┘  └───────┘  └──────────┘            │
├─────────────────────────────────────────────────────────────────┤
│                    Satellite Management                          │
│  ┌─────────┐  ┌──────────────┐  ┌──────────┐  ┌────────┐       │
│  │ Groups  │  │ LoadBalancing│  │ Failover │  │ Health │       │
│  └─────────┘  └──────────────┘  └──────────┘  └────────┘       │
│  ┌────────────┐  ┌─────────────┐                               │
│  │ Capability │  │   Metrics   │                               │
│  └────────────┘  └─────────────┘                               │
├─────────────────────────────────────────────────────────────────┤
│                       Event System                               │
│  ┌───────────┐  ┌────────────┐  ┌─────┐  ┌───────────┐         │
│  │ Middleware│  │ Persistence│  │ DLQ │  │ AsyncQueue│         │
│  └───────────┘  └────────────┘  └─────┘  └───────────┘         │
├─────────────────────────────────────────────────────────────────┤
│                      Service Layer                               │
│  ┌───────────┐  ┌───────────────┐  ┌─────────┐  ┌───────┐      │
│  │ Container │  │ CircuitBreaker│  │ Metrics │  │ Scopes│      │
│  └───────────┘  └───────────────┘  └─────────┘  └───────┘      │
├─────────────────────────────────────────────────────────────────┤
│                     Network & Config                             │
│  ┌──────────┐  ┌─────┐  ┌──────────┐  ┌─────────┐              │
│  │ Protocol │  │ TLS │  │ Security │  │ Config  │              │
│  └──────────┘  └─────┘  └──────────┘  └─────────┘              │
│  ┌───────┐  ┌───────────┐  ┌─────────────┐  ┌─────┐           │
│  │ Retry │  │ KeepAlive │  │ Compression │  │ RPC │           │
│  └───────┘  └───────────┘  └─────────────┘  └─────┘           │
├─────────────────────────────────────────────────────────────────┤
│                        Utilities                                 │
│  ┌─────────┐  ┌────────────┐  ┌────────────┐  ┌───────────┐    │
│  │ Logging │  │ Decorators │  │ Validation │  │ RateLimit │    │
│  └─────────┘  └────────────┘  └────────────┘  └───────────┘    │
└─────────────────────────────────────────────────────────────────┘

Schnellstart

Service erstellen

from trixy_core.service import IService, ServicePriority, ServiceGroup

class MyService(IService):
    PRIORITY = ServicePriority.OPTIONAL
    GROUP = ServiceGroup.UTILITY
    DEPENDENCIES = ["event_manager"]

    async def on_start(self) -> None:
        self.logger.info("Service gestartet")

    async def on_stop(self) -> None:
        self.logger.info("Service gestoppt")

Event-Handler registrieren

from trixy_core.events import TrixyEvent, EventPriority

class MyPlugin:
    @TrixyEvent(["wakeword_received"])
    def on_wakeword(self, event_name: str, event_data: dict) -> None:
        satellite = event_data.get("satellite")
        print(f"Wakeword von {satellite}")

    @TrixyEvent(["speech_recognized"], priority=EventPriority.HIGH)
    async def on_speech(self, event_name: str, event_data: dict) -> None:
        text = event_data.get("text")
        await self.process_command(text)

Plugin entwickeln

from trixy_core.plugins import TrixyPlugin

class MyPlugin(TrixyPlugin):
    NAME = "my_plugin"
    VERSION = "1.0.0"
    DESCRIPTION = "Mein Plugin"

    async def on_start(self) -> None:
        config_value = self.config.get("setting", "default")
        self.application.event_manager.emit("plugin_ready", {"name": self.NAME})

    async def on_stop(self) -> None:
        pass

Decorators verwenden

from trixy_core.utils.decorators import timed, cached, retry, validate

@timed(name="api_call")
@retry(max_attempts=3, backoff=1.0)
async def fetch_data(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

@cached(ttl=300, max_size=100)
def get_user(user_id: int) -> User:
    return database.query(User).get(user_id)

@validate(name=str, age=(int, lambda x: x >= 0))
def create_user(name: str, age: int) -> User:
    return User(name=name, age=age)

Konventionen

• Sprache: Alle Kommentare und Dokumentation auf Deutsch
• Type Hints: Python 3.10+ Features durchgehend
• Async: Async/await für I/O-Operationen
• Dataclasses: Für strukturierte Daten
• Enums: Für definierte Wertebereiche

Versionierung

Die API folgt Semantic Versioning (SemVer):

• Major: Inkompatible API-Änderungen
• Minor: Abwärtskompatible Funktionalität
• Patch: Abwärtskompatible Bugfixes

Aktuelle Version: 1.0.0