Re: Proton API layout proposal

[Rafael Schloming <rh...@alum.mit.edu>]

On Thu, Jan 29, 2015 at 9:56 AM, Justin Ross <ju...@gmail.com> wrote:

> On Wed, Jan 28, 2015 at 3:36 PM, Justin Ross <ju...@gmail.com>
> wrote:
> >
> >  - Python is using utils, not util.  I don't care whether we go util or
> > utils, but I'd very much like to avoid it being half one way and half the
> > other.  If we decide utils, I'll update the wiki page.
> >
>
> Distinct from the naming consistency question, util[s] has an ambiguity of
> purpose that I think is important to resolve--particularly in Python,
> because it's difficult to have clean dependencies if we don't.
>
> These are the two ways people tend use util:
>
>  1. Functions and classes for internal use by other parts of the proton
> library; that is, handy stuff that your language library didn't give you
>  2. Functions and classes for external use by consumers of proton
>
> PROTON-805 adds more of the latter to proton/utils.py, and it already had
> BlockingConnection.  Having both types of util in one module ends up making
> imports a mess because it contains at once quite low-level things and
> high-level things.
>
> Maybe we should have proton/extras.py for stuff like BlockingConnection and
> SyncRequestResponseHandler and reserve utils.py for the internal utility
> code.
>

Are you thinking of extras.py as being like contrib or something different?
(FYI, we already have a contrib on the proton-j side of things, so having a
proton/contrib.py would be consistent.)

I definitely agree that PROTON-805 is making dubious use of the utils
package, not only for the reasons you state, but also because the general
request/response scenario should probably at some point be supported in a
more core way, and that might result in a different API. I could be wrong
since I haven't actually looked into how it works and it might be just
fine, but I'd be inclined to put it into a more sandboxy area for the
moment. Someplace where it's ok to leave it for a bit to provide backwards
compatibility even if it's functionality is subsumed by other APIs.

--Rafael

Re: Proton API layout proposal

[Justin Ross <ju...@gmail.com>]

Yes, quite a lot like contrib.  I think that's a fine name.  If no one else
objects, I'll add that to our api layout doc.

On Mon, Feb 2, 2015 at 4:20 PM, Rafael Schloming <rh...@alum.mit.edu> wrote:

> On Thu, Jan 29, 2015 at 9:56 AM, Justin Ross <ju...@gmail.com>
> wrote:
>
> > On Wed, Jan 28, 2015 at 3:36 PM, Justin Ross <ju...@gmail.com>
> > wrote:
> > >
> > >  - Python is using utils, not util.  I don't care whether we go util or
> > > utils, but I'd very much like to avoid it being half one way and half
> the
> > > other.  If we decide utils, I'll update the wiki page.
> > >
> >
> > Distinct from the naming consistency question, util[s] has an ambiguity
> of
> > purpose that I think is important to resolve--particularly in Python,
> > because it's difficult to have clean dependencies if we don't.
> >
> > These are the two ways people tend use util:
> >
> >  1. Functions and classes for internal use by other parts of the proton
> > library; that is, handy stuff that your language library didn't give you
> >  2. Functions and classes for external use by consumers of proton
> >
> > PROTON-805 adds more of the latter to proton/utils.py, and it already had
> > BlockingConnection.  Having both types of util in one module ends up
> making
> > imports a mess because it contains at once quite low-level things and
> > high-level things.
> >
> > Maybe we should have proton/extras.py for stuff like BlockingConnection
> and
> > SyncRequestResponseHandler and reserve utils.py for the internal utility
> > code.
> >
>
> Are you thinking of extras.py as being like contrib or something different?
> (FYI, we already have a contrib on the proton-j side of things, so having a
> proton/contrib.py would be consistent.)
>
> I definitely agree that PROTON-805 is making dubious use of the utils
> package, not only for the reasons you state, but also because the general
> request/response scenario should probably at some point be supported in a
> more core way, and that might result in a different API. I could be wrong
> since I haven't actually looked into how it works and it might be just
> fine, but I'd be inclined to put it into a more sandboxy area for the
> moment. Someplace where it's ok to leave it for a bit to provide backwards
> compatibility even if it's functionality is subsumed by other APIs.
>
> --Rafael
>