kdev-python 1.4 stable released!

I'm happy to announce the release of the first stable version of kdev-python, version 1.4! As this is the first stable release, this post is supposed to be an overview about what kdev-python actually does.

KDevelop with kdev-python 1.4

First of all, kdev-python is a plugin for KDevelop. Its purpose is to make development of python applications more convenient. The main focus of the program is static analysis of source code, and providing features which use the information gathered, such as

• Semantic syntax highlighting (not the regex-stuff kate does, but real highlighting, showing your defined functions colorized etc.)
• Intelligent code completion, depending on where the cursor is and what variables exist etc.
• Navigation features, such as Jump to Declaration, searching for functions/classes, class browser, ...
• and many more

There's also a few features other than static code analysis, such as debugger integration, but the former is clearly the main focus of the project. kdev-python itself is written in C++.

Dependencies and language support

The 1.4 release is only meant to be used with python 2.7. It does not depend on python 2.7, but scripts containing syntax which is incompatible with python 2.7, such as stuff new in python 3.x, will be marked as containing syntax errors. You can work around some things with __future__ imports, tough. A python 3.x version of the plugin is currently being developed; it's almost done, and will soon be merged to the master branch. The next release (1.5) will support python 3.
kdev-python 1.4 is meant to be used with kdevplatform 1.4 (kdevelop 4.4), which is also where the version number comes from. Versions 1.3 or older or 1.5 or newer of kdevplatform are not compatible due to API changes.

Installation

Installing kdev-python 1.4 should be possible through your distribution's package management system soon-ish. The package will probably be called "kdev-python" or similar. The sources are available from here. Compilation instructions can be found in the tarball.
The checksums for the file are:

SHA-256 8743844c6bcf09b3f9db05891539973633049470eb7c046b75b3cfe4542da1e2  kdev-python-v1.4.1.tar.bz2
SHA-1 b887811d9a79eee3323cf3ad1be093c5801d31d6  kdev-python-v1.4.1.tar.bz2
MD5 8980b2cdb955f8f34f7560ffc940ef1b  kdev-python-v1.4.1.tar.bz2

After installing, make sure to add the installation directory to your $KDEDIRS environment variable, and run kbuildsycoca if necessary. You may want to add those two commands to /etc/profile to have them executed at login automatically.

Using kdev-python

To use kdev-python, just start up KDevelop and open any python file. You can verify that kdev-python is working by looking at Help » Loaded plugins:

kdev-python in the plugins list

If you want to open a whole python project, just click Project » Open/Import project, and select your project's root folder.
As soon as you do so, the background parser will start analyzing your code. You can observe its progress by looking at the right bottom corner of the KDevelop main window:

Background parser progress bar

Depending on how large your project is and on how many external libraries it imports, this may take up to several minutes the first time you open a particular project (on my computer it takes roughly 15 minutes per million lines of code). The computed information is stored to a persistent cache, so subsequent startups will be much faster. You can already start coding while the background parser is still analyzing your project, but the information being displayed might not be complete yet.
The following sections will give an introduction on how to use the most common features of kdev-python.

Code completion

kdev-python does context-sensitive code completion; there will be different suggestions depending on where in the program your cursor is located. It will open up automatically when the program thinks it would be useful, or you can force it to show by pressing Ctrl+Space (by default). Here's a few examples of what it does:

Even in complex cases, there often is useful completion suggestions

Slices are interpreted correctly

If a function which was just completed takes no arguments, the cursor is placed behind the brackets...

... and if it takes arguments, it's placed inside the brackets.

Full completion (Ctrl+Space) shows types of objects next to their names.

Generator expressions are supported by this handy little feature.

There's also completion for importing objects from libraries

An example of context-sensitive completion: for inheritance, only classes are listed in the completion list.

The "implement function" completion feature

For the "raise" statement, only names that will give a valid exception object are suggtested.

Another example of a not-so-simple case where completion still works.

When invoking full completion inside the brackets of a function, you are presented with a list of arguments the function takes

The most basic case: All matching objects from the local and global scope are suggtested.

Obviously, all this is based on the static language analysis framework. Thus, in obscure cases (such as when using exec), it will not be able to do anything useful. In quite a lot of cases it turns out to be very nice, tough.

Note that it is very difficult to get proper support for python libraries written in C. Currently, only a few select ones are supported. The support for PyQt4 / PyKDE4 is very good, as can be seen from the above screenshots; there's also some very basic support for numpy and a few others. Help is very welcome here, it's quite easy to get your favourite library supported (I think it can well be done in one afternoon without prior knowledge, and you can do it in just python probably).

Navigation widget

The navigation widget is another feature of KDevelop which allows you to navigate code easily. To show the navigation widget, move your mouse over any highlighted use:

The navigation widget.

Another example of the navigation widget. While the widget is shown, all uses of the selected object are highlighted with a different background color

You can navigate inside the widget; all the blue things are clickable. You can for example click the "Material" in the first screenshot to look at the navigation widget for that class. You can also click the place of the object's declaration to jump there, or make KDevelop find all uses of an object.

The navigation widget currently does not work for import statements, that needs to be implemented in future releases.

QuickOpen

Another very useful feature of KDevelop (which is not really specific to kdev-python) is QuickOpen. It allows you to instantly jump to any class or method declaration in your whole project. Just click into the filter bar at the top which says "QuickOpen" (or use the shortcut shown in the menu), and type parts of a function or class name, then press Enter:

The Quickopen feature

"Outline" does the same, but only in the current file.

Output marks & debugging

In Run » Configure launches, you can select "Script Application" for a launch in the left toolview. Then, enter "python" for the interpreter, and provide a full path to your application in the "Script" line edit (note that this dialog has already been totally refactored, it's much nicer in kdevelop master. The changes have not yet been released tough). If you now run your application and it encounters an error, you can use F4 and Shift+F4 to jump to the next or previous line in a backtrace:

Press F4 or click on an output mark to jump to that position in the respective file.

KDevelop will automatically open that file and jump to the correct place.

There is also (somewhat basic) support for the python debugger, pdb; just click the "debug" button after configuring your script as described in the previous paragraph:

pdb plugin in action

The navigation widget is replaced with the debugger widget, which displays the current value of the object your mouse is moved over. The left toolbar displays all current variables; you can exapand the trees to see properties of objects. You can also enter some arbitrary python expression in the line edit in the bottom left and press enter; it will be evaluated on every debugger step and will be displayed there, too. The right toolview shows a stack trace. Note that since this is based on a thin wrapper around pdb, threads are not supported (since they're not supported in pdb either). There is some special code to support debugging of Qt applications with event loops correctly.

Future plans 

There's two big things which need to be done next: Proper support for Python 3, and proper support for frequently used libraries. Support for Python 3 is being worked on, and some ideas for e.g. better django support are also there. So, you can be excited about what will happen in future releases! ;)

Final words

So, that's about it -- as every application's first release, kdev-python 1.4 is totally bug-free; it will never crash or display something which is incorrect! If it still does, you probably found a hidden feature; you can report it to bugs.kde.org in the kdev-python product, so I can add it to the official feature list. :)

If you'd like to help this project, there's lots of things to be done! Just write me an email, or visit us in #kdevelop on irc.freenode.net.