Coverage for src / lexigram / contracts / domain / base.py: 0%

1"""Basic domain modelling protocols and types. 

2 

3This module defines ``DomainModelProtocol`` which specifies the interface 

4for domain models in the Lexigram framework. The actual implementation 

5lives in ``lexigram.domain.base``. 

6""" 

7 

8from __future__ import annotations 

9 

10from typing import Any, ClassVar, Protocol, TypeVar, runtime_checkable 

11 

12 

13@runtime_checkable 

14class DomainModelProtocol(Protocol): 

15 """Protocol defining the interface for domain models. 

16 

17 This protocol is intentionally **Pydantic-aligned**: it mirrors the 

18 Pydantic v2 ``BaseModel`` API surface because ``DomainModel`` (the 

19 concrete base in ``lexigram.domain``) builds on Pydantic v2. This 

20 is a deliberate design decision — all first-party implementations are 

21 Pydantic models, so tight alignment removes friction. 

22 

23 The trade-off is that non-Pydantic implementations must provide 

24 compatible shims for ``model_dump``, ``model_validate``, etc. 

25 

26 ``model_rebuild`` and ``model_extra`` are **excluded** from this 

27 protocol: they are Pydantic implementation internals not relevant to 

28 the domain-model contract. 

29 """ 

30 

31 model_config: ClassVar[dict[str, Any]] = {} 

32 

33 def model_dump( 

34 self, 

35 *, 

36 mode: str = "python", 

37 exclude: set[str] | None = None, 

38 include: set[str] | None = None, 

39 **kwargs: Any, 

40 ) -> dict[str, Any]: 

41 """Return a dict representation of the model. 

42 

43 Args: 

44 mode: "python" or "json" - json converts to serializable types 

45 exclude: Fields to exclude from output 

46 include: Fields to include in output (if None, includes all) 

47 """ 

48 ... 

49 

50 def model_dump_json(self, **kwargs: Any) -> str: 

51 """Return a JSON string representation of the model.""" 

52 ... 

53 

54 @classmethod 

55 def model_validate(cls, data: dict[str, Any], **kwargs: Any) -> Any: 

56 """Create an instance from a dictionary.""" 

57 ... 

58 

59 @classmethod 

60 def model_validate_json(cls, json_str: str, **kwargs: Any) -> Any: 

61 """Create an instance from a JSON string.""" 

62 ... 

63 

64 def model_copy( 

65 self, 

66 *, 

67 update: dict[str, Any] | None = None, 

68 deep: bool = False, 

69 ) -> Any: 

70 """Create a copy of the model with optional updates. 

71 

72 Args: 

73 update: Fields to update in the copy 

74 deep: If True, perform a deep copy 

75 """ 

76 ... 

77 

78 def model_json_schema(self) -> dict[str, Any]: 

79 """Generate JSON schema for the model.""" 

80 ... 

81 

82 def __init__(self, *args: Any, **kwargs: Any) -> None: 

83 """Initialize the model with the given arguments.""" 

84 ... 

85 

86 

87ID = TypeVar("ID") 

88 

89 

90__all__ = ["ID", "DomainModelProtocol"]