More docs and tests

Signed-off-by: Andrea Zoppi <texzk@email.it>
TexZK · Feb 5, 2024 · 71fc887 · 71fc887
1 parent 686617d
commit 71fc887
Show file tree

Hide file tree

Showing 27 changed files with 584 additions and 60 deletions.
diff --git a/docs/_autosummary/hexrec.base.BaseFile.rst b/docs/_autosummary/hexrec.base.BaseFile.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: BaseFile
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.base.BaseRecord.rst b/docs/_autosummary/hexrec.base.BaseRecord.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: BaseRecord
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.base.BaseTag.rst b/docs/_autosummary/hexrec.base.BaseTag.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: BaseTag
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.asciihex.AsciiHexFile.rst b/docs/_autosummary/hexrec.formats.asciihex.AsciiHexFile.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: AsciiHexFile
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.asciihex.AsciiHexRecord.rst b/docs/_autosummary/hexrec.formats.asciihex.AsciiHexRecord.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: AsciiHexRecord
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.asciihex.AsciiHexTag.rst b/docs/_autosummary/hexrec.formats.asciihex.AsciiHexTag.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: AsciiHexTag
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.ihex.IhexFile.rst b/docs/_autosummary/hexrec.formats.ihex.IhexFile.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: IhexFile
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.ihex.IhexRecord.rst b/docs/_autosummary/hexrec.formats.ihex.IhexRecord.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: IhexRecord
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.ihex.IhexTag.rst b/docs/_autosummary/hexrec.formats.ihex.IhexTag.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: IhexTag
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.mos.MosFile.rst b/docs/_autosummary/hexrec.formats.mos.MosFile.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: MosFile
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.mos.MosRecord.rst b/docs/_autosummary/hexrec.formats.mos.MosRecord.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: MosRecord
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.mos.MosTag.rst b/docs/_autosummary/hexrec.formats.mos.MosTag.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: MosTag
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.raw.RawFile.rst b/docs/_autosummary/hexrec.formats.raw.RawFile.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: RawFile
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.raw.RawRecord.rst b/docs/_autosummary/hexrec.formats.raw.RawRecord.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: RawRecord
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.raw.RawTag.rst b/docs/_autosummary/hexrec.formats.raw.RawTag.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: RawTag
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.srec.SrecFile.rst b/docs/_autosummary/hexrec.formats.srec.SrecFile.rst
@@ -1,10 +1,11 @@
-hexrec.formats.srec.SrecFile
+hexrec.formats.srec.SrecFile
 ============================
 
 .. currentmodule:: hexrec.formats.srec
 
 .. autoclass:: SrecFile
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.srec.SrecRecord.rst b/docs/_autosummary/hexrec.formats.srec.SrecRecord.rst
@@ -1,10 +1,11 @@
-hexrec.formats.srec.SrecRecord
+hexrec.formats.srec.SrecRecord
 ==============================
 
 .. currentmodule:: hexrec.formats.srec
 
 .. autoclass:: SrecRecord
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.srec.SrecTag.rst b/docs/_autosummary/hexrec.formats.srec.SrecTag.rst
@@ -1,10 +1,11 @@
-hexrec.formats.srec.SrecTag
+hexrec.formats.srec.SrecTag
 ===========================
 
 .. currentmodule:: hexrec.formats.srec
 
 .. autoclass:: SrecTag
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.xtek.XtekFile.rst b/docs/_autosummary/hexrec.formats.xtek.XtekFile.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: XtekFile
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.xtek.XtekRecord.rst b/docs/_autosummary/hexrec.formats.xtek.XtekRecord.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: XtekRecord
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_autosummary/hexrec.formats.xtek.XtekTag.rst b/docs/_autosummary/hexrec.formats.xtek.XtekTag.rst
@@ -5,6 +5,7 @@
 
 .. autoclass:: XtekTag
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/docs/_templates/custom-class-template.rst b/docs/_templates/custom-class-template.rst
@@ -1,9 +1,10 @@
-{{ fullname | escape | underline }}
+{{ fullname | escape | underline}}
 
 .. currentmodule:: {{ module }}
 
 .. autoclass:: {{ objname }}
    :members:
+   :inherited-members:
    :private-members:
    :special-members:
 

diff --git a/src/hexrec/formats/raw.py b/src/hexrec/formats/raw.py
@@ -79,7 +79,6 @@ def create_data(
         address: int,
         data: AnyBytes,
     ) -> 'RawRecord':
-        # TODO: __doc__
 
         address = address.__index__()
         if address < 0:
@@ -142,8 +141,52 @@ def parse(
         maxdatalen: int = sys.maxsize,
         address: int = 0,
     ) -> 'RawFile':
-        # TODO: __doc__
-
+        r"""Parses records from a byte stream.
+
+        It executes :meth:`RawRecord.parse` for each line of the incoming
+        `stream`, creating a new file object with the collected records calling
+        :meth:`from_records`.
+
+        Notes:
+            Please refer to the actual implementation of each record file
+            *format*, because it may be more specialized.
+
+        Args:
+            stream (bytes IO):
+                Stream to serialize records onto.
+
+            ignore_errors (bool):
+                Ignore :class:`Exception` raised by :meth:`RawRecord.parse`.
+
+            maxdatalen (int):
+                Maximum *data* record data size, to chop the incoming stream.
+
+            address (int):
+                Initial address.
+
+        Returns:
+            :class:`RawFile`: *self*.
+
+        See Also:
+            :meth:`parse`
+            :meth:`BaseRecord.parse`
+            :meth:`from_records`
+
+        Examples:
+            >>> from hexrec import RawFile
+            >>> import io
+            >>> stream = io.BytesIO(b'Hello, World!')
+            >>> file = RawFile.parse(stream, maxdatalen=5, address=1000)
+            >>> for record in file.records:
+            ...     print(f'{record.address}: {record.data!r}')
+            1000: b'Hello'
+            1005: b', Wor'
+            1010: b'ld!'
+            >>> file.get_meta()
+            {'maxdatalen': 5}
+        """
+
+        del ignore_errors  # unused
         maxdatalen = maxdatalen.__index__()
         if maxdatalen < 1:
             raise ValueError('invalid maximum data length')
@@ -171,7 +214,47 @@ def update_records(
         self,
         align: bool = False,
     ) -> 'RawFile':
-        # TODO: __doc__
+        r"""Applies memory and meta to records.
+
+        This method processes the stored :attr:`memory` and *meta* information
+        to generate the sequence of :attr:`records`.
+
+        This effectively converts the *memory role* into the *records role*
+        (keeping both).
+
+        The :attr:`records` is assigned upon return.
+        Any exceptions being raised should not alter the file object.
+
+        Args:
+            align (bool):
+                Aligns data record chunk address bounds to :attr:`maxdatalen`.
+
+        Returns:
+            :class:`RawFile`: *self*.
+
+        Raises:
+            ValueError: :attr:`memory` attribute not populated.
+
+        See Also:
+            :attr:`records`
+            :attr:`memory`
+            :meth:`get_meta`
+            :meth:`apply_records`
+
+        Examples:
+            >>> from hexrec import RawFile
+            >>> blocks = [[123, b'abc']]
+            >>> file = RawFile.from_blocks(blocks, maxdatalen=16)
+            >>> file.memory.to_blocks()
+            [[123, b'abc']]
+            >>> file.get_meta()
+            {'maxdatalen': 16}
+            >>> _ = file.update_records()
+            >>> len(file.records)
+            1
+            >>> _ = file.print()
+            abc
+        """
 
         memory = self._memory
         if memory is None:
@@ -199,14 +282,48 @@ def update_records(
 
     def validate_records(
         self,
+        data_start: bool = True,
         data_contiguity: bool = True,
         data_ordering: bool = True,
     ) -> 'RawFile':
-        # TODO: __doc__
+        r"""Validates records.
+
+        It performs consistency checks for the underlying :attr:`records`.
+
+        Args:
+            data_start (bool):
+                Data records must start from address zero.
+
+            data_contiguity (bool):
+                Requires *data* records be ordered and contiguous.
+
+            data_ordering (bool):
+                Checks that the *data* record sequence has monotonically
+                increasing addresses, without any overlapping.
+
+        Returns:
+            :class:`RawFile`: *self*.
+
+        Raises:
+            ValueError: Invalid record sequence.
+
+        Examples:
+            >>> from hexrec import RawFile
+            >>> records = [RawFile.Record.create_data(123, b'abc')]
+            >>> file = RawFile.from_records(records)
+            >>> file.validate_records()
+            Traceback (most recent call last):
+                ...
+            ValueError: first record address not zero
+        """
 
         if self._records is None:
             raise ValueError('records required')
 
+        if data_start and self._records:
+            if self._records[0].address != 0:
+                raise ValueError('first record address not zero')
+
         last_data_end = None
 
         for record in self._records: