Debian Codegraph @

pypy3.10/doc/connection-ref.html

raw
1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
7 <title>Listeners and Clients</title>
8 <link rel="stylesheet" href="html4css1.css" type="text/css" />
9 </head>
10 <body>
11 <div class="header">
12 <a class="reference" href="sharedctypes.html">Prev</a> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="processing-ref.html">Up</a> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="programming-guidelines.html">Next</a>
13 <hr class="header"/>
14 </div>
15 <div class="document" id="listeners-and-clients">
16 <h1 class="title">Listeners and Clients</h1>
17 <p>Usually message passing between processes is done using queues or by
18 using connection objects returned by <tt class="docutils literal"><span class="pre">Pipe()</span></tt>.</p>
19 <p>However, the <tt class="docutils literal"><span class="pre">processing.connection</span></tt> module allows some extra
20 flexibility. It basically gives a high level API for dealing with
21 sockets or Windows named pipes, and also has support for <em>digest
22 authentication</em> using the <tt class="docutils literal"><span class="pre">hmac</span></tt> module from the standard library.</p>
23 <div class="section">
24 <h1><a id="classes-and-functions" name="classes-and-functions">Classes and functions</a></h1>
25 <p>The module defines the following functions:</p>
26 <blockquote>
27 <dl class="docutils">
28 <dt><tt class="docutils literal"><span class="pre">Listener(address=None,</span> <span class="pre">family=None,</span> <span class="pre">backlog=1,</span> <span class="pre">authenticate=False,</span> <span class="pre">authkey=None)</span></tt></dt>
29 <dd>Returns a wrapper for a bound socket or Windows named pipe
30 which is 'listening' for connections.</dd>
31 <dt><tt class="docutils literal"><span class="pre">Client(address,</span> <span class="pre">family=None,</span> <span class="pre">authenticate=False,</span> <span class="pre">authkey=None)</span></tt></dt>
32 <dd><p class="first">Attempts to set up a connection to the listener which is using
33 address <tt class="docutils literal"><span class="pre">address</span></tt>, returning a <a class="reference" href="connection-object.html">connection object</a>.</p>
34 <p>The type of the connection is determined by <tt class="docutils literal"><span class="pre">family</span></tt>
35 argument, but this can generally be omitted since it can
36 usually be inferred from the format of <tt class="docutils literal"><span class="pre">address</span></tt>.</p>
37 <p class="last">If <tt class="docutils literal"><span class="pre">authentication</span></tt> or <tt class="docutils literal"><span class="pre">authkey</span></tt> is a string then digest
38 authentication is used. The key used for authentication will
39 be either <tt class="docutils literal"><span class="pre">authkey</span></tt> or <tt class="docutils literal"><span class="pre">currentProcess.getAuthKey()</span></tt> if
40 <tt class="docutils literal"><span class="pre">authkey</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt>. If authentication fails then
41 <tt class="docutils literal"><span class="pre">AuthenticationError</span></tt> is raised. See <a class="reference" href="#authentication-keys">Authentication keys</a>.</p>
42 </dd>
43 </dl>
44 </blockquote>
45 <!-- `deliverChallenge(connection, authkey)`
46 Sends a randomly generated message to the other end of the
47 connection and waits for a reply.
48
49 If the reply matches the digest of the message using `authkey`
50 as the key then a welcome message is sent to the other end of
51 the connection. Otherwise `AuthenticationError` is raised.
52
53 `answerChallenge(connection, authkey)`
54 Receives a message, calculates the digest of the message using
55 `authkey` as the key, and then sends the digest back.
56
57 If a welcome message is not received then
58 `AuthenticationError` is raised. -->
59 <p>The module exports two exception types:</p>
60 <blockquote>
61 <dl class="docutils">
62 <dt><strong>exception</strong> <tt class="docutils literal"><span class="pre">AuthenticationError</span></tt></dt>
63 <dd>Exception raised when there is an authentication error.</dd>
64 <dt><strong>exception</strong> <tt class="docutils literal"><span class="pre">BufferTooShort</span></tt></dt>
65 <dd><p class="first">Exception raise by the <tt class="docutils literal"><span class="pre">recvBytesInto()</span></tt> method of a
66 connection object when the supplied buffer object is too small
67 for the message read.</p>
68 <p class="last">If <tt class="docutils literal"><span class="pre">e</span></tt> is an instance of <tt class="docutils literal"><span class="pre">BufferTooShort</span></tt> then <tt class="docutils literal"><span class="pre">e.args[0]</span></tt> will
69 give the message as a byte string.</p>
70 </dd>
71 </dl>
72 </blockquote>
73 </div>
74 <div class="section">
75 <h1><a id="listener-objects" name="listener-objects">Listener objects</a></h1>
76 <p>Instances of <tt class="docutils literal"><span class="pre">Listener</span></tt> have the following methods:</p>
77 <blockquote>
78 <dl class="docutils">
79 <dt><tt class="docutils literal"><span class="pre">__init__(address=None,</span> <span class="pre">family=None,</span> <span class="pre">backlog=1,</span> <span class="pre">authenticate=False,</span> <span class="pre">authkey=None)</span></tt></dt>
80 <dd><dl class="first last docutils">
81 <dt><tt class="docutils literal"><span class="pre">address</span></tt></dt>
82 <dd>The address to be used by the bound socket
83 or named pipe of the listener object.</dd>
84 <dt><tt class="docutils literal"><span class="pre">family</span></tt></dt>
85 <dd><p class="first">The type of the socket (or named pipe) to use.</p>
86 <p>This can be one of the strings <tt class="docutils literal"><span class="pre">'AF_INET'</span></tt> (for a TCP
87 socket), <tt class="docutils literal"><span class="pre">'AF_UNIX'</span></tt> (for a Unix domain socket) or
88 <tt class="docutils literal"><span class="pre">'AF_PIPE'</span></tt> (for a Windows named pipe). Of these only
89 the first is guaranteed to be available.</p>
90 <p>If <tt class="docutils literal"><span class="pre">family</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt> than the family is inferred from the
91 format of <tt class="docutils literal"><span class="pre">address</span></tt>. If <tt class="docutils literal"><span class="pre">address</span></tt> is also <tt class="docutils literal"><span class="pre">None</span></tt> then a
92 default is chosen. This default is the family which is
93 assumed to be the fastest available. See <a class="reference" href="#address-formats">Address
94 formats</a>.</p>
95 <p class="last">Note that if <tt class="docutils literal"><span class="pre">family</span></tt> is <tt class="docutils literal"><span class="pre">'AF_UNIX'</span></tt> then the associated
96 file will have only be readable/writable by the user
97 running the current process -- use <tt class="docutils literal"><span class="pre">os.chmod()</span></tt> is you need
98 to let other users access the socket.</p>
99 </dd>
100 <dt><tt class="docutils literal"><span class="pre">backlog</span></tt></dt>
101 <dd>If the listener object uses a socket then <tt class="docutils literal"><span class="pre">backlog</span></tt> is
102 passed to the <tt class="docutils literal"><span class="pre">listen()</span></tt> method of the socket once it has
103 been bound.</dd>
104 <dt><tt class="docutils literal"><span class="pre">authenticate</span></tt></dt>
105 <dd>If <tt class="docutils literal"><span class="pre">authenticate</span></tt> is true or <tt class="docutils literal"><span class="pre">authkey</span></tt> is not <tt class="docutils literal"><span class="pre">None</span></tt> then
106 digest authentication is used.</dd>
107 <dt><tt class="docutils literal"><span class="pre">authkey</span></tt></dt>
108 <dd><p class="first">If <tt class="docutils literal"><span class="pre">authkey</span></tt> is a string then it will be used as the
109 authentication key; otherwise it must be <tt class="docutils literal"><span class="pre">None</span></tt>.</p>
110 <p>If <tt class="docutils literal"><span class="pre">authkey</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt> and <tt class="docutils literal"><span class="pre">authenticate</span></tt> is true then
111 <tt class="docutils literal"><span class="pre">currentProcess.getAuthKey()</span></tt> is used as the authentication
112 key.</p>
113 <p>If <tt class="docutils literal"><span class="pre">authkey</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt> and <tt class="docutils literal"><span class="pre">authentication</span></tt> is false then
114 no authentication is done.</p>
115 <p class="last">If authentication fails then <tt class="docutils literal"><span class="pre">AuthenticationError</span></tt> is
116 raised. See <a class="reference" href="#authentication-keys">Authentication keys</a>.</p>
117 </dd>
118 </dl>
119 </dd>
120 <dt><tt class="docutils literal"><span class="pre">accept()</span></tt></dt>
121 <dd><p class="first">Accept a connection on the bound socket or named pipe of the
122 listener object. If authentication is attempted and fails
123 then <tt class="docutils literal"><span class="pre">AuthenticationError</span></tt> is raised.</p>
124 <p class="last">Returns a <tt class="docutils literal"><span class="pre">connection</span> <span class="pre">object</span> <span class="pre">&lt;connection-object.html&gt;</span></tt> object.</p>
125 </dd>
126 <dt><tt class="docutils literal"><span class="pre">close()</span></tt></dt>
127 <dd><p class="first">Close the bound socket or named pipe of the listener object.</p>
128 <p class="last">This is called automatically when the listener is garbage
129 collected. However it is advisable to call it explicitly.</p>
130 </dd>
131 </dl>
132 </blockquote>
133 <p>Listener objects have the following read-only properties:</p>
134 <blockquote>
135 <dl class="docutils">
136 <dt><tt class="docutils literal"><span class="pre">address</span></tt></dt>
137 <dd>The address which is being used by the listener object.</dd>
138 <dt><tt class="docutils literal"><span class="pre">last_accepted</span></tt></dt>
139 <dd><p class="first">The address from which the last accepted connection came.</p>
140 <p class="last">If this is unavailable then <tt class="docutils literal"><span class="pre">None</span></tt> is returned.</p>
141 </dd>
142 </dl>
143 </blockquote>
144 </div>
145 <div class="section">
146 <h1><a id="address-formats" name="address-formats">Address formats</a></h1>
147 <ul>
148 <li><p class="first">An <tt class="docutils literal"><span class="pre">'AF_INET'</span></tt> address is a tuple of the form <tt class="docutils literal"><span class="pre">(hostname,</span> <span class="pre">port)</span></tt>
149 where <tt class="docutils literal"><span class="pre">hostname</span></tt> is a string and <tt class="docutils literal"><span class="pre">port</span></tt> is an integer</p>
150 </li>
151 <li><p class="first">An <tt class="docutils literal"><span class="pre">'AF_UNIX'</span></tt> address is a string representing a filename on the
152 filesystem.</p>
153 </li>
154 <li><p class="first">An <tt class="docutils literal"><span class="pre">'AF_PIPE'</span></tt> address is a string of the form
155 <tt class="docutils literal"><span class="pre">r'\\.\pipe\PipeName'</span></tt>.</p>
156 <p>To use <tt class="docutils literal"><span class="pre">Client</span></tt> to connect to a named pipe on a remote computer
157 called <tt class="docutils literal"><span class="pre">ServerName</span></tt> one should use an address of the form
158 <tt class="docutils literal"><span class="pre">r'\\ServerName\pipe\PipeName'</span></tt> instead.</p>
159 </li>
160 </ul>
161 <p>Note that any string beginning with two backslashes is assumed by
162 default to be an <tt class="docutils literal"><span class="pre">'AF_PIPE'</span></tt> address rather than an <tt class="docutils literal"><span class="pre">'AF_UNIX'</span></tt>
163 address.</p>
164 </div>
165 <div class="section">
166 <h1><a id="authentication-keys" name="authentication-keys">Authentication keys</a></h1>
167 <p>When one uses the <tt class="docutils literal"><span class="pre">recv()</span></tt> method of a connection object, the data
168 received is automatically unpickled. Unfortunately unpickling data
169 from an untrusted source is a security risk. Therefore <tt class="docutils literal"><span class="pre">Listener</span></tt> and
170 <tt class="docutils literal"><span class="pre">Client</span></tt> use the <tt class="docutils literal"><span class="pre">hmac</span></tt> module to provide digest authentication.</p>
171 <p>An authentication key is a string which can be thought of as a
172 password: once a connection is established both ends will demand proof
173 that the other knows the authentication key. (Demonstrating that both
174 ends are using the same key does <em>not</em> involve sending the key over
175 the connection.)</p>
176 <p>If authentication is requested but do authentication key is specified
177 then the return value of <tt class="docutils literal"><span class="pre">currentProcess().getAuthKey()</span></tt> is used (see
178 <a class="reference" href="process-objects.html">Process objects</a>). This value will
179 automatically inherited by any <tt class="docutils literal"><span class="pre">Process</span></tt> object that the current
180 process creates. This means that (by default) all processes of a
181 multi-process program will share a single authentication key which can
182 be used when setting up connections between the themselves.</p>
183 <p>Suitable authentication keys can also be generated by using
184 <tt class="docutils literal"><span class="pre">os.urandom()</span></tt>.</p>
185 </div>
186 <div class="section">
187 <h1><a id="example" name="example">Example</a></h1>
188 <p>The following server code creates a listener which uses <tt class="docutils literal"><span class="pre">'secret</span>
189 <span class="pre">password'</span></tt> as an authentication key. It then waits for a connection
190 and sends some data to the client:</p>
191 <pre class="literal-block">
192 from processing.connection import Listener
193 from array import array
194
195 address = ('localhost', 6000) # family is deduced to be 'AF_INET'
196 listener = Listener(address, authkey='secret password')
197
198 conn = listener.accept()
199 print 'connection accepted from', listener.last_accepted
200
201 conn.send([2.25, None, 'junk', float])
202
203 conn.sendBytes('hello')
204
205 conn.sendBytes(array('i', [42, 1729]))
206
207 conn.close()
208 listener.close()
209 </pre>
210 <p>The following code connects to the server and receives some data from
211 the server:</p>
212 <pre class="literal-block">
213 from processing.connection import Client
214 from array import array
215
216 address = ('localhost', 6000)
217 conn = Client(address, authkey='secret password')
218
219 print conn.recv() # =&gt; [2.25, None, 'junk', float]
220
221 print conn.recvBytes() # =&gt; 'hello'
222
223 arr = array('i', [0, 0, 0, 0, 0])
224 print conn.recvBytesInto(arr) # =&gt; 8
225 print arr # =&gt; array('i', [42, 1729, 0, 0, 0])
226
227 conn.close()
228 </pre>
229 </div>
230 </div>
231 <div class="footer">
232 <hr class="footer" />
233 <a class="reference" href="sharedctypes.html">Prev</a> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="processing-ref.html">Up</a> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="programming-guidelines.html">Next</a>
234 </div>
235 </body>
236 </html>