Coverage for src/metador_core/container/protocols.py: 100%

1"""Protocol roughly formalizing the overlap of h5py.File and IH5Record API. 

2 

3We build the MetadorContainer interface assuming only these methods. 

4""" 

5from __future__ import annotations 

6 

7from typing import ( 

8 Any, 

9 Callable, 

10 ItemsView, 

11 Iterable, 

12 KeysView, 

13 Literal, 

14 MutableMapping, 

15 Optional, 

16 Protocol, 

17 TypeVar, 

18 Union, 

19 ValuesView, 

20 runtime_checkable, 

21) 

22 

23from typing_extensions import get_args 

24 

25 

26@runtime_checkable 

27class H5NodeLike(Protocol): # pragma: no cover 

28 """HDF5 Files, Groups and Datasets are all Nodes.""" 

29 

30 @property 

31 def name(self) -> str: 

32 """Absolute path of the node.""" 

33 

34 @property 

35 def attrs(self) -> MutableMapping: 

36 """Attached HDF5 attributes.""" 

37 

38 @property 

39 def parent(self) -> H5GroupLike: 

40 """Parent group.""" 

41 

42 @property 

43 def file(self) -> H5FileLike: 

44 """Original file-like object this node belongs to.""" 

45 

46 

47@runtime_checkable 

48class H5DatasetLike(H5NodeLike, Protocol): # pragma: no cover 

49 """Datasets provide numpy-style indexing into data. 

50 

51 Metador containers use it for storing bytes, 

52 and for getting bytes out again using [()]. 

53 """ 

54 

55 def __getitem__(self, key: Any) -> Any: 

56 ... 

57 

58 def __setitem__(self, key: Any, value) -> None: 

59 ... 

60 

61 # needed to distinguish from other types: 

62 @property 

63 def ndim(self) -> int: 

64 """Numpy-style dimensionality.""" 

65 

66 

67CallbackResult = TypeVar("CallbackResult") 

68VisitCallback = Callable[[str], Optional[CallbackResult]] 

69VisititemsCallback = Callable[[str, H5NodeLike], Optional[CallbackResult]] 

70 

71 

72@runtime_checkable 

73class H5GroupLike(H5NodeLike, Protocol): # pragma: no cover 

74 # MutableMapping-like 

75 

76 def __getitem__(self, name: str) -> Union[H5GroupLike, H5DatasetLike]: 

77 ... 

78 

79 def __setitem__(self, name: str, obj) -> None: 

80 ... 

81 

82 def __delitem__(self, name: str) -> None: 

83 ... 

84 

85 def __iter__(self) -> Iterable[str]: 

86 ... 

87 

88 def __len__(self) -> int: 

89 ... 

90 

91 # Container-like 

92 

93 def __contains__(self, name: str) -> bool: 

94 ... 

95 

96 # dict-like extras 

97 

98 def keys(self) -> KeysView[str]: 

99 ... 

100 

101 def values(self) -> ValuesView[Union[H5GroupLike, H5DatasetLike]]: 

102 ... 

103 

104 def items(self) -> ItemsView[str, Union[H5GroupLike, H5DatasetLike]]: 

105 ... 

106 

107 def get(self, name: str, *args, **kwargs) -> Union[H5GroupLike, H5DatasetLike]: 

108 ... 

109 

110 # h5py specific 

111 

112 def visititems(self, func: VisititemsCallback) -> Optional[CallbackResult]: 

113 # returns value returned from callback 

114 ... 

115 

116 def visit(self, func: VisitCallback) -> Optional[CallbackResult]: 

117 # returns value returned from callback 

118 ... 

119 

120 def create_dataset(self, path, *args, **kwargs) -> H5DatasetLike: 

121 # returns original passed-in data 

122 ... 

123 

124 def require_dataset(self, path, *args, **kwargs) -> H5DatasetLike: 

125 ... 

126 

127 def create_group(self, path: str) -> H5GroupLike: 

128 # returns new group 

129 ... 

130 

131 def require_group(self, path: str) -> H5GroupLike: 

132 ... 

133 

134 def move(self, source: str, dest: str) -> None: 

135 ... 

136 

137 def copy(self, source, dest, **kwargs) -> None: 

138 ... 

139 

140 

141OpenMode = Literal["r", "r+", "a", "w", "w-", "x"] 

142"""User open modes that can be passed during initialization.""" 

143_OPEN_MODES = list(get_args(OpenMode)) 

144 

145 

146@runtime_checkable 

147class H5FileLike(H5GroupLike, Protocol): # pragma: no cover 

148 """A HDF5 File acts like the root group and has some extra features.""" 

149 

150 @property 

151 def mode(self) -> Literal["r", "r+"]: 

152 """Return 'r' if container is immutable, otherwise 'r+'.""" 

153 

154 def close(self) -> None: 

155 ... 

156 

157 # context manager (`with` notation) 

158 

159 def __enter__(self) -> H5FileLike: 

160 ... 

161 

162 def __exit__(self, ex_type, ex_value, ex_traceback) -> None: 

163 ... 

164 

165 

166__all__ = ["H5FileLike", "H5GroupLike", "H5DatasetLike", "H5NodeLike", "OpenMode"]