Document in-place prefix deletion and the identity assertion

Author: utkarshalpha

src/h2/frame_buffer.py

@@ -155,6 +155,13 @@ def __next__(self) -> Frame:
 
         # At this point, as we know we'll use or discard the entire frame, we
         # can update the data.
+        # Deleting the consumed prefix mutates the bytearray in place instead
+        # of copying the remaining bytes into a new object, as slicing would.
+        # ``del s[i:j]`` is documented for mutable sequences in
+        # https://docs.python.org/3/library/stdtypes.html#mutable-sequence-types
+        # and CPython's bytearray tracks an internal offset (``ob_start`` in
+        # Objects/bytearrayobject.c) that makes repeated deletes from the
+        # front amortized O(1) per byte rather than O(len) per frame.
         del self._data[:9+length]
 
         # Pass the frame through the header buffer.

tests/test_basic_logic.py

@@ -33,6 +33,10 @@ def test_consumed_frames_are_removed_in_place(self) -> None:
 
         next(buffer)
 
+        # ``is`` checks object identity (CPython compares ``id(...)`` of both
+        # operands): the buffer must still be the very same bytearray object,
+        # proving the consumed frame was deleted in place rather than the
+        # buffer being replaced by a sliced copy.
         assert buffer._data is data
         assert buffer._data == frame