MakingSampleApps - wxPyWiki

Making Sample Apps

Often when people have problems with figuring out how to do something, or to make things work the way they expect, they will ask about it on the mail list, or places like StackOverflow. The most common response to their initial question is something like, "Please create a small runnable app that shows the problem and send that to the list." This is a very useful tool for those giving help because:

They can run, tweak, and play with the sample, drawing on their own experiences with debugging wxPython apps.
There is nothing vague and confusing about code. If somebody just tries to explain what they tried to do in prose without sample code, it is very likely that there will be a break-down in communication somewhere, especially if the helper and the helpee speak different languages natively.
Having a runnable sample to play with makes much better use of the helper's time. Often a problem can be spotted in a minute or two, and a solution tested and sent back to the list in five. Without a sample the helper needs to first duplicate the problem (which may or may not be successful if the initial description is vague) and then find a solution. This can multiply the time spent on the problem 100% or more.
Most of the time, if the person needing help makes the effort to make a runnable sample he will figure out how to solve the problem himself before even sending it to the list, and will have learned something valuable in the process.
There is even an industry acronym for making small samples like this when requesting help. See SSCCE.org.

How to make a sample

Just to be clear, the sample app you send to the list should not be a copy of the app you are having trouble with. Nobody wants to read through all the rest of the code of your app just to figure out one little problem with one widget 15 clicks away from the startup. It should also usually not be a copy of your app with lots of stuff ripped out. To have a chance of solving the problem yourself it is best to figure out how to make the mistake again, so you can then figure out what not to do. So here are some suggested steps about how to make a sample app to send to the list.

Start from scratch with just a frame, a panel and the control(s) that you are having trouble with, and put it all in one module.
Initialize the control with some typical values like what your app uses.
If it's applicable to the problem hook up some event handlers that are the same or similar to what your app uses, if any of them need app-specific data or functionality then just stub it out with static or generated bogus data/functionality.
Keep work needed for the previous steps as simple as possible. Do just enough work to show the problem. For even a novice programmer with basic wx familiarity these steps should take 15 minutes or less.
Run your sample. If it misbehaves in the same way as your app then you can usually assume that it is a wxPython problem, or maybe that you are just using wxPython in the wrong way. Send your sample and questions about it to the wxPython-users list. If the sample doesn't misbehave then it is almost certainly a problem in your app and you can progressively add things to the sample until you duplicate the problem and then that can help you to figure out how to fix it in your app.
When you send your sample app and questions to the wxPython-users list be sure to mention the version of wxPython you are using, and also the platform(s) you are using when the problem manifests itself.
Unless you are absolutely sure that all the lines in your sample code are short enough to not be word-wrapped by mail software then DO NOT paste your code into the main body of your email message. Send your code as an attachment instead. Note that you can not make attachments when using the Google Groups Web interface to read and respond to messages, you will need to send an email message from your subscribed mail address instead. Update: Google has a new beta UI for the Groups application. If you switch to the new UI you will be able to attach files to messages posted via their browser interface.

Read the last item above once more. Repeat until it is burned into your memory!

Other helpful hints

wxPython version: Since many of the typical helpers have multiple versions of wxPython installed on their systems, they will want to make sure that the version they test with is the same one that you reported the problem about. I've found it helpful to add the following line into the code just after the wx module is imported. If you do it for us before you send your sample then that will be another bit of time that you can save for the helper.
```
 print wx.version() 
```
Widget Inspection Tool: Another thing that I almost always add into the samples that are sent to the list are statements for loading and activating the Widget Inspection Tool, especially if the problem has to do with layout issues. It gives a simple hierarchical overview of the widgets and sizers in the application, a way to view common properties of the widgets, sizers and sizer items, and also a PyCrust shell for interacting with selected widgets in an interactive Python interpreter. If you also make use of this tool it may help you to solve problems yourself before you give up and send the sample to the mail list. To activate and use the tool simply add these lines into the sample just before MainLoop is called:
```
 import wx.lib.inspection
 wx.lib.inspection.InspectionTool().Show() 
```

Comments

Franz Steinhaeusler 01/30/07

I'm very glad you created this page. It was also my opinion for a long time now, that people should always create a small as possible sample to show the difficulties with the code. And It saves time for everybody interested in it and we have a common base to discuss, trying out and find a possible solution.