Coverage for src/metador_core/ih5/__init__.py: 100%

1"""Immutable HDF5-based multi-container records. 

2 

3This API **supports a subset of h5py**, namely reading, writing and deleting groups, 

4values and attributes. It **does not** support [hard, symbolic or external 

5links](https://docs.h5py.org/en/latest/high/group.html#link-classes), 

6so the data must be self-contained and strictly hierarchical. 

7 

8 

9**Correspondence of IH5 overlay classes and raw h5py classes:** 

10 

11| IH5 API | h5py | 

12| ------------ | ------------ | 

13| `IH5Record` | [h5py.File](https://docs.h5py.org/en/latest/high/file.html) | 

14| `IH5Group` | [h5py.Group](https://docs.h5py.org/en/latest/high/group.html) | 

15| `IH5Dataset` | [h5py.Dataset](https://docs.h5py.org/en/latest/high/dataset.html) | 

16| `IH5AttributeManager` | [h5py.AttributeManager](https://docs.h5py.org/en/latest/high/attr.html) | 

17 

18Anything that can be done to an IH5 Group, Dataset or AttributeManager can also be done to 

19the h5py counterparts. 

20 

21If you are missing some functionality from h5py in the overlay classes, 

22please contact us or open an issue and we will see whether and how the missing 

23methods can be added in a coherent manner matching the IH5 semantics. 

24 

25## Getting Started 

26 

27A quite minimal working example: 

28 

29```python 

30# just use IH5Record instead of h5py.File: 

31from metador_core.ih5.container import IH5Record 

32 

33 

34# initial creation: 

35with IH5Record("record_name", "w") as ds: 

36 # A new record is automatically in writable mode, 

37 # so let us write some data, just like with h5py: 

38 ds["foo/bar"] = "something" 

39 ds["foo"].attrs["attribute"] = 123 

40 

41# updating the record we created later on: 

42with IH5Record("record_name", "r") as ds: 

43 # A record is opened in read-only mode, so 

44 # before we can add, modify or delete anything, we need to call: 

45 ds.create_patch() 

46 

47 del ds["foo/bar"] 

48 ds["/foo/bar/baz"] = [1, 2, 3] 

49``` 

50 

51You SHOULD use `IH5Record` as a context manager, like in the example above. 

52If you for some reason do not, be aware that you MUST manually call `commit()` 

53to finilize your changes. You can also just use `close()`, which will also call 

54`commit()` for you. **Consider it good practice calling `commit()` 

55manually after completing your updates of the record.** 

56"""