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 

126 with phil: 

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

128 # conversion for HDF5 to perform. 

129 if not isinstance(data, Empty): 

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

131 

132 if shape is None: 

133 shape = data.shape 

134 elif isinstance(shape, int): 

135 shape = (shape,) 

136 

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

138 # in the call to h5a.create. 

139 

140 if isinstance(dtype, Datatype): 

141 use_htype = dtype.id 

142 dtype = dtype.dtype 

143 elif dtype is None: 

144 dtype = data.dtype 

145 else: 

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

147 

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

149 

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

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

152 # subarrays. 

153 if dtype.subdtype is not None: 

154 

155 subdtype, subshape = dtype.subdtype 

156 

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

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

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

160 

161 # New "advertised" shape and dtype 

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

163 dtype = subdtype 

164 

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

166 # is compatible, and reshape if needed. 

167 else: 

168 

169 if shape is not None and numpy.product(shape, dtype=numpy.ulonglong) != numpy.product(data.shape, dtype=numpy.ulonglong): 

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

171 

172 if shape != data.shape: 

173 data = data.reshape(shape) 

174 

175 # We need this to handle special string types. 

176 if not isinstance(data, Empty): 

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

178 

179 # Make HDF5 datatype and dataspace for the H5A calls 

180 if use_htype is None: 

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

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

183 else: 

184 htype = use_htype 

185 htype2 = None 

186 

187 if isinstance(data, Empty): 

188 space = h5s.create(h5s.NULL) 

189 else: 

190 space = h5s.create_simple(shape) 

191 

192 # This mess exists because you can't overwrite attributes in HDF5. 

193 # So we write to a temporary attribute first, and then rename. 

194 # see issue 1385 

195 # if track_order is enabled new attributes (which exceed the 

196 # max_compact range, 8 is default) cannot be created as temporary 

197 # attributes with subsequent rename, doing that would trigger 

198 # the error discussed in the above issue 

199 attr_exists = False 

200 if h5a.exists(self._id, self._e(name)): 

201 attr_exists = True 

202 tempname = uuid.uuid4().hex 

203 else: 

204 tempname = name 

205 

206 attr = h5a.create(self._id, self._e(tempname), htype, space) 

207 try: 

208 if not isinstance(data, Empty): 

209 attr.write(data, mtype=htype2) 

210 if attr_exists: 

211 # Rename temp attribute to proper name 

212 # No atomic rename in HDF5 :( 

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

214 h5a.rename(self._id, self._e(tempname), self._e(name)) 

215 except: 

216 attr.close() 

217 h5a.delete(self._id, self._e(tempname)) 

218 raise 

219 finally: 

220 attr.close() 

221 

222 def modify(self, name, value): 

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

224 

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

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

227 externally generated files. 

228 

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

230 """ 

231 with phil: 

232 if not name in self: 

233 self[name] = value 

234 else: 

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

236 

237 if is_empty_dataspace(attr): 

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

239 

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

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

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

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

244 

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

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

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

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

249 attr.write(value) 

250 

251 @with_phil 

252 def __len__(self): 

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

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

255 return h5a.get_num_attrs(self._id) 

256 

257 def __iter__(self): 

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

259 with phil: 

260 

261 attrlist = [] 

262 def iter_cb(name, *args): 

263 """ Callback to gather attribute names """ 

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

265 

266 cpl = self._id.get_create_plist() 

267 crt_order = cpl.get_attr_creation_order() 

268 cpl.close() 

269 if crt_order & h5p.CRT_ORDER_TRACKED: 

270 idx_type = h5.INDEX_CRT_ORDER 

271 else: 

272 idx_type = h5.INDEX_NAME 

273 

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

275 

276 for name in attrlist: 

277 yield name 

278 

279 @with_phil 

280 def __contains__(self, name): 

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

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

283 

284 @with_phil 

285 def __repr__(self): 

286 if not self._id: 

287 return "<Attributes of closed HDF5 object>" 

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