Merge pull request #408

MPT-24897 Document truncation, retry and stub errors on stream()

Author: jentyk

docs/streaming.md

@@ -291,7 +291,9 @@ contract uses for it:
 Only `id` is guaranteed on a stub. No other property of the deleted row is carried. A
 **truthy** `deleted` marker is what identifies a stub; a record with no `$meta`, no `deleted`
 key, or a falsy one is data. In practice the platform omits `$meta` entirely on a normal
-record, so those cases are defensive rather than expected.
+record, so those cases are defensive rather than expected. A stub that carries no string
+`id` breaks the one guarantee the contract makes, so `stream()` raises `TypeError` rather
+than yielding a stub that identifies nothing.
 
 `stream()` yields these as `DeletionStub`, never as a model, so the object cannot be mistaken
 for a record by code that expects one. Deserializing a stub as a model would produce an

mpt_api_client/http/mixins/streaming_mixin.py

@@ -553,20 +553,28 @@ def stream(
             models when ``skip_deleted`` is set.
 
         Raises:
+            MPTMaxRetryError: If opening the response fails after maximum retry attempts;
+                transparent retry ends once the response commits, so it never follows
+                the first record.
             MPTStreamingNotEnabledError: If the API does not confirm streaming mode.
             MPTStreamingFormatMismatchError: If the response ``Content-Type`` names a
                 media type other than the requested format.
             MPTStreamingNotSupportedError: If the resource cannot stream (``501``).
             MPTStreamingNotAcceptableError: If the requested format is unsupported (``406``).
             MPTStreamingOverCapError: If the export exceeds the configured cap (``413``).
             MPTStreamingItemCountMissingError: If the response declares no usable item count.
+            MPTStreamingTruncatedError: If the connection aborts mid-body, ending the
+                response before the HTTP message completes; the records yielded before
+                the abort are an incomplete snapshot to discard.
             MPTStreamingIncompleteError: If the fully consumed stream does not match the
                 declared item count.
             JSONDecodeError: If the body cannot be parsed in the requested wire format —
                 a malformed or non-object record line in the line-delimited format, or a
                 malformed or unterminated envelope in the envelope format.
             ValueError: If ``stream_format`` is neither a `StreamFormat` member nor a
                 member's value.
+            TypeError: If a deletion stub carries no string ``id``, the one property the
+                contract guarantees on a stub.
         """
         # Coerce eagerly: an equal plain string becomes its member, anything else fails
         # with a clear ValueError instead of an AttributeError deep in header building.
@@ -736,20 +744,28 @@ async def stream(
             models when ``skip_deleted`` is set.
 
         Raises:
+            MPTMaxRetryError: If opening the response fails after maximum retry attempts;
+                transparent retry ends once the response commits, so it never follows
+                the first record.
             MPTStreamingNotEnabledError: If the API does not confirm streaming mode.
             MPTStreamingFormatMismatchError: If the response ``Content-Type`` names a
                 media type other than the requested format.
             MPTStreamingNotSupportedError: If the resource cannot stream (``501``).
             MPTStreamingNotAcceptableError: If the requested format is unsupported (``406``).
             MPTStreamingOverCapError: If the export exceeds the configured cap (``413``).
             MPTStreamingItemCountMissingError: If the response declares no usable item count.
+            MPTStreamingTruncatedError: If the connection aborts mid-body, ending the
+                response before the HTTP message completes; the records yielded before
+                the abort are an incomplete snapshot to discard.
             MPTStreamingIncompleteError: If the fully consumed stream does not match the
                 declared item count.
             JSONDecodeError: If the body cannot be parsed in the requested wire format —
                 a malformed or non-object record line in the line-delimited format, or a
                 malformed or unterminated envelope in the envelope format.
             ValueError: If ``stream_format`` is neither a `StreamFormat` member nor a
                 member's value.
+            TypeError: If a deletion stub carries no string ``id``, the one property the
+                contract guarantees on a stub.
         """
         # Coerce eagerly: an equal plain string becomes its member, anything else fails
         # with a clear ValueError instead of an AttributeError deep in header building.