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

1"""Management page handler protocols for lexigram-admin contributors. 

2 

3``handle_action`` is duck-typed (not part of the protocol) so that 

4handlers with only ``handle`` satisfy ``isinstance(handler, ManagementPageHandler)``. 

5The framework uses ``hasattr(handler, "handle_action")`` to discover action support. 

6""" 

7 

8from __future__ import annotations 

9 

10from typing import Any, Protocol, runtime_checkable 

11 

12from lexigram.contracts.admin.page_content import PageContent 

13 

14 

15@runtime_checkable 

16class ManagementPageHandler(Protocol): 

17 """Protocol for contributor management page handlers. 

18 

19 Implement this instead of registering dotted-string handler paths 

20 in ``ManagementPageDefinition``. The framework discovers handlers 

21 that satisfy this protocol and dispatches requests directly. 

22 

23 To support POST actions, define an additional ``handle_action(request, action_name)`` 

24 method. It is checked at runtime via ``hasattr``, not structurally typed here. 

25 """ 

26 

27 async def handle(self, request: Any) -> PageContent: 

28 """Handle a GET request for the management page. 

29 

30 Returns: 

31 Structured ``PageContent`` — the host renders it. Returning 

32 raw HTML is a contract violation (the host replaces it with 

33 an error page and logs). 

34 """ 

35 ... 

36 

37 

38# Backward-compatible alias — existing code importing AdminPageHandlerProtocol 

39# continues to work without changes. 

40AdminPageHandlerProtocol = ManagementPageHandler 

41 

42__all__ = ["AdminPageHandlerProtocol", "ManagementPageHandler"]