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

netaddr is a network address manipulation library written in pure Python.

It supports the Pythonic manipulation of several common network address
notations and standards, including :-

- Internet Protocols version 4 and version 6 addressing
- CIDR (Classless Inter-Domain Routing)
- IEEE MAC (Media Access Control), EUI-48 and EUI-64 identifiers

There are many different types of addressing found within the various levels
of a networking stack.

If you compare a Media Access Control (MAC) address to an Internet Protocol
(IP) address, they appear, at a glance, to be very distinct from one another.

However, apart from one being layer 2 (link layer) address and one being a
layer 3 (network layer) address, the differences in how they are manipulated
by code in a library are minimal. A significant overlap exists in the number 
and type of operations that are perform on each one.


LICENSE
-------

This software is release under the BSD license.

See the LICENSE file for full text and copyright notice.


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

requires Python 2.3 or higher. It does not currently run on Python 3.x.


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

See the INSTALL file for details.


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

You can various levels of documentation the following places :-

- 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 in the root directory extracted
from a source release tarball or zip file. Accessing the index.html with 
the browser of your choice.

- Python docstrings

I've tried to be as verbose with my docstrings and code comments as seems 
sensible. Hopefully I haven't taken it too far and harm the readability 
of the actual code.

- online wiki page

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

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


CHANGES
-------

Please see the CHANGELOG for details.


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

No publicly available code can ever be deemed truly complete and trustworth
without reasonable unit test coverage (not in my book anyway). Full coverage 
is the aim but its probably only about 70% of the way there at the moment. 
Expect this situation to improve in coming releases.

Running the tests is pretty straightfoward. Have a look in the tests directory
where you extracted the source release tarball or zip file and run any file
that starts with a ut_. Tests are expected to run through without any errors.

If any do fail, please help the project along by filling in a bug report 
here :-
	
	http://code.google.com/p/netaddr/issues/list

*IMPORTANT*

For the record, I have made the effort to test this code on both big and little 
endian architectures throughout its initial development cycle. It took some 
extra work but for a networking library to take itself seriously this kind of 
thing is mandatory.

However, I do not own any big endian hardware as I work exclusively on Intel. If 
you happen to work on big endian hardware (such as SPARC), *PLEASE* ensure you 
run the *ALL* the unit tests before you use this in library in a production setting.

I'm quite happy that it'll work but there isn't any point in vouching for something
that I am not able to test all the time. If any unit tests do fail and you are 
running this library on a natively big-endian platform please make an extra effort 
to file bug reports.

References
----------

The following is a list of all the main all external references have guided 
netaddr's implementation and add to its functionality.

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!
