1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
.. currentmodule:: aiorpcx
SOCKS Proxy
===========
The :mod:`aiorpcx` package includes a `SOCKS
<https://en.wikipedia.org/wiki/SOCKS>`_ proxy client. It understands
the ``SOCKS4``, ``SOCKS4a`` and ``SOCKS5`` protocols.
Exceptions
----------
.. exception:: SOCKSError
The base class of SOCKS exceptions. Each raised exception will be
an instance of a derived class.
.. exception:: SOCKSProtocolError
A subclass of :class:`SOCKSError`. Raised when the proxy does not
follow the ``SOCKS`` protocol.
.. exception:: SOCKSFailure
A subclass of :class:`SOCKSError`. Raised when the proxy refuses
or fails to make a connection.
Authentication
--------------
Currently the only supported authentication method is with a username
and password. Usernames can be used by all SOCKS protocols, but only
``SOCKS5`` uses the password.
.. class:: SOCKSUserAuth
A :class:`namedtuple` for authentication with a SOCKS server. It
has two members:
.. attribute:: username
A string.
.. attribute:: password
A string. Ignored by the :class:`SOCKS4` and :class:`SOCKS4a`
protocols.
Protocols
---------
When creating a :class:`SocksProxy` object, a protocol must be
specified and be one of the following.
.. class:: SOCKS4
An abstract class representing the ``SOCKS4`` protocol.
.. class:: SOCKS4a
An abstract class representing the ``SOCKS4a`` protocol.
.. class:: SOCKS5
An abstract class representing the ``SOCKS5`` protocol.
Proxy
-----
You can create a :class:`SOCKSProxy` object directly, but using one
of its auto-detection class methods is likely more useful.
.. class:: SOCKSProxy(address, protocol, auth)
An object representing a SOCKS proxy. The address is a Python
socket `address
<https://docs.python.org/3/library/socket.html#socket-families>`_
typically a (host, port) pair for IPv4, and a (host, port, flowinfo,
scopeid) tuple for IPv6.
The *protocol* is one of :class:`SOCKS4`, :class:`SOCKS4a` and
:class:`SOCKS5`.
*auth* is a :class:`SOCKSUserAuth` object or :const:`None`.
After construction, :attr:`host`, :attr:`port` and :attr:`peername`
are set to :const:`None`.
.. classmethod:: auto_detect_address(address, auth, \*, \
loop=None, timeout=5.0)
Try to detect a SOCKS proxy at *address*.
Protocols :class:`SOCKS5`, :class:`SOCKS4a` and :class:`SOCKS4`
are tried in order. If a SOCKS proxy is detected return a
:class:`SOCKSProxy` object, otherwise :const:`None`. Returning a
proxy object only means one was detected, not that it is
functioning - for example, it may not have full network
connectivity.
*auth* is a :class:`SOCKSUserAuth` object or :const:`None`.
If testing any protocol takes more than *timeout* seconds, it is
timed out and taken as not detected.
This class method is a `coroutine`_.
.. classmethod:: auto_detect_host(host, ports, auth, \*, \
loop=None, timeout=5.0)
Try to detect a SOCKS proxy on *host* on one of the *ports*.
Call :meth:`auto_detect_address` for each ``(host, port)`` pair
until a proxy is detected, and return it, otherwise
:const:`None`.
*auth* is a :class:`SOCKSUserAuth` object or :const:`None`.
If testing any protocol on any port takes more than *timeout*
seconds, it is timed out and taken as not detected.
This class method is a `coroutine`_.
.. method:: create_connection(protocol_factory, host, port, \*, \
resolve=False, loop=None, ssl=None, family=0, proto=0, \
flags=0, timeout=30.0)
Connect to (host, port) through the proxy in the background.
When successful, the coroutine returns a ``(transport, protocol,
address)`` triple, and sets the proxy attribute :attr:`peername`.
* If *resolve* is :const:`True`, *host* is resolved locally
rather than by the proxy. *family*, *proto*, *flags* are the
optional address family, protocol and flags passed to
`loop.getaddrinfo()`_ to get a list of remote addresses. If
given, these should all be integers from the corresponding
:mod:`socket` module constants.
* *ssl* is as documented for `loop.create_connection()`_.
If successfully connected the :attr:`_address` member of the
protocol is set. If *resolve* is :const:`True` it is set to the
successful address, otherwise ``(host, port)``.
If connecting takes more than *timeout* seconds an
:exc:`asyncio.TimeoutError` exception is raised.
This method is a `coroutine`_.
.. attribute:: host
Set on a successful :meth:`create_connection` to the host passed
to the proxy server. This will be the resolved address if its
*resolve* argument was :const:`True`.
.. attribute:: port
Set on a successful :meth:`create_connection` to the host passed
to the proxy server.
.. attribute:: peername
Set on a successful :meth:`create_connection` to the result of
:meth:`socket.getpeername` on the socket connected to the proxy.
.. _loop.create_connection():
https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.AbstractEventLoop.create_connection
.. _loop.getaddrinfo():
https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.AbstractEventLoop.getaddrinfo
.. _coroutine:
https://docs.python.org/3/library/asyncio-task.html#coroutine
|
