Although Python source code usually has excellent readability, it is still possible to write code that's difficult to read. It's also nice to if all code in a project follows the same standards and looks similar. For this reason I've decided to put together this page of wxPython Coding Guidelines and I'm going to ask that anybody that contributes library code or patches follows these guidelines as much as possible. For a general purpose style guide to assist with programming with wxPython, please see the wxPython Style Guide in the wiki.

These guidelines will be very similar to the general Style Guide for Python Code, but there are a few differences. If something is not explicitly stated here then fall back to the Python style guide. As stated there, consistency to this guide is important, but more important is to know when to be inconsistent. Use your best judgment in all things, but don't do it your own way just because you think my way stinks! ;-)

Compatibility

I release wxPython binaries for both Python 2.6 and Python 2.7. This means that any contributions to wxPython also need to be at least Python 2.6 compatible.

Whitespace

In my opinion liberal use of whitespace can greatly aid the readability of Python code. Here are my recommendations and what I usually try to do:

Boolean Constants

Now that Python is getting a real boolean type and boolean constants, True and False should be used instead of true, false, TRUE, FALSE (although aliases for these do exist for the old namespace.) In the wx module there is some code that tests for the existence of the new constants, and creates them if they don't exist in the version of Python that is being used, and places them in __builtins__.

Naming Conventions

Comments and Docstrings

Include Demo Module

All modules contributed to wxPython should have a module that can be dropped into the wxPython Demo framework. It is a very simple thing to do, just make a copy of demo/template.py and name it the same as the class to be demoed, (or some other appropriate name.) Then just add code to the TestPanel class that shows your contributed module and you're done. To test, edit Main.py and add the name of the new demo module to the _treeList list.

Don't forget to set the yourDemoModule.overview string! If the overview text starts with "<html>" then it will be shown in the wxHtmlWindow as is. If not then the demo will treat it as plain text and will preprocess it for showing in the wxHtmlWindow.

The overview should be some descriptive text that gives basic information about the classes being demoed, their capabilites, limitations, etc. If appropriate you could also give info about the API of the contributed classes. In some cases you could just set overview to wx.lib.yourContrib.__doc__.

Making Patches

For any updates to wxPython code, including updates to your contribution once I have accepted it and checked it in to the SVN repository, you'll need to use patch files to send updates to me. This way I can easily merge your changes with any that I have made. I will no longer accept full source code replacements for updates.

The easiest way to do a patch against the latest version of the code is to use SVN. You simply need to have a current copy of the workspace checked out to your local system and then use the svn diff command to make the patch file. You may also want to review this page.

License

You will need to license your contributed code with the wxWidgets License, which is essentially the LGPL with a few extensions that make the code just a little bit more Free. To set the license that your source code uses it is sufficient to just put something like "License: wxWidgets" in the header. By the way, the wxWidgets Library License is now certified by the Open Source Initiative.