Coverage for src / lexigram / contracts / web / routing.py: 50%

1"""HTTP route metadata decorators. 

2 

3These decorators attach route configuration to handler functions so that 

4any controller — regardless of which extension package it lives in — can 

5declare routes without importing from ``lexigram-web``. 

6 

7The decorators themselves have zero dependencies: they only write a 

8``_route_config`` dict onto the decorated callable. 

9 

10Example:: 

11 

12 from lexigram.contracts.web.routing import get, post 

13 

14 class MyController(ControllerProtocol): 

15 @get("/items") 

16 async def list_items(self) -> list: ... 

17 

18 @post("/items") 

19 async def create_item(self, body: Item) -> Item: ... 

20""" 

21 

22from __future__ import annotations 

23 

24from typing import TYPE_CHECKING, Any 

25 

26if TYPE_CHECKING: 

27 from collections.abc import Callable 

28 

29 

30def _route(method: str, path: str, **kwargs: Any) -> Callable[..., Any]: 

31 """Create a route decorator for the given HTTP method. 

32 

33 Args: 

34 method: HTTP method string (``"GET"``, ``"POST"``, etc.). 

35 path: URL path pattern for the route. 

36 **kwargs: Additional route configuration (e.g. ``summary``, ``tags``). 

37 

38 Returns: 

39 A decorator that stamps ``_route_config`` onto the handler function. 

40 """ 

41 

42 def decorator(func: Any) -> Any: 

43 func._route_config = {"method": method, "path": path, **kwargs} 

44 return func 

45 

46 return decorator 

47 

48 

49def get(path: str, **kwargs: Any) -> Callable[..., Any]: 

50 """Declare a GET route handler. 

51 

52 Args: 

53 path: URL path pattern. 

54 **kwargs: Extra route configuration. 

55 

56 Returns: 

57 Route decorator. 

58 """ 

59 return _route("GET", path, **kwargs) 

60 

61 

62def post(path: str, **kwargs: Any) -> Callable[..., Any]: 

63 """Declare a POST route handler. 

64 

65 Args: 

66 path: URL path pattern. 

67 **kwargs: Extra route configuration. 

68 

69 Returns: 

70 Route decorator. 

71 """ 

72 return _route("POST", path, **kwargs) 

73 

74 

75def put(path: str, **kwargs: Any) -> Callable[..., Any]: 

76 """Declare a PUT route handler. 

77 

78 Args: 

79 path: URL path pattern. 

80 **kwargs: Extra route configuration. 

81 

82 Returns: 

83 Route decorator. 

84 """ 

85 return _route("PUT", path, **kwargs) 

86 

87 

88def delete(path: str, **kwargs: Any) -> Callable[..., Any]: 

89 """Declare a DELETE route handler. 

90 

91 Args: 

92 path: URL path pattern. 

93 **kwargs: Extra route configuration. 

94 

95 Returns: 

96 Route decorator. 

97 """ 

98 return _route("DELETE", path, **kwargs) 

99 

100 

101def patch(path: str, **kwargs: Any) -> Callable[..., Any]: 

102 """Declare a PATCH route handler. 

103 

104 Args: 

105 path: URL path pattern. 

106 **kwargs: Extra route configuration. 

107 

108 Returns: 

109 Route decorator. 

110 """ 

111 return _route("PATCH", path, **kwargs) 

112 

113 

114__all__ = ["delete", "get", "patch", "post", "put"]