« back to all changes in this revision
Viewing changes to Doc/library/asyncore.rst
- browse files at revision 39019
- compare with another revision
- download diff
- download tarball
- view history from revision 39019
- Committer: benjamin.peterson
- Date: 2008-04-25 01:29:10 UTC
- Revision ID: svn-v3-trunk1:6015fed2-1504-0410-9fe1-9d1591cc4771:python%2Ftrunk:62490
reformat some documentation of classes so methods and attributes are under the class directive
- files modified:
- Doc/library/asynchat.rst
added
removed
Doc/library/asyncore.rst
95
95
should be added to the list of channels :cfunc:`select`\ ed or
96
96
:cfunc:`poll`\ ed for read and write events.
97
97
98
Thus, the set of channel events is larger than the basic socket events. The
99
full set of methods that can be overridden in your subclass follows:
100
101
102
.. method:: dispatcher.handle_read()
103
104
Called when the asynchronous loop detects that a :meth:`read` call on the
105
channel's socket will succeed.
106
107
108
.. method:: dispatcher.handle_write()
109
110
Called when the asynchronous loop detects that a writable socket can be
111
written. Often this method will implement the necessary buffering for
112
performance. For example::
113
114
def handle_write(self):
115
sent = self.send(self.buffer)
116
self.buffer = self.buffer[sent:]
117
118
119
.. method:: dispatcher.handle_expt()
120
121
Called when there is out of band (OOB) data for a socket connection. This
122
will almost never happen, as OOB is tenuously supported and rarely used.
123
124
125
.. method:: dispatcher.handle_connect()
126
127
Called when the active opener's socket actually makes a connection. Might
128
send a "welcome" banner, or initiate a protocol negotiation with the remote
129
endpoint, for example.
130
131
132
.. method:: dispatcher.handle_close()
133
134
Called when the socket is closed.
135
136
137
.. method:: dispatcher.handle_error()
138
139
Called when an exception is raised and not otherwise handled. The default
140
version prints a condensed traceback.
141
142
143
.. method:: dispatcher.handle_accept()
144
145
Called on listening channels (passive openers) when a connection can be
146
established with a new remote endpoint that has issued a :meth:`connect`
147
call for the local endpoint.
148
149
150
.. method:: dispatcher.readable()
151
152
Called each time around the asynchronous loop to determine whether a
153
channel's socket should be added to the list on which read events can
154
occur. The default method simply returns ``True``, indicating that by
155
default, all channels will be interested in read events.
156
157
158
.. method:: dispatcher.writable()
159
160
Called each time around the asynchronous loop to determine whether a
161
channel's socket should be added to the list on which write events can
162
occur. The default method simply returns ``True``, indicating that by
163
default, all channels will be interested in write events.
164
165
In addition, each channel delegates or extends many of the socket methods.
166
Most of these are nearly identical to their socket partners.
167
168
169
.. method:: dispatcher.create_socket(family, type)
170
171
This is identical to the creation of a normal socket, and will use the same
172
options for creation. Refer to the :mod:`socket` documentation for
173
information on creating sockets.
174
175
176
.. method:: dispatcher.connect(address)
177
178
As with the normal socket object, *address* is a tuple with the first
179
element the host to connect to, and the second the port number.
180
181
182
.. method:: dispatcher.send(data)
183
184
Send *data* to the remote end-point of the socket.
185
186
187
.. method:: dispatcher.recv(buffer_size)
188
189
Read at most *buffer_size* bytes from the socket's remote end-point.
190
An empty string implies that the channel has been closed from the other
191
end.
192
193
194
.. method:: dispatcher.listen(backlog)
195
196
Listen for connections made to the socket. The *backlog* argument
197
specifies the maximum number of queued connections and should be at least
198
1; the maximum value is system-dependent (usually 5).
199
200
201
.. method:: dispatcher.bind(address)
202
203
Bind the socket to *address*. The socket must not already be bound. (The
204
format of *address* depends on the address family --- see above.) To mark
205
the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call
206
the :class:`dispatcher` object's :meth:`set_reuse_addr` method.
207
208
209
.. method:: dispatcher.accept()
210
211
Accept a connection. The socket must be bound to an address and listening
212
for connections. The return value is a pair ``(conn, address)`` where
213
*conn* is a *new* socket object usable to send and receive data on the
214
connection, and *address* is the address bound to the socket on the other
215
end of the connection.
216
217
218
.. method:: dispatcher.close()
219
220
Close the socket. All future operations on the socket object will fail.
221
The remote end-point will receive no more data (after queued data is
222
flushed). Sockets are automatically closed when they are
223
garbage-collected.
98
Thus, the set of channel events is larger than the basic socket events. The
99
full set of methods that can be overridden in your subclass follows:
100
101
102
.. method:: handle_read()
103
104
Called when the asynchronous loop detects that a :meth:`read` call on the
105
channel's socket will succeed.
106
107
108
.. method:: handle_write()
109
110
Called when the asynchronous loop detects that a writable socket can be
111
written. Often this method will implement the necessary buffering for
112
performance. For example::
113
114
def handle_write(self):
115
sent = self.send(self.buffer)
116
self.buffer = self.buffer[sent:]
117
118
119
.. method:: handle_expt()
120
121
Called when there is out of band (OOB) data for a socket connection. This
122
will almost never happen, as OOB is tenuously supported and rarely used.
123
124
125
.. method:: handle_connect()
126
127
Called when the active opener's socket actually makes a connection. Might
128
send a "welcome" banner, or initiate a protocol negotiation with the
129
remote endpoint, for example.
130
131
132
.. method:: handle_close()
133
134
Called when the socket is closed.
135
136
137
.. method:: handle_error()
138
139
Called when an exception is raised and not otherwise handled. The default
140
version prints a condensed traceback.
141
142
143
.. method:: handle_accept()
144
145
Called on listening channels (passive openers) when a connection can be
146
established with a new remote endpoint that has issued a :meth:`connect`
147
call for the local endpoint.
148
149
150
.. method:: readable()
151
152
Called each time around the asynchronous loop to determine whether a
153
channel's socket should be added to the list on which read events can
154
occur. The default method simply returns ``True``, indicating that by
155
default, all channels will be interested in read events.
156
157
158
.. method:: writable()
159
160
Called each time around the asynchronous loop to determine whether a
161
channel's socket should be added to the list on which write events can
162
occur. The default method simply returns ``True``, indicating that by
163
default, all channels will be interested in write events.
164
165
166
In addition, each channel delegates or extends many of the socket methods.
167
Most of these are nearly identical to their socket partners.
168
169
170
.. method:: create_socket(family, type)
171
172
This is identical to the creation of a normal socket, and will use the
173
same options for creation. Refer to the :mod:`socket` documentation for
174
information on creating sockets.
175
176
177
.. method:: connect(address)
178
179
As with the normal socket object, *address* is a tuple with the first
180
element the host to connect to, and the second the port number.
181
182
183
.. method:: send(data)
184
185
Send *data* to the remote end-point of the socket.
186
187
188
.. method:: recv(buffer_size)
189
190
Read at most *buffer_size* bytes from the socket's remote end-point. An
191
empty string implies that the channel has been closed from the other end.
192
193
194
.. method:: listen(backlog)
195
196
Listen for connections made to the socket. The *backlog* argument
197
specifies the maximum number of queued connections and should be at least
198
1; the maximum value is system-dependent (usually 5).
199
200
201
.. method:: bind(address)
202
203
Bind the socket to *address*. The socket must not already be bound. (The
204
format of *address* depends on the address family --- see above.) To mark
205
the socket as re-usable (setting the :const:`SO_REUSEADDR` option), call
206
the :class:`dispatcher` object's :meth:`set_reuse_addr` method.
207
208
209
.. method:: accept()
210
211
Accept a connection. The socket must be bound to an address and listening
212
for connections. The return value is a pair ``(conn, address)`` where
213
*conn* is a *new* socket object usable to send and receive data on the
214
connection, and *address* is the address bound to the socket on the other
215
end of the connection.
216
217
218
.. method:: close()
219
220
Close the socket. All future operations on the socket object will fail.
221
The remote end-point will receive no more data (after queued data is
222
flushed). Sockets are automatically closed when they are
223
garbage-collected.
224
224
225
225
226
226
.. _asyncore-example:
Loggerhead is a web-based interface for Breezy
Version: 2.0.1