Coverage for oc_ocdm / counter_handler / counter_handler.py: 100%

1#!/usr/bin/python 

2 

3# SPDX-FileCopyrightText: 2020-2022 Simone Persiani <iosonopersia@gmail.com> 

4# SPDX-FileCopyrightText: 2024 Arcangelo Massari <arcangelo.massari@unibo.it> 

5# 

6# SPDX-License-Identifier: ISC 

7 

8# -*- coding: utf-8 -*- 

9from abc import ABC, abstractmethod 

10 

11 

12class CounterHandler(ABC): 

13 """Abstract class representing the interface for every concrete counter handler.""" 

14 

15 @abstractmethod 

16 def set_counter( 

17 self, 

18 new_value: int, 

19 entity_short_name: str, 

20 prov_short_name: str = "", 

21 identifier: int = 1, 

22 supplier_prefix: str = "", 

23 ) -> None: 

24 """ 

25 Method signature for concrete implementations that allow setting the counter value 

26 of graph and provenance entities. 

27 

28 :param new_value: The new counter value to be set 

29 :type new_value: int 

30 :param entity_short_name: The short name associated either to the type of the entity itself 

31 or, in case of a provenance entity, to the type of the relative graph entity. 

32 :type entity_short_name: str 

33 :param prov_short_name: In case of a provenance entity, the short name associated to the type 

34 of the entity itself. An empty string otherwise. 

35 :type prov_short_name: str 

36 :param identifier: In case of a provenance entity, the counter value that identifies the relative 

37 graph entity. The integer value '1' otherwise. 

38 :type identifier: int 

39 :raises NotImplementedError: always 

40 :return: None 

41 """ 

42 raise NotImplementedError # pragma: no cover 

43 

44 @abstractmethod 

45 def read_counter( 

46 self, entity_short_name: str, prov_short_name: str = "", identifier: int = 1, supplier_prefix: str = "" 

47 ) -> int: 

48 """ 

49 Method signature for concrete implementations that allow reading the counter value 

50 of graph and provenance entities. 

51 

52 :param entity_short_name: The short name associated either to the type of the entity itself 

53 or, in case of a provenance entity, to the type of the relative graph entity. 

54 :type entity_short_name: str 

55 :param prov_short_name: In case of a provenance entity, the short name associated to the type 

56 of the entity itself. An empty string otherwise. 

57 :type prov_short_name: str 

58 :param identifier: In case of a provenance entity, the counter value that identifies the relative 

59 graph entity. The integer value '1' otherwise. 

60 :type identifier: int 

61 :raises NotImplementedError: always 

62 :return: The requested counter value. 

63 """ 

64 raise NotImplementedError # pragma: no cover 

65 

66 @abstractmethod 

67 def increment_counter( 

68 self, entity_short_name: str, prov_short_name: str = "", identifier: int = 1, supplier_prefix: str = "" 

69 ) -> int: 

70 """ 

71 Method signature for concrete implementations that allow incrementing by one unit 

72 the counter value of graph and provenance entities. 

73 

74 :param entity_short_name: The short name associated either to the type of the entity itself 

75 or, in case of a provenance entity, to the type of the relative graph entity. 

76 :type entity_short_name: str 

77 :param prov_short_name: In case of a provenance entity, the short name associated to the type 

78 of the entity itself. An empty string otherwise. 

79 :type prov_short_name: str 

80 :param identifier: In case of a provenance entity, the counter value that identifies the relative 

81 graph entity. The integer value '1' otherwise. 

82 :type identifier: int 

83 :raises NotImplementedError: always 

84 :return: The newly-updated (already incremented) counter value. 

85 """ 

86 raise NotImplementedError # pragma: no cover 

87 

88 @abstractmethod 

89 def set_metadata_counter(self, new_value: int, entity_short_name: str, dataset_name: str | None) -> None: 

90 """ 

91 Method signature for concrete implementations that allow setting the counter value 

92 of metadata entities. 

93 

94 :param new_value: The new counter value to be set 

95 :type new_value: int 

96 :param entity_short_name: The short name associated either to the type of the entity itself. 

97 :type entity_short_name: str 

98 :param dataset_name: In case of a ``Dataset``, its name. Otherwise, the name of the relative dataset. 

99 :type dataset_name: str 

100 :raises NotImplementedError: always 

101 :return: None 

102 """ 

103 raise NotImplementedError # pragma: no cover 

104 

105 @abstractmethod 

106 def read_metadata_counter(self, entity_short_name: str, dataset_name: str | None) -> int: 

107 """ 

108 Method signature for concrete implementations that allow reading the counter value 

109 of metadata entities. 

110 

111 :param entity_short_name: The short name associated either to the type of the entity itself. 

112 :type entity_short_name: str 

113 :param dataset_name: In case of a ``Dataset``, its name. Otherwise, the name of the relative dataset. 

114 :type dataset_name: str 

115 :raises NotImplementedError: always 

116 :return: The requested counter value. 

117 """ 

118 raise NotImplementedError # pragma: no cover 

119 

120 @abstractmethod 

121 def increment_metadata_counter(self, entity_short_name: str, dataset_name: str | None) -> int: 

122 """ 

123 Method signature for concrete implementations that allow incrementing by one unit 

124 the counter value of metadata entities. 

125 

126 :param entity_short_name: The short name associated either to the type of the entity itself. 

127 :type entity_short_name: str 

128 :param dataset_name: In case of a ``Dataset``, its name. Otherwise, the name of the relative dataset. 

129 :type dataset_name: str 

130 :raises NotImplementedError: always 

131 :return: The newly-updated (already incremented) counter value. 

132 """ 

133 raise NotImplementedError # pragma: no cover