mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Review ipaddr docs and add them in the TOC under "Internet protocols".

Browse source
This commit is contained in:
Georg Brandl 2009-05-01 21:28:35 +00:00
parent 3fd4ea9dab
commit b64b8278d1
2 changed files with 80 additions and 77 deletions
Download patch file Download diff file Expand all files Collapse all files

1
Doc/library/internet.rst
View file

@ -35,6 +35,7 @@ is currently supported on most popular platforms. Here is an overview:
smtpd.rst smtpd.rst
telnetlib.rst telnetlib.rst
uuid.rst uuid.rst
ipaddr.rst
urlparse.rst urlparse.rst
socketserver.rst socketserver.rst
basehttpserver.rst basehttpserver.rst

130
Doc/library/ipaddr.rst
View file

@ -1,4 +1,3 @@
:mod:`ipaddr` --- IP address manipulation library :mod:`ipaddr` --- IP address manipulation library
================================================= =================================================
@ -19,22 +18,22 @@ both IPv4 and IPv6.
.. function:: IP(ipaddr) .. function:: IP(ipaddr)
Take an IP string or int and return an object of the correct type. Take an IP string or int and return an object of the correct type. Returns
Returns an :class:`IPv4` or :class:`IPv6` object. an :class:`IPv4` or :class:`IPv6` object.
The ``ipaddr`` parameter must be a string or integer representing the IP The *ipaddr* parameter must be a string or integer representing the IP
address. Either IPv4 or IPv6 addresses may be supplied. Integers less address. Either IPv4 or IPv6 addresses may be supplied. Integers less than
than 2**32 will be considered to be IPv4. 2**32 will be considered to be IPv4.
Raises :exc:`ValueError` if the ipaddr passed is not either an IPv4 or an Raises :exc:`ValueError` if the *ipaddr* passed is not either an IPv4 or an
IPv6 address. IPv6 address.
.. function:: collapse_address_list(addresses) .. function:: collapse_address_list(addresses)
Collapses a sequence of :class:`IPv4` or :class:`IPv6` objects into Collapse a sequence of :class:`IPv4` or :class:`IPv6` objects into the most
the most concise representation. Returns a list of :class:`IPv4` concise representation. Returns a list of :class:`IPv4` or :class:`IPv6`
or :class:`IPv6` objects. objects.
Example usage:: Example usage::
@ -46,98 +45,98 @@ Example usage::
A generic IP address object. This base class defines the API and contains A generic IP address object. This base class defines the API and contains
common code. Most authors should either use the :func:`IP` function or common code. Most authors should either use the :func:`IP` function or
create :class:`IPv4` or :class:`IPv6` objects directly rather than using create :class:`IPv4` or :class:`IPv6` objects directly rather than using this
this base class. base class.
IP address objects support the following python operators: IP address objects support the following python operators:
``=``, ``!=``, ``<``, ``>``, ``<=``, ``>=``, and ``in``. ``=``, ``!=``, ``<``, ``>``, ``<=``, ``>=``, and ``in``.
An IP address object may be used as a sequence index or as a hash key An IP address object may be used as a sequence index or as a hash key and can
and can be converted back to an integer representation using ``int()``. be converted back to an integer representation using :func:`int`. It may
It may also be used as a sequence that yeilds the string also be used as a sequence that yields the string representation of every IP
representation of every IP address within the object's subnet. address within the object's subnet.
The following properties are available on all IP address objects: The following properties are available on all IP address objects:
.. data:: broadcast .. attr:: broadcast
Integer representation of the broadcast address. Read only. Integer representation of the broadcast address. Read only.
.. data:: broadcast_ext .. attr:: broadcast_ext
Dotted decimal or colon string version of the broadcast address. Read only. Dotted decimal or colon string version of the broadcast address. Read
only.
.. data:: hostmask .. attr:: hostmask
Integer representation of the hostmask. Read only. Integer representation of the hostmask. Read only.
.. data:: hostmask_ext .. attr:: hostmask_ext
Dotted decimal or colon string version of the hostmask. Read only. Dotted decimal or colon string version of the hostmask. Read only.
.. data:: ip .. attr:: ip
Integer representation of the IP address. Read only. Integer representation of the IP address. Read only.
.. data:: ip_ext .. attr:: ip_ext
Dotted decimal or colon string version of the IP address. Read only. Dotted decimal or colon string version of the IP address. Read only.
.. data:: ip_ext_full .. attr:: ip_ext_full
Canonical string version of the IP address. Read only. Canonical string version of the IP address. Read only.
.. data:: is_loopback .. attr:: is_loopback
True if the address is a loopback address as defined in IPv4 :rfc:`3330` True if the address is a loopback address as defined in IPv4 :rfc:`3330`
or IPv6 :rfc:`2373` section 2.5.3. or IPv6 :rfc:`2373` section 2.5.3.
.. data:: is_link_local .. attr:: is_link_local
True if the address is a link-local address as defined in IPv4 :rfc:`3927` True if the address is a link-local address as defined in IPv4 :rfc:`3927`
or IPv6 :rfc:`4291`. or IPv6 :rfc:`4291`.
.. data:: is_multicast .. attr:: is_multicast
True if the address is reserved for multicast use. True if the address is reserved for multicast use. See IPv4 :rfc:`3171`
See IPv4 :rfc:`3171` or IPv6 :rfc:`2373` section 2.7 for details. or IPv6 :rfc:`2373` section 2.7 for details.
.. data:: is_private .. attr:: is_private
True if the address is reserved for private networks as defined in True if the address is reserved for private networks as defined in IPv4
IPv4 :rfc:`1918` or IPv6 :rfc:`4193`. :rfc:`1918` or IPv6 :rfc:`4193`.
.. data:: netmask .. attr:: netmask
Integer representation of the netmask. Read only. Integer representation of the netmask. Read only.
.. data:: netmask_ext .. attr:: netmask_ext
Dotted decimal or colon string version of the netmask. Read only. Dotted decimal or colon string version of the netmask. Read only.
.. data:: network .. attr:: network
Integer representation of the network. Read only. Integer representation of the network. Read only.
.. data:: network_ext .. attr:: network_ext
Dotted decimal or colon string version of the network. Read only. Dotted decimal or colon string version of the network. Read only.
.. data:: numhosts .. attr:: numhosts
Number of hosts in the current subnet. Read only. Number of hosts in the current subnet. Read only.
.. data:: packed .. attr:: packed
The packed network byte order representation of this network address. Read only. The packed network byte order representation of this network address.
Read only.
.. data:: prefixlen .. attr:: prefixlen
A property to get and set the prefix length. Readable and writeable. A property to get and set the prefix length. Readable and writeable.
.. data:: version .. attr:: version
Integer IP version number. Read only. Integer IP version number. Read only.
@ -146,8 +145,8 @@ Example usage::
.. method:: address_exclude(other) .. method:: address_exclude(other)
Remove an address from within a larger block. Remove an address from within a larger block. Returns a sorted list of IP
Returns a sorted list of IP address objects representing networks. address objects representing networks.
Examples:: Examples::
@ -162,7 +161,7 @@ Example usage::
[IP('::0/128'), IP('::2/127'), IP('::4/126'), IP('::8/125'), [IP('::0/128'), IP('::2/127'), IP('::4/126'), IP('::8/125'),
... IP('0:0:8000::/33')] ... IP('0:0:8000::/33')]
Raises :exc:`ValueError` if `other` is not completely contained by self. Raises :exc:`ValueError` if *other* is not completely contained by *self*.
.. method:: compare_networks(other) .. method:: compare_networks(other)
@ -170,9 +169,9 @@ Example usage::
Compare this IP object's network to another IP network. Compare this IP object's network to another IP network.
Returns -1, 0 or 1. Returns -1, 0 or 1.
This compares the integer representation of the network addresses. This compares the integer representation of the network addresses. The
The host bits are not considered by this method. host bits are not considered by this method. If you want to compare host
If you want to compare host bits, you can use ``host_a.ip < host_b.ip``. bits, you can use ``host_a.ip < host_b.ip``.
If the IP versions of self and other are the same, returns: If the IP versions of self and other are the same, returns:
@ -204,14 +203,14 @@ Example usage::
Returns a list of subnets which when joined make up the current subnet. Returns a list of subnets which when joined make up the current subnet.
The optional ``prefixlen_diff`` argument specifies how many bits the prefix The optional *prefixlen_diff* argument specifies how many bits the prefix
length should be increased by. Given a /24 network and prefixlen_diff=3, length should be increased by. Given a /24 network and
for example, 8 subnets of size /27 will be returned. ``prefixlen_diff=3``, for example, 8 subnets of size /27 will be returned.
If called on a host IP address rather than a network, a list containing If called on a host IP address rather than a network, a list containing
the host itself will be returned. the host itself will be returned.
Raises :exc:`PrefixlenDiffInvalidError` if the prefixlen_diff is out of Raises :exc:`PrefixlenDiffInvalidError` if the *prefixlen_diff* is out of
range. range.
@ -220,9 +219,10 @@ Example usage::
Returns a single IP object representing the supernet containing the Returns a single IP object representing the supernet containing the
current network. current network.
The optional ``prefixlen_diff`` argument specifies how many bits the prefix The optional *prefixlen_diff* argument specifies how many bits the prefix
length should be decreased by. Given a /24 network and prefixlen_diff=3, length should be decreased by. Given a /24 network and
for example, a supernet with a 21 bit netmask is returned. ``prefixlen_diff=3``, for example, a supernet with a 21 bit netmask is
returned.
Raises :exc:`PrefixlenDiffInvalidError` if the prefixlen_diff is out of Raises :exc:`PrefixlenDiffInvalidError` if the prefixlen_diff is out of
range. range.
@ -269,9 +269,10 @@ Example usage::
.netmask_ext: 64 .netmask_ext: 64
.prefixlen: 64 .prefixlen: 64
.. data:: is_site_local .. attr:: is_site_local
True if the address was reserved as site-local in :rfc:`3513` section 2.5.6. True if the address was reserved as site-local in :rfc:`3513` section
2.5.6.
.. note:: .. note::
@ -279,9 +280,10 @@ Example usage::
Use :data:`is_private` to test if this address is in the space of Use :data:`is_private` to test if this address is in the space of
unique local addresses as defined by :rfc:`4193`. unique local addresses as defined by :rfc:`4193`.
.. data:: is_unspecified .. attr:: is_unspecified
True if this is the unspecified address as defined in :rfc:`2373` section 2.5.2. True if this is the unspecified address as defined in :rfc:`2373` section
2.5.2.
The following exceptions are defined by this module: The following exceptions are defined by this module:
@ -316,12 +318,12 @@ The following exceptions are defined by this module:
.. exception:: PrefixlenDiffInvalidError .. exception:: PrefixlenDiffInvalidError
Raised when :meth:`BaseIP.subnet` or :meth:`BaseIP.supernet` is called with a bad Raised when :meth:`BaseIP.subnet` or :meth:`BaseIP.supernet` is called with a
``prefixlen_diff``. bad ``prefixlen_diff``.
.. seealso:: .. seealso::
http://code.google.com/p/ipaddr-py/ http://code.google.com/p/ipaddr-py/
The original source of this module and a place to download it as The original source of this module and a place to download it as a package
a package for use on earlier versions of Python. for use on earlier versions of Python.