Merge branch 'doc' into v1

pydapsys/file.py

@@ -26,6 +26,7 @@ def __init__(self, element="Target stream", is_type: Optional[str] = None, expec
 
 @dataclass
 class File:
+    """A DAPSYS file. Consists of the root of the table of contents and the dictionary of pages"""
     toc: Root
     pages: dict[int, DataPage]
 
@@ -43,6 +44,12 @@ def get_data(self, path: str, stype: Literal[StreamType.Waveform] = ...) -> Iter
 
     def get_data(self, path: str, stype: Optional[StreamType] = None) -> Union[
         Iterable[DataPage], Iterable[TextPage], Iterable[WaveformPage]]:
+        """
+        Yields all pages associated with the given stream path. To check for sanity, the expected stream type can be passed to the method.
+        :param path: path of the stream in the table of contents (without the root node)
+        :param stype: The expected type of the stream. If the stream is of a different type, the function will raise an exception. None by default.
+        :return: An iterable of all pages associated with the stream
+        """
         entry = self.toc.path(path)
         if not isinstance(entry, Stream):
             raise ToCEEntryIsNotAStreamError(element=path)
@@ -53,5 +60,10 @@ def get_data(self, path: str, stype: Optional[StreamType] = None) -> Union[
 
     @staticmethod
     def from_binary(binio: BinaryIO, byte_order='<') -> File:
+        """Reads a DAPSYS file from the given binary io object and directly constructs a new File class from it.
+        :param binio: BinaryIO object to read from
+        :param byte_order: byte order to use when reading from the binary io object. Defaults to little endian.
+        :return: The File object constructed from the contents of the io stream
+        """
         toc_root, pages = read_from(binio, byte_order=byte_order)
         return File(toc_root, pages)

pydapsys/read.py

@@ -106,6 +106,11 @@ def _read_page(file: DapsysBinaryReader) -> DataPage:
 
 
 def read_from(binio: BinaryIO, byte_order='<') -> Tuple[Root, Dict[int, DataPage]]:
+    """Reads a DAPSYS file from a readable binaryio object
+    :param binio:  binary io to read from
+    :param byte_order: Byte order to use when reading
+    :returns: A tuple containing the Root of the table of contents and a dictionary mapping the page ids to their respective pages
+    """
     dapsys_io = DapsysBinaryReader(binio, byte_order=byte_order)
     dapsys_io.skip(0x30)
     page_count = dapsys_io.read_u32()

pydapsys/toc/display.py

@@ -35,6 +35,7 @@ class PlotType(IntEnum):
 
 @dataclass
 class RGBA8(object):
+    """R(ed)G(reen)(B)lue(A)lpha color"""
     r: int
     g: int
     b: int

pydapsys/toc/entry.py

@@ -68,12 +68,17 @@ def streams(self) -> CaseInsensitiveDictView[Stream]:
 
     @property
     def structure(self) -> Dict:
+        """Returns a dictionary with subdictionaries and strings describing the structure of this objects children"""
         d = dict()
         for v in self.children.values():
             d[v.name] = v.structure if isinstance(v, ChildContainer) else f"{v.stream_type.name};{len(v.page_ids)}"
         return d
 
     def path(self, path: str) -> Entry:
+        """Returns the Entry from the given relative path.
+        :param path: Relative path to the target entry
+        :returns: the target entry
+        """
         splits = path.split('/', 1)
         selected_entry = self[splits[0]]
         if len(splits) == 1: