1Metadata-Version: 2.1 2Name: PySocks 3Version: 1.7.1 4Summary: A Python SOCKS client module. See https://github.com/Anorov/PySocks for more information. 5Home-page: https://github.com/Anorov/PySocks 6Author: Anorov 7Author-email: anorov.vorona@gmail.com 8License: BSD 9Keywords: socks,proxy 10Platform: UNKNOWN 11Classifier: Programming Language :: Python :: 2 12Classifier: Programming Language :: Python :: 2.7 13Classifier: Programming Language :: Python :: 3 14Classifier: Programming Language :: Python :: 3.4 15Classifier: Programming Language :: Python :: 3.5 16Classifier: Programming Language :: Python :: 3.6 17Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.* 18Description-Content-Type: text/markdown 19License-File: LICENSE 20 21PySocks 22======= 23 24PySocks 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. 25 26Acts as a drop-in replacement to the socket module. Seamlessly configure SOCKS proxies for any socket object by calling `socket_object.set_proxy()`. 27 28---------------- 29 30Features 31======== 32 33* SOCKS proxy client for Python 2.7 and 3.4+ 34* TCP supported 35* UDP mostly supported (issues may occur in some edge cases) 36* HTTP proxy client included but not supported or recommended (you should use urllib2's or requests' own HTTP proxy interface) 37* urllib2 handler included. `pip install` / `setup.py install` will automatically install the `sockshandler` module. 38 39Installation 40============ 41 42 pip install PySocks 43 44Or download the tarball / `git clone` and... 45 46 python setup.py install 47 48These will install both the `socks` and `sockshandler` modules. 49 50Alternatively, include just `socks.py` in your project. 51 52-------------------------------------------- 53 54*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. 55 56-------------------------------------------- 57 58Usage 59===== 60 61## socks.socksocket ## 62 63 import socks 64 65 s = socks.socksocket() # Same API as socket.socket in the standard lib 66 67 s.set_proxy(socks.SOCKS5, "localhost") # SOCKS4 and SOCKS5 use port 1080 by default 68 # Or 69 s.set_proxy(socks.SOCKS4, "localhost", 4444) 70 # Or 71 s.set_proxy(socks.HTTP, "5.5.5.5", 8888) 72 73 # Can be treated identical to a regular socket object 74 s.connect(("www.somesite.com", 80)) 75 s.sendall("GET / HTTP/1.1 ...") 76 print s.recv(4096) 77 78## Monkeypatching ## 79 80To monkeypatch the entire standard library with a single default proxy: 81 82 import urllib2 83 import socket 84 import socks 85 86 socks.set_default_proxy(socks.SOCKS5, "localhost") 87 socket.socket = socks.socksocket 88 89 urllib2.urlopen("http://www.somesite.com/") # All requests will pass through the SOCKS proxy 90 91Note 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. 92 93## urllib2 Handler ## 94 95Example 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. 96 97 import urllib2 98 import socks 99 from sockshandler import SocksiPyHandler 100 101 opener = urllib2.build_opener(SocksiPyHandler(socks.SOCKS5, "127.0.0.1", 9050)) 102 print opener.open("http://www.somesite.com/") # All requests made by the opener will pass through the SOCKS proxy 103 104-------------------------------------------- 105 106Original SocksiPy README attached below, amended to reflect API changes. 107 108-------------------------------------------- 109 110SocksiPy 111 112A Python SOCKS module. 113 114(C) 2006 Dan-Haim. All rights reserved. 115 116See LICENSE file for details. 117 118 119*WHAT IS A SOCKS PROXY?* 120 121A SOCKS proxy is a proxy server at the TCP level. In other words, it acts as 122a tunnel, relaying all traffic going through it without modifying it. 123SOCKS proxies can be used to relay traffic using any network protocol that 124uses TCP. 125 126*WHAT IS SOCKSIPY?* 127 128This Python module allows you to create TCP connections through a SOCKS 129proxy without any special effort. 130It also supports relaying UDP packets with a SOCKS5 proxy. 131 132*PROXY COMPATIBILITY* 133 134SocksiPy is compatible with three different types of proxies: 135 1361. SOCKS Version 4 (SOCKS4), including the SOCKS4a extension. 1372. SOCKS Version 5 (SOCKS5). 1383. HTTP Proxies which support tunneling using the CONNECT method. 139 140*SYSTEM REQUIREMENTS* 141 142Being written in Python, SocksiPy can run on any platform that has a Python 143interpreter and TCP/IP support. 144This module has been tested with Python 2.3 and should work with greater versions 145just as well. 146 147 148INSTALLATION 149------------- 150 151Simply copy the file "socks.py" to your Python's `lib/site-packages` directory, 152and you're ready to go. [Editor's note: it is better to use `python setup.py install` for PySocks] 153 154 155USAGE 156------ 157 158First load the socks module with the command: 159 160 >>> import socks 161 >>> 162 163The socks module provides a class called `socksocket`, which is the base to all of the module's functionality. 164 165The `socksocket` object has the same initialization parameters as the normal socket 166object to ensure maximal compatibility, however it should be noted that `socksocket` will only function with family being `AF_INET` and 167type being either `SOCK_STREAM` or `SOCK_DGRAM`. 168Generally, it is best to initialize the `socksocket` object with no parameters 169 170 >>> s = socks.socksocket() 171 >>> 172 173The `socksocket` object has an interface which is very similiar to socket's (in fact 174the `socksocket` class is derived from socket) with a few extra methods. 175To select the proxy server you would like to use, use the `set_proxy` method, whose 176syntax is: 177 178 set_proxy(proxy_type, addr[, port[, rdns[, username[, password]]]]) 179 180Explanation of the parameters: 181 182`proxy_type` - The type of the proxy server. This can be one of three possible 183choices: `PROXY_TYPE_SOCKS4`, `PROXY_TYPE_SOCKS5` and `PROXY_TYPE_HTTP` for SOCKS4, 184SOCKS5 and HTTP servers respectively. `SOCKS4`, `SOCKS5`, and `HTTP` are all aliases, respectively. 185 186`addr` - The IP address or DNS name of the proxy server. 187 188`port` - The port of the proxy server. Defaults to 1080 for socks and 8080 for http. 189 190`rdns` - This is a boolean flag than modifies the behavior regarding DNS resolving. 191If it is set to True, DNS resolving will be preformed remotely, on the server. 192If it is set to False, DNS resolving will be preformed locally. Please note that 193setting this to True with SOCKS4 servers actually use an extension to the protocol, 194called SOCKS4a, which may not be supported on all servers (SOCKS5 and http servers 195always support DNS). The default is True. 196 197`username` - For SOCKS5 servers, this allows simple username / password authentication 198with the server. For SOCKS4 servers, this parameter will be sent as the userid. 199This parameter is ignored if an HTTP server is being used. If it is not provided, 200authentication will not be used (servers may accept unauthenticated requests). 201 202`password` - This parameter is valid only for SOCKS5 servers and specifies the 203respective password for the username provided. 204 205Example of usage: 206 207 >>> s.set_proxy(socks.SOCKS5, "socks.example.com") # uses default port 1080 208 >>> s.set_proxy(socks.SOCKS4, "socks.test.com", 1081) 209 210After the set_proxy method has been called, simply call the connect method with the 211traditional parameters to establish a connection through the proxy: 212 213 >>> s.connect(("www.sourceforge.net", 80)) 214 >>> 215 216Connection will take a bit longer to allow negotiation with the proxy server. 217Please note that calling connect without calling `set_proxy` earlier will connect 218without a proxy (just like a regular socket). 219 220Errors: Any errors in the connection process will trigger exceptions. The exception 221may either be generated by the underlying socket layer or may be custom module 222exceptions, whose details follow: 223 224class `ProxyError` - This is a base exception class. It is not raised directly but 225rather all other exception classes raised by this module are derived from it. 226This allows an easy way to catch all proxy-related errors. It descends from `IOError`. 227 228All `ProxyError` exceptions have an attribute `socket_err`, which will contain either a 229caught `socket.error` exception, or `None` if there wasn't any. 230 231class `GeneralProxyError` - When thrown, it indicates a problem which does not fall 232into another category. 233 234* `Sent invalid data` - This error means that unexpected data has been received from 235the server. The most common reason is that the server specified as the proxy is 236not really a SOCKS4/SOCKS5/HTTP proxy, or maybe the proxy type specified is wrong. 237 238* `Connection closed unexpectedly` - The proxy server unexpectedly closed the connection. 239This may indicate that the proxy server is experiencing network or software problems. 240 241* `Bad proxy type` - This will be raised if the type of the proxy supplied to the 242set_proxy function was not one of `SOCKS4`/`SOCKS5`/`HTTP`. 243 244* `Bad input` - This will be raised if the `connect()` method is called with bad input 245parameters. 246 247class `SOCKS5AuthError` - This indicates that the connection through a SOCKS5 server 248failed due to an authentication problem. 249 250* `Authentication is required` - This will happen if you use a SOCKS5 server which 251requires authentication without providing a username / password at all. 252 253* `All offered authentication methods were rejected` - This will happen if the proxy 254requires a special authentication method which is not supported by this module. 255 256* `Unknown username or invalid password` - Self descriptive. 257 258class `SOCKS5Error` - This will be raised for SOCKS5 errors which are not related to 259authentication. 260The parameter is a tuple containing a code, as given by the server, 261and a description of the 262error. The possible errors, according to the RFC, are: 263 264* `0x01` - General SOCKS server failure - If for any reason the proxy server is unable to 265fulfill your request (internal server error). 266* `0x02` - connection not allowed by ruleset - If the address you're trying to connect to 267is blacklisted on the server or requires authentication. 268* `0x03` - Network unreachable - The target could not be contacted. A router on the network 269had replied with a destination net unreachable error. 270* `0x04` - Host unreachable - The target could not be contacted. A router on the network 271had replied with a destination host unreachable error. 272* `0x05` - Connection refused - The target server has actively refused the connection 273(the requested port is closed). 274* `0x06` - TTL expired - The TTL value of the SYN packet from the proxy to the target server 275has expired. This usually means that there are network problems causing the packet 276to be caught in a router-to-router "ping-pong". 277* `0x07` - Command not supported - For instance if the server does not support UDP. 278* `0x08` - Address type not supported - The client has provided an invalid address type. 279When using this module, this error should not occur. 280 281class `SOCKS4Error` - This will be raised for SOCKS4 errors. The parameter is a tuple 282containing a code and a description of the error, as given by the server. The 283possible error, according to the specification are: 284 285* `0x5B` - Request rejected or failed - Will be raised in the event of an failure for any 286reason other then the two mentioned next. 287* `0x5C` - request rejected because SOCKS server cannot connect to identd on the client - 288The Socks server had tried an ident lookup on your computer and has failed. In this 289case you should run an identd server and/or configure your firewall to allow incoming 290connections to local port 113 from the remote server. 291* `0x5D` - request rejected because the client program and identd report different user-ids - 292The Socks server had performed an ident lookup on your computer and has received a 293different userid than the one you have provided. Change your userid (through the 294username parameter of the set_proxy method) to match and try again. 295 296class `HTTPError` - This will be raised for HTTP errors. The message will contain 297the HTTP status code and provided error message. 298 299After establishing the connection, the object behaves like a standard socket. 300 301Methods like `makefile()` and `settimeout()` should behave just like regular sockets. 302Call the `close()` method to close the connection. 303 304In addition to the `socksocket` class, an additional function worth mentioning is the 305`set_default_proxy` function. The parameters are the same as the `set_proxy` method. 306This function will set default proxy settings for newly created `socksocket` objects, 307in which the proxy settings haven't been changed via the `set_proxy` method. 308This is quite useful if you wish to force 3rd party modules to use a SOCKS proxy, 309by overriding the socket object. 310For example: 311 312 >>> socks.set_default_proxy(socks.SOCKS5, "socks.example.com") 313 >>> socket.socket = socks.socksocket 314 >>> urllib.urlopen("http://www.sourceforge.net/") 315 316 317PROBLEMS 318--------- 319 320Please open a GitHub issue at https://github.com/Anorov/PySocks 321 322 323