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

1"""Abstract base class for timestamp management.""" 

2 

3from abc import ABC, abstractmethod 

4 

5 

6class Clock(ABC): 

7 """Abstract base class for timestamp management. 

8 

9 Defines the minimal interface for generating ISO8601 UTC timestamps 

10 used throughout the system. This abstract base class enables: 

11 

12 * Consistent timestamp formatting across all operations 

13 * Testable time-dependent behavior through dependency injection 

14 * Support for different time sources (system clock, fixed time for tests) 

15 * Hexagonal architecture compliance by isolating system time concerns 

16 

17 The MVP uses UTC timestamps in ISO8601 format for created/updated frontmatter 

18 fields and freewrite filenames. Expected format examples: 

19 - "2025-09-10T10:00:00-07:00" (with timezone offset) 

20 - "2025-09-10T17:00:00Z" (UTC timezone) 

21 

22 Examples: 

23 >>> class TestClock(Clock): 

24 ... def now_iso(self) -> str: 

25 ... return '2025-09-10T17:00:00Z' 

26 >>> clock = TestClock() 

27 >>> timestamp = clock.now_iso() 

28 >>> isinstance(timestamp, str) 

29 True 

30 

31 """ 

32 

33 @abstractmethod 

34 def now_iso(self) -> str: 

35 """Generate current timestamp in ISO8601 UTC format. 

36 

37 This method must be implemented by concrete subclasses to provide 

38 specific timestamp generation strategies (system clock, fixed time, etc.). 

39 

40 Returns: 

41 Current timestamp as ISO8601 formatted string in UTC. 

42 Expected formats: "2025-09-10T17:00:00Z" or "2025-09-10T10:00:00-07:00" 

43 

44 Raises: 

45 NotImplementedError: If not implemented by a concrete subclass 

46 

47 """ 

48 msg = 'Subclasses must implement the now_iso() method' # pragma: no cover 

49 raise NotImplementedError(msg) # pragma: no cover