Add and document __format__ method for IPv[46]Address

[ewosborne]

BPO	32820
Nosy	@ncoghlan, @ericvsmith, @tiran, @zware, @serhiy-storchaka, @ewosborne, @iritkatriel
PRs	bpo-32820: __format__ method for ipaddress #5627 bpo-32820: Simplify __format__ implementation for ipaddress. #16378

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2020-10-17.13:07:00.219>
created_at = <Date 2018-02-11.15:45:54.656>
labels = ['type-feature', 'library', '3.9', '3.10', 'docs']
title = 'Add and document __format__ method for IPv[46]Address'
updated_at = <Date 2020-10-17.15:10:37.808>
user = 'https://github.com/ewosborne'

bugs.python.org fields:

activity = <Date 2020-10-17.15:10:37.808>
actor = 'ewosborne'
assignee = 'docs@python'
closed = True
closed_date = <Date 2020-10-17.13:07:00.219>
closer = 'eric.smith'
components = ['Documentation', 'Library (Lib)']
creation = <Date 2018-02-11.15:45:54.656>
creator = 'ewosborne'
dependencies = []
files = []
hgrepos = []
issue_num = 32820
keywords = ['patch']
message_count = 39.0
messages = ['311997', '311998', '312005', '312019', '312026', '312043', '312044', '312050', '312052', '312062', '312093', '312120', '312121', '312125', '312156', '312176', '312361', '312396', '312403', '312413', '312414', '312415', '312652', '312654', '312663', '312667', '312698', '313214', '352064', '352065', '353147', '353379', '378783', '378788', '378804', '378809', '378811', '378813', '378821']
nosy_count = 8.0
nosy_names = ['ncoghlan', 'eric.smith', 'christian.heimes', 'docs@python', 'zach.ware', 'serhiy.storchaka', 'ewosborne', 'iritkatriel']
pr_nums = ['5627', '16378']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue32820'
versions = ['Python 3.9', 'Python 3.10']

[ewosborne]

This issue adds two things to the ipaddress lib:

• an __index__ method to allow bin(), oct(), hex() to work
• a property method to get the fully padded (32-bit or 128-bit) address as a string

[ewosborne]

test_not_an_index_issue15559() disallows __index__, so nevermind. Will resubmit without __index__ to get the full binary string, though.

[ewosborne]

redoing with a bits() property method to return a string, a la:

    def bits(self):
        fstr = '0' + str(IPV4LENGTH) + 'b'
        return '0b' + format(int(self), fstr)

Works thusly:

import ipaddress as ip
a = ip.IPv4Address('0.0.0.42')
a.bits == '0b00000000000000000000000000101010'

[ericvsmith]

Without commenting on how useful or desirable this would be, I'll point out the string can be computed as:

return f'{int(self):#0{IPV4LENGTH+2}b}'

[ewosborne]

Faster, too.
My way:
In [7]: %timeit bits(a)
1.67 µs ± 7.31 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)

Your way:
In [11]: %timeit b2(a)
1.2 µs ± 5.93 ns per loop (mean ± std. dev. of 7 runs, 1000000 loops each)

I was a little worried about doing it all as a clever one-liner but this
seems worthwhile. I'll change the code I submitted.
thanks!

eric

On Sun, Feb 11, 2018 at 6:21 PM Eric V. Smith <report@bugs.python.org>
wrote:

Eric V. Smith <eric@trueblade.com> added the comment:

Without commenting on how useful or desirable this would be, I'll point
out the string can be computed as:

return f'{int(self):#0{IPV4LENGTH+2}b}'

----------
nosy: +eric.smith

---

Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue32820\>

---

[serhiy-storchaka]

The usefulness of this feature looks questionable to me.

[tiran]

I agree with Serhiy and Eric. It's a needless complication of the module. What's the actual use case of printing a human readable bit representation of an IP address?

[ewosborne]

It is often useful to have non-decimal representations of IP addresses.
Hex shows up a lot in sniffer traces, which is why I wanted to provide
__index__, but that's not going to happen. I use binary a lot when
teaching subnet masking and address summarization - if you line up bit
patterns it's much easier to show how things lay out. It's easy enough to
use bin(int(addr)) but that doesn't zero-pad the string it returns. I find
myself doing something like

In [23]: a
Out[23]: IPv4Address('1.2.3.4')

In [24]: x = bin(int(a))[2:]

In [25]: full_x = '0b' + ('0' * (32-len(x)) + x)

In [26]: full_x
Out[26]: '0b00000001000000100000001100000100'

Although, as Eric Smith has pointed out, there's a one liner way to do
this. But if an IP address can represent itself as an integer (IMO the
least useful form) it should have at least a binary representation, and
lack of a seperate __bin__ means this is as close as I could get.

eric

On Mon, Feb 12, 2018 at 7:39 AM Christian Heimes <report@bugs.python.org>
wrote:

Christian Heimes <lists@cheimes.de> added the comment:

I agree with Serhiy and Eric. It's a needless complication of the module.
What's the actual use case of printing a human readable bit representation
of an IP address?

----------
nosy: +christian.heimes

---

Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue32820\>

---

[serhiy-storchaka]

I wouldn't say that "0b00000000000000010000110110111000100001011010001100000000000000000000000000000000100010100010111000000011011100000111001100110100" is a very human readable. For more readability it is better to group digits by 4 or 8, and why not use hexadecimal then?

In any case the application of this feature looks pretty narrow to me. And since it can be implemented as a one-line function, I think it shouldn't be added in the stdlib. The ipaddress classes are already complex.

[ewosborne]

IPv6 is nasty no matter how you do it (cf.
https://tools.ietf.org/html/rfc1924). And the ipaddr library already has
hex (packed()).

Binary's not about direct readabilty, but about ease of comparison. It's
much easier to show the reader

'0b00000001000000100000001100000100'
'0b00000001000000100000001100000011'
'0b11111111111111111111111111111100'

and have them figure out whether the mask contains both hosts than to show
them

'1.2.3.4'
'1.2.3.3'
'255.255.255.252'
and ask them to convert to binary in their heads. Without the zero padding
on the left, this is very easy to get wrong.

But I certainly agree that this is somewhat niche and a convenience
function, and if the consensus is that this is too narrow for stdlib, so be
it.

eric

On Mon, Feb 12, 2018 at 8:46 AM Serhiy Storchaka <report@bugs.python.org>
wrote:

Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment:

I wouldn't say that
"0b00000000000000010000110110111000100001011010001100000000000000000000000000000000100010100010111000000011011100000111001100110100"
is a very human readable. For more readability it is better to group digits
by 4 or 8, and why not use hexadecimal then?

In any case the application of this feature looks pretty narrow to me. And
since it can be implemented as a one-line function, I think it shouldn't be
added in the stdlib. The ipaddress classes are already complex.

----------

---

Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue32820\>

---

[ncoghlan]

I think the aspect that makes this potentially worthy of a helper function is the need to dynamically adjust the field width based on whether you're printing an IPv4 address or an IPv6 one, whether you're printing it in binary or hexadecimal, whether you're printing separator characters, and whether you're printing the base indicator prefix.

For example, consider the following:

>>> ip4 = ipaddress.ip_address("1.2.3.4")
>>> ip4
IPv4Address('1.2.3.4')
>>> ip6 = ipaddress.ip_address("::1:2:3:4")
>>> ip6
IPv6Address('::1:2:3:4')
>>> format(int(ip4), "#041_b")
'0b0000_0001_0000_0010_0000_0011_0000_0100'
>>> format(int(ip6), "#041_x")
'0x0000_0000_0000_0000_0001_0002_0003_0004'

The "41" in those examples comes from "prefix_len + (num_bits / bits_per_char) + (num_bits / bits_per_char / chars_per_separator) - 1":

IPv4 in binary: 2 + (32 / 1) + (32 / 1 / 4) - 1 = 2 + 32 + 8 - 1 = 41
IPv6 in hex: 2 + (128 / 4) + (128 / 1 / 4) - 1 = 2 + 32 + 8 - 1 = 41

So I think the potentially interesting method to implement here would be *format*, such that the field width calculation could be made implicit based on the other options selected.

While backwards compatibility means that IP address formatting would still need to be equivalent to "str(ip)" by default, it would be reasonably straightforward to make "format(ip, 'b')" output the number in binary, "format(ip, 'x')" do it in hex, and "format(ip, 'n')" be equivalent to "b" for IPv4 addresses, and "x" for IPv6 ones.

Unlike ordinary numbers, the IP addresses would always be zero-padded to a fixed width (32-bits for IPv4, 128 bits for IPv6), but "#" and "_" would be accepted to indicate whether or to add the base indicator prefix and/or group separators.

Given those enhancements, the display examples above would become:

>>> format(ip4, "#_n")
'0b0000_0001_0000_0010_0000_0011_0000_0100'
>>> format(ip6, "#_n")
'0x0000_0000_0000_0000_0001_0002_0003_0004'