diff -r e1fdd79cfb01 Doc/library/ipaddress.rst --- a/Doc/library/ipaddress.rst Wed Aug 21 19:45:19 2013 +0100 +++ b/Doc/library/ipaddress.rst Wed Aug 21 21:37:05 2013 +0100 @@ -296,6 +296,12 @@ True +Hashing +""""""" + +Address objects are hashable, so they can be used as keys in dictionaries. + + Arithmetic operators """""""""""""""""""" @@ -352,14 +358,17 @@ a slash (``/``). The IP address is the network address, and the mask can be either a single number, which means it's a *prefix*, or a string representation of an IPv4 address. If it's the latter, the mask is - interpreted as a *net mask* if it starts with a non-zero field, or as - a *host mask* if it starts with a zero field. If no mask is provided, - it's considered to be ``/32``. + interpreted as a *net mask* if possible, or as a *host mask* otherwise. + If no mask is provided, it's considered to be ``/32``. For example, the following *address* specifications are equivalent: ``192.168.1.0/24``, ``192.168.1.0/255.255.255.0`` and ``192.168.1.0/0.0.0.255``. + Note that the two ambiguous cases are both treated as netmasks: + ``0.0.0.0/0.0.0.0`` is ``0.0.0.0/0``, and + ``1.2.3.4/255.255.255.255`` is ``1.2.3.4/32``. + 2. An integer that fits into 32 bits. This is equivalent to a single-address network, with the network address being *address* and the mask being ``/32``. @@ -405,9 +414,13 @@ The broadcast address for the network. Packets sent to the broadcast address should be received by every host on the network. - .. attribute:: host mask + .. attribute:: netmask - The host mask, as a string. + The netmask, as an :class:`IPv4Address` object. + + .. attribute:: hostmask + + The host mask, as an :class:`IPv4Address` object. .. attribute:: with_prefixlen .. attribute:: compressed @@ -526,15 +539,15 @@ Construct an IPv6 network definition. *address* can be one of the following: - 1. A string consisting of an IP address and an optional mask, separated by - a slash (``/``). The IP address is the network address, and the mask - can be either a single number, which means it's a *prefix*, or a string - representation of an IPv6 address. If it's the latter, the mask is - interpreted as a *net mask*. If no mask is provided, it's considered to - be ``/128``. + 1. A string consisting of an IP address and an optional prefix length, + separated by a slash (``/``). The IP address is the network address, + and the prefix length must be a single number, the *prefix*. If no + prefix length is provided, it's considered to be ``/128``. - For example, the following *address* specifications are equivalent: - ``2001:db00::0/24`` and ``2001:db00::0/ffff:ff00::``. + For example, the *address* specification might be ``2001:db00::0/24``. + + Note that IPv6 networks can't be specified using a net mask or a host + mask - those features are only in :class:`IPv4Network`. 2. An integer that fits into 128 bits. This is equivalent to a single-address network, with the network address being *address* and @@ -561,7 +574,8 @@ .. attribute:: is_link_local .. attribute:: network_address .. attribute:: broadcast_address - .. attribute:: host mask + .. attribute:: netmask + .. attribute:: hostmask .. attribute:: with_prefixlen .. attribute:: compressed .. attribute:: exploded @@ -596,8 +610,14 @@ Logical operators """"""""""""""""" -Network objects can be compared with the usual set of logical operators, -similarly to address objects. +Network objects can be compared with the usual set of logical operators. +Network objects are ordered first by network address, then by net mask. + + +Hashing +""""""" + +Network objects are hashable, so they can be used as keys in dictionaries. Iteration @@ -718,6 +738,57 @@ :class:`IPv4Interface`. +Operators +^^^^^^^^^ + +Interface objects support some operators. Unless stated otherwise, operators can +only be applied between compatible objects (i.e. IPv4 with IPv4, IPv6 with +IPv6). + + +Logical operators +""""""""""""""""" + +Interface objects can be compared with the usual set of logical operators. + +For equality comparison (``==`` and ``!=``), both the IP address and network must +be the same for the objects to be equal. An Interface will not compare equal to +any Address or Network object. + +For ordering (``<``, ``>``, etc) the rules are different. +Interface and address objects with the same IP version can be compared, and the +address objects will always sort before the interface objects. Two interface +objects are compared by comparing their networks, using the same rules as +:class:`IPv4Network` or :class:`IPv6Network`. The IP address plays no part in +the comparison. Note that you will get strange results when comparing two +interface objects with the same network but different IP addresses. E.g.:: + + >>> import ipaddress + >>> a = ipaddress.IPv4Interface('128.0.0.3/8') + >>> b = ipaddress.IPv4Interface('128.0.0.5/8') + >>> a < b + False + >>> b < a + False + >>> a > b + True + >>> b > a + True + +Also, note that since the comparison rules for interfaces are different from the +rules for addresses, this means that :class:`IPv4Interface` and its base class +:class:`IPv4Address` don't follow the Liskov Substitution Principle. I.e. you +can't pass a :class:`IPv4Interface` to code that expects a :class:`IPv4Address` +and uses comparison operators or hashing. Similarly for :class:`IPv6Interface` +and :class:`IPv6Address`. + + +Hashing +""""""" + +Interface objects are hashable, so they can be used as keys in dictionaries. + + Other Module Level Functions ---------------------------- diff -r e1fdd79cfb01 Lib/ipaddress.py --- a/Lib/ipaddress.py Wed Aug 21 19:45:19 2013 +0100 +++ b/Lib/ipaddress.py Wed Aug 21 21:37:05 2013 +0100 @@ -1991,13 +1991,13 @@ Args: address: A string or integer representing the IPv6 network or the - IP and prefix/netmask. + IP and prefix length. '2001:db8::/128' '2001:db8:0000:0000:0000:0000:0000:0000/128' '2001:db8::' are all functionally the same in IPv6. That is to say, - failing to provide a subnetmask will create an object with - a mask of /128. + failing to provide a prefix length will create an object with + a prefix length of /128. Additionally, an integer can be passed, so IPv6Network('2001:db8::') == @@ -2012,7 +2012,7 @@ Raises: AddressValueError: If address isn't a valid IPv6 address. - NetmaskValueError: If the netmask isn't valid for + NetmaskValueError: If the prefix length isn't valid for an IPv6 address. ValueError: If strict was True and a network address was not supplied. @@ -2062,14 +2062,14 @@ self.hosts = self.__iter__ def _is_valid_netmask(self, prefixlen): - """Verify that the netmask/prefixlen is valid. + """Verify that the prefix length is valid. Args: - prefixlen: A string, the netmask in prefix length format. + prefixlen: A string, the prefix length. Returns: A boolean, True if the prefix represents a valid IPv6 - netmask. + prefix length. """ try: