API Reference
*************

This page documents netaddr's public API. Only things explicitly
mentioned in this documentation are supported and considered part of
the public API.

Any of the following is considered private and unsupported:

* Anything within any of the "netaddr" submodules ("from netaddr.X
  import Y")

* Anything with a name started with a single underscore ("_X")

* Anything not explicitly documented as part of the public API


IP Class Hierarchy
==================

Here the class hierarchy for IP related classes

   +---------+                                                +---------+
   | ipv4(M) |                                                | ipv6(M) |
   +---------+                                                +---------+
        |                                                          |
     (HAS A)                                                    (HAS A)
        |                                                          |
        +-----+----------------+-----------------+                 |
              |       +--------|-------+---------|--------+--------+
              |       |        |       |         |        |
              |       |        |       |         |        |
              v       v        v       v         |        |
            +-----------+    +-----------+       |        |
            | IPAddress |    | IPNetwork |       |        |
            +-----------+    +-----------+       |        |
                  |                |             |        |
               (HAS A)          (HAS A)          |        |
                  |                |             v        v
                  +-------+--------+           +------------+
                          |                    |  IPRange   |
                          |                    +------------+
                          v                          |
                      +-------+                      |
                      | IPSet |                      v
                      +-------+                  +--------+
                                                 | IPGlob |
                                                 +--------+


Constants
=========

The following constants are used by the various *flags* arguments on
netaddr class constructors.

netaddr.INET_PTON

   Use inet_pton() semantics instead of inet_aton() when parsing IPv4.

   See the "IPAddress.__init__()" documentation for details.

   Changed in version 1.0.0: Started rejecting leading zeros
   regardless of the platform (it was previously allowed on some).

netaddr.INET_ATON

   Use "inet_aton()" semantics when parsing IPv4.

   See the "IPAddress.__init__()" documentation for details.

   Added in version 0.10.0.

netaddr.ZEROFILL

   Remove any preceding zeros from IPv4 address octets before parsing.

   See the "IPAddress.__init__()" documentation for details.

netaddr.NOHOST

   Remove any host bits found to the right of an applied CIDR prefix.

   See the "IPNetwork.__init__()" documentation for details.


Custom Exceptions
=================


IP addresses
============

An IP address is a virtual address used to identify the source and
destination of (layer 3) packets being transferred between hosts in a
switched network. This library fully supports both IPv4 and the new
IPv6 standards.

The *IPAddress* class is used to identify individual IP addresses.


IPv6 formatting dialects
------------------------

The following dialect classes can be used with the IPAddress.format
method.


IP networks and subnets
=======================

The *IPNetwork* class is used to represent a group of IP addresses
that comprise a network/subnet/VLAN containing hosts.

Nowadays, IP networks are usually specified using the CIDR format with
a prefix indicating the size of the netmask. In the real world, there
are a number of ways to express a "network"" and so the flexibility of
the *IPNetwork* class constructor reflects this.


Arbitrary IP address ranges
===========================

netaddr was designed to accommodate the many different ways in which
groups of IP addresses and IP networks are specified, not only in
router configurations but also less standard but more human-readable
forms found in, for instance, configuration files.

Here are the options currently available.


bounded ranges
--------------

A bounded range is a group of IP addresses specified using a start and
end address forming a contiguous block. No bit boundaries are assumed
but the end address must be numerically greater than or equal to the
start address.


IP glob ranges
--------------

A very useful way to represent IP network in configuration files and
on the command line for those who do not speak CIDR.

The *IPGlob* class is used to represent individual glob ranges.


globbing functions
------------------

It is also very useful to be able to convert between glob ranges and
CIDR and IP ranges. The following function enable these various
conversions.


"nmap" ranges
-------------

"nmap" is a well known network security tool. It has a particularly
flexible way of specifying IP address groupings.

Functions are provided that allow the verification and enumeration of
IP address specified in this format.


IP sets
=======

When dealing with large numbers of IP addresses and ranges it is often
useful to manipulate them as sets so you can calculate intersections,
unions and differences between various groups of them.

The *IPSet* class was built specifically for this purpose.


IP functions and generators
===========================

The following are a set of useful helper functions related to the
various format supported in this library.


MAC addresses and the IEEE EUI standard
=======================================

A MAC address is the 48-bit hardware address associated with a
particular physical interface on a networked host. They are found in
all networked devices and serve to identify (layer 2) frames in the
networking stack.

The *EUI* class is used to represents MACs (as well as their larger
and less common 64-bit cousins).


MAC formatting dialects
-----------------------

The following dialects are used to specify the formatting of MAC
addresses.


Validation functions
====================


A bit of fun
============

Who said networking was all about being serious? It's always good to
lighten up and have a bit of fun.

Let's face it, no networking library worth its salt would be complete
without support for RFC 1924 - http://www.ietf.org/rfc/rfc1924 ":-)"
