Add MessageDecoder.get_buffered_data to retrieve final contents

Technologicat · Technologicat · commit 640c927f823f · 2020-01-06T05:16:09.000+02:00
This completes the API abstraction of MessageDecoder; since the ReceiveBuffer
is internal, the user shouldn't have to care about it. (But we're leaving it
in a public attribute, just in case.)
diff --git a/unpythonic/net/msg.py b/unpythonic/net/msg.py
@@ -275,9 +275,9 @@ class MessageDecoder:
                 break
             ...
 
-    A `ReceiveBuffer` is created internally. If you need to access it (e.g.
-    when you're done receiving messages and would like to switch to a raw
-    stream), it's the `buffer` attribute.
+    If you need to access data remaining in the internal buffer (e.g. when
+    you're done receiving messages and would like to switch to a raw stream),
+    call `get_buffered_data`.
     """
     def __init__(self, source):
         """The `source` is a message source in the sense of `decodemsg`."""
@@ -287,3 +287,16 @@ def __init__(self, source):
     def decode(self):
         """Decode next message from source, and update receive buffer."""
         return decodemsg(self.buffer, self.source)
+
+    def get_buffered_data(self):
+        """Return data currently in the receive buffer.
+
+        Usually this is not needed; an application may need this if you intend
+        to switch over from messages back to raw data on an existing stream
+        transport.
+
+        When you're done receiving messages, any remaining data already in the
+        receive buffer should be processed first, before you resume reading and
+        processing any more data from your original stream.
+        """
+        return self.buffer.getvalue()
diff --git a/unpythonic/net/test/test_msg.py b/unpythonic/net/test/test_msg.py
@@ -35,7 +35,7 @@ def test():
     #   whole point of having this protocol).
     #     - Note this means that should you wish to stop receiving messages on a particular
     #       source, and resume reading a raw stream from it instead, you must manually prepend
-    #       the final contents of the receive buffer (`decoder.buffer.getvalue()`) to whatever
+    #       the final contents of the receive buffer (`decoder.get_buffered_data()`) to whatever
     #       data you later receive from that source (since that data has already been placed
     #       into the receive buffer, so it is no longer available at the source).
     #     - So it's recommended to have a dedicated channel to communicate using messages,
