Debian Codegraph @

PySocks.egg-info/PKG-INFO

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