codekingpro/portable-devtools

1Metadata-Version: 2.12Name: PySocks3Version: 1.7.14Summary: A Python SOCKS client module. See https://github.com/Anorov/PySocks for more information.5Home-page: https://github.com/Anorov/PySocks6Author: Anorov7Author-email: anorov.vorona@gmail.com8License: BSD9Keywords: socks,proxy10Platform: UNKNOWN11Classifier: Programming Language :: Python :: 212Classifier: Programming Language :: Python :: 2.713Classifier: Programming Language :: Python :: 314Classifier: Programming Language :: Python :: 3.415Classifier: Programming Language :: Python :: 3.516Classifier: Programming Language :: Python :: 3.617Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*18Description-Content-Type: text/markdown19 20PySocks21=======22 23PySocks lets you send traffic through SOCKS and HTTP proxy servers. It is a modern fork of [SocksiPy](http://socksipy.sourceforge.net/) with bug fixes and extra features.24 25Acts as a drop-in replacement to the socket module. Seamlessly configure SOCKS proxies for any socket object by calling `socket_object.set_proxy()`.26 27----------------28 29Features30========31 32* SOCKS proxy client for Python 2.7 and 3.4+33* TCP supported34* UDP mostly supported (issues may occur in some edge cases)35* HTTP proxy client included but not supported or recommended (you should use urllib2's or requests' own HTTP proxy interface)36* urllib2 handler included. `pip install` / `setup.py install` will automatically install the `sockshandler` module.37 38Installation39============40 41    pip install PySocks42 43Or download the tarball / `git clone` and...44 45    python setup.py install46 47These will install both the `socks` and `sockshandler` modules.48 49Alternatively, include just `socks.py` in your project.50 51--------------------------------------------52 53*Warning:* PySocks/SocksiPy only supports HTTP proxies that use CONNECT tunneling. Certain HTTP proxies may not work with this library. If you wish to use HTTP (not SOCKS) proxies, it is recommended that you rely on your HTTP client's native proxy support (`proxies` dict for `requests`, or `urllib2.ProxyHandler` for `urllib2`) instead.54 55--------------------------------------------56 57Usage58=====59 60## socks.socksocket ##61 62    import socks63 64    s = socks.socksocket() # Same API as socket.socket in the standard lib65 66    s.set_proxy(socks.SOCKS5, "localhost") # SOCKS4 and SOCKS5 use port 1080 by default67    # Or68    s.set_proxy(socks.SOCKS4, "localhost", 4444)69    # Or70    s.set_proxy(socks.HTTP, "5.5.5.5", 8888)71 72    # Can be treated identical to a regular socket object73    s.connect(("www.somesite.com", 80))74    s.sendall("GET / HTTP/1.1 ...")75    print s.recv(4096)76 77## Monkeypatching ##78 79To monkeypatch the entire standard library with a single default proxy:80 81    import urllib282    import socket83    import socks84 85    socks.set_default_proxy(socks.SOCKS5, "localhost")86    socket.socket = socks.socksocket87 88    urllib2.urlopen("http://www.somesite.com/") # All requests will pass through the SOCKS proxy89 90Note that monkeypatching may not work for all standard modules or for all third party modules, and generally isn't recommended. Monkeypatching is usually an anti-pattern in Python.91 92## urllib2 Handler ##93 94Example use case with the `sockshandler` urllib2 handler. Note that you must import both `socks` and `sockshandler`, as the handler is its own module separate from PySocks. The module is included in the PyPI package.95 96    import urllib297    import socks98    from sockshandler import SocksiPyHandler99 100    opener = urllib2.build_opener(SocksiPyHandler(socks.SOCKS5, "127.0.0.1", 9050))101    print opener.open("http://www.somesite.com/") # All requests made by the opener will pass through the SOCKS proxy102 103--------------------------------------------104 105Original SocksiPy README attached below, amended to reflect API changes.106 107--------------------------------------------108 109SocksiPy110 111A Python SOCKS module.112 113(C) 2006 Dan-Haim. All rights reserved.114 115See LICENSE file for details.116 117 118*WHAT IS A SOCKS PROXY?*119 120A SOCKS proxy is a proxy server at the TCP level. In other words, it acts as121a tunnel, relaying all traffic going through it without modifying it.122SOCKS proxies can be used to relay traffic using any network protocol that123uses TCP.124 125*WHAT IS SOCKSIPY?*126 127This Python module allows you to create TCP connections through a SOCKS128proxy without any special effort.129It also supports relaying UDP packets with a SOCKS5 proxy.130 131*PROXY COMPATIBILITY*132 133SocksiPy is compatible with three different types of proxies:134 1351. SOCKS Version 4 (SOCKS4), including the SOCKS4a extension.1362. SOCKS Version 5 (SOCKS5).1373. HTTP Proxies which support tunneling using the CONNECT method.138 139*SYSTEM REQUIREMENTS*140 141Being written in Python, SocksiPy can run on any platform that has a Python142interpreter and TCP/IP support.143This module has been tested with Python 2.3 and should work with greater versions144just as well.145 146 147INSTALLATION148-------------149 150Simply copy the file "socks.py" to your Python's `lib/site-packages` directory,151and you're ready to go. [Editor's note: it is better to use `python setup.py install` for PySocks]152 153 154USAGE155------156 157First load the socks module with the command:158 159    >>> import socks160    >>>161 162The socks module provides a class called `socksocket`, which is the base to all of the module's functionality.163 164The `socksocket` object has the same initialization parameters as the normal socket165object to ensure maximal compatibility, however it should be noted that `socksocket` will only function with family being `AF_INET` and166type being either `SOCK_STREAM` or `SOCK_DGRAM`.167Generally, it is best to initialize the `socksocket` object with no parameters168 169    >>> s = socks.socksocket()170    >>>171 172The `socksocket` object has an interface which is very similiar to socket's (in fact173the `socksocket` class is derived from socket) with a few extra methods.174To select the proxy server you would like to use, use the `set_proxy` method, whose175syntax is:176 177    set_proxy(proxy_type, addr[, port[, rdns[, username[, password]]]])178 179Explanation of the parameters:180 181`proxy_type` - The type of the proxy server. This can be one of three possible182choices: `PROXY_TYPE_SOCKS4`, `PROXY_TYPE_SOCKS5` and `PROXY_TYPE_HTTP` for SOCKS4,183SOCKS5 and HTTP servers respectively. `SOCKS4`, `SOCKS5`, and `HTTP` are all aliases, respectively.184 185`addr` - The IP address or DNS name of the proxy server.186 187`port` - The port of the proxy server. Defaults to 1080 for socks and 8080 for http.188 189`rdns` - This is a boolean flag than modifies the behavior regarding DNS resolving.190If it is set to True, DNS resolving will be preformed remotely, on the server.191If it is set to False, DNS resolving will be preformed locally. Please note that192setting this to True with SOCKS4 servers actually use an extension to the protocol,193called SOCKS4a, which may not be supported on all servers (SOCKS5 and http servers194always support DNS). The default is True.195 196`username` - For SOCKS5 servers, this allows simple username / password authentication197with the server. For SOCKS4 servers, this parameter will be sent as the userid.198This parameter is ignored if an HTTP server is being used. If it is not provided,199authentication will not be used (servers may accept unauthenticated requests).200 201`password` - This parameter is valid only for SOCKS5 servers and specifies the202respective password for the username provided.203 204Example of usage:205 206    >>> s.set_proxy(socks.SOCKS5, "socks.example.com") # uses default port 1080207    >>> s.set_proxy(socks.SOCKS4, "socks.test.com", 1081)208 209After the set_proxy method has been called, simply call the connect method with the210traditional parameters to establish a connection through the proxy:211 212    >>> s.connect(("www.sourceforge.net", 80))213    >>>214 215Connection will take a bit longer to allow negotiation with the proxy server.216Please note that calling connect without calling `set_proxy` earlier will connect217without a proxy (just like a regular socket).218 219Errors: Any errors in the connection process will trigger exceptions. The exception220may either be generated by the underlying socket layer or may be custom module221exceptions, whose details follow:222 223class `ProxyError` - This is a base exception class. It is not raised directly but224rather all other exception classes raised by this module are derived from it.225This allows an easy way to catch all proxy-related errors. It descends from `IOError`.226 227All `ProxyError` exceptions have an attribute `socket_err`, which will contain either a228caught `socket.error` exception, or `None` if there wasn't any.229 230class `GeneralProxyError` - When thrown, it indicates a problem which does not fall231into another category.232 233* `Sent invalid data` - This error means that unexpected data has been received from234the server. The most common reason is that the server specified as the proxy is235not really a SOCKS4/SOCKS5/HTTP proxy, or maybe the proxy type specified is wrong.236 237* `Connection closed unexpectedly` - The proxy server unexpectedly closed the connection.238This may indicate that the proxy server is experiencing network or software problems.239 240* `Bad proxy type` - This will be raised if the type of the proxy supplied to the241set_proxy function was not one of `SOCKS4`/`SOCKS5`/`HTTP`.242 243* `Bad input` - This will be raised if the `connect()` method is called with bad input244parameters.245 246class `SOCKS5AuthError` - This indicates that the connection through a SOCKS5 server247failed due to an authentication problem.248 249* `Authentication is required` - This will happen if you use a SOCKS5 server which250requires authentication without providing a username / password at all.251 252* `All offered authentication methods were rejected` - This will happen if the proxy253requires a special authentication method which is not supported by this module.254 255* `Unknown username or invalid password` - Self descriptive.256 257class `SOCKS5Error` - This will be raised for SOCKS5 errors which are not related to258authentication.259The parameter is a tuple containing a code, as given by the server,260and a description of the261error. The possible errors, according to the RFC, are:262 263* `0x01` - General SOCKS server failure - If for any reason the proxy server is unable to264fulfill your request (internal server error).265* `0x02` - connection not allowed by ruleset - If the address you're trying to connect to266is blacklisted on the server or requires authentication.267* `0x03` - Network unreachable - The target could not be contacted. A router on the network268had replied with a destination net unreachable error.269* `0x04` - Host unreachable - The target could not be contacted. A router on the network270had replied with a destination host unreachable error.271* `0x05` - Connection refused - The target server has actively refused the connection272(the requested port is closed).273* `0x06` - TTL expired - The TTL value of the SYN packet from the proxy to the target server274has expired. This usually means that there are network problems causing the packet275to be caught in a router-to-router "ping-pong".276* `0x07` - Command not supported - For instance if the server does not support UDP.277* `0x08` - Address type not supported - The client has provided an invalid address type.278When using this module, this error should not occur.279 280class `SOCKS4Error` - This will be raised for SOCKS4 errors. The parameter is a tuple281containing a code and a description of the error, as given by the server. The282possible error, according to the specification are:283 284* `0x5B` - Request rejected or failed - Will be raised in the event of an failure for any285reason other then the two mentioned next.286* `0x5C` - request rejected because SOCKS server cannot connect to identd on the client -287The Socks server had tried an ident lookup on your computer and has failed. In this288case you should run an identd server and/or configure your firewall to allow incoming289connections to local port 113 from the remote server.290* `0x5D` - request rejected because the client program and identd report different user-ids -291The Socks server had performed an ident lookup on your computer and has received a292different userid than the one you have provided. Change your userid (through the293username parameter of the set_proxy method) to match and try again.294 295class `HTTPError` - This will be raised for HTTP errors. The message will contain296the HTTP status code and provided error message.297 298After establishing the connection, the object behaves like a standard socket.299 300Methods like `makefile()` and `settimeout()` should behave just like regular sockets.301Call the `close()` method to close the connection.302 303In addition to the `socksocket` class, an additional function worth mentioning is the304`set_default_proxy` function. The parameters are the same as the `set_proxy` method.305This function will set default proxy settings for newly created `socksocket` objects,306in which the proxy settings haven't been changed via the `set_proxy` method.307This is quite useful if you wish to force 3rd party modules to use a SOCKS proxy,308by overriding the socket object.309For example:310 311    >>> socks.set_default_proxy(socks.SOCKS5, "socks.example.com")312    >>> socket.socket = socks.socksocket313    >>> urllib.urlopen("http://www.sourceforge.net/")314 315 316PROBLEMS317---------318 319Please open a GitHub issue at https://github.com/Anorov/PySocks320 321 322