diff --git a/atrcopy/container.py b/atrcopy/container.py index 330f25d..d357513 100644 --- a/atrcopy/container.py +++ b/atrcopy/container.py @@ -9,6 +9,13 @@ from .utils import to_numpy class DiskImageContainer: + """Unpacker for disk image compression. + + Disk images may be compressed by any number of techniques. Subclasses of + DiskImageContainer implement the `unpack_bytes` method which examines the + byte_data argument for the supported compression type, and if valid returns + the unpacked bytes to be used in the disk image parsing. + """ def __init__(self, data): self.unpacked = self.__unpack_raw_data(data) @@ -18,6 +25,22 @@ class DiskImageContainer: return to_numpy(unpacked) def unpack_bytes(self, byte_data): + """Attempt to unpack `byte_data` using this unpacking algorithm. + + `byte_data` is a byte string, and should return a byte string if + successfully unpacked. Conversion to a numpy array will take place + automatically, outside of this method. + + If the data is not recognized by this subclass, raise an + InvalidContainer exception. This signals to the caller that a different + container type should be tried. + + If the data is recognized by this subclass but the unpacking algorithm + is not implemented, raise an UnsupportedContainer exception. This is + different than the InvalidContainer exception because it indicates that + the data was indeed recognized by this subclass (despite not being + unpacked) and checking further containers is not necessary. + """ pass diff --git a/atrcopy/dcm.py b/atrcopy/dcm.py index 0982f77..ec4d0ca 100644 --- a/atrcopy/dcm.py +++ b/atrcopy/dcm.py @@ -16,7 +16,7 @@ class DCMContainer(DiskImageContainer): try: data = self.raw[self.index] except IndexError: - raise errors.InvalidContainer + raise errors.InvalidContainer("Incomplete DCM file") else: self.index += 1 return data @@ -38,4 +38,11 @@ class DCMContainer(DiskImageContainer): raise errors.InvalidContainer(f"Unsupported density flag {density_flag} in DCM") else: raise errors.InvalidContainer("Not a DCM file") + + # DCM decoding goes here. Currently, instead of decoding it raises the + # UnsupportedContainer exception, which signals to the caller that the + # container has been successfully identified but can't be parsed. + # + # When decoding is supported, return the decoded byte array instead of + # this exception. raise errors.UnsupportedContainer("DCM archives are not yet supported")