Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/h5py/_hl/attrs.py: 20%

1# This file is part of h5py, a Python interface to the HDF5 library. 

2# 

3# http://www.h5py.org 

4# 

5# Copyright 2008-2013 Andrew Collette and contributors 

6# 

7# License: Standard 3-clause BSD; see "license.txt" for full license terms 

8# and contributor agreement. 

9 

10""" 

11 Implements high-level operations for attributes. 

12 

13 Provides the AttributeManager class, available on high-level objects 

14 as <obj>.attrs. 

15""" 

16 

17import numpy 

18import uuid 

19 

20from .. import h5, h5s, h5t, h5a, h5p 

21from . import base 

22from .base import phil, with_phil, Empty, is_empty_dataspace, product 

23from .datatype import Datatype 

24 

25 

26class AttributeManager(base.MutableMappingHDF5, base.CommonStateObject): 

27 

28 """ 

29 Allows dictionary-style access to an HDF5 object's attributes. 

30 

31 These are created exclusively by the library and are available as 

32 a Python attribute at <object>.attrs 

33 

34 Like Group objects, attributes provide a minimal dictionary- 

35 style interface. Anything which can be reasonably converted to a 

36 Numpy array or Numpy scalar can be stored. 

37 

38 Attributes are automatically created on assignment with the 

39 syntax <obj>.attrs[name] = value, with the HDF5 type automatically 

40 deduced from the value. Existing attributes are overwritten. 

41 

42 To modify an existing attribute while preserving its type, use the 

43 method modify(). To specify an attribute of a particular type and 

44 shape, use create(). 

45 """ 

46 

47 def __init__(self, parent): 

48 """ Private constructor. 

49 """ 

50 self._id = parent.id 

51 

52 @with_phil 

53 def __getitem__(self, name): 

54 """ Read the value of an attribute. 

55 """ 

56 attr = h5a.open(self._id, self._e(name)) 

57 shape = attr.shape 

58 

59 # shape is None for empty dataspaces 

60 if shape is None: 

61 return Empty(attr.dtype) 

62 

63 dtype = attr.dtype 

64 

65 # Do this first, as we'll be fiddling with the dtype for top-level 

66 # array types 

67 htype = h5t.py_create(dtype) 

68 

69 # NumPy doesn't support top-level array types, so we have to "fake" 

70 # the correct type and shape for the array. For example, consider 

71 # attr.shape == (5,) and attr.dtype == '(3,)f'. Then: 

72 if dtype.subdtype is not None: 

73 subdtype, subshape = dtype.subdtype 

74 shape = attr.shape + subshape # (5, 3) 

75 dtype = subdtype # 'f' 

76 

77 arr = numpy.zeros(shape, dtype=dtype, order='C') 

78 attr.read(arr, mtype=htype) 

79 

80 string_info = h5t.check_string_dtype(dtype) 

81 if string_info and (string_info.length is None): 

82 # Vlen strings: convert bytes to Python str 

83 arr = numpy.array([ 

84 b.decode('utf-8', 'surrogateescape') for b in arr.flat 

85 ], dtype=dtype).reshape(arr.shape) 

86 

87 if arr.ndim == 0: 

88 return arr[()] 

89 return arr 

90 

91 def get_id(self, name): 

92 """Get a low-level AttrID object for the named attribute. 

93 """ 

94 return h5a.open(self._id, self._e(name)) 

95 

96 @with_phil 

97 def __setitem__(self, name, value): 

98 """ Set a new attribute, overwriting any existing attribute. 

99 

100 The type and shape of the attribute are determined from the data. To 

101 use a specific type or shape, or to preserve the type of an attribute, 

102 use the methods create() and modify(). 

103 """ 

104 self.create(name, data=value) 

105 

106 @with_phil 

107 def __delitem__(self, name): 

108 """ Delete an attribute (which must already exist). """ 

109 h5a.delete(self._id, self._e(name)) 

110 

111 def create(self, name, data, shape=None, dtype=None): 

112 """ Create a new attribute, overwriting any existing attribute. 

113 

114 name 

115 Name of the new attribute (required) 

116 data 

117 An array to initialize the attribute (required) 

118 shape 

119 Shape of the attribute. Overrides data.shape if both are 

120 given, in which case the total number of points must be unchanged. 

121 dtype 

122 Data type of the attribute. Overrides data.dtype if both 

123 are given. 

124 """ 

125 name = self._e(name) 

126 

127 with phil: 

128 # First, make sure we have a NumPy array. We leave the data type 

129 # conversion for HDF5 to perform. 

130 if not isinstance(data, Empty): 

131 data = base.array_for_new_object(data, specified_dtype=dtype) 

132 

133 if shape is None: 

134 shape = data.shape 

135 elif isinstance(shape, int): 

136 shape = (shape,) 

137 

138 use_htype = None # If a committed type is given, we must use it 

139 # in the call to h5a.create. 

140 

141 if isinstance(dtype, Datatype): 

142 use_htype = dtype.id 

143 dtype = dtype.dtype 

144 elif dtype is None: 

145 dtype = data.dtype 

146 else: 

147 dtype = numpy.dtype(dtype) # In case a string, e.g. 'i8' is passed 

148 

149 original_dtype = dtype # We'll need this for top-level array types 

150 

151 # Where a top-level array type is requested, we have to do some 

152 # fiddling around to present the data as a smaller array of 

153 # subarrays. 

154 if dtype.subdtype is not None: 

155 

156 subdtype, subshape = dtype.subdtype 

157 

158 # Make sure the subshape matches the last N axes' sizes. 

159 if shape[-len(subshape):] != subshape: 

160 raise ValueError("Array dtype shape %s is incompatible with data shape %s" % (subshape, shape)) 

161 

162 # New "advertised" shape and dtype 

163 shape = shape[0:len(shape)-len(subshape)] 

164 dtype = subdtype 

165 

166 # Not an array type; make sure to check the number of elements 

167 # is compatible, and reshape if needed. 

168 else: 

169 

170 if shape is not None and product(shape) != product(data.shape): 

171 raise ValueError("Shape of new attribute conflicts with shape of data") 

172 

173 if shape != data.shape: 

174 data = data.reshape(shape) 

175 

176 # We need this to handle special string types. 

177 if not isinstance(data, Empty): 

178 data = numpy.asarray(data, dtype=dtype) 

179 

180 # Make HDF5 datatype and dataspace for the H5A calls 

181 if use_htype is None: 

182 htype = h5t.py_create(original_dtype, logical=True) 

183 htype2 = h5t.py_create(original_dtype) # Must be bit-for-bit representation rather than logical 

184 else: 

185 htype = use_htype 

186 htype2 = None 

187 

188 if isinstance(data, Empty): 

189 space = h5s.create(h5s.NULL) 

190 else: 

191 space = h5s.create_simple(shape) 

192 

193 # For a long time, h5py would create attributes with a random name 

194 # and then rename them, imitating how you can atomically replace 

195 # a file in a filesystem. But HDF5 does not offer atomic replacement 

196 # (you have to delete the existing attribute first), and renaming 

197 # exposes some bugs - see https://github.com/h5py/h5py/issues/1385 

198 # So we've gone back to the simpler delete & recreate model. 

199 if h5a.exists(self._id, name): 

200 h5a.delete(self._id, name) 

201 

202 attr = h5a.create(self._id, name, htype, space) 

203 try: 

204 if not isinstance(data, Empty): 

205 attr.write(data, mtype=htype2) 

206 except: 

207 attr.close() 

208 h5a.delete(self._id, name) 

209 raise 

210 attr.close() 

211 

212 def modify(self, name, value): 

213 """ Change the value of an attribute while preserving its type. 

214 

215 Differs from __setitem__ in that if the attribute already exists, its 

216 type is preserved. This can be very useful for interacting with 

217 externally generated files. 

218 

219 If the attribute doesn't exist, it will be automatically created. 

220 """ 

221 with phil: 

222 if not name in self: 

223 self[name] = value 

224 else: 

225 attr = h5a.open(self._id, self._e(name)) 

226 

227 if is_empty_dataspace(attr): 

228 raise OSError("Empty attributes can't be modified") 

229 

230 # If the input data is already an array, let HDF5 do the conversion. 

231 # If it's a list or similar, don't make numpy guess a dtype for it. 

232 dt = None if isinstance(value, numpy.ndarray) else attr.dtype 

233 value = numpy.asarray(value, order='C', dtype=dt) 

234 

235 # Allow the case of () <-> (1,) 

236 if (value.shape != attr.shape) and not \ 

237 (value.size == 1 and product(attr.shape) == 1): 

238 raise TypeError("Shape of data is incompatible with existing attribute") 

239 attr.write(value) 

240 

241 @with_phil 

242 def __len__(self): 

243 """ Number of attributes attached to the object. """ 

244 # I expect we will not have more than 2**32 attributes 

245 return h5a.get_num_attrs(self._id) 

246 

247 def __iter__(self): 

248 """ Iterate over the names of attributes. """ 

249 with phil: 

250 

251 attrlist = [] 

252 def iter_cb(name, *args): 

253 """ Callback to gather attribute names """ 

254 attrlist.append(self._d(name)) 

255 

256 cpl = self._id.get_create_plist() 

257 crt_order = cpl.get_attr_creation_order() 

258 cpl.close() 

259 if crt_order & h5p.CRT_ORDER_TRACKED: 

260 idx_type = h5.INDEX_CRT_ORDER 

261 else: 

262 idx_type = h5.INDEX_NAME 

263 

264 h5a.iterate(self._id, iter_cb, index_type=idx_type) 

265 

266 for name in attrlist: 

267 yield name 

268 

269 @with_phil 

270 def __contains__(self, name): 

271 """ Determine if an attribute exists, by name. """ 

272 return h5a.exists(self._id, self._e(name)) 

273 

274 @with_phil 

275 def __repr__(self): 

276 if not self._id: 

277 return "<Attributes of closed HDF5 object>" 

278 return "<Attributes of HDF5 object at %s>" % id(self._id)