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

1from __future__ import annotations 

2 

3from typing import TYPE_CHECKING, Protocol, runtime_checkable 

4 

5if TYPE_CHECKING: 

6 from lexigram.contracts.cli.contributions import ( 

7 CommandContribution, 

8 DoctorCheckContribution, 

9 HealthCheckContribution, 

10 HookContribution, 

11 ShellContextContribution, 

12 ) 

13 from lexigram.contracts.cli.types import GeneratorDefinition 

14 

15 

16@runtime_checkable 

17class CliContributorProtocol(Protocol): 

18 """Protocol for CLI contributors that register generators, commands, 

19 health checks, doctor checks, shell context, and hooks into the CLI. 

20 

21 Each contributor is discovered via the ``lexigram.cli.contributors`` 

22 entry point group. Install the package to make contributions available. 

23 """ 

24 

25 @property 

26 def contributor_id(self) -> str: 

27 """Unique identifier for this contributor (e.g. 'core', 'web', 'sql').""" 

28 ... 

29 

30 def get_generators(self) -> list[GeneratorDefinition]: 

31 """Return all generator definitions this contributor provides. 

32 

33 Returns: 

34 A list of GeneratorDefinition instances. May be empty. 

35 """ 

36 ... 

37 

38 def get_commands(self) -> list[CommandContribution]: 

39 """Return CLI command groups contributed by this package. 

40 

41 Returns: 

42 A list of CommandContribution instances. May be empty. 

43 """ 

44 ... 

45 

46 def get_health_checks(self) -> list[HealthCheckContribution]: 

47 """Return runtime health checks contributed by this package. 

48 

49 Health checks require a booted DI container. 

50 

51 Returns: 

52 A list of HealthCheckContribution instances. May be empty. 

53 """ 

54 ... 

55 

56 def get_doctor_checks(self) -> list[DoctorCheckContribution]: 

57 """Return static environment/config diagnostic checks. 

58 

59 Doctor checks are sync and require no container. 

60 

61 Returns: 

62 A list of DoctorCheckContribution instances. May be empty. 

63 """ 

64 ... 

65 

66 def get_shell_context(self) -> list[ShellContextContribution]: 

67 """Return objects to inject into the interactive shell namespace. 

68 

69 Returns: 

70 A list of ShellContextContribution instances. May be empty. 

71 """ 

72 ... 

73 

74 def get_hooks(self) -> list[HookContribution]: 

75 """Return CLI lifecycle hooks contributed by this package. 

76 

77 Returns: 

78 A list of HookContribution instances. May be empty. 

79 """ 

80 ... 

81 

82 

83__all__ = ["CliContributorProtocol"]