This appendix provides tips for usage and pointers to useful online resources for developers using Wing IDE.
Archaeopteryx Software provides a number of support resources free of charge.
All of these are available on the web at
The Python Language Reference, maintained by the developers of Python,
is available online at
www.python.org or from the Help menu in
This reference manual contains the following parts:
This section describes some useful tools that are available to Python programmers but that have not yet been integrated into the Wing's graphical user interface.
Performance profiling is supported by the Python
To create a profile file named
profile.tmp for invocation of
main() you would include the following code
in your application:
import profile profile.run('import mymodule; mymodule.main()', 'profile.tmp')
This will accumulate profile data while running the function
mymodule. Note that importing and fully specifying
the module scope is important if you plan to run the profiler under
the Wing debugger. The profiler makes assumptions about scope that
are violated by the debugger so just specifying
will not work.
pstats module is used to inspect the contents of
the profiler's output file. For example, the following command would
sort the file by cumulative time spent in each function, and then
print out the top 10 compute-intensive calls:
import pstats p = pstats.Stats('profile.tmp') p.sort_stats('cumulative').print_stats(10)
Detailed documentation for profiling is available in the Python Library Reference under The Python Profiler.
Because Python versions 2.0 and later contain code to detect and break object reference cycles, you may not need to worry about cyclical references unless you are using Python 1.5.2.
A common problem in reference counted garbage-collected languages like Python is memory leakage due to cyclical object references. This occurs in cases where an object A has a reference to another object B that has a reference back to object A. The interpreter fails to discard memory held by these objects even if they become unused by the program because a non-zero reference count exists as a result of the cycle.
Cycles may be much longer than just two objects, for example
A -> B -> C -> D -> A would result in failure to discard objects
A through D.
In these cases, a long-running program will eventually run out of memory as more and more objects are left intact because of their participation in object reference cycles.
A Python module called Cyclops is available for monitoring your program as it runs, to determine when cyclical memory references are preventing the Python interpreter from discarding unused objects.
This module can be used to print information on existing cycles at any time, including at time of program exit.
The following function might be used to invoke a function called
and then output cycle information for modules and functions upon exit:
#------------------------------------ def RunWithCyclops(): """Run the main program under Cyclops. Require Cyclops.py found at http://www.python.org/ftp/python/contrib/System/Cyclops.py."""
from cyclops import Cyclops import types
def mod_refs(x): return x.__dict__.values()
def mod_tag(x, i): return "." + x.__dict__.keys()[i]
def func_refs(x): return x.func_globals, x.func_defaults
def func_tag(x, i): return (".func_globals", ".func_defaults")[i]
def instance_filter(cycle): for obj, index in cycle: if type(obj) is types.InstanceType: return 1 return 0
z = Cyclops.CycleFinder() z.chase_type(types.ModuleType, mod_refs, mod_tag) z.chase_type(types.FunctionType, func_refs, func_tag)
z.run(main) z.find_cycles() z.show_stats() z.show_cycles()
Once cycles are found, the most effective method for fixing the resulting
memory leaks is to introduce a
destroy function that manually
clears references that are causing a cycle (for example, by setting them to
None or by calling the
clear() method on Python dictionaries
If a cycle is broken at a single point in this way, all objects in the cycle will subsequently be freed. For this reason, busting cycles tends to be relatively easy.
For more information on using Cyclops, please refer to documentation within
the copy located in
Gdb can be used as a tool to aid in debugging C/C++ extension modules written for Python, although doing so can be a bit tricky and prone to problems. The following text contains hints to make this easier.
Note that this section assumes you are already familiar with gdb; for more information on gdb commands, please refer to the gdb documentation.
The first step in debugging C/C++ modules with gdb is to make
sure that you are using a version of Python
that was compiled with debug symbols. To do this, you need a source
distribution of Python and you need to configure the distribution as
described in the accompanying
In most cases, this can be done as follows: (1) Type
./configure, (2) type
or edit the Makefile so
OPT=-g, (3) type
make, and (4) once
the build is complete, install it with
make install (but see
the README first if you don't want to install into
If you are building an extension module that you are compiling into the Python interpreter, you can now just run Python within gdb, set a breakpoint at the desired location in your extension module, and execute your Python test program.
In most cases, however, the extension module is not compiled into
Python but is instead loaded dynamically at runtime. In order to get
your extension module to load, it must be on the
or within the same directory where the module is
Gdb additionally requires setting
LD_LIBRARY_PATH to include the
directory where the dynamically loaded module is located. A common
problem in doing this is that gdb will reread
.cshrc each time
that it runs, so setting
LD_LIBRARY_PATH before invoking gdb
has no effect if you also set
To work around this, set
instead. This file is read only once at login time.
Then start Python as follows:
myhost> gdb (gdb) file python (gdb) run yourprogram.py yourargs
Note that breakpoints in a shared library cannot be set until after
the shared library is loaded. If running your program triggers
loading of your extension module library, you can use
to interrupt the debug program, set breakpoints, and then continue.
Otherwise, you must continue running your program until the extension
module is loaded. When in doubt, add a
can be set after
file python and before running since this
call is not in a shared library).
Unfortunately, even if you take all of the above steps, gdb will often get confused if you load and unload shared libraries repeatedly during a single debug session. You can usually re-run Python 5-10 times but subsequently may see crashing, failure to stop at breakpoints, or other odd behaviors. When this occurs, there is no alternative but to exit and restart gdb.
Finally a hint for viewing Python data from the C/C++ side when using
gdb. The following gdb command will print out the contents of a
PyObject * called
obj as if you had issued the command
print obj from within the Python language:
(gdb) p PyObject_Print (obj, stderr, 0)
The source code for Wing IDE is available to all users that have a permanent (non-evaluation) license to Wing IDE Standard or higher product level. This section contains information that may be useful to those wanting to delve into the source code to make changes or add custom features.
Before getting started, you should download and install the source distributions, as described in section 1.9.
Once the source is installed, see the document
build-files/README.txt for build instructions.
If you have problems getting set up for source development, please
send email to
The source code, relative to the top level of the Wing IDE installation, is organized into three major groups of functionality, according to its origin and the distribution licenses that apply to the code:
srcdirectory. This is the proprietary code to which you have certain rights if you own a license, but which you may not redistribute.
opensourcecontains the portions of the IDE that were written at Archaeopteryx Software and have been released under an open source license.
externaldirectory contains additional open source items used within the IDE but written and maintained outside of Archaeopteryx Software Inc. Some of these contain substantial modifications that may not yet be included in the primary distributions of these tools.
Distributed among the above directories are the following major sub-systems of the IDE:
external.scintillato do most of its work.
external.scintillasource code editor module.
pygtk-0.6.5, which is a Python language wrapper for the
gtkGUI development library.
Throughout the source, Python documentation strings and comments are used to describe the code. As a result, most documentation is located within the code itself.
Each IDE module also has a
README file containing at least some
text identifying the module. This may also contain high level documentation
for the module's source, so it's a good place to start when inspecting the
The top-level docstring (at start of each Python file) contains a CVS logging area, which lists all recent revision comments for that file.
Three techniques are used to build names for language constructs in the Wing IDE source code: (1) leading underscores indicate the public, semi-private, and private nature of the construct, (2) prefix letters are used to indicate the type of some constructs, and (3) capitalization is used to indicate the type of some constructs. This naming style is used with all Python language constructs, including classes, functions, methods, variables, attributes, and in some cases module names.
The presence and number of underscores before construct names is used to indicate the scope of access intended for that construct.
CallMe()) are used for publically accessible classes, methods, functions, or attributes. These may be accessed from anywhere.
_DoSomething()) is used to indicate that a construct is semi-private, for access only from within the construct's scope and related scopes (such as in sub-classes, or other classes that are part of a logical sub-system).
__MyMethod()) indicates that a construct is private. For object attributes, Python will enforce local-only access of these values by making them invisible from subclasses or outside of the body of the class.
A prefix-based naming convention is also applied to some language constructs, as follows:
Capitalization of letters within construct names is also standardized:
XxxXxxxare used for classes, methods, instance attributes, functions, and constants.
xxx_xxxare used for parameters, locals, module names, and disk directories.
Underscoring, prefixing, and capitalization are combined as appropriate
for all constructs, to build names like
_CMyClass (a semi-private class),
kAValue (a public constant), and
__fCount (a private instance attribute).