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
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
|
<html>
<head>
<title>Developer's Guide: General Remarks</title>
</head>
<body bgcolor=white text=black link=blue vlink=navy alink=red>
<TABLE WIDTH="100%">
<TR>
<TH ALIGN="left" WIDTH="33%"><img SRC="Images/arrow-left.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Prev"></TH>
<TH ALIGN="center" WIDTH="33%"><img SRC="Images/arrow-up.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Up"></TH>
<TH ALIGN="right" WIDTH="33%"><img SRC="Images/arrow-right.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Next"></TH>
</TR>
<TR>
<TD ALIGN="left"><A HREF="devguide-2.html">The Design of Sketch</A></TD>
<TD ALIGN="center"><A HREF="devguide.html">Developer's Guide</A></TD>
<TD ALIGN="right"><A HREF="devguide-4.html">Coordinate Systems
</A></TD>
</TR>
</TABLE>
<HR NOSHADE>
<H1><FONT face="Helvetica,Arial"><A NAME="N1"></A>General Remarks</font></H1>
<H2><FONT face="Helvetica,Arial"><A NAME="N2"></A>Directory Structure
</font></H2>
<P>The source is divided into the core sources, containing the basic
graphics classes, the UI code and some utility modules. <A HREF="devguide-22.html">Import filters</A> and other <A HREF="devguide-20.html">plugins</A>
are maintained outside of this core source. Other external packages
provide direct access to Xlib functions and objects (<A HREF="#N4">Pax</A>) and stream filter objects (<A HREF="#N5">Filter</A>).</P>
<P>
<DL>
<DT><B><tt>sketch-<version>/</tt></B><DD>
<P>The top level directory holds the main scripts <tt>sketch.py</tt> and
<tt>sk2ps.py</tt></P>
<P>
<DL>
<DT><B><tt>Sketch/</tt></B><DD>
<P>The top-level directory for the core sources. This works as a
Python package which export many of the commonly needed support
and graphics objects (classes, functions, constants etc.).</P>
<P>Ideally, the <CODE>Sketch</CODE> package should export every thing a
`normal' plugin may need. This is not yet the case, as some
interfaces are not very stable yet and may need to be
redesigned. Once they have reached a certain level of stability,
they will be moved into <CODE>Sketch</CODE>.</P>
<P>
<DL>
<DT><B><tt>Base/</tt></B><DD>
<P>Contains the most fundamental modules such as the
modules for file IO, undo/redo, the plugin manager and
code for user preferences.</P>
<DT><B><tt>Modules/</tt></B><DD>
<P>The C-Modules.</P>
</DL>
The modules in <CODE>Base/</CODE> and <CODE>Modules/</CODE> are accessible as
<CODE>Sketch.<i>modulename</i></CODE>. These directories are not
currently subpackages.</P>
<P>
<DL>
<DT><B><tt>Graphics/</tt></B><DD>
<P>The subpackage for the graphics modules. </P>
<P>It contains all of the builtin graphics classes:
primitives, compound objects, special effects
(blend/mask/...), the document object, ...</P>
<P>It also holds the graphics devices for drawing into the
window or PostScript file.</P>
<P>The <CODE>Graphics</CODE> modules are accesible as
<CODE>Sketch.Graphics.<i>modulename</i></CODE>. Many of the
objects defined in Graphics modules are exported
directly by the Sketch module.</P>
<DT><B><tt>UI/</tt></B><DD>
<P>The subpackage for user interface related code.</P>
<P>Contains the user interface code including the
application object.</P>
<DT><B><tt>Lib/</tt></B><DD>
<P>A subpackage for some support modules that are not
really Sketch specific, such as a Type 1 font
interpreter (simply extracts the outline information)
and a simple parser for PostScript files adhering to the
DSC.</P>
<DT><B><tt>Pixmaps/</tt></B><DD>
<P>Pixmap files used by Sketch.</P>
</DL>
</P>
<DT><B><tt>Plugins/</tt></B><DD>
<P>The subdirectories contain the various <A HREF="devguide-20.html">plugins</A>:</P>
<P>
<DL>
<DT><B><A NAME="N3"></A>
<tt>Filters/</tt></B><DD>
<P>Contains the <A HREF="devguide-22.html">import filters</A>
and export filters for SK-files and other formats.</P>
<DT><B><tt>Objects/</tt></B><DD>
<P><A HREF="devguide-24.html">Plugin objects</A>.</P>
</DL>
</P>
<DT><B><tt>Resources/</tt></B><DD>
<P>The subdirectories contain platform/UI independent resources:</P>
<P>
<DL>
<DT><B><tt>Fontmetrics/</tt></B><DD>
<P>Fontmetrics (<tt>*.afm</tt>) for standard PostScript fonts
and `font directory files' (<tt>*.sfd</tt>) that describe
fonts for Sketch.</P>
<DT><B><tt>Misc/</tt></B><DD>
<P>Files that define arrows (<tt>*.arrow</tt>), dashes
(<tt>*.dashes</tt>), palettes (<tt>*.spl</tt>) and
Tk-resources.</P>
</DL>
</P>
<DT><B><A NAME="N4"></A><tt>Pax/</tt></B><DD>
<P>Modules that allow Sketch direct access to Xlib. This is a
heavily modified version of the Xt-module.</P>
<DT><B><A NAME="N5"></A><tt>Filter/</tt></B><DD>
<P>A module for stream filters. A stream filter behaves just like a
(non seekable) file and comes in two variants: An encoding
filter encodes the data written to it and writes the encoded
data to a data target (a file or another filter); a decoding
filter reads data from a data source (a file or another filter)
and provides it in decoded form.</P>
<P>These stream filters are modeled after the filters in
PostScript Level 2.</P>
<P>Don't confuse these filters with the Import filters in the <A HREF="#N3"><tt>Plugins/Filters/</tt></A> directory
(although import filters might use stream filters to decode the
data).</P>
<DT><B><tt>Examples/</tt></B><DD>
<P>Some example drawings.</P>
</DL>
</P>
</DL>
</P>
<H2><FONT face="Helvetica,Arial"><A NAME="N6"></A>Naming Conventions</font></H2>
<P>Module names are <CODE>lowercase</CODE>.</P>
<P>Functions have identifiers that are either
<CODE>lowercase_with_underscores</CODE> or <CODE>Capitalized</CODE>. This is a bit of a
mess, but generally the former should be preferred.</P>
<P>Variables, local or global, are also <CODE>lowercase_with_underscores</CODE>.
Module internal names (for functions, variables, etc.) shouldstart with
an underscore (`<CODE>_</CODE>') (this is a Python convention that affects
import statements and module finalization).</P>
<P>Class names are <CODE>Capitalized</CODE>. Public methods are also
<CODE>Capitalized</CODE>, protected methods are <CODE>lowercase_with_underscores</CODE>,
private methods start with two underscores (another Python convention).
Instance variables are also <CODE>lowercase_with_underscores</CODE>.</P>
<P>Constants are often <CODE>UPPERCASE</CODE> (an exception are the X-constants in
<CODE>Pax/X.py</CODE>)</P>
<P>Python does not enforce encapsulation and the distinction between
public, protected and private methods and instance variables is more or
less a convention programmers are expected to adhere to.</P>
<H2><FONT face="Helvetica,Arial"><A NAME="N7"></A>Coding Guidelines</font></H2>
<P>This <EM>not</EM> a `coding style' or something similar you are required to
adhere to, just some remarks on writing maintainable and readable Python
code (IMHO).</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N8"></A>Import statements</font></H3>
<P>Don't use <CODE>from <i>module</i> import *</CODE></P>
<P>It is difficult to find out whether the code really depends on objects
exported by the module. Editing the source or moving some parts of the
code to other modules may result in code that doesn't need that module
any more, so the import statement should be removed.</P>
<P>Using `<CODE>import <i>module</i></CODE>' or `<CODE>from <i>module</i>
import <i>foo</i>, <i>bar</i></CODE>' makes this easier.</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N9"></A>Multiple assignments</font></H3>
<P>Don't use multiple assignments.</P>
<P>Multiple assignments are assignments like this:</P>
<P>
<PRE>
a, b = 0, 1
</PRE>
</P>
<P>I think this is harder to read than</P>
<P>
<PRE>
a = 0
b = 1
</PRE>
</P>
<P>or, if you really want only one line,
<PRE>
a = 0; b = 1
</PRE>
</P>
<P>In the current interpreter (Python 1.5.1) the multiple assignment is
even slower than two single assignments (for local variables; the
interpreter actually builds a tuple and unpacks it immediately)</P>
<P>Multiple assignments are convenient, though, if the first assignment has
side effects influencing the second assignment. If you want to swap the
values of the variables <CODE>a</CODE> and <CODE>b</CODE> you may write
<PRE>
a, b = b, a
</PRE>
</P>
<P>Note that even in this case the traditional idiom for swapping
variables, <CODE>temp = a; a = b; b = temp</CODE> is <EM>faster</EM> than multiple
assignment (see <tt>Tools/swapbench.py</tt>).</P>
<H3><FONT face="Helvetica,Arial"><A NAME="N10"></A>Truth Values, <CODE>__getattr__</CODE> and <CODE>__len__</CODE></font></H3>
<P>In various places, instance or class attributes have the value <CODE>None</CODE>
to indictate that the attribute has no particular value, while, if the
attribute is set, its value is an instance object (one such attribute is
<A HREF="devguide-13.html#N2"><tt>HierarchyNode</tt></A>'s attribute <CODE>parent</CODE>). Functions and
methods often return <CODE>None</CODE> instead of an instance object for similar
reasons.</P>
<P>There are more cases, and, indeed, the following applies whenever you
have an object that may be <CODE>None</CODE> or an instance object.</P>
<P>In all these cases, you have to test whether the object you have is
<CODE>None</CODE> or not. It is tempting to write e.g.
<PRE>
if self.parent:
self.parent.SomePublicMethod()
</PRE>
</P>
<P>Don't do that. Test whether the object <EM>is</EM> <CODE>None</CODE>:
<PRE>
if self.parent is not None:
self.parent.SomePublicMethod()
</PRE>
</P>
<P>There are two reasons for this:</P>
<P>Firstly, if the object is an instance object, Python tries to determine
if it is true or false by calling its <CODE>__nonzero__</CODE> method and, if it
doesn't have that method, its <CODE>__len__</CODE> method. Now, most objects in
Sketch don't have these methods, so Python tries to call the
<CODE>__getattr__</CODE> method, which many objects, including all graphics
objects, have, twice, for <CODE>__nonzero__</CODE> and <CODE>__len__</CODE>. This
overhead can be avoided by testing for identity with <CODE>None</CODE>.</P>
<P>Secondly, even if you know that the object has no <CODE>__len__</CODE> or
<CODE>__nonzero__</CODE> methods (and, hence, is always considered `true'), it
may have them in future versions (the compound graphics objects might
implement the Python sequence protocol and, accordingly, the
<CODE>__len__</CODE> method). In that case, code that simply tests whether the
object is true would break, as the object might be false even though it
is <EM>not</EM> <CODE>None</CODE>.</P>
<HR NOSHADE>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left"><A HREF="devguide-2.html">The Design of Sketch</A></TD>
<TD ALIGN="center"><A HREF="devguide.html">Developer's Guide</A></TD>
<TD ALIGN="right"><A HREF="devguide-4.html">Coordinate Systems
</A></TD>
</TR>
<TR>
<TH ALIGN="left" WIDTH="33%"><img SRC="Images/arrow-left.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Prev"></TH>
<TH ALIGN="center" WIDTH="33%"><img SRC="Images/arrow-up.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Up"></TH>
<TH ALIGN="right" WIDTH="33%"><img SRC="Images/arrow-right.png" WIDTH="16" HEIGHT="16" ALIGN="top" ALT="Next"></TH>
</TR>
</TABLE>
</body>
</html>
|
