mirror of
https://github.com/python/cpython.git
synced 2025-09-26 18:29:57 +00:00
Review ipaddr docs and add them in the TOC under "Internet protocols".
This commit is contained in:
Georg Brandl
parent
3fd4ea9dab
commit
b64b8278d1
2 changed files with 80 additions and 77 deletions
|
|
@ -35,6 +35,7 @@ is currently supported on most popular platforms. Here is an overview:
|
|||
smtpd.rst
|
||||
telnetlib.rst
|
||||
uuid.rst
|
||||
ipaddr.rst
|
||||
urlparse.rst
|
||||
socketserver.rst
|
||||
basehttpserver.rst
|
||||
|
|
|
|||
|
|
@ -1,4 +1,3 @@
|
|||
|
||||
:mod:`ipaddr` --- IP address manipulation library
|
||||
=================================================
|
||||
|
||||
|
|
@ -19,22 +18,22 @@ both IPv4 and IPv6.
|
|||
|
||||
.. function:: IP(ipaddr)
|
||||
|
||||
Take an IP string or int and return an object of the correct type.
|
||||
Returns an :class:`IPv4` or :class:`IPv6` object.
|
||||
Take an IP string or int and return an object of the correct type. Returns
|
||||
an :class:`IPv4` or :class:`IPv6` object.
|
||||
|
||||
The ``ipaddr`` parameter must be a string or integer representing the IP
|
||||
address. Either IPv4 or IPv6 addresses may be supplied. Integers less
|
||||
than 2**32 will be considered to be IPv4.
|
||||
The *ipaddr* parameter must be a string or integer representing the IP
|
||||
address. Either IPv4 or IPv6 addresses may be supplied. Integers less than
|
||||
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.
|
||||
|
||||
|
||||
.. function:: collapse_address_list(addresses)
|
||||
|
||||
Collapses a sequence of :class:`IPv4` or :class:`IPv6` objects into
|
||||
the most concise representation. Returns a list of :class:`IPv4`
|
||||
or :class:`IPv6` objects.
|
||||
Collapse a sequence of :class:`IPv4` or :class:`IPv6` objects into the most
|
||||
concise representation. Returns a list of :class:`IPv4` or :class:`IPv6`
|
||||
objects.
|
||||
|
||||
Example usage::
|
||||
|
||||
|
|
@ -46,98 +45,98 @@ Example usage::
|
|||
|
||||
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
|
||||
create :class:`IPv4` or :class:`IPv6` objects directly rather than using
|
||||
this base class.
|
||||
|
||||
create :class:`IPv4` or :class:`IPv6` objects directly rather than using this
|
||||
base class.
|
||||
|
||||
IP address objects support the following python operators:
|
||||
``=``, ``!=``, ``<``, ``>``, ``<=``, ``>=``, and ``in``.
|
||||
|
||||
An IP address object may be used as a sequence index or as a hash key
|
||||
and can be converted back to an integer representation using ``int()``.
|
||||
It may also be used as a sequence that yeilds the string
|
||||
representation of every IP address within the object's subnet.
|
||||
|
||||
An IP address object may be used as a sequence index or as a hash key and can
|
||||
be converted back to an integer representation using :func:`int`. It may
|
||||
also be used as a sequence that yields the string representation of every IP
|
||||
address within the object's subnet.
|
||||
|
||||
The following properties are available on all IP address objects:
|
||||
|
||||
.. data:: broadcast
|
||||
.. attr:: broadcast
|
||||
|
||||
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.
|
||||
|
||||
.. data:: hostmask_ext
|
||||
.. attr:: hostmask_ext
|
||||
|
||||
Dotted decimal or colon string version of the hostmask. Read only.
|
||||
|
||||
.. data:: ip
|
||||
.. attr:: ip
|
||||
|
||||
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.
|
||||
|
||||
.. data:: ip_ext_full
|
||||
.. attr:: ip_ext_full
|
||||
|
||||
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`
|
||||
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`
|
||||
or IPv6 :rfc:`4291`.
|
||||
|
||||
.. data:: is_multicast
|
||||
.. attr:: is_multicast
|
||||
|
||||
True if the address is reserved for multicast use.
|
||||
See IPv4 :rfc:`3171` or IPv6 :rfc:`2373` section 2.7 for details.
|
||||
True if the address is reserved for multicast use. See IPv4 :rfc:`3171`
|
||||
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
|
||||
IPv4 :rfc:`1918` or IPv6 :rfc:`4193`.
|
||||
True if the address is reserved for private networks as defined in IPv4
|
||||
:rfc:`1918` or IPv6 :rfc:`4193`.
|
||||
|
||||
.. data:: netmask
|
||||
.. attr:: netmask
|
||||
|
||||
Integer representation of the netmask. Read only.
|
||||
|
||||
.. data:: netmask_ext
|
||||
.. attr:: netmask_ext
|
||||
|
||||
Dotted decimal or colon string version of the netmask. Read only.
|
||||
|
||||
.. data:: network
|
||||
.. attr:: network
|
||||
|
||||
Integer representation of the network. Read only.
|
||||
|
||||
.. data:: network_ext
|
||||
.. attr:: network_ext
|
||||
|
||||
Dotted decimal or colon string version of the network. Read only.
|
||||
|
||||
.. data:: numhosts
|
||||
.. attr:: numhosts
|
||||
|
||||
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.
|
||||
|
||||
.. data:: version
|
||||
.. attr:: version
|
||||
|
||||
Integer IP version number. Read only.
|
||||
|
||||
|
|
@ -146,8 +145,8 @@ Example usage::
|
|||
|
||||
.. method:: address_exclude(other)
|
||||
|
||||
Remove an address from within a larger block.
|
||||
Returns a sorted list of IP address objects representing networks.
|
||||
Remove an address from within a larger block. Returns a sorted list of IP
|
||||
address objects representing networks.
|
||||
|
||||
Examples::
|
||||
|
||||
|
|
@ -162,7 +161,7 @@ Example usage::
|
|||
[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.
|
||||
Raises :exc:`ValueError` if *other* is not completely contained by *self*.
|
||||
|
||||
|
||||
.. method:: compare_networks(other)
|
||||
|
|
@ -170,9 +169,9 @@ Example usage::
|
|||
Compare this IP object's network to another IP network.
|
||||
Returns -1, 0 or 1.
|
||||
|
||||
This compares the integer representation of the network addresses.
|
||||
The host bits are not considered by this method.
|
||||
If you want to compare host bits, you can use ``host_a.ip < host_b.ip``.
|
||||
This compares the integer representation of the network addresses. The
|
||||
host bits are not considered by this method. If you want to compare host
|
||||
bits, you can use ``host_a.ip < host_b.ip``.
|
||||
|
||||
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.
|
||||
|
||||
The optional ``prefixlen_diff`` argument specifies how many bits the prefix
|
||||
length should be increased by. Given a /24 network and prefixlen_diff=3,
|
||||
for example, 8 subnets of size /27 will be returned.
|
||||
The optional *prefixlen_diff* argument specifies how many bits the prefix
|
||||
length should be increased by. Given a /24 network and
|
||||
``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
|
||||
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.
|
||||
|
||||
|
||||
|
|
@ -220,9 +219,10 @@ Example usage::
|
|||
Returns a single IP object representing the supernet containing the
|
||||
current network.
|
||||
|
||||
The optional ``prefixlen_diff`` argument specifies how many bits the prefix
|
||||
length should be decreased by. Given a /24 network and prefixlen_diff=3,
|
||||
for example, a supernet with a 21 bit netmask is returned.
|
||||
The optional *prefixlen_diff* argument specifies how many bits the prefix
|
||||
length should be decreased by. Given a /24 network and
|
||||
``prefixlen_diff=3``, for example, a supernet with a 21 bit netmask is
|
||||
returned.
|
||||
|
||||
Raises :exc:`PrefixlenDiffInvalidError` if the prefixlen_diff is out of
|
||||
range.
|
||||
|
|
@ -269,9 +269,10 @@ Example usage::
|
|||
.netmask_ext: 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::
|
||||
|
||||
|
|
@ -279,9 +280,10 @@ Example usage::
|
|||
Use :data:`is_private` to test if this address is in the space of
|
||||
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:
|
||||
|
|
@ -316,12 +318,12 @@ The following exceptions are defined by this module:
|
|||
|
||||
.. exception:: PrefixlenDiffInvalidError
|
||||
|
||||
Raised when :meth:`BaseIP.subnet` or :meth:`BaseIP.supernet` is called with a bad
|
||||
``prefixlen_diff``.
|
||||
Raised when :meth:`BaseIP.subnet` or :meth:`BaseIP.supernet` is called with a
|
||||
bad ``prefixlen_diff``.
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
http://code.google.com/p/ipaddr-py/
|
||||
The original source of this module and a place to download it as
|
||||
a package for use on earlier versions of Python.
|
||||
The original source of this module and a place to download it as a package
|
||||
for use on earlier versions of Python.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue