Coverage for src / lexigram / contracts / data / sql / mapper.py: 0%

1"""Read-only mapper protocol for data transformation contracts. 

2 

3Defines the contract for mapping between domain/storage models without 

4mutating either side. 

5""" 

6 

7from __future__ import annotations 

8 

9from typing import Generic, Protocol, TypeVar, runtime_checkable 

10 

11S = TypeVar("S") 

12T = TypeVar("T") 

13 

14__all__ = ["DataMapperProtocol", "ReadOnlyMapperProtocol", "S", "T"] 

15 

16 

17@runtime_checkable 

18class ReadOnlyMapperProtocol(Protocol, Generic[S, T]): 

19 """Protocol for a stateless, read-only mapper between two types. 

20 

21 Implementations translate a source model of type ``S`` to a target 

22 model of type ``T`` without modifying either. The batch variant 

23 is provided for efficiency when mapping large collections. 

24 """ 

25 

26 def to_target(self, source: S) -> T: 

27 """Map a single source instance to the target type. 

28 

29 Args: 

30 source: Source model instance to translate. 

31 

32 Returns: 

33 Corresponding target model instance. 

34 """ 

35 ... 

36 

37 def to_target_batch(self, sources: list[S]) -> list[T]: 

38 """Map a sequence of source instances to the target type. 

39 

40 Args: 

41 sources: Sequence of source model instances to translate. 

42 

43 Returns: 

44 List of corresponding target model instances in the same order. 

45 """ 

46 ... 

47 

48 

49@runtime_checkable 

50class DataMapperProtocol(ReadOnlyMapperProtocol[S, T], Protocol, Generic[S, T]): 

51 """Protocol for a bidirectional stateless mapper between two types. 

52 

53 Extends :class:`ReadOnlyMapperProtocol` with the ability to map from 

54 the target type back to the source type, enabling round-trip 

55 transformations (e.g. domain model ↔ storage row). 

56 """ 

57 

58 def to_source(self, target: T) -> S: 

59 """Map a single target instance back to the source type. 

60 

61 Args: 

62 target: Target model instance to translate. 

63 

64 Returns: 

65 Corresponding source model instance. 

66 """ 

67 ... 

68 

69 def to_source_batch(self, targets: list[T]) -> list[S]: 

70 """Map a sequence of target instances back to the source type. 

71 

72 Args: 

73 targets: Sequence of target model instances to translate. 

74 

75 Returns: 

76 List of corresponding source model instances in the same order. 

77 """ 

78 ...