[Python-checkins] r72629 - python/branches/py3k/Lib/ipaddr.py

Thu May 14 17:51:36 CEST 2009

Author: raymond.hettinger
Date: Thu May 14 17:51:36 2009
New Revision: 72629
Log:
Convert docstring examples to doctests and fix
any errors that were found. Add a usage note
to compare_networks() showing how to do the 
ordering with modern python.
Modified:
 python/branches/py3k/Lib/ipaddr.py
Modified: python/branches/py3k/Lib/ipaddr.py
==============================================================================

--- python/branches/py3k/Lib/ipaddr.py	(original)
+++ python/branches/py3k/Lib/ipaddr.py	Thu May 14 17:51:36 2009
@@ -135,16 +135,17 @@
 
 Example:
 
- ip1 = IPv4('1.1.0.0/24')
- ip2 = IPv4('1.1.1.0/24')
- ip3 = IPv4('1.1.2.0/24')
- ip4 = IPv4('1.1.3.0/24')
- ip5 = IPv4('1.1.4.0/24')
- ip6 = IPv4('1.1.0.1/22')
+ >>> ip1 = IPv4('1.1.0.0/24')
+ >>> ip2 = IPv4('1.1.1.0/24')
+ >>> ip3 = IPv4('1.1.2.0/24')
+ >>> ip4 = IPv4('1.1.3.0/24')
+ >>> ip5 = IPv4('1.1.4.0/24')
+ >>> ip6 = IPv4('1.1.0.1/22')
 
- _collapse_address_list_recursive([ip1, ip2, ip3, ip4, ip5, ip6]) ->
- [IPv4('1.1.0.0/22'), IPv4('1.1.4.0/24')]
+ >>> _collapse_address_list_recursive([ip1, ip2, ip3, ip4, ip5, ip6])
+ [IPv4('1.1.0.0/22'), IPv4('1.1.4.0/24'), IPv4('1.1.0.1/22')]
 
+ Notes:
 This shouldn't be called directly; it is called via
 collapse_address_list([]).
 
@@ -180,8 +181,9 @@
 """Collapse a list of IP objects.
 
 Example:
- collapse_address_list([IPv4('1.1.0.0/24'), IPv4('1.1.1.0/24')]) ->
- [IPv4('1.1.0.0/23')]
+
+ >>> collapse_address_list([IPv4('1.1.0.0/24'), IPv4('1.1.1.0/24')])
+ [IPv4('1.1.0.0/23')]
 
 Args:
 addresses: A list of IPv4 or IPv6 objects.
@@ -270,21 +272,20 @@
 
 For example:
 
- addr1 = IP('10.1.1.0/24')
- addr2 = IP('10.1.1.0/26')
- addr1.address_exclude(addr2) =
- [IP('10.1.1.64/26'), IP('10.1.1.128/25')]
+ >>> addr1 = IP('10.1.1.0/24')
+ >>> addr2 = IP('10.1.1.0/26')
+ >>> addr1.address_exclude(addr2)
+ [IPv4('10.1.1.64/26'), IPv4('10.1.1.128/25')]
 
 or IPv6:
 
- addr1 = IP('::1/32')
- addr2 = IP('::1/128')
- addr1.address_exclude(addr2) = [IP('::0/128'),
- IP('::2/127'),
- IP('::4/126'),
- IP('::8/125'),
- ...
- IP('0:0:8000::/33')]
+ >>> addr1 = IP('::1/32')
+ >>> addr2 = IP('::1/128')
+ >>> s = addr1.address_exclude(addr2)
+ >>> s[:4]
+ [IPv6('::/128'), IPv6('::2/127'), IPv6('::4/126'), IPv6('::8/125')]
+ >>> s[-1]
+ IPv6('0:0:8000::/33')
 
 Args:
 other: An IP object of the same type.
@@ -373,6 +374,15 @@
 1 if self.version > other.version
 eg: IPv6('::1/128') > IPv4('255.255.255.0/24')
 
+ To sort networks with sorted(), min(), max() and other tools with a
+ *key* argument, use the operator.attrgetter() function to extract the
+ relevant fields:
+
+ >>> from operator import attrgetter
+ >>> s = [IPv6('::1/128'), IPv4('255.255.255.0/24')]
+ >>> sorted(s, key=attrgetter('version', 'network', 'netmask'))
+ [IPv4('255.255.255.0/24'), IPv6('::1/128')]
+
 """
 if self.version < other.version:
 return -1
@@ -521,19 +531,23 @@
 
 """This class represents and manipulates 32-bit IPv4 addresses.
 
- Attributes: [examples for IPv4('1.2.3.4/27')]
- .ip: 16909060
- .ip_ext: '1.2.3.4'
- .ip_ext_full: '1.2.3.4'
- .network: 16909056L
- .network_ext: '1.2.3.0'
- .hostmask: 31L (0x1F)
- .hostmask_ext: '0.0.0.31'
- .broadcast: 16909087L (0x102031F)
- .broadcast_ext: '1.2.3.31'
- .netmask: 4294967040L (0xFFFFFFE0)
- .netmask_ext: '255.255.255.224'
- .prefixlen: 27
+ >>> addr = IPv4('1.2.3.4/27')
+ >>> for attr in ['ip', 'ip_ext', 'ip_ext_full', 'network', 'network_ext',
+ ... 'hostmask', 'hostmask_ext', 'broadcast', 'broadcast_ext',
+ ... 'netmask', 'netmask_ext', 'prefixlen']:
+ ... print(attr, '=', getattr(addr, attr))
+ ip = 16909060
+ ip_ext = 1.2.3.4
+ ip_ext_full = 1.2.3.4
+ network = 16909056
+ network_ext = 1.2.3.0
+ hostmask = 31
+ hostmask_ext = 0.0.0.31
+ broadcast = 16909087
+ broadcast_ext = 1.2.3.31
+ netmask = 4294967264
+ netmask_ext = 255.255.255.224
+ prefixlen = 27
 
 """
 
@@ -558,9 +572,9 @@
 net-masks. (255.0.0.0 == 0.255.255.255)
 
 Additionally, an integer can be passed, so
- IPv4('192.168.1.1') == IPv4(3232235777).
+ IPv4('192.168.1.1') == IPv4(3232235777).
 or, more generally
- IPv4(IPv4('192.168.1.1').ip) == IPv4('192.168.1.1')
+ IPv4(IPv4('192.168.1.1').ip) == IPv4('192.168.1.1')
 
 Raises:
 IPv4IpValidationError: If ipaddr isn't a valid IPv4 address.
@@ -863,19 +877,23 @@
 
 """This class respresents and manipulates 128-bit IPv6 addresses.
 
- Attributes: [examples for IPv6('2001:658:22A:CAFE:200::1/64')]
- .ip: 42540616829182469433547762482097946625L
- .ip_ext: '2001:658:22a:cafe:200::1'
- .ip_ext_full: '2001:0658:022a:cafe:0200:0000:0000:0001'
- .network: 42540616829182469433403647294022090752L
- .network_ext: '2001:658:22a:cafe::'
- .hostmask: 18446744073709551615L
- .hostmask_ext: '::ffff:ffff:ffff:ffff'
- .broadcast: 42540616829182469451850391367731642367L
- .broadcast_ext: '2001:658:22a:cafe:ffff:ffff:ffff:ffff'
- .netmask: 340282366920938463444927863358058659840L
- .netmask_ext: 64
- .prefixlen: 64
+ >>> addr = IPv6('2001:658:22A:CAFE:200::1/64')
+ >>> for attr in ['ip', 'ip_ext', 'ip_ext_full', 'network', 'network_ext',
+ ... 'hostmask', 'hostmask_ext', 'broadcast', 'broadcast_ext',
+ ... 'netmask', 'netmask_ext', 'prefixlen']:
+ ... print(attr, '=', getattr(addr, attr))
+ ip = 42540616829182469433547762482097946625
+ ip_ext = 2001:658:22a:cafe:200::1
+ ip_ext_full = 2001:0658:022a:cafe:0200:0000:0000:0001
+ network = 42540616829182469433403647294022090752
+ network_ext = 2001:658:22a:cafe::
+ hostmask = 18446744073709551615
+ hostmask_ext = ::ffff:ffff:ffff:ffff
+ broadcast = 42540616829182469451850391367731642367
+ broadcast_ext = 2001:658:22a:cafe:ffff:ffff:ffff:ffff
+ netmask = 340282366920938463444927863358058659840
+ netmask_ext = 64
+ prefixlen = 64
 
 """
 
@@ -896,10 +914,10 @@
 a mask of /128.
 
 Additionally, an integer can be passed, so
- IPv6('2001:4860::') ==
- IPv6(42541956101370907050197289607612071936L).
+ IPv6('2001:4860::') ==
+ IPv6(42541956101370907050197289607612071936L).
 or, more generally
- IPv6(IPv6('2001:4860::').ip) == IPv6('2001:4860::')
+ IPv6(IPv6('2001:4860::').ip) == IPv6('2001:4860::')
 
 Raises:
 IPv6IpValidationError: If ipaddr isn't a valid IPv6 address.
@@ -1367,3 +1385,8 @@
 _IPV6_RFC4291_LINK_LOCAL = IPv6('fe80::/10')
 _IPV6_RFC3513_SITE_LOCAL = IPv6('fec0::/10') # Deprecated by RFC3879.
 _IPV6_RFC4193_PRIVATE = IPv6('fc00::/7')
+
+if __name__ == '__main__':
+
+ import doctest
+ print(doctest.testmod())
