INTRODUCTION
============

netaddr is a pure Python network address representation and manipulation 
library.

It allows you to work with several common network address formats and 
notations in a very Pythonic way, including :-

- Internet Protocol addresses (comprehensive support for both IPv4 and IPv6)
- CIDR (Classless Inter-Domain Routing) notation
- IEEE EUI-48 (a.k.a. MAC addresses) and EUI-64 identifiers

There is a decent set of routines for generating, sorting and summarizing
addresses along with the ability to convert individual addresses and ranges
between different formats (e.g. arbitrary IP address ranges to and from CIDR).
You can easily represent groups of related addresses in order to emulate 
networks and networking functionality within your Python code.

netaddr also provides a convenient interface to address specific information
gathered from various standard sources on the Internet such as :-

- OUI and IAB organisational lookups for MAC addresses
- Range specific details/membership for IPv4, IPv6 and multicast addresses
- geographical IP information (coming soon)

See the documentation for more details.


LICENSE
-------

This software is released under the liberal BSD license.

See the LICENSE file for full text and copyright notice.


DEPENDENCIES
------------

Requires Python 2.4 or higher.

Python 3.x is not currently supported but is planned for future releases.


INSTALLATION
------------

See the INSTALL file for details.


DOCUMENTATION
-------------

You can access various levels of documentation to suit your needs :-

- API documentation

The API is fully documented and is automatically generated for each release
using epydoc - http://epydoc.sourceforge.net/. 

It can be found in the docs/api/ directory where you extracted the source 
tarball/zip file or checked out the code. Open the index.html file with 
the HTML browser of your choice.

- Python docstrings

The docstrings contain a lot of detail. See these if you require information
on specific aspects of netaddr's API via an interactive Python interpreter
session or your favourite text editor.

- online wiki

A set of basic HOWTO code samples are available on the code hosting site's
wiki at the following URL :-

	http://code.google.com/p/netaddr/w/list


CHANGE HISTORY
--------------

Please see the CHANGELOG for details.


UNIT TESTS
----------

No code can ever be deemed truly complete and trustworthy without reasonable
unit test coverage. Full coverage for netaddr is the certainly the ultimate
goal. Wherever possible all changes and new features are covered with specific
regression tests.

To run them just look the tests directory and run the following using your 
Python interpreter :-

	python ut_netaddr.py

Tests are expected to run through without error. If any do fail, *please* help
assist the project by creating bug reports at the following URL :-
	
	http://code.google.com/p/netaddr/issues/list

*IMPORTANT*

Efforts have been made to ensure this code work equally well on both big and 
little endian architectures. However, the project does not own or have access
to any big endian hardware (e.g. SPARC and PowerPC) for continual regression 
testing. If you happen to work on big endian architectures with Python and wish
to use netaddr *PLEASE* ensure you run the unit tests before you using it in a 
production setting just to make sure everything is functioning as expected.

References
----------

The following lists the main external references that have not only guided the 
implementation of netaddr's features and capabilities but also provide data
that is exposed via its API.

IPv4 RFCs

	RFC 1918 - Address Allocation for Private Internets
		http://www.ietf.org/html/rfc1918

	RFC 3330 - Special-Use IPv4 Addresses
		http://www.ietf.org/html/rfc3330

	RFC 3927 - Dynamic Configuration of IPv4 Link-Local Addresses
		http://www.ietf.org/html/rfc3927

Multicast (IPv4) RFCs

	RFC 2365 - Administratively Scoped IP Multicast
		http://www.ietf.org/html/rfc2365

	RFC 3171 - IANA IPv4 Multicast Guidelines
		http://www.ietf.org/rfc/rfc3171

	RFC 3927 - Dynamic Configuration of IPv4 Link-Local Addresses
		http://www.ietf.org/html/rfc3927

IPv6 RFCs

	RFC 3330 - Special-Use IPv4 Addresses
		http://www.ietf.org/html/rfc3330

	RFC 4291 - IPv6 Addressing Architecture
		http://www.ietf.org/rfc/rfc4291

	RFC 3306 - Unicast-Prefix-based IPv6 Multicast
		http://www.ietf.org/rfc/rfc3306

	RFC 3956 - The RP Address in IPv6 Multicast Address
		http://www.ietf.org/rfc/rfc3956

	RFC 3879 - Deprecating Site Local Addresses
		http://www.ietf.org/rfc/rfc3879

	RFC 4193 - Unique Local IPv6 Unicast Addresses
		http://www.ietf.org/rfc/rfc4193

	RFC 4941 - Privacy Extensions for Stateless Address
		http://www.ietf.org/rfc/rfc4941

CIDR RFCs

	RFC 1338 - Supernetting: an Address Assignment and Aggregation Strategy
		http://www.ietf.org/rfc/rfc1338

	RFC 4632 - Classless Inter-domain Routing (CIDR): The Internet Address 
			   Assignment and Aggregation Plan
		http://www.ietf.org/rfc/rfc4632

IANA online resources

	IANA Protocol Registry
		http://www.iana.org/protocols/

	IPv4 Address Space
		http://www.iana.org/assignments/ipv4-address-space

	IPv6 Address Space
		http://www.iana.org/assignments/ipv6-address-space

	Multicast Registrations
		http://www.iana.org/assignments/multicast-addresses

IEEE online resources

	IEEE Organisation Registry
		http://standards.ieee.org/regauth/oui/index.shtml

	OUI (Organisationally Unique Identifier) Registrations
		http://standards.ieee.org/regauth/oui/oui.txt

	IAB (Individual Address Block) Registrations
		http://standards.ieee.org/regauth/oui/iab.txt

AUTHORS
-------

See the AUTHORS file for details.

Share and enjoy!
