Issue #14814: Add first draft of PEP 3144 ipaddress module documentation (initial patch by Sandro Tosi)

1 files changed, 251 insertions, 0 deletions

diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst
new file mode 100644
index 0000000..b4cbb2c
--- /dev/null
+++ b/Doc/library/ipaddress.rst
@@ -0,0 +1,251 @@
+:mod:`ipaddress` --- IPv4/IPv6 manipulation library
+===================================================
+
+.. module:: ipaddress
+   :synopsis: IPv4/IPv6 manipulation library.
+.. moduleauthor:: Peter Moody
+
+**Source code:** :source:`Lib/ipaddress.py`
+
+--------------
+
+The :mod:`ipaddress` module provides the capabilities to create, manipulate and
+operate on IPv4 and IPv6 addresses and networks.
+
+This is the full module API reference - for an overview and introduction,
+see :ref:`ipaddress-howto`.
+
+The functions and classes in this module make it straightforward to handle
+various tasks related to IP addresses, including checking whether or not two
+hosts are on the same subnet, iterating over all hosts in a particular
+subnet, as well as checking whether or not a string represents a valid
+IP address or network definition.
+
+
+Defining IP Addresses and Interfaces
+------------------------------------
+
+The :mod:`ipaddress` module provides factory functions to define IP addresses
+and networks:
+
+.. function:: ip_address(address)
+
+   Return an :class:`IPv4Address` or :class:`IPv6Address` object depending on
+   the IP address passed as argument.  *address* is 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 by default.  A
+   :exc:`ValueError` is raised if the *address* passed is neither an IPv4 nor
+   IPv6 address.
+
+   >>> ipaddress.ip_address('192.168.0.1')
+   IPv4Address('192.168.0.1')
+   >>> ipaddress.ip_address('2001:db8::')
+   IPv6Address('2001:db8::')
+
+
+.. function:: ip_network(address, strict=True)
+
+   Return an :class:`IPv4Network` or :class:`IPv6Network` object depending on
+   the IP address passed as argument.  *address* is a string or integer
+   representing the IP network.  Either IPv4 or IPv6 networks may be supplied;
+   integers less than 2**32 will be considered to be IPv4 by default.  *strict*
+   is passed to :class:`IPv4Network` or :class:`IPv6Network` constructor.  A
+   :exc:`ValueError` is raised if the string passed isn't either an IPv4 or IPv6
+   address, or if the network has host bits set.
+
+   >>> ipaddress.ip_network('192.168.0.0/28')
+   IPv4Network('192.168.0.0/28')
+
+
+.. function:: ip_interface(address)
+
+   Return an :class:`IPv4Interface` or :class:`IPv6Interface` object depending
+   on the IP address passed as argument.  *address* is 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 by default..  A
+   :exc:`ValueError` is raised if the *address* passed isn't either an IPv4 or
+   IPv6 address.
+
+
+Representing IP Addresses and Networks
+--------------------------------------
+
+The module defines the following and classes to represent IP addresses
+and networks:
+
+.. todo: list the properties and methods
+
+.. class:: IPv4Address(address)
+
+   Construct an IPv4 address.  *address* is a string or integer representing the
+   IP address.  An :exc:`AddressValueError` is raised if *address* is not a
+   valid IPv4 address.
+
+   >>> ipaddress.IPv4Address('192.168.0.1')
+   IPv4Address('192.168.0.1')
+   >>> ipaddress.IPv4Address('192.0.2.1') == ipaddress.IPv4Address(3221225985)
+   True
+
+
+.. class:: IPv4Interface(address)
+
+   Construct an IPv4 interface.  *address* is a string or integer representing
+   the IP interface.  An :exc:`AddressValueError` is raised if *address* is not
+   a valid IPv4 address.
+
+   The network address for the interface is determined by calling
+   ``IPv4Network(address, strict=False)``.
+
+   >>> ipaddress.IPv4Interface('192.168.0.0/24')
+   IPv4Interface('192.168.0.0/24')
+   >>> ipaddress.IPv4Interface('192.168.0.0/24').network
+   IPv4Network('192.168.0.0/24')
+
+
+.. class:: IPv4Network(address, strict=True)
+
+   Construct an IPv4 network.  *address* is a string or integer representing the
+   IP address (and optionally the network).  An :exc:`AddressValueError` is
+   raised if *address* is not a valid IPv4 address.  A :exc:`NetmaskValueError`
+   is raised if the netmask is not valid for an IPv4 address.
+
+   If *strict* is ``True`` and host bits are set in the supplied address,
+   then :exc:`ValueError` is raised. Otherwise, the host bits are masked out
+   to determine the appropriate network address.
+
+   >>> ipaddress.IPv4Network('192.0.2.0/27')
+   IPv4Network('192.0.2.0/27')
+   >>> ipaddress.IPv4Network('192.0.2.0/27').netmask
+   IPv4Address('255.255.255.224')
+   >>> ipaddress.IPv4Network('192.0.2.5/27', strict=False)
+   IPv4Network('192.0.2.0/27')
+
+
+.. class:: IPv6Address(address)
+
+   Construct an IPv6 address.  *address* is a string or integer representing the
+   IP address.  An :exc:`AddressValueError` is raised if *address* is not a
+   valid IPv6 address.
+
+   >>> ipaddress.IPv6Address('2001:db8::1000')
+   IPv6Address('2001:db8::1000')
+
+
+.. class:: IPv6Interface(address)
+
+   Construct an IPv6 interface.  *address* is a string or integer representing
+   the IP interface.  An :exc:`AddressValueError` is raised if *address* is not
+   a valid IPv6 address.
+
+   The network address for the interface is determined by calling
+   ``IPv6Network(address, strict=False)``.
+
+   >>> ipaddress.IPv6Interface('2001:db8::1000/96')
+   IPv6Interface('2001:db8::1000/96')
+   >>> ipaddress.IPv6Interface('2001:db8::1000/96').network
+   IPv6Network('2001:db8::/96')
+
+
+.. class:: IPv6Network(address, strict=True)
+
+   Construct an IPv6 network.  *address* is a string or integer representing the
+   IP address (and optionally the network).  An :exc:`AddressValueError` is
+   raised if *address* is not a valid IPv6 address.  A :exc:`NetmaskValueError`
+   is raised if the netmask is not valid for an IPv6 address.
+
+   If *strict* is ``True`` and host bits are set in the supplied address,
+   then :exc:`ValueError` is raised. Otherwise, the host bits are masked out
+   to determine the appropriate network address.
+
+   >>> ipaddress.IPv6Network('2001:db8::/96')
+   IPv6Network('2001:db8::/96')
+   >>> ipaddress.IPv6Network('2001:db8::/96').netmask
+   IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff::')
+   >>> ipaddress.IPv6Network('2001:db8::1000/96', strict=False)
+   IPv6Network('2001:db8::/96')
+
+
+Other Module Level Functions
+----------------------------
+
+The module also provides the following module level functions:
+
+.. function:: v4_int_to_packed(address)
+
+   Represent an address as 4 packed bytes in network (big-endian) order.
+   *address* is an integer representation of an IPv4 IP address.  A
+   :exc:`ValueError` is raised if the integer is negative or too large to be an
+   IPv4 IP address.
+
+   >>> ipaddress.ip_address(3221225985)
+   IPv4Address('192.0.2.1')
+   >>> ipaddress.v4_int_to_packed(3221225985)
+   b'\xc0\x00\x02\x01'
+
+
+.. function:: v6_int_to_packed(address)
+
+   Represent an address as 16 packed bytes in network (big-endian) order.
+   *address* is an integer representation of an IPv6 IP address.  A
+   :exc:`ValueError` is raised if the integer is negative or too large to be an
+   IPv6 IP address.
+
+
+.. function:: summarize_address_range(first, last)
+
+   Return an iterator of the summarized network range given the first and last
+   IP addresses.  *first* is the first :class:`IPv4Address` or
+   :class:`IPv6Address` in the range and *last* is the last :class:`IPv4Address`
+   or :class:`IPv6Address` in the range.  A :exc:`TypeError` is raised if
+   *first* or *last* are not IP addresses or are not of the same version.  A
+   :exc:`ValueError` is raised if *last* is not greater than *first* or if
+   *first* address version is not 4 or 6.
+
+   >>> [ipaddr for ipaddr in ipaddress.summarize_address_range(
+   ...    ipaddress.IPv4Address('192.0.2.0'),
+   ...    ipaddress.IPv4Address('192.0.2.130'))]
+   [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'), IPv4Network('192.0.2.130/32')]
+
+
+.. function:: collapse_addresses(addresses)
+
+   Return an iterator of the collapsed :class:`IPv4Network` or
+   :class:`IPv6Network` objects.  *addresses* is an iterator of
+   :class:`IPv4Network` or :class:`IPv6Network` objects.  A :exc:`TypeError` is
+   raised if *addresses* contains mixed version objects.
+
+   >>> [ipaddr for ipaddr in
+   ... ipaddress.collapse_addresses([ipaddress.IPv4Network('192.0.2.0/25'),
+   ... ipaddress.IPv4Network('192.0.2.128/25')])]
+   [IPv4Network('192.0.2.0/24')]
+
+
+.. function:: get_mixed_type_key(obj)
+
+   Return a key suitable for sorting between networks and addresses.  Address
+   and Network objects are not sortable by default; they're fundamentally
+   different, so the expression::
+
+     IPv4Address('192.0.2.0') <= IPv4Network('192.0.2.0/24')
+
+   doesn't make sense.  There are some times however, where you may wish to
+   have :mod:`ipaddress` sort these anyway.  If you need to do this, you can use
+   this function as the ``key`` argument to :func:`sorted()`.
+
+   *obj* is either a network or address object.
+
+
+Custom Exceptions
+-----------------
+
+To support more specific error reporting from class constructors, the
+module defines the following exceptions:
+
+.. exception:: AddressValueError(ValueError)
+
+   Any value error related to the address.
+
+
+.. exception:: NetmaskValueError(ValueError)
+
+   Any value error related to the netmask.