On Fri, Sep 2, 2011 at 8:03 AM, Peter Moody <pmoody@google.com> wrote:

I'll make an implementation with these changes this weekend.

Great to hear!

It sounds like it's going to be clunky, but that's definitely with a grain or two of bias.

Hopefully it won't be too inconvenient - in theory, it just means that when you derive the network details from a host address and masking information you can't throw the original host address information away any more (since IPNetwork own't be keeping it around).

Documentation isn't my strong suit, but assuming the implementation is palatable to all involved, that can be forthcoming as well.

Splitting the API up a little should actually make the documentation task itself easier. For folks that are already familiar with networking concepts, it isn't that hard to mentally map the "IPNetwork" name as meaning "either an actual IP network or else an arbitrary host/netmask pair". We might grumble about it (*cough*), but we wouldn't be confused once we made the connection. However, once ipaddr goes into the standard library, its module documentation is going to be the first introduction many future Python programmers will have to the details of how IP addressing actually works. We'll refer them off to other resources, of course, but having clean semantics in the API itself is important in helping people that are *not* already networking experts use the module correctly. That means having the class model map cleanly to the real world entities it represents, and while IP networks and specific interfaces on those networks are both represented accurately by the combination of an IP address with masking information, they're *not* the same kind of thing. It's the difference between using Pair(a, b) for both 2-D coordinates and rational numbers vs using separate Point(x, y) and Rational(n, d) classes. Yes, the information stored in both cases is the same, but the semantics assigned to that information changes. Cheers, Nick. -- Nick Coghlan   |   ncoghlan@gmail.com   |   Brisbane, Australia