Python is a very flexible, interpreted language that much of QuArK is written in. QuArK (versions 6.4 and higher) includes a Python compiler, so all you have to do to change to the python code is edit a *.py file in a text editor, save it, and run QuArK: compilation of changed .py files into .pyc files is automatic.

If you want to develop in Python however, you will probably want the full distribution from www.python.org, since this includes documentation including a tutorial, command-line listener for testing out what functions do, etc.

There are introductions to Python available at various levels:

• The tutorial etc. that comes with Python: Quite usable if you're a reasonably experienced (intermediate?) programmer.
• Programming Python (OReilly): All the info is there, but the presentation is not for beginners.
• Learning Python (OReilly): Looks like a good introduction for newbie programmers.
• Learn Python in 24 Hours (SAMS): This one looks like it could be used by absolute newbie programmers, since it seems to introduce basic programming concepts from scratch. HINT HINT: if some reader of this is an absolute newbie programmer, their reactions to this book would be useful information.

Since Python is interpreted, its class system is far more flexible than C++ or Delphi, and you can do stuff that you can't even dream of in these languages (some of which is very useful for GUI-building). The downside of being interpreted is that it's relatively slow.

So things that need to be fast are coded in Delphi, and made available to be called as functions in the Python. These are both functions and procedures called as part of the module quarkx, and also attributes and methods of map objects such as faces, poly's etc. that are defined in the Delphi code, but need to be accessed from the Python code as well.

All of the Delphi-defined stuff is all documented in 'QuarkX' which is a fine reference manual. The Delphi-defined stuff integrates very smoothly into Python, and looks native. So if you can't find a method-name in the Python code, check the Delphi, starting with the quarkx module.

Although your first Python project will probably be a plugin, you'll need to use not only quarkx, but also perhaps some of the facilities in the module quarkpy, where many basic facilities are also defined. Unfortunately the contents of quarkpy aren't very well cataloged. Info about this, such as it is, is in 'QuarkPy'.

QuarkX functions & None: If you write something like:

    if quarkx.function():
      blah
      blah

expecting blah blah to not execute when function() returns None as a value, you'll probably get a bizarre run-time error. Instead write:

    if quarkx.function() is not None:
      blah
      blah

This is because most of the Python objects implemented in Delphi do not explicitely support 'truth' evaluation. Armin thought the Python core would detect it but it seems it just tries to do the evaluation anyway, thus calling a Nil function. Everything in Python can be true or false, including the Delphi-defined objects -- at least the Python core expects it so, and the Delphi code doesn't do it right :-( So always explicitely compare with None.

Vector equality: Don't try to compare QuarkX vectors with equality, rather test their difference for being zero. Armin discusses this in the 'QuarkX' document.

Tuples & assigment: Python has a concept of `tuple', which is a sequence of numbers whose members can't be changed (they're `immutable'). 1-element tuples are written with a comma after them, which leads to wierd looking things like:

  mytuple = mynumber,

  mynumber, = mytuple

This latter is an example of `tuple assignment', if the right hand side of an assignemt is a tuple, then on the left hand side you can put a tuple-expression, and the appropriate assignments will get made to its variables.

These commas are a bit unusual and easy to miss at first, and since many of the most useful specifics in dialog boxes are of tuple-type, missing them can lead to a lot of frustration.

Tabs & whitespace: One of Python's distinctive features is `whitespace structuring', whereby all members of the same block have to be indented the same distance, and sub-blocks are indented more. This saves hunting around for matching curlies, but can lead to at least one kind of serious screwup, involving tabs: if Python's idea of what a tab is different from your editors, you can screw up functioning code just by saving it. I have my text editor set to convert all tabs to 4 spaces.