Skip to main content

Hacking — wiki

Notes for hacking, developing, and modifying pygame.

Building pygame

See the wiki page: Compilation to figure out how to compile pygame on different platforms.

Keeping up with developments.

Try and discuss changes on the mailing list. Especially if you plan to do a big change, it might be a good idea to coordinate with people. See info, for details on joining the mailing list.

Most developers are not on irc all of the time - and some never.  So if you need a more realtime chat try and organise a time on the mailing list.  Email lets people communicate in their own time zones.

Commit logs are important to keep them short, and also to summarize the changes you have made.

Buildbots, pygame compiled on every change

There is a pygame github page. Development now happens on github.

The set up more buildbots issue tracked developments in the buildbots.

Linux manylinux builds

Manylinux builds are binary files for pip which should work on many versions of linux. See in the pygame repo manylinux-build/README.rst

Generating docs

python makeref.py

The makeref.py program runs Sphinx to generate HTML docs and src/docs/{module}_doc.h C headers from reStructuredText source.

The reStructuredText .rst files are stored in the reST/source and reST/source/ref directories.

An online reStructuredText primer can be found at the Python site.

Sphinx specific markup is described in theSphinx Documentation.

The Python Sphinx package itself depends on Docutils, Jinja2, and Pygments.

For Python 2.x, installing Sphinx will also grab and install its dependencies.

Sphinx can be downloaded from PyPi or using easy-install.

For Python 3.x only the latest repository versions work.

Be sure to install Sphinx last so it does not grab the wrong dependency versions:

pip install sphinx

Running tests

To run the tests from the test sub-directory in the pygame distribution:

python run_tests.py

To run the tests from the pygame.tests module:

python -m pygame.tests

In either case the --help command line option will give usage instructions.

Code style

Try and follow the code style of the particular file you are editing.

Use 4 spaces instead of tabs, and Pep-8 generally.  Make sure your editor doesn't insert tabs.

Try to keep things under 80 characters wide.

Try not to mix in white space commits with other code commits.  This makes reading diffs easier if you separate the whitespace updates from the actual changes.

Writing tests.

Tests are in the test/ directory.

Please see test/README.txt (in the pygame repo) for more of a description on the tests, and the testing framework.

A naming convention is used for all tests. So from the name of a module, class, method, or function, you can find the tests for it.

Each module has a test file.  eg. for pygame.surface there is test/surface_test.py

In that file there are methods for each of the classes, functions and methods. So Surface.blit has a 'test_blit' method.  There can be multiple test methods for each method. eg. 'test_blit_keyword_args' in surface_test.py one of a few tests Surface.blit.  Add extra words at the end of the method name to make multiple tests for the same method.

Methods named with todo at the front "todo_blit" are methods that need to be written. Or finished. By default all of the todo tests are skipped by the test runner.  You can however, make the todo_ tests fail - to see how many more tests need to be finished.

Tests can use tags in order to organise them. There are optionally [modulename]_tags.py files for each module. A test/surface_tags.py file is used to specify tags for the pygame.surface module. You can use tags to skip tests on different platforms, or to choose different tests to exclude or run.

There are some test related tools + code in test/util/ .

To see if anything in a module is not documented... you can use: python compare_docs.py pygame.sprite sprite.doc

To generate some test stubs for your unittests from an existing file... you can do: python gen_stubs.py midi

Submitting changes to github

See http://www.contribution-guide.org/. If you are a member of the pygame repo on github you can start a new branch like this:
git clone git@github.com:pygame/pygame.git
cd pygame
git checkout -b my-fixes-branch
# Edit your changes here.
git commit .
git push --set-upstream origin my-fixes-branch
Then go to the web https://github.com/pygame/pygame to create a pull request. Add a couple of reviewers who you think might want to review the code. If you are not part of the github pygame organization, then fork pygame with github, and then when you're ready, send us a pull request.