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

1"""Abstract base class for ID generators.""" 

2 

3from abc import ABC, abstractmethod 

4from typing import TYPE_CHECKING 

5 

6if TYPE_CHECKING: # pragma: no cover 

7 from prosemark.domain.models import NodeId 

8 

9 

10class IdGenerator(ABC): 

11 """Abstract base class for ID generators. 

12 

13 Defines the minimal interface for generating unique identifiers 

14 for nodes in the system. All implementations must generate stable, 

15 unique NodeId values. 

16 

17 The IdGenerator enables: 

18 * Stable, unique identifiers for nodes 

19 * Testable ID generation through dependency injection 

20 * Support for different ID strategies (UUIDv7 for production, sequential for tests) 

21 * Hexagonal architecture compliance by isolating system concerns 

22 

23 Examples: 

24 >>> class TestIdGenerator(IdGenerator): 

25 ... def new(self) -> NodeId: 

26 ... return NodeId('0192f0c1-2345-7123-8abc-def012345678') 

27 >>> generator = TestIdGenerator() 

28 >>> node_id = generator.new() 

29 >>> isinstance(node_id, NodeId) 

30 True 

31 

32 """ 

33 

34 @abstractmethod 

35 def new(self) -> 'NodeId': 

36 """Generate a new unique NodeId. 

37 

38 This method must be implemented by concrete subclasses to provide 

39 specific ID generation strategies (UUIDv7, sequential, etc.). 

40 

41 Returns: 

42 A new unique NodeId instance 

43 

44 Raises: 

45 NotImplementedError: If not implemented by a concrete subclass 

46 

47 """ 

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

49 raise NotImplementedError(msg) # pragma: no cover