Coverage for src / lexigram / contracts / cli / contributions.py: 100%

1"""CLI contribution types for the expanded contributor protocol.""" 

2 

3from __future__ import annotations 

4 

5from dataclasses import dataclass 

6from enum import Enum 

7 

8 

9@dataclass(frozen=True) 

10class CommandContribution: 

11 """A CLI command group contributed by an extension package. 

12 

13 The ``app_factory_path`` points to a function that returns a 

14 ``typer.Typer`` instance containing all subcommands for this group. 

15 The format is ``"module.path:callable_name"``. 

16 """ 

17 

18 name: str 

19 help: str 

20 app_factory_path: str 

21 contributor: str 

22 category: str = "extension" 

23 hidden: bool = False 

24 requires_app_context: bool = False 

25 

26 

27@dataclass(frozen=True) 

28class HealthCheckContribution: 

29 """A runtime health check contributed by an extension package. 

30 

31 The ``check_path`` points to an async function with signature: 

32 ``async def check(container) -> HealthCheckResult`` 

33 The format is ``"module.path:function_name"``. 

34 """ 

35 

36 name: str 

37 description: str 

38 check_path: str 

39 contributor: str 

40 category: str = "general" 

41 timeout: float = 10.0 

42 critical: bool = False 

43 

44 

45@dataclass(frozen=True) 

46class DoctorCheckContribution: 

47 """An environment/config diagnostic check contributed by an extension. 

48 

49 The ``check_path`` points to a sync function with signature: 

50 ``def check() -> DoctorCheckResult`` 

51 The format is ``"module.path:function_name"``. 

52 """ 

53 

54 name: str 

55 description: str 

56 check_path: str 

57 contributor: str 

58 category: str = "general" 

59 can_fix: bool = False 

60 

61 

62@dataclass(frozen=True) 

63class ShellContextContribution: 

64 """An object to inject into the interactive shell namespace. 

65 

66 The ``factory_path`` points to an async function with signature: 

67 ``async def factory(container) -> Any`` 

68 The format is ``"module.path:function_name"``. 

69 """ 

70 

71 name: str 

72 description: str 

73 factory_path: str 

74 contributor: str 

75 

76 

77@dataclass(frozen=True) 

78class HookContribution: 

79 """A CLI lifecycle hook contributed by an extension package. 

80 

81 The ``handler_path`` points to a callable with signature: 

82 ``def handler(ctx) -> None`` or ``async def handler(ctx) -> None`` 

83 The format is ``"module.path:function_name"``. 

84 """ 

85 

86 event: str 

87 handler_path: str 

88 contributor: str 

89 priority: int = 50 

90 

91 

92class SchemaSetupResult(str, Enum): 

93 """Outcome status of a schema setup contribution's ensure() call.""" 

94 

95 CREATED = "created" 

96 ALREADY_PRESENT = "already_present" 

97 FAILED = "failed" 

98 

99 

100@dataclass(frozen=True) 

101class SchemaSetupOutcome: 

102 """Result of running a single SchemaSetupContribution's ensure() callable.""" 

103 

104 status: SchemaSetupResult 

105 message: str | None = None 

106 

107 

108@dataclass(frozen=True) 

109class SchemaSetupContribution: 

110 """A database schema setup step contributed by an extension package. 

111 

112 The ``setup_fn_path`` points to an async function with signature: 

113 ``async def ensure(db: DatabaseProviderProtocol) -> SchemaSetupOutcome`` 

114 The format is ``"module.path:function_name"``. 

115 """ 

116 

117 name: str 

118 description: str 

119 setup_fn_path: str 

120 contributor: str 

121 category: str = "general" 

122 

123 

124__all__ = [ 

125 "CommandContribution", 

126 "DoctorCheckContribution", 

127 "HealthCheckContribution", 

128 "HookContribution", 

129 "SchemaSetupContribution", 

130 "SchemaSetupOutcome", 

131 "SchemaSetupResult", 

132 "ShellContextContribution", 

133]