When you document Python's send, you're going to have to explain that it either appends bytes to the current delivery or delegates to whatever the send behavior happens to be on the passed in object, and then explain how Message has a send behavior that does X. This is much more complex than it should be.
And this new behavior is only present in the Python layer. The C-layer send still just appends bytes. Since at the Python layer people will rapidly begin to think of send only in terms of sending whole messages (because that's what the examples will do), they will be surprised when they attempt the same in C. To me, it would be much better to have append_some_bytes and send_a_message as distinct, self-evident operations. On Wed, Jan 28, 2015 at 7:34 AM, Rafael Schloming <[email protected]> wrote: > > ----------------------------------------------------------- > This is an automatically generated e-mail. To reply, visit: > https://reviews.apache.org/r/30318/#review70001 > ----------------------------------------------------------- > > Ship it! > > > Ship It! > > - Rafael Schloming > > > On Jan. 28, 2015, 12:17 p.m., Gordon Sim wrote: > > > > ----------------------------------------------------------- > > This is an automatically generated e-mail. To reply, visit: > > https://reviews.apache.org/r/30318/ > > ----------------------------------------------------------- > > > > (Updated Jan. 28, 2015, 12:17 p.m.) > > > > > > Review request for qpid and Rafael Schloming. > > > > > > Repository: qpid-proton-git > > > > > > Description > > ------- > > > > Sending a message requires several steps: create a delivery with a > unique tag, encode the message, cal send(), call advance. While this gives > a lot of flexibility and power (e.g. streaming messages in chunks without > ever holding the entire thing in memory), for many, many use cases, a > simpler solution would be adequate and would avoid users having to learn > what is in my view one of the more esoteric aspects of the API. > > > > The attached patch adds send support for a Message object, such that a > message can be sent with a single call. It also allows the send() method to > be 'dual purpose'. It remains backwards compatible as a way of appending > bytes to the current delivery, but can also be used as a one-step call to > send a single message. > > > > At present the engine examples in python make use of a similar > simplification, but one that is added dynamiccaly and is therefore less > clean and obvious. It currently also doesn't work as well for sending on > links established by the remote peer. This addition would in my view allow > for simpler use where needed, without breaking any existing usage. > > > > > > Diffs > > ----- > > > > proton-c/bindings/python/proton/__init__.py 17cef30 > > > > Diff: https://reviews.apache.org/r/30318/diff/ > > > > > > Testing > > ------- > > > > > > Thanks, > > > > Gordon Sim > > > > > >
