Coverage for src/evutils/io/_bin.py: 75%

1"""Binary (.bin) file decoder and encoder. 

2 

3.. note:: 

4 Not implemented yet: both classes raise :class:`NotImplementedError` on 

5 construction. The classes exist so the ``.bin`` extension is reserved in 

6 the reader/writer registries and the error message is explicit. 

7""" 

8 

9import numpy as np 

10from ..types import EventArray, TriggerArray 

11from .common import EventDecoder, EventEncoder 

12 

13_NOT_IMPLEMENTED = ( 

14 "The .bin event format is not implemented yet. " 

15 "Convert the file to a supported format (RAW/EVT, DAT, AER, HDF5, NPZ, CSV) " 

16 "or pass an explicit file_decoder/file_encoder." 

17) 

18 

19class EventDecoder_Bin(EventDecoder): 

20 """A decoder for reading events from binary files. 

21 

22 .. note:: 

23 Not implemented yet -- constructing this class raises 

24 :class:`NotImplementedError`. 

25 

26 Parameters 

27 ---------- 

28 source : ByteSource 

29 Byte source to read events from. 

30 **kwargs 

31 Additional decoder arguments. 

32 

33 Raises 

34 ------ 

35 NotImplementedError 

36 Always, until the format is implemented. 

37 

38 """ 

39 

40 def __init__(self, source: "io.BufferedIOBase | str | bytes", **kwargs): 

41 raise NotImplementedError(_NOT_IMPLEMENTED) 

42 

43 def init(self) -> None: 

44 """Initialize the file for reading.""" 

45 raise NotImplementedError(_NOT_IMPLEMENTED) 

46 

47 def read_chunk(self, delta_t_hint: int | None = None, n_events_hint: int | None = None) -> "np.ndarray | EventArray | None": 

48 """Read a chunk of events.""" 

49 raise NotImplementedError(_NOT_IMPLEMENTED) 

50 

51 def reset(self) -> None: 

52 """Reset the file pointer to the beginning of the file.""" 

53 raise NotImplementedError(_NOT_IMPLEMENTED) 

54 

55class EventEncoder_Bin(EventEncoder): 

56 """An encoder for writing events to binary files. 

57 

58 .. note:: 

59 Not implemented yet -- constructing this class raises 

60 :class:`NotImplementedError`. 

61 

62 Parameters 

63 ---------- 

64 writable : io.BufferedIOBase 

65 Destination for writing events. 

66 **kwargs 

67 Additional encoder arguments (``width``, ``height``, ``dt``, ...). 

68 

69 Raises 

70 ------ 

71 NotImplementedError 

72 Always, until the format is implemented. 

73 

74 """ 

75 

76 def __init__(self, writable: "io.BufferedIOBase", **kwargs): 

77 raise NotImplementedError(_NOT_IMPLEMENTED) 

78 

79 def init(self) -> None: 

80 """Initialize the file for writing.""" 

81 raise NotImplementedError(_NOT_IMPLEMENTED) 

82 

83 def write(self, events: 'np.ndarray | EventArray', triggers: 'np.ndarray | TriggerArray | None' = None) -> int: 

84 """Write a chunk of events.""" 

85 raise NotImplementedError(_NOT_IMPLEMENTED)