Author: gregory.p.smith Date: Sat May 30 22:01:43 2009 New Revision: 73061 Log: Merged revisions 73060 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r73060 | gregory.p.smith | 2009-05-30 12:58:11 -0700 (Sat, 30 May 2009) | 2 lines Add more examples to the ipaddr documentation. ........ Modified: python/branches/py3k/ (props changed) python/branches/py3k/Doc/library/ipaddr.rst Modified: python/branches/py3k/Doc/library/ipaddr.rst ============================================================================== --- python/branches/py3k/Doc/library/ipaddr.rst (original) +++ python/branches/py3k/Doc/library/ipaddr.rst Sat May 30 22:01:43 2009 @@ -16,6 +16,90 @@ both IPv4 and IPv6. +.. _ipaddr_examples: + +Examples +-------- + +Netmask. + + >>> ipaddr.IP('1.1.1.1/255.255.255.0') + IPv4('1.1.1.1/24') + >>> ipaddr.IP('1080::200C:417B/96') + IPv6('1080::200c:417b/96') + +Hostmask. + + >>> ipaddr.IPv4('1.1.1.1/0.0.0.255') + IPv4('1.1.1.1/24') + +Prefix length. + + >>> addr = ipaddr.IPv4('1.1.1.1/24') + >>> addr.prefixlen + 24 + +Individual addresses. + + >>> ipaddr.IP('1.1.1.1') + IPv4('1.1.1.1/32') + +Many standard Python operations are also supported. + +Comparison. + + >>> ipaddr.IPv4('1.1.1.1') == ipaddr.IPv4('1.1.1.2') + False + >>> ipaddr.IPv4('1.1.1.1') < ipaddr.IPv4('1.1.1.2') + True + +Inclusion. + + >>> ipaddr.IPv4('1.1.1.1') in ipaddr.IPv4("1.0.0.0/8") + True + +Sorting. + + >>> a = ipaddr.IPv4('1.1.1.10') + >>> b = ipaddr.IPv4('1.10.1.10') + >>> c = ipaddr.IPv4('1.1.10.10') + >>> d = ipaddr.IPv4('1.1.1.1') + >>> sorted([a, b, c, d]) + [IPv4('1.1.1.1/32'), IPv4('1.1.1.10/32'), IPv4('1.1.10.10/32'), IPv4('1.10.1.10/32')] + +Conversion to string and integer forms. + + >>> spam = ipaddr.IPv4('192.168.1.254')) + >>> str(spam) + '192.168.1.254/32' + >>> spam.ip_ext + '192.168.1.254' + >>> int(spam) + 3232236030 + >>> eggs = ipaddr.IPv6('ffff::1/120') + >>> int(eggs) + 340277174624079928635746076935438991361 + +Additionally, there are quite a few network-specific features available to +ipaddr. + + >>> ipaddr.IPv4('10.0.0.0/8').supernet() + IPv4('10.0.0.0/7') + >>> ipaddr.IPv4('10.0.0.0/8').subnet() + [IPv4('10.0.0.0/9'), IPv4('10.128.0.0/9')] + # This returns networks with a prefix length of /10 + >>> ipaddr.IPv4('10.0.0.0/8').subnet(prefixlen_diff=2) + [IPv4('10.0.0.0/10'), IPv4('10.64.0.0/10'), IPv4('10.128.0.0/10'), IPv4('10.192.0.0/10')] + # Remove an address from a superblock. + >>> ipaddr.IP('10.0.0.0/24').address_exclude(ipaddr.IP('10.0.0.0/28')) + [IPv4('10.0.0.16/28'), IPv4('10.0.0.32/27'), IPv4('10.0.0.64/26'), IPv4('10.0.0.128/25')] + + +.. _ipaddr_funcs_and_classes: + +Functions And Classes +--------------------- + .. function:: IP(ipaddr) Take an IP string or int and return an object of the correct type. Returns @@ -159,8 +243,7 @@ >>> 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')] + [IP('::0/128'), IP('::2/127'), IP('::4/126'), IP('::8/125'), IP('0:0:8000::/33')] Raises :exc:`ValueError` if *other* is not completely contained by *self*. @@ -297,6 +380,11 @@ 2.5.2. +.. _ipaddr_exceptions: + +Exceptions +---------- + The following exceptions are defined by this module: .. exception:: Error