Prev Up Next
The Design of Sketch Developer's Guide Coordinate Systems

General Remarks

Directory Structure

The source is divided into the core sources, containing the basic graphics classes, the UI code and some utility modules. Import filters and other plugins are maintained outside of this core source. Other external packages provide direct access to Xlib functions and objects (Pax) and stream filter objects (Filter).

sketch-<version>/

The top level directory holds the main scripts sketch.py and sk2ps.py

Sketch/

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.).

Ideally, the Sketch 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 Sketch.

Base/

Contains the most fundamental modules such as the modules for file IO, undo/redo, the plugin manager and code for user preferences.

Modules/

The C-Modules.

The modules in Base/ and Modules/ are accessible as Sketch.modulename. These directories are not currently subpackages.

Graphics/

The subpackage for the graphics modules.

It contains all of the builtin graphics classes: primitives, compound objects, special effects (blend/mask/...), the document object, ...

It also holds the graphics devices for drawing into the window or PostScript file.

The Graphics modules are accesible as Sketch.Graphics.modulename. Many of the objects defined in Graphics modules are exported directly by the Sketch module.

UI/

The subpackage for user interface related code.

Contains the user interface code including the application object.

Lib/

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.

Pixmaps/

Pixmap files used by Sketch.

Plugins/

The subdirectories contain the various plugins:

Filters/

Contains the import filters and export filters for SK-files and other formats.

Objects/

Plugin objects.

Resources/

The subdirectories contain platform/UI independent resources:

Fontmetrics/

Fontmetrics (*.afm) for standard PostScript fonts and `font directory files' (*.sfd) that describe fonts for Sketch.

Misc/

Files that define arrows (*.arrow), dashes (*.dashes), palettes (*.spl) and Tk-resources.

Pax/

Modules that allow Sketch direct access to Xlib. This is a heavily modified version of the Xt-module.

Filter/

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.

These stream filters are modeled after the filters in PostScript Level 2.

Don't confuse these filters with the Import filters in the Plugins/Filters/ directory (although import filters might use stream filters to decode the data).

Examples/

Some example drawings.

Naming Conventions

Module names are lowercase.

Functions have identifiers that are either lowercase_with_underscores or Capitalized. This is a bit of a mess, but generally the former should be preferred.

Variables, local or global, are also lowercase_with_underscores. Module internal names (for functions, variables, etc.) shouldstart with an underscore (`_') (this is a Python convention that affects import statements and module finalization).

Class names are Capitalized. Public methods are also Capitalized, protected methods are lowercase_with_underscores, private methods start with two underscores (another Python convention). Instance variables are also lowercase_with_underscores.

Constants are often UPPERCASE (an exception are the X-constants in Pax/X.py)

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.

Coding Guidelines

This not a `coding style' or something similar you are required to adhere to, just some remarks on writing maintainable and readable Python code (IMHO).

Import statements

Don't use from module import *

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.

Using `import module' or `from module import foo, bar' makes this easier.

Multiple assignments

Don't use multiple assignments.

Multiple assignments are assignments like this:

	a, b = 0, 1

I think this is harder to read than

	a = 0
	b = 1

or, if you really want only one line,

	a = 0; b = 1

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)

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 a and b you may write

	a, b = b, a

Note that even in this case the traditional idiom for swapping variables, temp = a; a = b; b = temp is faster than multiple assignment (see Tools/swapbench.py).

Truth Values, __getattr__ and __len__

In various places, instance or class attributes have the value None 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 HierarchyNode's attribute parent). Functions and methods often return None instead of an instance object for similar reasons.

There are more cases, and, indeed, the following applies whenever you have an object that may be None or an instance object.

In all these cases, you have to test whether the object you have is None or not. It is tempting to write e.g.

	if self.parent:
		self.parent.SomePublicMethod()

Don't do that. Test whether the object is None:

	if self.parent is not None:
		self.parent.SomePublicMethod()

There are two reasons for this:

Firstly, if the object is an instance object, Python tries to determine if it is true or false by calling its __nonzero__ method and, if it doesn't have that method, its __len__ method. Now, most objects in Sketch don't have these methods, so Python tries to call the __getattr__ method, which many objects, including all graphics objects, have, twice, for __nonzero__ and __len__. This overhead can be avoided by testing for identity with None.

Secondly, even if you know that the object has no __len__ or __nonzero__ 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 __len__ 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 not None.


The Design of Sketch Developer's Guide Coordinate Systems
Prev Up Next