Coverage for src/prosemark/ports/binder_repo.py: 100%

1"""BinderRepo abstract base class for binder persistence operations.""" 

2 

3from abc import ABC, abstractmethod 

4from typing import TYPE_CHECKING 

5 

6if TYPE_CHECKING: # pragma: no cover 

7 from prosemark.domain.models import Binder 

8 

9 

10class BinderRepo(ABC): 

11 """Abstract base class for binder persistence operations. 

12 

13 Implementations must preserve text outside managed blocks during 

14 round-trip operations (load -> save -> load). This ensures that any 

15 content in binder files that is not part of the managed hierarchy 

16 is maintained through save/load cycles. 

17 

18 The BinderRepo serves as a critical port in the hexagonal architecture, 

19 isolating domain logic from storage concerns and enabling different 

20 storage mechanisms while maintaining consistent behavior. 

21 """ 

22 

23 @abstractmethod 

24 def load(self) -> 'Binder': 

25 """Load binder from storage. 

26 

27 Returns: 

28 The loaded Binder aggregate. 

29 

30 Raises: 

31 BinderNotFoundError: If binder file doesn't exist. 

32 FileSystemError: If file cannot be read. 

33 BinderIntegrityError: If binder data is corrupted. 

34 

35 """ 

36 

37 @abstractmethod 

38 def save(self, binder: 'Binder') -> None: 

39 """Save binder to storage. 

40 

41 Args: 

42 binder: The Binder aggregate to persist. 

43 

44 Raises: 

45 FileSystemError: If file cannot be written. 

46 

47 """