Python Plugin Design:

This plugin consists of two parts: the parser, which is intended to create an
abstract syntax tree (AST) from a string of python code, and the DUChain Library,
which analyzes this AST semantically, extracting information about contexts, variable /
class / function declarations, and other stuff.

The parser
----------
... is not written by us. We're querying the python C API to extract an AST from a given
string of python code. For information about the parser API, see 
http://docs.python.org/c-api/veryhigh.html?highlight=pyparser_#PyParser_SimpleParseString
(for example). As this AST is based on PyObjects, relies on a large amount of macros for data
access, and is not based on classes, but on structs, we transform it to a more convenient form.
This is done in parser/astbuilder.cpp by the PythonAstTransformer class. It walks through a python
tree, and generates the corresponding plugin-tree objects (those which end with Ast, like StatementAst etc.).
This transformer is not written by hand, but is generated by the conversionGenerator.py script. This script
reads information on how the AST should be transformed from the parser/python26.sdef file.
It should be obvious from the large amount of examples what those rules look like.
This class returns a CodeAst, which is then passed back to the parse job, which then calls
the DUChain classes to analyze the tree. If an error occurs, parsing is aborted and the error is
reported to the user.
As the standard python AST library obfuscates some ranges (like, in foo.bar.baz, all of foo, bar and baz are
said to start at column 0, while we need to know bar starts at 4 and baz at 8), we had no choice than to fork
the python parser and make those changes ourselves. The python source code can be found in the python-src
directory. The patches which were applied to the parser are in the patches/ subdirectory in git patch format; 
those can be used if we want to switch the python version one day (from python 2.7 to 3.x, for example).

The DUChain Library
-------------------
This library builds a Definition-Use-Chain from the AST, which is then used to
support code completion, syntax highlighting and other language features in
KDevelop. The design of the DUChain is described at:
http://api.kde.org/4.x-api/kdevplatform-apidocs/language/html/duchain-design.html

The following language elements create a new Context:
- a class definition
- a function definition
- a compound statement, that includes for, while, if, with statements <- this has been removed,
as those do not really create a new context in the python language (i.e. variable declarations
inside such "contexts" still exist outside, unlike C++)

