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

1# SPDX-License-Identifier: MIT 

2# Copyright © 2025 Bijan Mousavi 

3 

4"""Defines the contract for the API specification writing service. 

5 

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

7service responsible for generating and writing API specification documents 

8(e.g., OpenAPI, JSON Schema) must implement. 

9""" 

10 

11from __future__ import annotations 

12 

13from pathlib import Path 

14from typing import Any, Protocol, TypeVar, runtime_checkable 

15 

16from bijux_cli.core.enums import OutputFormat 

17 

18T = TypeVar("T") 

19 

20 

21@runtime_checkable 

22class DocsProtocol(Protocol): 

23 """Defines the contract for writing API specifications. 

24 

25 This interface specifies methods for serializing and writing specification 

26 documents, such as OpenAPI or JSON Schema, in various formats. 

27 """ 

28 

29 def write( 

30 self, 

31 spec: dict[str, Any], 

32 *, 

33 fmt: OutputFormat = OutputFormat.JSON, 

34 name: str = "spec", 

35 ) -> str: 

36 """Writes a specification to a file. 

37 

38 Args: 

39 spec (dict[str, Any]): The specification dictionary to write. 

40 fmt (OutputFormat): The output format. Defaults to `OutputFormat.JSON`. 

41 name (str): The base name for the output file. Defaults to 'spec'. 

42 

43 Returns: 

44 str: The path to the written file as a string. 

45 """ 

46 ... 

47 

48 def write_sync( 

49 self, spec: dict[Any, Any], fmt: OutputFormat, name: str | Path 

50 ) -> Path: 

51 """Writes the specification to a file synchronously. 

52 

53 Args: 

54 spec (dict[Any, Any]): The specification dictionary to write. 

55 fmt (OutputFormat): The output format (e.g., JSON, YAML). 

56 name (str | Path): The path or name for the output file. 

57 

58 Returns: 

59 Path: The `Path` object pointing to the written file. 

60 """ 

61 ... 

62 

63 def close(self) -> None: 

64 """Closes the writer and releases any associated resources.""" 

65 ...