Issue 14814: Implement PEP 3144 (the ipaddress module) (original) (raw)
Created on 2012-05-15 12:00 by ncoghlan, last changed 2022-04-11 14:57 by admin. This issue is now closed.
Messages (118)
Author: Alyssa Coghlan (ncoghlan) * 
Date: 2012-05-15 12:00
This issue tracks the incorporation of the ipaddress module into Python 3.3.
Tasks to be completed:
- add Lib/ipaddress.py from [1]
- add Lib/test_ipaddress.py from [1]
- create module reference docs from docstrings in [1]
- add Doc/library/ipaddress.py and link from index
- create howto guide from wiki page [2]
- add Doc/howto/ipaddress.rst and link from index
[1] https://code.google.com/p/ipaddress-py/source/browse/
[2] https://code.google.com/p/ipaddr-py/wiki/Using3144
Author: Roundup Robot (python-dev) 
Date: 2012-05-20 11:02
New changeset 82a649047272 by Nick Coghlan in branch 'default': Issue #14814: addition of the ipaddress module (stage 1 - code and tests) http://hg.python.org/cpython/rev/82a649047272
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-05-20 11:06
Stage 1 complete - the code and tests are in (along with the other miscellaneous updates to ACKS, NEWS and What's New).
Next steps are to convert the wiki page into a HOWTO and the docstrings into a module API reference. Georg offered to help with the first pass at the latter.
The module and its test suite were the main thing I really wanted in place for the alpha 4 deadline - with the frequent updates to the online docs, we have a bit more leeway with the timing.
Author: Ramchandra Apte (Ramchandra Apte) *
Date: 2012-05-20 14:42
Looking at the code at http://code.google.com/p/ipaddress-py/source/browse/ipaddress.py I see a few classes which could benefit from functools.total_ordering.
Author: Éric Araujo (eric.araujo) *
Date: 2012-05-20 20:02
Great to get this in the standard library!
I noticed the ipaddress module contains an unnecessary shebang. I also was under the impression that “Licensed to the PSF under a contributor agreement” was sufficient and the whole license text could be removed.
Author: Sandro Tosi (sandro.tosi) *
Date: 2012-05-20 22:40
I'm attaching a very preliminary draft of the howto, any comment is welcome. Of course, it misses several references to the API doc; I'll see if I can beat Georg and post a preliminary version of that too :)
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-05-21 03:32
Review comments from Terry Reedy: http://mail.python.org/pipermail/python-dev/2012-May/119548.html
The PEP review focused mainly on the API, Terry's comments focus on code readability and the docstrings.
Author: Sandro Tosi (sandro.tosi) *
Date: 2012-05-22 19:55
Thank Nick for pointing to Terry's review! I'm attaching here a patch addressing the points Terry highlighed. probably we should review this patch before moving forward with the API doc?
Author: Terry J. Reedy (terry.reedy) *
Date: 2012-05-22 20:54
[Agreed that spacing comments were bogus.]
As for the rest, patch looks good except for 'is is' in
ValueError: If the integer is is negative or...
I am glad I could help improve things a bit. I will try to look at the how-to by tomorrow to see if I understand it.
Author: Tshepang Lekhonkhobe (tshepang) *
Date: 2012-05-22 21:02
looks easy enough for me; I've marked a bunch of minor issues with the code review tool
Author: Roundup Robot (python-dev)
Date: 2012-05-23 20:27
New changeset 0be296605165 by Sandro Tosi in branch 'default': Issue #14814: improve docstrings and arguments value handling, as per Terry J. Reedy's comments http://hg.python.org/cpython/rev/0be296605165
Author: Hynek Schlawack (hynek) *
Date: 2012-05-23 20:43
A small bikeshed as it’s a new module:
- there’s only one free line before _collapse_addresses_recursive, _get_prefix_length and _count_righthand_zero_bits.
- class IPv6Address docstring has a \n too much
- ip_interface, v4_int_to_packed, v6_int_to_packed are missing an empty line at the end of the docstring
- the doctstring of _BaseNetwork.hosts is indented
- does it make sense to have a shebang in a library?
Just wanted to make it even more shiny. :)
Author: Roundup Robot (python-dev)
Date: 2012-05-23 21:17
New changeset f4f2139202c5 by Sandro Tosi in branch 'default': Issue #14814: minor improvements as suggested by Hynek Schlawack http://hg.python.org/cpython/rev/f4f2139202c5
Author: Sandro Tosi (sandro.tosi) *
Date: 2012-05-23 21:20
Thanks Hynek: comments committed
Author: Hynek Schlawack (hynek) *
Date: 2012-05-24 10:13
Here is a patch with some more pep8-wankery + some dead code removal. Feel free to add only what you like, no hard feelings. :)
Author: Hynek Schlawack (hynek) *
Date: 2012-05-25 08:59
Cool, you actually did reviews. :)
I’ve updated the patch, anything else?
(to my excuse, I originally didn’t want to tamper with code, but now the patch is actually useful and not just pretty ;))
Author: Roundup Robot (python-dev)
Date: 2012-05-26 10:13
New changeset 63d2c9affb11 by Hynek Schlawack in branch 'default': #14814: Some PEP8 adjustments and dead code weeding http://hg.python.org/cpython/rev/63d2c9affb11
Author: Hynek Schlawack (hynek) *
Date: 2012-05-26 10:16
One last wish: could we curb the copyright header a bit? I don't know the exact policy on that but as other modules don't have that I presume we could do without/with a shorter one. If we have one, I'd rather add something like "based on the original ipaddress module by Peter Moody".
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-05-26 11:34
Yeah, only the first two lines of the copyright header are really needed.
Author: Roundup Robot (python-dev)
Date: 2012-05-26 14:26
New changeset f70e12499d05 by Nick Coghlan in branch 'default': Issue #14814: In the spirit of TOOWTDI, ditch the redundant version parameter to the factory functions by using the appropriate direct class references instead http://hg.python.org/cpython/rev/f70e12499d05
Author: Roundup Robot (python-dev)
Date: 2012-05-26 14:57
New changeset 462fff00c3fb by Nick Coghlan in branch 'default': Issue #14814: Cleanup ipaddress header comments http://hg.python.org/cpython/rev/462fff00c3fb
Author: Roundup Robot (python-dev)
Date: 2012-05-26 15:03
New changeset 0b54721bf1cc by Nick Coghlan in branch 'default': Issue #14814: Clean out an obsolete property and method from ipaddress Network objects http://hg.python.org/cpython/rev/0b54721bf1cc
Author: Roundup Robot (python-dev)
Date: 2012-05-26 15:53
New changeset 04b939c0c84d by Nick Coghlan in branch 'default': Issue #14814: Add a basic ipaddress tutorial (thanks to Sandro Tosi for the initial conversion from Peter Moody's wiki version) http://hg.python.org/cpython/rev/04b939c0c84d
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-05-26 15:57
The module reference docs are the main outstanding item now. Georg, up to you whether you want to generate the first pass at those from the docstrings for the alpha or leave it until afterwards.
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-05-26 16:03
There's one other thing I particularly want to look at, but it can wait until after the alpha: the "TODO" comments I added relating to the new self._address_class attribute on the *Network classes.
Specifically, it seems to me that the various network methods that currently return simple Address objects should instead be returning Interface objects.
Author: Roundup Robot (python-dev)
Date: 2012-05-29 03:03
New changeset 7d252dbfbee3 by Eli Bendersky in branch 'default': Issue 14814: Add namespaces keyword arg to find(*) methods in _elementtree. http://hg.python.org/cpython/rev/7d252dbfbee3
Author: Hynek Schlawack (hynek) *
Date: 2012-05-31 20:08
It's funny how raising the test coverage always uncovers lurking bugs in obscure branches. :) Patch attached, let me know if I got it wrong – would commit otherwise.
A few quick side-note: does the version variable make sense in stdlib?
Author: Roundup Robot (python-dev)
Date: 2012-05-31 22:21
New changeset bd2c2def77a7 by Hynek Schlawack in branch 'default': #14814: Remove stale hex method from ipaddress http://hg.python.org/cpython/rev/bd2c2def77a7
Author: Roundup Robot (python-dev)
Date: 2012-06-01 09:54
New changeset 0eb63de72e96 by Hynek Schlawack in branch 'default': #14814: Remove 2.x's new-style classes syntax from ipaddress http://hg.python.org/cpython/rev/0eb63de72e96
Author: Roundup Robot (python-dev)
Date: 2012-06-01 18:21
New changeset 000cc4e0e1cd by Hynek Schlawack in branch 'default': #14814: Fix errror message creation in ipaddress.collapse_addresses http://hg.python.org/cpython/rev/000cc4e0e1cd
Author: Roundup Robot (python-dev)
Date: 2012-06-02 15:17
New changeset facdca62aa68 by Sandro Tosi in branch 'default': Issue #14814: minor spelling fixes http://hg.python.org/cpython/rev/facdca62aa68
New changeset 4b4044292d09 by Sandro Tosi in branch 'default': Issue #14814: use print() function http://hg.python.org/cpython/rev/4b4044292d09
Author: Sandro Tosi (sandro.tosi) *
Date: 2012-06-02 15:53
Attached is a draft of the module documentation. I didn't commit yet cause we might want to rework it deeply. Else we can just commit the patch and let the comments coming as additional diffs.
Author: Sandro Tosi (sandro.tosi) *
Date: 2012-06-02 15:54
and the patch...
Author: Hynek Schlawack (hynek) *
Date: 2012-06-02 16:27
As discussed on IRC, please:
- add a link to the tutorial
- add some typical use cases to the header of the api
- change the name of the tutorial from "Howto" to "HOWTO" or a more descriptive title that doesn't contain the word how to at all.
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-06-03 21:46
With a cross link from the header of the module reference to the howto guide, I think what Sandro posted is good enough for a first draft.
Once the basic content is checked in, then I'll tinker a bit to figure out a more logical order (and possibly move some details from the current howto guide into the module reference).
Author: Roundup Robot (python-dev)
Date: 2012-06-04 12:20
New changeset 6808a72fc9ec by Hynek Schlawack in branch 'default': #14814: Use correct comparison for IP addresses http://hg.python.org/cpython/rev/6808a72fc9ec
Author: Roundup Robot (python-dev)
Date: 2012-06-04 16:34
New changeset df6d1a4d83fa by Hynek Schlawack in branch 'default': #14814: Remove dead code from ipaddress http://hg.python.org/cpython/rev/df6d1a4d83fa
Author: Hynek Schlawack (hynek) *
Date: 2012-06-04 22:03
Dear friends of ip addresses, I made something:
refactor dup code, minor janitoring, bump coverage
- remove duplicate netmask/hostmask code (it was identical in ipv4address & interface)
- make two ifs more pythonic
- Refactor and fix packed property for ipv6 addresses and networks. Apparently nobody has ever used this. :)
- Test coverage is now at 97%, the rest are mostly unreachable safeguards.
Please have a look at it if you will. The test suite passes of course.
That said, I'm pretty sure the constructor for IPv6Network is broken (particularly constructing from int and packed – also the the strict tests in these two cases don't make any sense as net mask is always ALL_ONES).
I'll be dreaming of ip addresses tonight. ;)
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-06-04 23:38
Hynek's latest patch mostly looks good to me, but I think the "packed" property on network definitions just needs to go away.
The original ipaddr API that is the basis for ipaddress doesn't really have a clear distinction between network definitions and IP addresses, and I think the current network code is still showing some of the legacies of that.
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-06-04 23:41
Also noting a TODO item here: currently, the address-producing operations on network objects just produce vanilla address objects of the appropriate version. My question is, should we have those operations create interface objects instead?
My current thought is that the latter would lose less information, since you can easily strip the network details later if desired.
Author: Roundup Robot (python-dev)
Date: 2012-06-05 09:57
New changeset cca2a1cc9598 by Hynek Schlawack in branch 'default': #14814: ipaddress: refactor dup code, minor janitoring, bump coverage http://hg.python.org/cpython/rev/cca2a1cc9598
Author: Hynek Schlawack (hynek) *
Date: 2012-06-05 10:04
So one more issue from me: as indicated, the constructor using packed of IPv6Networks is broken (wrong indent).
The question is whether we want to be able to construct using packed at all.
Also the strict check doesn't make any sense because the net mask is ALL_ONES so if the construction of the IPv6Address succeeds, there's no way the check can fail.
Author: Roundup Robot (python-dev)
Date: 2012-06-08 13:22
New changeset 4aeb5b9b62d7 by Hynek Schlawack in branch 'default': #14814: Remove redundant code from ipaddress.IPv6Network http://hg.python.org/cpython/rev/4aeb5b9b62d7
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-06-17 06:37
I looked into the idea of treating networks as containers of interface objects rather than addresses - it turns out it gets messy very quickly, because you definitely want your network address and broadcast address to be ordinary addresses, so making the host addresses interfaces instead of ordinary addresses would lead to inconsistent behaviour.
739f5c725958 is the result of that investigation (I forgot to mention this issue in the checkin message)
Author: Roundup Robot (python-dev)
Date: 2012-06-17 07:24
New changeset cacf3b1e20da by Nick Coghlan in branch 'default': Issue #14814: Add first draft of PEP 3144 ipaddress module documentation (initial patch by Sandro Tosi) http://hg.python.org/cpython/rev/cacf3b1e20da
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-06-17 07:29
OK, dropping to "deferred blocker" status, as I think the docs are now good enough for beta 1.
We still want to get the public methods and properties for the various objects documented during the beta period, though.
I'm not sure how best to handle that, though - the interfaces of the v4 and v6 variants are deliberately very similar, so documenting everything twice seems like a rather user hostile thing to do.
Author: Éric Araujo (eric.araujo) *
Date: 2012-06-17 15:56
A small markup error in the doc: in “.. exception:: Custom(ValueError)” (as in “.. class:: SomeThing(BaseThing)”), the parens are supposed to contain the signature for the constructor, not the base classes.
(Sorry I’m not replying to the python-checkins email; my diff colorizer extension was disabled due to mailer version update so I delete the -checkins messages and to read changesets on hgweb now.)
Author: Éric Araujo (eric.araujo) *
Date: 2012-06-17 15:57
Forgot the reference: http://sphinx.pocoo.org/domains.html#directive-py:exception
Author: Terry J. Reedy (terry.reedy) *
Date: 2012-06-18 06:17
the interfaces of the v4 and v6 variants are deliberately very similar
I am hoping that means 'identical, once the obvious translations are made': v4 to v6, xxx.xxx.xxx.xxx to , and anything else?
documenting everything twice seems like a rather user hostile thing to do.
Agreed. Please factor out common stuff. I see two choices.
- Document in parallel after an intro explaining the translations
xxxx4yyyy(args) xxxx6yyyy(args) Return ... (either in 4 terms which user translate for 6 or generic terms).
This might be better if you expect people to be doing one type of thing with both v4 and v6.
- Document serially, first v4 stuff then v6 stuff (at present, though order might be reversed in the future ;-).
v4 stuff
xxxx4yyyy(args) Return ...
v6 stuff
The following v6 functions are the same as the v4 functions above, except that ipv4address'es become ipv6address'es etc. xxxx6uuuu(args)
This might be better if you expect people to be doing multiple things with either v4 or v6, but not both.
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-06-18 07:14
My current thoughts are to avoid the usual approach of embedding the method and property definitions in the class definitions, and instead have separate sections under [1] for
IP Addresses IP Interfaces IP Networks
Inside each of those sections, document the constructors directly under the section heading, and then separate out these subsections:
Common IP properties and methods IPv4 properties and methods (if any) IPv6 properties and methods (if any)
[1] http://docs.python.org/dev/library/ipaddress#representing-ip-addresses-and-networks
Author: pmoody (pmoody) *
Date: 2012-06-18 17:04
I'm not sure if this is still an issue, but returning the address in a packed format was an early issue (http://code.google.com/p/ipaddr-py/issues/detail?id=14). No objections from me for removing it from the network objects or for removing the packed constructor (I'm assuming there isn't any python-ism about being able to copy-construct an object from any valid representation of said object)
Author: Hynek Schlawack (hynek) *
Date: 2012-06-25 12:55
Currently, we get the following warnings:
[ 26/369] test_ipaddress /home/vagrant/default/Lib/ipaddress.py:1401: BytesWarning: str() on a bytes instance addr = str(address).split('/') /home/vagrant/default/Lib/ipaddress.py:2004: BytesWarning: str() on a bytes instance addr = str(address).split('/') /home/vagrant/default/Lib/ipaddress.py:1258: BytesWarning: str() on a bytes instance
Hadn't time yet to look into it, I might update the ticket as soon as I had.
Author: Hynek Schlawack (hynek) *
Date: 2012-06-25 15:33
Ok I looked into it. It uses str() to convert objects into text representation which it then parses.
Author: Hynek Schlawack (hynek) *
Date: 2012-06-25 18:19
And the origin of the bytes seems to be:
Compatibility function to cast str to bytes objects
_cb = lambda bytestr: bytes(bytestr, 'charmap')
Author: Georg Brandl (georg.brandl) *
Date: 2012-06-26 20:52
Moving back to blocker for beta2.
Author: pmoody (pmoody) *
Date: 2012-06-27 22:38
Hynek, I don't see that error when I run the tests on a freshly built python.
Author: Hynek Schlawack (hynek) *
Date: 2012-06-28 08:45
Try running the test like:
./python[.exe] -bb -Wd -m test test_ipaddress
Author: pmoody (pmoody) *
Date: 2012-06-29 17:59
Reported externally, ipaddress tries to parse 4 character strings as bytes.
https://groups.google.com/forum/?hl=en_US&fromgroups#!topic/ipaddr-py-dev/j6FkeJtsBz4
Author: pmoody (pmoody) *
Date: 2012-06-29 18:31
one more patch, superseding the last patch.
also reported externally, the v6 parser would incorrectly parse some v6 addresses.
http://code.google.com/p/ipaddr-py/issues/detail?id=97
Author: Roundup Robot (python-dev)
Date: 2012-07-06 15:14
New changeset b7cfdb48af62 by Nick Coghlan in branch 'default': Issue 14814: Better handling of cases where octet/hextet parsing fails, including ensuring that tracebacks are still clean even when calling class constructors directly http://hg.python.org/cpython/rev/b7cfdb48af62
Author: Roundup Robot (python-dev)
Date: 2012-07-06 15:43
New changeset 30e8f2242190 by Nick Coghlan in branch 'default': Issue 14814: Eliminate bytes warnings from ipaddress by correctly throwing an exception early when given bytes data of the wrong length. Also removes 2.x backwards compatibility code from associated tests. http://hg.python.org/cpython/rev/30e8f2242190
Author: Roundup Robot (python-dev)
Date: 2012-07-07 03:35
New changeset d9c98730e2e8 by Nick Coghlan in branch 'default': Issue 14814: %s implies coercion with str() - remove a lot of redundant str() calls from the ipaddress implementation http://hg.python.org/cpython/rev/d9c98730e2e8
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-07 05:45
Just letting people know I'm working on a patch that updates the class constructors to give meaningful error messages for malformed addresses, instead of assuming that users can figure it out just by looking at the address. I'm also updating the test suite to check that these more detailed errors are being reported as expected.
Author: Roundup Robot (python-dev)
Date: 2012-07-07 09:31
New changeset 16ff4889a858 by Nick Coghlan in branch 'default': Issue 14814: Provide more informative error messages in ipaddress, and ensure that errors are caught as expected http://hg.python.org/cpython/rev/16ff4889a858
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-07 09:35
There's actually one semantic change in that last patch: IPv4Address (et al) will now accept leading zeroes in those cases where they're not ambiguous (i.e. values less than 8, which have identical representations in both decimal and octal notation).
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-07 09:36
Also, I noted the provisional API status in the NEWS message, but I wonder if it would make more sense to leave that kind of note for the commit messages.
Author: Roundup Robot (python-dev)
Date: 2012-07-07 11:43
New changeset af4ae710daf3 by Nick Coghlan in branch 'default': Issue 14814: Make the ipaddress code easier to follow by using newer language features (patch by Serhiy Storchaka) http://hg.python.org/cpython/rev/af4ae710daf3
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-07 11:50
Many of Serhiy's tweaks were also micro-optimisations, but I committed them mainly because I found them easier to read.
Author: Roundup Robot (python-dev)
Date: 2012-07-07 12:15
New changeset d03dbc324b60 by Nick Coghlan in branch 'default': Issue 14814: Explain how to get more error detail in the ipaddress tutorial, and tweak the display for octet errors in IPv4 (noticed the formatting problem when adding to the docs) http://hg.python.org/cpython/rev/d03dbc324b60
Author: Roundup Robot (python-dev)
Date: 2012-07-07 12:53
New changeset 86d3b4067f74 by Nick Coghlan in branch 'default': Issue 14814: Further clean ups to the ipaddress tutorial http://hg.python.org/cpython/rev/86d3b4067f74
Author: Roundup Robot (python-dev)
Date: 2012-07-07 13:08
New changeset 2e9cba1d1554 by Nick Coghlan in branch 'default': Issue 14814: Correctly return NotImplemented from ipaddress._BaseNetwork.eq http://hg.python.org/cpython/rev/2e9cba1d1554
Author: Roundup Robot (python-dev)
Date: 2012-07-07 14:45
New changeset 9b359b6c9a39 by Nick Coghlan in branch 'default': Issue 14814: Ensure ordering semantics across all 3 entity types in ipaddress are consistent and well-defined http://hg.python.org/cpython/rev/9b359b6c9a39
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2012-07-07 14:50
Should do _version and _max_prefixlen be instance members? Or they can be class members as _HEX_DIGITS?
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-07 15:12
My guess would be that they're intended as a micro-optimisation (instance lookups should be faster than class attribute lookups). You do lose on the memory front though, since they make the instances bigger.
Without a micro benchmark of any kind, I'm not inclined to mess with them at this point.
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-07 15:20
FWIW, if we were going to micro-optimise ipaddress, one of the first places I'd start is using slots to try to bring the instance size down (since any application using the module is likely to end up creating a lot of these objects). There are more significant things to worry about at this stage, though.
Author: Éric Araujo (eric.araujo) *
Date: 2012-07-07 15:37
Any reason for not using functools.total_ordering?
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-07 22:55
Yup, it's broken (doesn't handle NotImplemented correctly) and Raymond isn't keen on fixing it. I should add a link to the relevant tracker issue in a comment, though.
Author: Roundup Robot (python-dev)
Date: 2012-07-08 07:36
New changeset 18c1d4d60bdf by Nick Coghlan in branch 'default': Issue 14814: Further error case testing coverage and cleanups http://hg.python.org/cpython/rev/18c1d4d60bdf
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2012-07-08 08:51
_get_prefix_length now used only in test.
Author: Roundup Robot (python-dev)
Date: 2012-07-08 11:38
New changeset 45265ecaa3e4 by Nick Coghlan in branch 'default': Issue 14814: Remove dead function (noticed by Serhiy Storchaka) http://hg.python.org/cpython/rev/45265ecaa3e4
Author: Roundup Robot (python-dev)
Date: 2012-07-08 13:14
New changeset 7aa75ea4116d by Nick Coghlan in branch 'default': Issue 14814: The new systematic tests aren't just about error reporting any more - change names accordingly. Added and tweaked some example to ensure they were covering the intended code paths http://hg.python.org/cpython/rev/7aa75ea4116d
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-15 02:34
Unassigning for the moment - I'm busy fighting fires in pkgutil (which is actually broken due to the import changes). If someone else has time to flesh out the method and data attribute documentation for the ipaddress classes, that would be great.
Author: Georg Brandl (georg.brandl) *
Date: 2012-07-21 14:27
IIUC only docs are missing now? That's not a b2 blocker then.
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 07:14
I'm looking at the docs. Started with the HOWTO (Doc/howto/ipaddress.rst)
This example:
net4 = ipaddress.ip_network('192.0.2.0/24') for x in net4.iterhosts(): print(x)
Seems to be wrong:
... Traceback (most recent call last): File "", line 1, in AttributeError: 'IPv4Network' object has no attribute 'iterhosts'
I wonder if it simply needs to iterate the net4 object itself.
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 07:15
P.S. I intend to prepare patch(es) eventually, but I will document the problems I find here, in case anyone is interested to discuss.
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 07:19
Ah, probably hosts() replaced iterhosts()
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 07:36
Attaching a patch for the howto
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 08:00
FWIW I would prefer this HOWTO to be part of the document itself. Splitting a document to two parts and keeping them separated is problematic exactly for the same reasons as external documentation in general - it can be forgotten when things get updated.
HOWTOs are good to discuss concepts that don't pertain to a specific modules, and so there is no other "natural" place to place them. Tutorials that only discuss a single module belong in its doc page together with the reference - I think there are plenty of examples in the stdlib docs where this is the case.
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 08:18
The docs don't mention that addresses can also be packed in bytes
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-31 08:29
No, the HOWTO should be separate. Having them in the same document makes for something that is worse as both a tutorial and as an API reference (just look at argparse).
Yes, that means there are three places to update (code, reference, tutorial). There are three places to update regardless - the only question is whether two of those places are jammed awkwardly into the same file. Handling this will hopefully become more natural as the howto/tutorial section of the docs grows larger.
The main problem with the ipadddress docs at the moment is extracting the docstrings for the methods and including them in the reference docs in a sane way (i.e. without excessive duplication of material, as Terry and I discussed above).
Author: Serhiy Storchaka (serhiy.storchaka) *
Date: 2012-07-31 09:13
If this issue is not yet closed, here are a patch with few edits: using int.to_bytes/from_bytes instead struct.pack/unpack and using enumerate() instead range(len()).
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 09:41
I disagree about the HOWTO vs. doc thing, but I don't see it as a major issue so I won't dwell on it.
I'm now in the process of throwing together a patch for the reference doc - also bundling the address objects together, the network objects together, etc.
BTW I saw there was disagreement about whether packed bytes should be accepted as addresses. ATM they are in the code, so should this be documented? I want to provide a precise documentation of what exactly is a valid address.
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 11:56
Alright, attaching an attempt at improving the reference docs. This only handles the address objects for now:
- Grouping address objects together, network objects together, interface objects together
- Explain that everything IPv4Address exposes is also exposed by IPv6Address
- Document v4's attributes in a generic manner
- Document v6's specific attributes
- Document operators
- Precisely define the address format(s) accepted by the constructors
If this looks good to folks, I can commit and then proceed to similarly explaining the network and interface objects.
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-31 12:22
Thanks Eli, that looks like a great start to me.
And yeah, the separate vs integrated tutorial argument is an ongoing one that isn't going to be resolved by this issue :)
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 14:22
Thanks Nick. I've addressed your review comments and will be pushing the doc update.
Author: Roundup Robot (python-dev)
Date: 2012-07-31 14:23
New changeset 586eb57e06ba by Eli Bendersky in branch 'default': Issue #14814: reorganize ipaddress documentation and document all attributes of IPv[46]Address objects http://hg.python.org/cpython/rev/586eb57e06ba
Author: Roundup Robot (python-dev)
Date: 2012-07-31 14:25
New changeset 07ddf5ecaafa by Eli Bendersky in branch 'default': Issue #14814: fix some typos in howto/ipaddress.rst http://hg.python.org/cpython/rev/07ddf5ecaafa
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 14:32
By the way, Nick, was not this module intended to be introduced as provisional in 3.3? At least PEP 411 lists it as one of the candidates.
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-07-31 18:07
Attaching part 1 of the patch for documenting the network objects. Contains general introduction, detailed documentation of constructors and all attributes.
Left to document: methods, operations (like iterating, "in", comparison operators)
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-07-31 22:18
Yes, the module docs should have the provisional notice. Good catch.
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-08-01 06:07
Attaching an updated patch that completes the documentation of network objects (attributes, methods and operations). Additionally, inserted the "provisional package" note and a "new in 3.3" notice.
Author: Roundup Robot (python-dev)
Date: 2012-08-05 12:02
New changeset b513ad06d1fa by Nick Coghlan in branch 'default': Issue 14814: Docs work showed some more cases of networks pretending to be addresses and highlighted the weird approach to implementing the 'is_whatever' properties. Impl now illustrates far more clearly that networks have a property if both their network and broadcast addresses have that property http://hg.python.org/cpython/rev/b513ad06d1fa
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-08-05 12:07
Nick, your commit incorporates my latest patch (ipaddr_refdoc_network.2.patch), right?
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-08-05 12:11
It actually wasn't meant to, as I only meant to commit the code changes (I was still working on the docs, using your patch as a starting point).
However, it makes more sense to just finish my changes and commit them rather than reverting anything.
(Good attempt by the way, but it was your 'networks have all the attributes of addresses' that got me digging deeper, since that isn't meant to be true any more)
Author: Roundup Robot (python-dev)
Date: 2012-08-05 12:32
New changeset cf8d42596a44 by Nick Coghlan in branch 'default': Issue #14814: Finish review of ipaddress network object docs (initial patch was by Eli Bendersky) http://hg.python.org/cpython/rev/cf8d42596a44
Author: Roundup Robot (python-dev)
Date: 2012-08-05 12:45
New changeset cf9526db1a7e by Nick Coghlan in branch 'default': Issue #14814: Remove redundant property from interface objects - prefixlen can be accessed via the associated network object http://hg.python.org/cpython/rev/cf9526db1a7e
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-08-05 12:45
I'm still not overjoyed with the "this isn't documented here, go read it over there" situation. However, duplicating the text everywhere isn't ideal either. So, let's finish it up with my current approach: explicitly listing the methods and attributes on each class where the documentation is elsewhere.
For Interface objects, there's no need to repeat the documentation for the corresponding Address object, since there's a real inheritance relationship there.
Fortunately, that makes the list of attributes still to be documented fairly short:
ip (raw address with no network info) network (the network definition) with_prefixlen with_hostmask with_netmask
Author: Roundup Robot (python-dev)
Date: 2012-08-05 12:52
New changeset abbae7314b52 by Nick Coghlan in branch 'default': Issue #14814: Attempt to clarify network address and broadcast address for less experienced users http://hg.python.org/cpython/rev/abbae7314b52
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-08-09 08:31
Here's a patch adding documentation to the *Interface classes.
I must say I'm not very psyched about the with_* methods. Their outputs are inconsistent, unlike in *Network, where all return strings.
Author: pmoody (pmoody) *
Date: 2012-08-09 16:40
There's no reason why IPv?Network().with_prefixlen can't return str(self).
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-08-09 17:55
pmoody - you mean IPv?Interface, right? The network classes consistently return strings in with_* methods
Author: pmoody (pmoody) *
Date: 2012-08-09 18:08
sorry, yes, I meant the interface classes.
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-08-10 03:47
Attaching a new patch that fixes the with_* methods to be more consistent, and the relevant tests too. The doc is now consistent as well.
For some reason IPv6Interface.with_netmask also returned the prefixlen representation. The test justified it by quoting RFC3513/2.3 but I did not see anything there that really forces us to do that. Perhaps the with_netmask/with_hostmask representations are nonsensical for v6 and we keep them for v4 compatibility, but in that case let them be compatible!
Author: Georg Brandl (georg.brandl) *
Date: 2012-08-19 10:57
Please keep in mind that this should be committed before next weekend if it is to make 3.3.
Author: Eli Bendersky (eli.bendersky) *
Date: 2012-08-19 12:06
I'm just waiting for a review. If Nick has no time for that, perhaps I can commit anyway since this is just adding documentation.
Author: Alyssa Coghlan (ncoghlan) *
Date: 2012-08-19 13:01
I'm at the pyconau sprints for the next couple of days - I'll make sure this is dealt with. On Aug 19, 2012 10:07 PM, "Eli Bendersky" <report@bugs.python.org> wrote:
Eli Bendersky added the comment:
I'm just waiting for a review. If Nick has no time for that, perhaps I can commit anyway since this is just adding documentation.
Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14814>
Author: Roundup Robot (python-dev)
Date: 2012-08-20 00:04
New changeset 258558e36d8a by Nick Coghlan in branch 'default': Issue #14814: document the Interface APIs and fix various problems with the string representations (initial patch by Eli Bendersky). http://hg.python.org/cpython/rev/258558e36d8a
Author: Roundup Robot (python-dev)
Date: 2012-08-20 00:19
New changeset 811d91591f73 by Nick Coghlan in branch 'default': Close #14814: Avoid depending on struct by using newer features. Also use enumerate where appropriate (patch by Serhiy Storchaka). Declaring PEP 3144 final at this point - any further changes to code or docs can go in new issues. http://hg.python.org/cpython/rev/811d91591f73
History
Date
User
Action
Args
2022-04-11 14:57:30
admin
set
github: 59019
2012-08-20 00:19:37
python-dev
set
status: open -> closed
resolution: fixed
messages: +
stage: needs patch -> resolved
2012-08-20 00:04:44
python-dev
set
messages: +
2012-08-19 23:26:00
ncoghlan
set
assignee: ncoghlan
2012-08-19 13:01:13
ncoghlan
set
messages: +
2012-08-19 12:06:55
eli.bendersky
set
messages: +
2012-08-19 11:00:40
georg.brandl
set
priority: deferred blocker -> release blocker
2012-08-19 10:57:35
georg.brandl
set
messages: +
2012-08-10 03:47:37
eli.bendersky
set
files: + ipaddr_interface.2.patch
messages: +
2012-08-09 18:08:55
pmoody
set
messages: +
2012-08-09 17:55:11
eli.bendersky
set
messages: +
2012-08-09 16:40:23
pmoody
set
messages: +
2012-08-09 08:31:49
eli.bendersky
set
files: + ipaddr_refdoc_interface.1.patch
2012-08-09 08:31:35
eli.bendersky
set
messages: +
2012-08-05 12:52:48
python-dev
set
messages: +
2012-08-05 12:45:59
ncoghlan
set
messages: +
2012-08-05 12:45:32
python-dev
set
messages: +
2012-08-05 12:32:47
python-dev
set
messages: +
2012-08-05 12:11:01
ncoghlan
set
messages: +
2012-08-05 12:07:21
eli.bendersky
set
messages: +
2012-08-05 12:02:28
python-dev
set
messages: +
2012-08-01 06:07:25
eli.bendersky
set
files: + ipaddr_refdoc_network.2.patch
messages: +
2012-07-31 22🔞17
ncoghlan
set
messages: +
2012-07-31 18:07:55
eli.bendersky
set
files: + ipaddr_refdoc_network.1.patch
messages: +
2012-07-31 14:32:12
eli.bendersky
set
messages: +
2012-07-31 14:25:52
python-dev
set
messages: +
2012-07-31 14:23:34
python-dev
set
messages: +
2012-07-31 14:22:21
eli.bendersky
set
messages: +
2012-07-31 12:22:43
ncoghlan
set
messages: +
2012-07-31 11:56:22
eli.bendersky
set
files: + ipaddr_refdoc.1.patch
messages: +
2012-07-31 09:41:49
eli.bendersky
set
messages: +
2012-07-31 09:13:54
serhiy.storchaka
set
files: + ipaddress-modernize.patch
messages: +
2012-07-31 08:29:57
ncoghlan
set
messages: +
2012-07-31 08🔞07
eli.bendersky
set
messages: +
2012-07-31 08:00:34
eli.bendersky
set
messages: +
2012-07-31 07:36:01
eli.bendersky
set
files: + ipaddr_howto.1.patch
messages: +
2012-07-31 07:19:58
eli.bendersky
set
messages: +
2012-07-31 07:15:37
eli.bendersky
set
messages: +
2012-07-31 07:14:58
eli.bendersky
set
nosy: + eli.bendersky
messages: +
2012-07-21 14:27:47
georg.brandl
set
priority: release blocker -> deferred blocker
messages: +
2012-07-15 02:34:12
ncoghlan
set
assignee: ncoghlan -> (no value)
messages: +
components: + Documentation, - Library (Lib)
stage: patch review -> needs patch
2012-07-08 13:14:15
python-dev
set
messages: +
2012-07-08 11:38:23
python-dev
set
messages: +
2012-07-08 08:51:37
serhiy.storchaka
set
messages: +
2012-07-08 07:36:34
python-dev
set
messages: +
2012-07-07 22:55:03
ncoghlan
set
messages: +
2012-07-07 15:37:15
eric.araujo
set
messages: +
2012-07-07 15:20:40
ncoghlan
set
messages: +
2012-07-07 15:12:28
ncoghlan
set
messages: +
2012-07-07 14:50:12
serhiy.storchaka
set
nosy: + serhiy.storchaka
messages: +
2012-07-07 14:45:45
python-dev
set
messages: +
2012-07-07 13:08:42
python-dev
set
messages: +
2012-07-07 12:53:58
python-dev
set
messages: +
2012-07-07 12:15:33
python-dev
set
messages: +
2012-07-07 11:50:12
ncoghlan
set
messages: +
2012-07-07 11:43:41
python-dev
set
messages: +
2012-07-07 09:36:44
ncoghlan
set
messages: +
2012-07-07 09:35:33
ncoghlan
set
messages: +
2012-07-07 09:31:38
python-dev
set
messages: +
2012-07-07 05:45:31
ncoghlan
set
messages: +
2012-07-07 03:35:25
python-dev
set
messages: +
2012-07-06 15:43:49
python-dev
set
messages: +
2012-07-06 15:14:07
python-dev
set
messages: +
2012-06-29 18:31:59
pmoody
set
files: + ipaddress-bytes-str-v6-parsing.diff
messages: +
2012-06-29 17:59:36
pmoody
set
files: + ipaddress-bytes-str.diff
messages: +
2012-06-28 08:45:33
hynek
set
messages: +
2012-06-27 22:38:27
pmoody
set
messages: +
2012-06-26 20:52:02
georg.brandl
set
priority: deferred blocker -> release blocker
messages: +
2012-06-25 18:19:44
hynek
set
messages: +
2012-06-25 15:33:48
hynek
set
messages: +
2012-06-25 12:55:16
hynek
set
messages: +
2012-06-18 17:04:22
pmoody
set
messages: +
2012-06-18 07:14:59
ncoghlan
set
messages: +
2012-06-18 06:17:10
terry.reedy
set
messages: +
2012-06-17 15:57:17
eric.araujo
set
messages: +
2012-06-17 15:56:52
eric.araujo
set
messages: +
2012-06-17 07:29:57
ncoghlan
set
priority: release blocker -> deferred blocker
messages: +
2012-06-17 07:24:25
python-dev
set
messages: +
2012-06-17 06:37:08
ncoghlan
set
messages: +
2012-06-08 13:22:03
python-dev
set
messages: +
2012-06-05 10:04:26
hynek
set
files: + ipaddress-ipv6network-constructor.diff
messages: +
2012-06-05 09:57:21
python-dev
set
messages: +
2012-06-04 23:41:59
ncoghlan
set
messages: +
2012-06-04 23:38:53
ncoghlan
set
messages: +
2012-06-04 22:03:33
hynek
set
files: + ipaddress-refactor-and-bump-coverage.diff
messages: +
2012-06-04 16:34:57
python-dev
set
messages: +
2012-06-04 12:20:18
python-dev
set
messages: +
2012-06-03 21:46:47
ncoghlan
set
messages: +
2012-06-02 16:27:15
hynek
set
messages: +
2012-06-02 15:54:11
sandro.tosi
set
files: + ipaddress_module_doc.diff
messages: +
2012-06-02 15:53:50
sandro.tosi
set
messages: +
stage: needs patch -> patch review
2012-06-02 15:17:48
python-dev
set
messages: +
2012-06-01 18:21:13
python-dev
set
messages: +
2012-06-01 09:54:13
python-dev
set
messages: +
2012-05-31 22:21:42
python-dev
set
messages: +
2012-05-31 20:08:29
hynek
set
files: + fix-type-error.diff
messages: +
2012-05-29 03:03:51
python-dev
set
messages: +
2012-05-26 16:03:25
ncoghlan
set
messages: +
2012-05-26 15:57:03
ncoghlan
set
messages: +
2012-05-26 15:53:50
python-dev
set
messages: +
2012-05-26 15:03:42
python-dev
set
messages: +
2012-05-26 14:57:38
python-dev
set
messages: +
2012-05-26 14:26:21
python-dev
set
messages: +
2012-05-26 11:34:34
ncoghlan
set
messages: +
2012-05-26 10:16:28
hynek
set
messages: +
2012-05-26 10:13:36
python-dev
set
messages: +
2012-05-25 08:59:03
hynek
set
files: + ipaddress-pep8-and-dead-code-v2.diff
messages: +
2012-05-24 10:13:54
hynek
set
files: + ipaddress-pep8-and-dead-code.diff
messages: +
2012-05-23 21:20:05
sandro.tosi
set
messages: +
2012-05-23 21:17:45
python-dev
set
messages: +
2012-05-23 20:43:19
hynek
set
nosy: + hynek
messages: +
2012-05-23 20:27:18
python-dev
set
messages: +
2012-05-23 00:03:51
ezio.melotti
set
nosy: + ezio.melotti
2012-05-22 21:02:17
tshepang
set
messages: +
2012-05-22 20:54:19
terry.reedy
set
messages: +
2012-05-22 19:55:36
sandro.tosi
set
files: + ipaddress_improvements.diff
messages: +
2012-05-21 03:32:52
ncoghlan
set
assignee: ncoghlan
messages: +
2012-05-20 22:40:42
sandro.tosi
set
files: + issue14814-ipaddress-howto.diff
nosy: + sandro.tosi
messages: +
keywords: + patch
2012-05-20 20:02:15
eric.araujo
set
nosy: + eric.araujo
messages: +
2012-05-20 14:42:55
Ramchandra Apte
set
nosy: + Ramchandra Apte
messages: +
2012-05-20 11:06:50
ncoghlan
set
nosy: + georg.brandl
messages: +
2012-05-20 11:02:17
python-dev
set
nosy: + python-dev
messages: +
2012-05-20 09:40:52
ncoghlan
set
nosy: + pmoody
2012-05-18 18:27:37
terry.reedy
set
nosy: + terry.reedy
2012-05-15 20:57:46
amak
set
nosy: + amak
2012-05-15 16:01:26
giampaolo.rodola
set
nosy: + giampaolo.rodola
2012-05-15 14:29:41
tshepang
set
nosy: + tshepang
2012-05-15 12:00:08
ncoghlan
create