Implement PEP 3144 (the ipaddress module)

Lib/ipaddress.py

 #!/usr/bin/python3
 #
 # Copyright 2007 Google Inc.
 #  Licensed to PSF under a Contributor Agreement.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
 #
 #      http://www.apache.org/licenses/LICENSE-2.0
@@ skipping 27 matching lines @@
     """A Value Error related to the netmask."""
 
 
 def ip_address(address, version=None):
     """Take an IP string/int and return an object of the correct type.
 
     Args:
         address: A string or integer, the IP address.  Either IPv4 or
           IPv6 addresses may be supplied; integers less than 2**32 will
           be considered to be IPv4 by default.
-        version: An Integer, 4 or 6. If set, don't try to automatically
-          determine what the IP address type is. important for things
+        version: An integer, 4 or 6.  If set, don't try to automatically
+          determine what the IP address type is.  Important for things
           like ip_address(1), which could be IPv4, '192.0.2.1',  or IPv6,
           '2001:db8::1'.
 
     Returns:
         An IPv4Address or IPv6Address object.
 
     Raises:
-        ValueError: if the string passed isn't either a v4 or a v6
-          address.
+        ValueError: if the *address* passed isn't either a v4 or a v6
+          address, or if the version is not None, 4, or 6.
 
     """
-    if version:
+    if version is not None:
         if version == 4:
             return IPv4Address(address)
         elif version == 6:
             return IPv6Address(address)
+        else:
+            raise ValueError()

[ezio.melotti, 2012/05/23 01:37:15]

Shouldn't this have a message?

 
     try:
         return IPv4Address(address)
     except (AddressValueError, NetmaskValueError):
         pass
 
     try:
         return IPv6Address(address)
     except (AddressValueError, NetmaskValueError):
         pass
 
     raise ValueError('%r does not appear to be an IPv4 or IPv6 address' %
                      address)
 
 
 def ip_network(address, version=None, strict=True):
     """Take an IP string/int and return an object of the correct type.
 
     Args:
         address: A string or integer, the IP network.  Either IPv4 or
           IPv6 networks may be supplied; integers less than 2**32 will
           be considered to be IPv4 by default.
-        version: An Integer, if set, don't try to automatically
-          determine what the IP address type is. important for things
+        version: An integer, 4 or 6.  If set, don't try to automatically

[ezio.melotti, 2012/05/23 01:37:15]

Ditto for the comma.

+          determine what the IP address type is.  Important for things
           like ip_network(1), which could be IPv4, '192.0.2.1/32', or IPv6,
           '2001:db8::1/128'.

[ezio.melotti, 2012/05/23 01:37:15]

The strict arg is not documented.

 
     Returns:
         An IPv4Network or IPv6Network object.
 
     Raises:
         ValueError: if the string passed isn't either a v4 or a v6
-          address. Or if the network has host bits set.
+          address. Or if the network has host bits set.  Or if the version
+          is not None, 4, or 6.
 
     """
-    if version:
+    if version is not None:
         if version == 4:
             return IPv4Network(address, strict)
         elif version == 6:
             return IPv6Network(address, strict)
+        else:
+            raise ValueError()
 
     try:
         return IPv4Network(address, strict)
     except (AddressValueError, NetmaskValueError):
         pass
 
     try:
         return IPv6Network(address, strict)
     except (AddressValueError, NetmaskValueError):
         pass
 
     raise ValueError('%r does not appear to be an IPv4 or IPv6 network' %
                      address)
 
 
 def ip_interface(address, version=None):
     """Take an IP string/int and return an object of the correct type.
 
     Args:
         address: A string or integer, the IP address.  Either IPv4 or
           IPv6 addresses may be supplied; integers less than 2**32 will
           be considered to be IPv4 by default.
-        version: An Integer, if set, don't try to automatically
-          determine what the IP address type is. important for things
-          like ip_network(1), which could be IPv4, '192.0.2.1/32', or IPv6,
+        version: An integer, 4 or 6.  If set, don't try to automatically
+          determine what the IP address type is.  Important for things
+          like ip_interface(1), which could be IPv4, '192.0.2.1/32', or IPv6,
           '2001:db8::1/128'.
 
     Returns:
-        An IPv4Network or IPv6Network object.
+        An IPv4Interface or IPv6Interface object.
 
     Raises:
         ValueError: if the string passed isn't either a v4 or a v6
-          address.
+          address.  Or if the version is not None, 4, or 6.
 
     Notes:
         The IPv?Interface classes describe an Address on a particular
         Network, so they're basically a combination of both the Address
         and Network classes.
     """
-    if version:
+    if version is not None:
         if version == 4:
             return IPv4Interface(address)
         elif version == 6:
             return IPv6Interface(address)
+        else:
+            raise ValueError()
 
     try:
         return IPv4Interface(address)
     except (AddressValueError, NetmaskValueError):
         pass
 
     try:
         return IPv6Interface(address)
     except (AddressValueError, NetmaskValueError):
         pass
 
     raise ValueError('%r does not appear to be an IPv4 or IPv6 network' %
                      address)
 
 
 def v4_int_to_packed(address):
-    """The binary representation of this address.
+    """Represent an address as 4 packed bytes in network (big-endian) order.
 
     Args:
         address: An integer representation of an IPv4 IP address.
 
     Returns:
-        The binary representation of this address.
+        The integer address packed as 4 bytes in network (big-endian) order.
 
     Raises:
-        ValueError: If the integer is too large to be an IPv4 IP
-          address.
+        ValueError: If the integer is  is negative or too large to be an
+          IPv4 IP address.
     """
-    if address > _BaseV4._ALL_ONES:
-        raise ValueError('Address too large for IPv4')
-    return struct.pack('!I', address)
+    try:
+        return struct.pack('!I', address)
+    except:
+        raise ValueError("Address negative or too large for IPv4")

[ezio.melotti, 2012/05/23 01:37:15]

I don't like the bare except too much.  Isn't the error message going to be
misleading when e.g. the address is not an int?

 
 
 def v6_int_to_packed(address):
-    """The binary representation of this address.
+    """Represent an address as 16 packed bytes in network (big-endian) order.
 
     Args:
         address: An integer representation of an IPv4 IP address.
 
     Returns:
-        The binary representation of this address.
+        The integer address packed as 16 bytes in network (big-endian) order.
     """
-    return struct.pack('!QQ', address >> 64, address & (2**64 - 1))
+    try:
+        return struct.pack('!QQ', address >> 64, address & (2**64 - 1))
+    except:
+        raise ValueError("Address negative or too large for IPv6")
 
 
 def _find_address_range(addresses):
-    """Find a sequence of addresses.
+    """Find a sequence of IPv#Address.
 
     Args:
-        addresses: a list of IPv4 or IPv6 addresses.
+        addresses: a list of IPv#Address objects.

[ezio.melotti, 2012/05/23 01:37:15]

I prefer "IPv4Address or IPv6Address"

 
     Returns:
         A tuple containing the first and last IP addresses in the sequence.
 
     """
     first = last = addresses[0]
     for ip in addresses[1:]:
         if ip._ip == last._ip + 1:
             last = ip
         else:
@@ skipping 1974 matching lines @@
     def with_prefixlen(self):
         return '%s/%d' % (str(self.network_address), self._prefixlen)
 
     @property
     def with_netmask(self):
         return '%s/%s' % (str(self.network_address), str(self.netmask))
 
     @property
     def with_hostmask(self):
         return '%s/%s' % (str(self.network_address), str(self.hostmask))