Coverage for src / lexigram / contracts / admin / widget_protocols.py: 100%

1"""Widget rendering protocols for the admin dashboard. 

2 

3These protocols define the contract between the admin dashboard shell 

4and package-level widget contributors. Each package owns its widget 

5handlers and renderers. 

6""" 

7 

8from __future__ import annotations 

9 

10from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable 

11 

12if TYPE_CHECKING: 

13 from lexigram.contracts.admin.errors import AdminError 

14 from lexigram.contracts.admin.types import WidgetParams 

15 from lexigram.contracts.core.result import Result 

16 

17__all__ = ["WidgetHandlerProtocol"] 

18 

19 

20@runtime_checkable 

21class WidgetHandlerProtocol(Protocol): 

22 """Contract for a single widget data handler. 

23 

24 Each widget has exactly one handler. The handler fetches data from 

25 the appropriate service and returns a typed WidgetViewModel. 

26 Infrastructure exceptions propagate — do not catch them here. 

27 

28 The return type is intentionally untyped at the protocol level because 

29 each handler returns its own specific WidgetViewModel frozen dataclass. 

30 """ 

31 

32 async def get_data(self, params: WidgetParams) -> Result[Any, AdminError]: 

33 """Fetch widget data and return a typed WidgetViewModel. 

34 

35 Args: 

36 params: Parsed widget request parameters. 

37 

38 Returns: 

39 Result containing a frozen WidgetViewModel dataclass instance, 

40 or an AdminError on failure. 

41 

42 Raises: 

43 Any infrastructure exception (DB, network, etc.) — not caught. 

44 """ 

45 ...