Provide control over fragmentation of outgoing frames

[aaugustin]

Currently websockets doesn't provide a way to fragment outgoing messages.

I'm not sure about the use case.

The spec makes it technically possible so it might be good to support it?

[aaugustin]

Two APIs may make send here:

1. Have send() accept iterables of str or bytes; it will send each chunk in a frame and return when the iterable is exhausted. This gives the user complete control but doesn't seem convenient for simple use cases such as "don't send a frame larger than 64kB".

2. Add a parameter to the protocol to define the maximum size of an outgoing frame and fragment automatically messages larger than this value. The value should be in bytes i.e. after utf-8 encoding.

Both could be implemented.

If both are used simultaneously, I don't know if explicit fragmentation (1.) or automatic fragmentation (2.) should have precedence. Should websockets refragment messages that the user explicitly fragmented, if a fragment exceeds the maximum size? Either choice could be surprising. Perhaps better not, in order to keep the implementation simple...

[aaugustin]

A variant of 1. would be to support asynchronous iteration as well. However, this opens another can of worms: no other data frame should be sent until the fragmented data frame is fully sent.

[aaugustin]

The RFC says:

The primary purpose of fragmentation is to allow sending a message that is of unknown size when the message is started without having to buffer that message.

Option 1 is a better match for this.

Option 2 can be implemented by end users on top of option 1 if they desire.

[aaugustin]

It would be nice to support async iterators as well as regular iterators. However that's complicated on Python < 3.5, without async for.