djblets.http.responses¶

Specialized HTTP response classes.

class EventStreamMessage[source]¶

Bases: TypedDict

A message in an event stream.

One message may contain an ID, application-defined event type, serialized payload data, and a retry time in milliseconds. These are all optional, but any empty message will be skipped.

New in version 4.0.

data: Optional[Union[bytes, str]]¶

The payload data to send.

This will be sent as the data field.

Type:

bytes or str

event: Optional[str]¶

The event name to send.

This will be sent as the event field.

Type:

str

id: Optional[str]¶

The ID to send.

This will be sent as the id field.

Type:

str

retry_ms: Optional[int]¶

The retry time in milliseconds for reconnections after a disconnect.

This will be sent as the retry field.

Type:

int

__annotations__ = {'data': ForwardRef('NotRequired[Optional[Union[bytes, str]]]', module='djblets.http.responses'), 'event': ForwardRef('NotRequired[Optional[str]]', module='djblets.http.responses'), 'id': ForwardRef('NotRequired[Optional[str]]', module='djblets.http.responses'), 'retry_ms': ForwardRef('NotRequired[Optional[int]]', module='djblets.http.responses')}¶

__optional_keys__ = frozenset({})¶

__orig_bases__ = (<function TypedDict>,)¶

__required_keys__ = frozenset({'data', 'event', 'id', 'retry_ms'})¶

__total__ = True¶

EventStreamMessages¶

An iterator for event stream messages.

New in version 4.0.

alias of Iterator[EventStreamMessage]

EventStream¶

An event stream that generates messages.

This may be an iterator of messages, or a callable that takes an optional Last-Event-ID header value and then yields messages.

New in version 4.0.

alias of Union[Iterator[EventStreamMessage], Callable[[Optional[str]], Iterator[EventStreamMessage]]]

class EventStreamHttpResponse(event_stream: EventStream, *, request: Optional[HttpRequest] = None, status: int = 200, content_type: str = 'text/event-stream', **kwargs)[source]¶

Bases: StreamingHttpResponse

A Server-Sent Events (SSE) HTTP response.

This manages a response containing Server-Sent Events, which can be used to continuously stream content (events, data, IDs, and retry intervals) to a caller in a standardized way.

Server-Sent Events are useful for long-running, resumeable process, such as conveying progress for long-running but interruptible operations, new updates to content, or events on a message bus.

Providers of SSE responses can use the Last-Event-ID header value to determine where the client left off, and resume from that point. If a function is passed as the event stream source, it will receive any value in this header as an argument.

Note

On HTTP/1.1 connections, web browsers are limited to 6 concurrent HTTP connections to the same domain across all tabs, and a long-running SSE stream will consume one of those slots until it ends.

HTTP/2 connections have a higher limit.

For widest compatibility when serving over HTTP/1.1 connections, it’s recommended to use shorter-lived, resumeable SSE responses.

New in version 4.0.

streaming = True[source]¶

__init__(event_stream: EventStream, *, request: Optional[HttpRequest] = None, status: int = 200, content_type: str = 'text/event-stream', **kwargs) → None[source]¶

Initialize the event stream.

The provided event stream source will be processed when sending content to the client, and not before.

Parameters:

• event_stream (callable or generator) – The event stream as a generator or a callable yielding results.

• request (django.http.HttpRequest, optional) – The HTTP request from the client.

• status (int, optional) – The HTTP status code to send in the response.

• content_type (str, optional) –

  The content type to send in the response.

  For greatest compatibility, this should be left as the default of text/event-stream.

• **kwargs (dict) – Additional keyword arguments to pass to the parent constructor.

event_stream: EventStream¶

The event stream providing values for the response.

Type:

callable or generator

__annotations__ = {'event_stream': 'EventStream', 'request': 'Optional[HttpRequest]'}¶

request: Optional[HttpRequest]¶

The HTTP request from the client, if provided to the response.

Type:

django.http.HttpRequest