Project Title: PySoy: Improve testing, documentation and examples

Organization: Python Software Foundation


Pysoy currently lacks proper testing coverage, which harms the development of the engine and makes it easier to reintroduce past bugs while developing. Furthermore, the recent merger of the experimental branch has left some of the documentation out-dated and most of the example programs non-functional. This proposal is a project to write a set of unit tests and doctests, write new example programs based on the old ones to showcase Pysoy's capabilities and to overall fix minor bugs, clean up the codebase and improve documentation.

Further details:


Main bulk of the project is updating and writing new unit tests, doctests and docstrings in pysoy and fixing any small bugs that I will encounter along the way. Furthermore, I'm planning to work on getting example programs to working again as many of them are currently broken and need to be rewritten. At the end of the project, I hope to have developer-friendly documentation ready, good test coverage and demonstratable example programs for pysoy.

Testing will done with the Python doctest and unittest modules. Doctests double as a documentation for interactive Python examples and as simple tests for them. More exhaustive or complex testing is done with the unittest module. There are already few tests written, but most of them failing and need fixing. I am going to fix any small or trivial bugs that I encounter while writing the tests, but I may sidestep more complex issues if the code is not mature enough to even start testing.

There are many example programs in pysoy/examples/, but the most of them were written for the old pysoy code which is now obsolete. I'm going to rewrite the examplesto work with the new libsoy. Since the codebase has changed much, rewriting the examples is not completely straightforward. Some of the features of the old pysoy/libsoy code have not yet been implemented in the current libsoy. Because of that, rewriting the examples that depend on unimplemented features have less priority than the others. Also, if time allows, I wish to write a benchmarking tests for measuring performance (fps, memory usage, ...).

Finally, I'm planning to generate developer-friendly documentation with Sphinx documentation generator. There's already a previous (out-dated?) attempt at this from back 2008. Sphinx documentation generation should be fairly trivial job once the docstrings are written.


These are initial goals. These will be updated through the summer as needed. Progress of the project will be reported regularly at my blog

Start of Program

At the start of the program I will get to know my mentor and co-peers. I am already fairly familiar with the codebase, as I worked for Pysoy in last year's GSOC, and Python's unittest and doctest modules. I must familiarize myself better with Sphinx for documentation generation. Probably good place to start improving testing is from fixing the already existing unit tests in pysoy/tests.

Midterm Evaluation

By the midterm, I hope to have written doctests and unit tests for about 50-70% of the codebase. I also plan to have at least 5-10 or so example programs to demonstrate by this time (there is currently only 1 working example program).

Final Evaluation

By the end of the program, I hope to have readied complete or near-complete test coverage, full developer-friendly Sphinx generated documentation and as many demonstratable example programs as possible.


Things left to do (in order of importance):

  1. Attempt to fix rendering issues with soy.bodies(.Box) -- Fixed partially. Can't get it to fix comletely.
  2. Attempt to get soy.controllers working again, needed for examples. -- libsoy side mostly done. Not sure how to write callbacks/events in pysoy side.
  3. Add documentation to soy.bodies and more examples programs for testing -- done
  4. Add documentation to soy.widgets and more examples programs for testing
  5. Add documentation to soy.scenes and more examples programs for testing
  6. Generate readable documentation with Sphinx or some other tool.
  7. Attempt (again) to fix rare memory corruption issues with soy.atoms.
  8. Write bindings for fields and examples.
  9. Write tests for collisions, probably needs work for bindings too. (not sure how to do testing for this)

Overall, there are fairly many unittest written now, but not many doctests which are helpful documentation as well.

About Me

I am an 23 year old student from the Helsinki, Finland. I'm in University of Helsinki studying computer science. I worked for PySoy in GSOC 2011. I will be able to work on the project full-time through the summer without any major breaks.

Contact Info

Name: Juhani Åhman


Email: juhanipm@…

XMPP: juhanipm@…

IRC fzzbt@freenet/ircnet