On Wed, Feb 18, 2015 at 10:53 AM, Justin Ross <justin.r...@gmail.com> wrote:
> On Wed, Feb 18, 2015 at 9:28 AM, Rafael Schloming <r...@alum.mit.edu> > wrote: > > > A couple of comments in no particular order... > > > > The "Core user model and uitility classes" description could be > > misinterpreted on a quick read. Maybe go with "Core protocol model..." or > > something like that? (Really all these APIs are for users, so it seems > > weird to mention it.) Also the utility classes mentioned here sound like > > they overlap with the util package. What is that actually referring to? > > > > Yes, good point. I'll go with protocol instead. > > If I could, I'd make util go away. It's for low-level things (not Proton > extensions, but language library extensions) that we wish to make public. > The best example we currently have is URL. > I actually was asking about the utility classes refered to in your "Core user model and utility classes". It sounds like there are utility classes directly in the proton package and utility classes in proton.util, which I don't think is actually the case. > > I like the proton.security addition, I think that makes sense as security > > is generally handled in one contained place in any application. > > > > I'm not so hot on the types subpackage. I don't think it actually buys > us a > > lot in terms of uncluttering core since there are only a few very simple > > things in that category. It basically consists of about 5 or so pure > > constructors that extend builtin python types with extra information, > e.g. > > timestamp which is just a subclass of long that gets encoded on the wire > as > > a timestamp. It's implementation is literally just this[1], as you can > see > > it adds very little surface area to the API. The other items in this > > category are similarly simple. Conceptually these types really are part > of > > the core protocol model, and unlike in the case of security, if your app > > does need to deal with timestamps or unsigned numbers or whatever, it is > > pretty likely that it will need to do it all over the place which means > > that you basically always need to do two imports in order to get the full > > protocol model. > > > > > http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html#section-primitive-type-definitions > > The number of AMQP primitive types is comparable to the number of endpoint > types. A given language may not need all the types, but it will likely > need more than half of them. Some of these will not find frequent use, > such as the decimal types. > > I think it is a source of clutter (the implementation size is not a factor > here; instead it's the number of things in a namespace). The grouping has > the additional benefit of clarifying that these are all things of one sort. > > Are there particular types that you think will find frequent use and should > be promoted to the "core" level? I too would like to consolidate the > imports, but I disagree about the scale of the clutter problem. > If you're talking about the java link you reference below, that's not a good way to measure the clutter. It includes all classes in all the sub packages, so all the types would be there regardless of whether they are in a sub package or not. I think the situation with clutter in the proton package in python is probably significantly improved now since we got rid of Driver and some other deprecated stuff. > > Gordon's python examples don't seem to import any types. For most higher > level languages, I would hope this would be the case. > >From a quick scan it looks like all the examples are using u"Hello World" as the message content. If we were to add in examples of sending more structured data, then your impression of common usage might change. Based on some use I've made of the API for implementing a message based protocol on top of AMQP, timestamp is pretty common. I suspect there are lots of scenarios where symbol and array would also be quite important. I know it's tempting to ignore arrays since they don't map well to a builtin python type, but arrays in particular can save you *significant* encoding overhead, e.g. sending an array of integers will save you 25% encoding overhead relative to sending a list of integers. This would be critical in a bunch of different scenarios, e.g. any sort of numeric computing with vectors and matrices, any sort of monitoring involving time series data. A lot those scenarios might also care about signed vs unsigned numbers as well as the actual precision of the value. Another quite general case is anything wanting to interop with endpoints in other languages. In those cases it may be necessary to be more explicit about the types you put into messages. I really do think some "real world usage" will point to all those types living together. In my experience using the API so far, you basically interact with Connection, Session, Link, Delivery, Message, and the specific set of types you need to represent the content in your message, and actually with some of the nice defaults in place, you don't even need to think about Connection, Session, Link, or Delivery if you don't want to. That means for a lot of cases Message pus the types is pretty much all you care about, so having them in separate packages is kind of unfortunate. Even including all the endpoint types, I don't think the list above should be too long and cluttered for a single package. If there are other things cluttering up the package I would look at what else we could clean up before pushing types into a sub package. This is why I like your security proposal as it gets the core package closer to just the really core stuff. --Rafael
