[RFC] Alternative approach to "related events".

h2/connection.py

@@ -1402,6 +1402,7 @@ def _receive_headers_frame(self, frame):
 
         if 'PRIORITY' in frame.flags:
             p_frames, p_events = self._receive_priority_frame(frame)
+            stream_events[0].priority_updated = p_events[0]
             stream_events.extend(p_events)
             assert not p_frames
 

h2/events.py

@@ -23,6 +23,9 @@ class RequestReceived(object):
     .. versionchanged:: 2.3.0
        Changed the type of ``headers`` to :class:`HeaderTuple
        <hpack:hpack.HeaderTuple>`. This has no effect on current users.
+
+    .. versionchanged:: 2.4.0
+       Added ``stream_ended`` and ``priority_updated`` properties.
     """
     def __init__(self):
         #: The Stream ID for the stream this request was made on.
@@ -31,6 +34,20 @@ def __init__(self):
         #: The request headers.
         self.headers = None
 
+        #: If this request also ended the stream, the associated
+        #: :class:`StreamEnded <h2.events.StreamEnded>` event will be available
+        #: here.
+        #:
+        #: .. versionadded:: 2.4.0
+        self.stream_ended = None
+
+        #: If this request also had associated priority information, the
+        #: associated :class:`PriorityUpdated <h2.events.PriorityUpdated>`
+        #: event will be available here.
+        #:
+        #: .. versionadded:: 2.4.0
+        self.priority_updated = None
+
     def __repr__(self):
         return "<RequestReceived stream_id:%s, headers:%s>" % (
             self.stream_id, self.headers
@@ -46,6 +63,9 @@ class ResponseReceived(object):
     .. versionchanged:: 2.3.0
        Changed the type of ``headers`` to :class:`HeaderTuple
        <hpack:hpack.HeaderTuple>`. This has no effect on current users.
+
+   .. versionchanged:: 2.4.0
+      Added ``stream_ended`` and ``priority_updated`` properties.
     """
     def __init__(self):
         #: The Stream ID for the stream this response was made on.
@@ -54,6 +74,20 @@ def __init__(self):
         #: The response headers.
         self.headers = None
 
+        #: If this response also ended the stream, the associated
+        #: :class:`StreamEnded <h2.events.StreamEnded>` event will be available
+        #: here.
+        #:
+        #: .. versionadded:: 2.4.0
+        self.stream_ended = None
+
+        #: If this response also had associated priority information, the
+        #: associated :class:`PriorityUpdated <h2.events.PriorityUpdated>`
+        #: event will be available here.
+        #:
+        #: .. versionadded:: 2.4.0
+        self.priority_updated = None
+
     def __repr__(self):
         return "<ResponseReceived stream_id:%s, headers:%s>" % (
             self.stream_id, self.headers
@@ -72,6 +106,9 @@ class TrailersReceived(object):
     .. versionchanged:: 2.3.0
        Changed the type of ``headers`` to :class:`HeaderTuple
        <hpack:hpack.HeaderTuple>`. This has no effect on current users.
+
+    .. versionchanged:: 2.4.0
+       Added ``stream_ended`` and ``priority_updated`` properties.
     """
     def __init__(self):
         #: The Stream ID for the stream on which these trailers were received.
@@ -80,6 +117,19 @@ def __init__(self):
         #: The trailers themselves.
         self.headers = None
 
+        #: Trailers always end streams. This property has the associated
+        #: :class:`StreamEnded <h2.events.StreamEnded>` in it.
+        #:
+        #: .. versionadded:: 2.4.0
+        self.stream_ended = None
+
+        #: If the trailers also set associated priority information, the
+        #: associated :class:`PriorityUpdated <h2.events.PriorityUpdated>`
+        #: event will be available here.
+        #:
+        #: .. versionadded:: 2.4.0
+        self.priority_updated = None
+
     def __repr__(self):
         return "<TrailersReceived stream_id:%s, headers:%s>" % (
             self.stream_id, self.headers
@@ -104,6 +154,9 @@ class InformationalResponseReceived(object):
     .. versionchanged:: 2.3.0
        Changed the type of ``headers`` to :class:`HeaderTuple
        <hpack:hpack.HeaderTuple>`. This has no effect on current users.
+
+    .. versionchanged:: 2.4.0
+       Added ``priority_updated`` property.
     """
     def __init__(self):
         #: The Stream ID for the stream this informational response was made
@@ -113,6 +166,13 @@ def __init__(self):
         #: The headers for this informational response.
         self.headers = None
 
+        #: If this response also had associated priority information, the
+        #: associated :class:`PriorityUpdated <h2.events.PriorityUpdated>`
+        #: event will be available here.
+        #:
+        #: .. versionadded:: 2.4.0
+        self.priority_updated = None
+
     def __repr__(self):
         return "<InformationalResponseReceived stream_id:%s, headers:%s>" % (
             self.stream_id, self.headers
@@ -138,6 +198,13 @@ def __init__(self):
         #: than ``len(data)``.
         self.flow_controlled_length = None
 
+        #: If this data chunk also completed the stream, the associated
+        #: :class:`StreamEnded <h2.events.StreamEnded>` event will be available
+        #: here.
+        #:
+        #: .. versionadded:: 2.4.0
+        self.stream_ended = None
+
     def __repr__(self):
         return (
             "<DataReceived stream_id:%s, "

h2/stream.py

@@ -901,9 +901,11 @@ def receive_headers(self, headers, end_stream, header_encoding):
         events = self.state_machine.process_input(input_)
 
         if end_stream:
-            events += self.state_machine.process_input(
+            es_events = self.state_machine.process_input(
                 StreamInputs.RECV_END_STREAM
             )
+            events[0].stream_ended = es_events[0]
+            events += es_events
 
         self._initialize_content_length(headers)
 
@@ -926,9 +928,11 @@ def receive_data(self, data, end_stream, flow_control_len):
         self._track_content_length(len(data), end_stream)
 
         if end_stream:
-            events += self.state_machine.process_input(
+            es_events = self.state_machine.process_input(
                 StreamInputs.RECV_END_STREAM
             )
+            events[0].stream_ended = es_events[0]
+            events.extend(es_events)
 
         events[0].data = data
         events[0].flow_controlled_length = flow_control_len