neehi version 2.0.1
A Python SOCKS module.
(C) 2006 Dan-Haim. All rights reserved.
Modifications copyright 2012 Sean Robinson <seankrobinson@gmail.com>
See LICENSE file for details.


WHAT IS A SOCKS PROXY?
A SOCKS proxy is a proxy server at the TCP level. In other words, it acts as
a tunnel, relaying all traffic going through it without modifying it.
SOCKS proxies can be used to relay traffic using any network protocol that
uses TCP.

WHAT IS NEEHI?
This Python package allows you to create TCP connections through a SOCKS
proxy without much special effort.

HOW IS NEEHI RELATED TO SOCKSIPY?
SocksiPy 1.00 is a Python module released in 2006 by Dan-Haim to support
writing Python code which makes TCP connections through SOCKS and HTTP
proxies.  neehi is a re-packaging of SocksiPy with bug fixes, the
addition of extensive unit tests, and Python 3 support.

WHY CREATE A FORK?
In 2012, I needed a Python SOCKS module, but SocksiPy contained two or
three minor bugs which hindered my use.  With multiple bug reports and
patches available on the SocksiPy web site and no new releases since
2006, it appeared to me that the module is unmaintained.  So, I decided
to take on fixing and updating SocksiPy.  I chose a new package name
to reduce confusion with the original module.

WHY START WITH VERSION 2.0?
While I did try to minimize API changes for the socksocket class, I am not
making any guarantees about compatibility between SocksiPy and neehi.
As such, the 2.0 designation highlights that developers moving from
SocksiPy to neehi should use caution.

PROXY COMPATIBILITY
neehi is compatible with three different types of proxies:
1. SOCKS Version 4 (Socks4), including the Socks4a extension.
2. SOCKS Version 5 (Socks5).
3. HTTP Proxies which support tunneling using the CONNECT method.

SYSTEM REQUIREMENTS
neehi is pure Python and aims to run on any platform that has a Python
interpreter and TCP/IP support.  It was initially developed on Python 2.3.
I have continued development and testing on Python 2.7 and 3.2.  Neehi
may work with Python 2.5 and later.



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

Neehi uses distutils to support testing, building, and installation.
To install from the neehi source directory:

        $ python ./setup.py install


USAGE
------

First load the package with the command:

>>> import neehi
>>>

NOTE: If you have code which uses SocksiPy, try the following command to
reduce your porting effort:

>>> import neehi as socks
>>>

The neehi package provides a class called "socksocket", which provides
most of the module's functionality.

socksocket has the same initialization parameters as the standard library's
socket.socket to ensure maximal compatibility, however, socksocket will
only function with family=socket.AF_INET and type=socket.SOCK_STREAM.
Generally, it is best to initialize a socksocket object with no parameters:

>>> s = neehi.socksocket()
>>>

or

>>> s = socks.socksocket()
>>>

To select the proxy server, use the setproxy method:

>>> s.setproxy(neehi.PROXY_TYPE_SOCKS5, "socks.example.com")
>>>

Or, one can combine the previous two steps using one of the socksocket factory
functions.  These functions create a socksocket and configure it in one
command.  To use a SOCKS5 proxy at socks.example.com:

>>> s = neehi.socks5("socks.example.com")
>>>

After, simply call the connect method with traditional socket.socket parameters
to establish a connection through the proxy:

>>> s.connect(("www.sourceforge.net", 80))
>>>

Connection will take a bit longer to allow negotiation with the proxy server.
Please note that calling connect without calling setproxy earlier will connect
without a proxy (just like a regular socket).

Errors: Any errors in the connection process will trigger exceptions. The
exception may either be generated by the underlying socket layer or may
be one of the following exceptions:

- ProxyError
- GeneralProxyError
- Socks5Error
- Socks5AuthError
- Socks4Error
- HTTPError

After establishing the connection, the object behaves like a standard socket.
Call the close method to close the connection.

The setdefaultproxy function will set default proxy settings for newly created
socksocket objects, in which the proxy settings haven't been changed via the
setproxy method.  This is quite useful if you wish to force third-party modules
to use a socks proxy, by overriding the socket object.

For example:

>>> neehi.setdefaultproxy(neehi.PROXY_TYPE_SOCKS5, "socks.example.com")
>>> socket.socket = neehi.socksocket
>>> urllib.urlopen("http://www.sourceforge.net/")
>>>

neehi also provides the above functionality with context managers:

>>> from neehi.cm import SocksProxy5
>>> with SocksProxy5('127.0.0.1'):
...     try:
...         urllib.urlopen("http://www.example.com")
...     except neehi.ProxyError as e:
...         print(e)
>>> [ resume non-sockified sockets ]

