Coverage for /home/runner/work/bijux-cli/bijux-cli/src/bijux_cli/contracts/emitter.py: 100%

1# SPDX-License-Identifier: MIT 

2# Copyright © 2025 Bijan Mousavi 

3 

4"""Defines the contract for the structured output emission service. 

5 

6This module specifies the `EmitterProtocol`, a formal interface that any 

7service responsible for serializing data payloads (e.g., to JSON or YAML) 

8and emitting them to an output stream must implement. 

9""" 

10 

11from __future__ import annotations 

12 

13from typing import Any, Protocol, TypeVar, runtime_checkable 

14 

15from bijux_cli.core.enums import OutputFormat 

16 

17T = TypeVar("T") 

18 

19 

20@runtime_checkable 

21class EmitterProtocol(Protocol): 

22 """Defines the contract for emitting structured output. 

23 

24 This interface specifies the methods for serializing and emitting data in 

25 various formats, often integrating with a logging or telemetry system. 

26 """ 

27 

28 def emit( 

29 self, 

30 payload: Any, 

31 *, 

32 fmt: OutputFormat | None = None, 

33 pretty: bool = False, 

34 level: str = "info", 

35 message: str = "Emitting output", 

36 output: str | None = None, 

37 **context: Any, 

38 ) -> None: 

39 """Serializes and emits a structured data payload. 

40 

41 Args: 

42 payload (Any): The data payload to serialize and emit. 

43 fmt (OutputFormat | None): The output format for serialization. 

44 pretty (bool): If True, pretty-prints the output with indentation. 

45 level (str): The log level for any accompanying message. 

46 message (str): A descriptive message for logging. 

47 output (str | None): An optional pre-formatted string to emit 

48 instead of serializing the payload. 

49 **context (Any): Additional key-value pairs for structured logging. 

50 

51 Returns: 

52 None: 

53 """ 

54 ... 

55 

56 def flush(self) -> None: 

57 """Flushes any buffered output to its destination stream.""" 

58 ...