Coverage for src / lexigram / contracts / mapping / protocols.py: 0%

1"""Object mapping protocols for the Lexigram Framework. 

2 

3Defines the contract for registry-based object-to-object transformation, 

4enabling decoupled mapping between domain models, DTOs, and other types. 

5""" 

6 

7from __future__ import annotations 

8 

9from typing import Any, Protocol, TypeVar, runtime_checkable 

10 

11S = TypeVar("S") 

12D = TypeVar("D") 

13 

14 

15@runtime_checkable 

16class ObjectMapperProtocol(Protocol): 

17 """Protocol for a registry-based object-to-object mapper. 

18 

19 Provides a clean map() API for converting between registered type pairs 

20 without ad-hoc conversion logic scattered through the codebase. 

21 """ 

22 

23 def map( 

24 self, 

25 source: Any, 

26 dest_type: type[Any], 

27 *, 

28 validate: bool = False, 

29 validator: Any | None = None, 

30 ) -> Any: 

31 """Map a source object to the destination type. 

32 

33 Uses a registered mapping function to transform the source instance 

34 into an instance of dest_type. 

35 

36 Args: 

37 source: The source object to transform. 

38 dest_type: The target type to produce. 

39 validate: Whether to validate the result after mapping. 

40 validator: Optional validator instance to use. 

41 

42 Returns: 

43 A new instance of dest_type. 

44 

45 Raises: 

46 MappingNotFoundError: If no mapping is registered for this type pair. 

47 """ 

48 ... 

49 

50 def register( 

51 self, 

52 source_type: type[Any], 

53 dest_type: type[Any], 

54 mapper_func: Any, 

55 ) -> None: 

56 """Register a mapping function from source_type to dest_type. 

57 

58 Args: 

59 source_type: The type to map from. 

60 dest_type: The type to map to. 

61 mapper_func: A callable that accepts a source instance and returns 

62 a dest instance. 

63 """ 

64 ... 

65 

66 

67__all__ = ["ObjectMapperProtocol"]