Notes for hacking, developing, and modifying pygame.

Building pygame¶

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

python setup.py build --debug install

python setup.py build -j4 install

Buildbots, pygame compiled on every change¶

How to do debug builds?How to speed up compilation? The build only compiles things that have changed by default. Parallel builds can be done with python 3.5+, where you can set the -j option with the number of workers you want to use. Probably setting it to the same as your number of CPU cores is a good idea.

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¶

Generating docs¶

python setup . py docs

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

This runs buildconfig/makeref.py which runs Sphinx to generate HTML docs and src_c/docs/{module}_doc.h C headers from reStructuredText source.

The reStructuredText .rst files are stored in the pygame/docs/reST/ref/ (reference manual) and docs/reST/tut/(tutorials) directories.

An online reStructuredText primer can be found on the Python website site.

Sphinx specific markup is described in theSphinx Documentation.

Parameters for functions should be documented with param info field lists.

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

pip install sphinx -- user

Running tests¶

You need a recent sphinx to build the pygame docs (1.7 at time of writing).

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

python test / __main__ . py - v

To run the tests from the installed pygame.tests module:

python - m pygame . tests - v

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

An important option is -v. This lets you see more details of the tests as they run.

C API docs¶

Code style¶

The C API docs can be found at https://www.pygame.org/docs/c_api.html . The source code for these docs in RestructuredText format is in docs/reST/c_api.rst and docs/reST/c_api/.

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.

For C code, we use clang-format. There is a config in src_c/.clang-format which tries to use a pep-7 style.

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¶

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

Issue triage¶

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: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.

There's a lot of issues, and people often only care about the issue for a short time. It can be helpful to categorize issues to save time for other developers, and to try and move an issue along.

Here are some general guidelines:

Thank the person for submitting the issue. They didn't have to, and it took them some time.

Close if it doesn't happen with SDL2.

Ask 1.9.6 issues to test with 2.

Tell people we need a test. Tell them in which file.

Tell people we don't have time, if we are not likely to fix it soon.

Tell people if a PR would be accepted. Tell them which files they may need to edit.

Tell people to use stackoverflow/etc for issues with their own code. Then close these issues. Maybe link to some documentation on it if there is some.

Labeling the module/OS/version they are on. If it's an issue with image loading label it 'image'. If it's on windows, label it 'windows', if it's an SDL2 issue label it SDL2.

Adding tasks to the top of the issue including, 'add a unit test', 'add reproducable code' are helpful to see how far along the issue is to being fixed.

So, you've come up with some excellent bug fixes, tests or improvements to pygame and you are wondering how to go from there to getting your code merged into the pygame mainline. Here are some top tips: