-
Notifications
You must be signed in to change notification settings - Fork 113
Expand file tree
/
Copy patherrors.texi
More file actions
173 lines (120 loc) · 4.51 KB
/
errors.texi
File metadata and controls
173 lines (120 loc) · 4.51 KB
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
@c The Python X Library -- error handling
@c
@c Copyright 2000 Peter Liljenberg
@c
@node Error Handling
@chapter Error Handling
If an X object method generates an error, it will be handled in one of two
different ways depending on the kind of method. Errors are represented
by X error objects in the Xlib.
If the method @emph{does not} return data, the error will most likely be
detected after the method has returned. All methods which does not
return data has a parameter called @code{onerror}, which can be used to
provide a error handler for any error generated by this method.
The error handler is called with to arguments: the error object and the
low-level request object. The error @emph{must not} do call any X
object methods. If that is necessary, the error handler must store the
error away for later retrieval. The class @code{error.CatchError} is
provided for this purpose.
If no error handler is given when calling a method which generates an
error, the error will be passed to the default error handler. If no
default error handler is specified, the error is simply printed on
@code{sys.stderr}.
If the method @emph{does} return data, the error will make it impossible
for it to return any valid data. An exception is raised with the error
object as the exception value. It is not passed to any error handlers.
@menu
* X Error Classes:: X error class hierarchy.
* CatchError:: Error handler class.
@end menu
@node X Error Classes
@section X Error Classes
X errors are structured in the following class hierarchy:
@example
@group
Exception
\_ error.XError
\_ error.BadRequest
\_ error.BadValue
\_ error.BadAtom
\_ error.BadMatch
\_ error.BadAccess
\_ error.BadAlloc
\_ error.BadName
\_ error.BadLength
\_ error.BadImplementation
\_ error.XResourceError
\_ error.BadWindow
\_ error.BadPixmap
\_ error.BadCursor
\_ error.BadFont
\_ error.BadDrawable
\_ error.BadColor
\_ error.BadGC
\_ error.BadIDChoice
@end group
@end example
All error objects has the following attributes:
@table @code
@item code
The numeric error code
@item sequence_number
The sequence number of the failed request
@item resource_id
The bad resource id. For all the @code{error.XResourceError} this is a
X resource object. For the other errors it is an integer, which for
some errors might have no meaning
@item major_opcode
The major opcode for the failed request
@item minor_opcode
The minor opcode for the failed request. This will be zero for all base
X11R6 request, but will be interesting for extension requests
@end table
@node CatchError
@section CatchError
@code{error.CatchError} is an object which can be used as an error
handler. It collects an error matching any of the specified types,
which can be retrieved later. If several errors occur, only the last
one is remembered.
@deffn Class CatchError ( *errors )
Create a new error handler object. Initialize by providing all error
classes you are interested in as arguments. If no error classes are
provided at all, this means that all errors will be considered.
@end deffn
Pass the @code{error.CatchError} object as the @code{onerror} parameter
to X object methods. If these methods generated any errors matching the
ones specified, it can be retrieved with the following functions:
@defmethod CatchError get_error ( )
Return the last error object caught, or None if no matching errors has
occured.
@end defmethod
@defmethod CatchError get_request ( )
Return the request object for the last error caught, or None if no
matching errors has occured.
@end defmethod
@code{error.CatchError} objects can be reused:
@defmethod CatchError reset ( )
Forget any caught error.
@end defmethod
Since the X protocol is mostly asynchronous any error we're watching for
might not have been received when we call @code{get_error}. To make
sure that the request has been processed by the server and any error
generated has been received by the Xlib, we must synchronize with the
server.
An example of using @code{error.CatchError}:
@example
@group
# Resize and the foo window
# If it has been destroyed since we looked at it the last time,
# reset variable foo to None
# Create a error handler for BadWindow errors
ec = error.CatchError(error.BadWindow)
# Perform the operation
foo.configure(width = 100, height = 200, onerror = ec)
# Sync communication with server
display.sync()
# And check if there was any error
if ec.get_error():
foo = None
@end group
@end example