Lenard Lindstrom avatar Lenard Lindstrom committed 2d7ce55

set svn file properties so svn branch and merge work as intended

Comments (0)

Files changed (86)

MakePrebuilt71.bat

-@echo off
-rem Make the prebuilt package from the libraries built with
-rem msys_build_deps.py. Takes one optional argument, the
-rem name of the output directory.
-rem
-rem This batch file needs python.exe, pexports.exe
-rem (found in altbinutils-pe at SourceForge,
-rem http://sourceforge.net/projects/mingwrep/) and
-rem Visual C's VCVARS32.BAT in the executables search path.
-rem Otherwise run make_prebuilt.py first, then the batch
-rem files MakeDefs.bat and MakeLibs.bat afterward.
-
-python.exe make_prebuilt.py %1
-if errorlevel 1 goto done
-if "%1"=="" goto useprebuilt
-copy /Y prebuilt-template\readme71.html "%1\readme.html"
-cd "%1"
-goto domake
-:useprebuilt
-copy /Y prebuilt-template\readme71.html prebuilt\readme.html
-cd prebuilt
-:domake
-cd lib
-CALL Make32.bat
-cd ..\..
-:done
-
-
+@echo off
+rem Make the prebuilt package from the libraries built with
+rem msys_build_deps.py. Takes one optional argument, the
+rem name of the output directory.
+rem
+rem This batch file needs python.exe, pexports.exe
+rem (found in altbinutils-pe at SourceForge,
+rem http://sourceforge.net/projects/mingwrep/) and
+rem Visual C's VCVARS32.BAT in the executables search path.
+rem Otherwise run make_prebuilt.py first, then the batch
+rem files MakeDefs.bat and MakeLibs.bat afterward.
+
+python.exe make_prebuilt.py %1
+if errorlevel 1 goto done
+if "%1"=="" goto useprebuilt
+copy /Y prebuilt-template\readme71.html "%1\readme.html"
+cd "%1"
+goto domake
+:useprebuilt
+copy /Y prebuilt-template\readme71.html prebuilt\readme.html
+cd prebuilt
+:domake
+cd lib
+CALL Make32.bat
+cd ..\..
+:done
+
+

MakePrebuilt90.bat

-@echo off
-rem Make the Win32 prebuilt file for Pythons 2.6 and up.
-rem Takes an optional argument, the prebuilt directory path.
-rem Requires Visual Studio, with VCVARS32.BAT is on the
-rem executable search path. Python must also be on the search
-rem path. msys_link_VC_2008_dlls.py requires pexports.exe 0.43.
-
-set DESTDIR=%1
-if "%DESTDIR%" == "" set DESTDIR=prebuilt
-
-python make_prebuilt.py %DESTDIR%
-if errorlevel 1 goto aborted
-
-copy /Y prebuilt-template\readme90.html "%DESTDIR%\readme.html"
-
-set DESTDIR=%DESTDIR%\lib
-deltree /Y %DESTDIR%\msvcr71
-python msys_link_VC_2008_dlls.py -d %DESTDIR% --all
-if errorlevel 1 goto aborted
-
-CALL VCVARS32.BAT
-cd %DESTDIR%
-CALL MakeLibs.bat
-if errorlevel 1 goto aborted
-
-echo '
-echo =====================================
-echo Prebuilt directory built successfully
-goto done
-
-:aborted
-echo '
-echo *** Error: failed to complete
-
-:done
+@echo off
+rem Make the Win32 prebuilt file for Pythons 2.6 and up.
+rem Takes an optional argument, the prebuilt directory path.
+rem Requires Visual Studio, with VCVARS32.BAT is on the
+rem executable search path. Python must also be on the search
+rem path. msys_link_VC_2008_dlls.py requires pexports.exe 0.43.
+
+set DESTDIR=%1
+if "%DESTDIR%" == "" set DESTDIR=prebuilt
+
+python make_prebuilt.py %DESTDIR%
+if errorlevel 1 goto aborted
+
+copy /Y prebuilt-template\readme90.html "%DESTDIR%\readme.html"
+
+set DESTDIR=%DESTDIR%\lib
+deltree /Y %DESTDIR%\msvcr71
+python msys_link_VC_2008_dlls.py -d %DESTDIR% --all
+if errorlevel 1 goto aborted
+
+CALL VCVARS32.BAT
+cd %DESTDIR%
+CALL MakeLibs.bat
+if errorlevel 1 goto aborted
+
+echo '
+echo =====================================
+echo Prebuilt directory built successfully
+goto done
+
+:aborted
+echo '
+echo *** Error: failed to complete
+
+:done
-# Program check_test.py
-# Requires Python 2.4
-
-"""A program for listing the modules accessed by a Pygame unit test module
-
-Usage:
-
-python check_test.py <test module>
-
-e.g.
-
-python check_test.py surface_test.py
-
-The returned list will show which Pygame modules were imported and accessed.
-Each module name is followed by a list of attributes accessed.
-
-"""
-
-import sys
-import os
-import trackmod
-trackmod.begin(pattern=['pygame', 'pygame.*'],
-               continuous=True,
-               submodule_accesses=False)
-skip = set(['pygame.locals', 'pygame.constants',
-            'pygame.base', 'pygame.threads'])
-
-os.chdir('test')
-test_file = sys.argv[1]
-del sys.argv[1]
-try:
-    execfile(test_file)
-finally:
-    trackmod.end()
-    print "=== Pygame package submodule accesses ==="
-    print
-    accesses = [(n, a) for n, a in trackmod.get_accesses().iteritems()
-                       if n not in skip]
-    accesses.sort(key=lambda t: t[0])
-    for name, attributes in accesses:
-        print "%s (%s)" % (name, ', '.join(attributes))
+# Program check_test.py
+# Requires Python 2.4
+
+"""A program for listing the modules accessed by a Pygame unit test module
+
+Usage:
+
+python check_test.py <test module>
+
+e.g.
+
+python check_test.py surface_test.py
+
+The returned list will show which Pygame modules were imported and accessed.
+Each module name is followed by a list of attributes accessed.
+
+"""
+
+import sys
+import os
+import trackmod
+trackmod.begin(pattern=['pygame', 'pygame.*'],
+               continuous=True,
+               submodule_accesses=False)
+skip = set(['pygame.locals', 'pygame.constants',
+            'pygame.base', 'pygame.threads'])
+
+os.chdir('test')
+test_file = sys.argv[1]
+del sys.argv[1]
+try:
+    execfile(test_file)
+finally:
+    trackmod.end()
+    print "=== Pygame package submodule accesses ==="
+    print
+    accesses = [(n, a) for n, a in trackmod.get_accesses().iteritems()
+                       if n not in skip]
+    accesses.sort(key=lambda t: t[0])
+    for name, attributes in accesses:
+        print "%s (%s)" % (name, ', '.join(attributes))
-"""Python 2.x/3.x compatibility tools"""
-
-import sys
-
-__all__ = ['geterror', 'long_', 'xrange_', 'ord_', 'unichr_',
-           'unicode_', 'raw_input_', 'as_bytes', 'as_unicode']
-
-def geterror ():
-    return sys.exc_info()[1]
-
-try:
-    long_ = long
-except NameError:
-    long_ = int
-
-try:
-    xrange_ = xrange
-except NameError:
-    xrange_ = range
-
-def get_BytesIO():
-    try:
-        from cStringIO import StringIO as BytesIO
-    except ImportError:
-        from io import BytesIO
-    return BytesIO
-
-def get_StringIO():
-    try:
-        from cStringIO import StringIO
-    except ImportError:
-        from io import StringIO
-    return StringIO
-
-def ord_(o):
-    try:
-        return ord(o)
-    except TypeError:
-        return o
-
-try:
-    unichr_ = unichr
-except NameError:
-    unichr_ = chr
-
-try:
-    unicode_ = unicode
-except NameError:
-    unicode_ = str
-
-try:
-    bytes_ = bytes
-except NameError:
-    bytes_ = str
-
-try:
-    raw_input_ = raw_input
-except NameError:
-    raw_input_ = input
-
-# Represent escaped bytes and strings in a portable way.
-#
-# as_bytes: Allow a Python 3.x string to represent a bytes object.
-#   e.g.: as_bytes("a\x01\b") == b"a\x01b" # Python 3.x
-#         as_bytes("a\x01\b") == "a\x01b"  # Python 2.x
-# as_unicode: Allow a Python "r" string to represent a unicode string.
-#   e.g.: as_unicode(r"Bo\u00F6tes") == u"Bo\u00F6tes" # Python 2.x
-#         as_unicode(r"Bo\u00F6tes") == "Bo\u00F6tes"  # Python 3.x
-try:
-    eval("u'a'")
-    def as_bytes(string):
-        """ '<binary literal>' => '<binary literal>' """
-        return string
-        
-    def as_unicode(rstring):
-        """ r'<Unicode literal>' => u'<Unicode literal>' """
-        return rstring.decode('unicode_escape', 'strict')
-except SyntaxError:
-    def as_bytes(string):
-        """ '<binary literal>' => b'<binary literal>' """
-        return string.encode('latin-1', 'strict')
-        
-    def as_unicode(rstring):
-        """ r'<Unicode literal>' => '<Unicode literal>' """
-        return rstring.encode('ascii', 'strict').decode('unicode_escape',
-                                                        'stict')
-
-
+"""Python 2.x/3.x compatibility tools"""
+
+import sys
+
+__all__ = ['geterror', 'long_', 'xrange_', 'ord_', 'unichr_',
+           'unicode_', 'raw_input_', 'as_bytes', 'as_unicode']
+
+def geterror ():
+    return sys.exc_info()[1]
+
+try:
+    long_ = long
+except NameError:
+    long_ = int
+
+try:
+    xrange_ = xrange
+except NameError:
+    xrange_ = range
+
+def get_BytesIO():
+    try:
+        from cStringIO import StringIO as BytesIO
+    except ImportError:
+        from io import BytesIO
+    return BytesIO
+
+def get_StringIO():
+    try:
+        from cStringIO import StringIO
+    except ImportError:
+        from io import StringIO
+    return StringIO
+
+def ord_(o):
+    try:
+        return ord(o)
+    except TypeError:
+        return o
+
+try:
+    unichr_ = unichr
+except NameError:
+    unichr_ = chr
+
+try:
+    unicode_ = unicode
+except NameError:
+    unicode_ = str
+
+try:
+    bytes_ = bytes
+except NameError:
+    bytes_ = str
+
+try:
+    raw_input_ = raw_input
+except NameError:
+    raw_input_ = input
+
+# Represent escaped bytes and strings in a portable way.
+#
+# as_bytes: Allow a Python 3.x string to represent a bytes object.
+#   e.g.: as_bytes("a\x01\b") == b"a\x01b" # Python 3.x
+#         as_bytes("a\x01\b") == "a\x01b"  # Python 2.x
+# as_unicode: Allow a Python "r" string to represent a unicode string.
+#   e.g.: as_unicode(r"Bo\u00F6tes") == u"Bo\u00F6tes" # Python 2.x
+#         as_unicode(r"Bo\u00F6tes") == "Bo\u00F6tes"  # Python 3.x
+try:
+    eval("u'a'")
+    def as_bytes(string):
+        """ '<binary literal>' => '<binary literal>' """
+        return string
+        
+    def as_unicode(rstring):
+        """ r'<Unicode literal>' => u'<Unicode literal>' """
+        return rstring.decode('unicode_escape', 'strict')
+except SyntaxError:
+    def as_bytes(string):
+        """ '<binary literal>' => b'<binary literal>' """
+        return string.encode('latin-1', 'strict')
+        
+    def as_unicode(rstring):
+        """ r'<Unicode literal>' => '<Unicode literal>' """
+        return rstring.encode('ascii', 'strict').decode('unicode_escape',
+                                                        'stict')
+
+
-pygame.examples
-module of example programs
-
-These examples should help get you started with pygame. Here is a
-brief rundown of what you get. The source code for these examples
-is in the public domain. Feel free to use for your own projects.
-
-There are several ways to run the examples. First they can be run
-as stand-alone programs. Second they can be imported and their
-main() methods called (see below). Finally, the easiest way is
-to use the python -m option:
-
-   python -m pygame.examples.&lt;example name&gt; &lt;example arguments&gt;
-
-eg:
-
-   python -m pygame.examples.scaletest someimage.png
-
-Resources for the examples are found in the pygame/examples/data
-subdirectory.
-
-We're always on the lookout for more examples and/or example
-requests. Code like this is probably the best way to start
-getting involved with python gaming.
-
-This page is adapted from the original examples readme.txt by:
-    Pete Shinners
-    shredwheat@mediaone.net
-
-Further references
-
-  pySDL    : <a href="http://pysdl.sourceforge.net">http://pysdl.sourceforge.net<a/>
-  SDL      : <a href="http://www.libsdl.org">http://www.libsdl.org<a/>
-  aliens.c : <a href="http://www.libsdl.org/projects/aliens">http://www.libsdl.org/projects/aliens<a/>
-
-examples as a package is new to pygame 1.9.0.
-<SECTION>
-
-
-
-aliens.main
-play the full aliens example
-pygame.aliens.main(): return None
-
-This started off as a port of the SDL demonstration,
-Aliens. Now it has evolved into something sort of resembling
-fun. This demonstrates a lot of different uses of sprites and
-optimized blitting. Also transparency, colorkeys, fonts, sound,
-music, joystick, and more. (PS, my high score is 117! goodluck)
-<END>
-
-
-
-oldalien.main
-play the original aliens example
-pygame.examples.oldalien.main(): return None
-
-This more closely resembles a port of the SDL Aliens
-demo. The code is a lot simpler, so it makes a better starting
-point for people looking at code for the first times. These
-blitting routines are not as optimized as they should/could be,
-but the code is easier to follow, and it plays quick enough.
-<END>
-
-
-
-stars.main
-run a simple starfield example
-pygame.examples.stars.main(): return None
-
-A simple starfield example. You can change the center of
-perspective by leftclicking the mouse on the screen.
-<END>
-
-
-
-chimp.main
-hit the moving chimp
-pygame.examples.chimp.main(): return None
-
-This simple example is derived from the line-by-line tutorial
-that comes with pygame. It is based on a 'popular' web banner.
-Note there are comments here, but for the full explanation,
-follow along in the tutorial.
-<END>
-
-
-
-
-moveit.main
-display animated objects on the screen
-pygame.examples.moveit.main(): return None
-
-This is the full and final example from the Pygame Tutorial,
-"How Do I Make It Move". It creates 10 objects and animates
-them on the screen.
-
-Note it's a bit scant on error checking, but it's easy to read. :]
-Fortunately, this is python, and we needn't wrestle with a pile of
-error codes.
-<END>
-
-
-
-
-fonty.main
-run a font rendering example
-pygame.examples.fonty.main(): return None
-
-Super quick, super simple application demonstrating
-the different ways to render fonts with the font module
-<END>
-
-
-
-vgrade.main
-display a vertical gradient
-pygame.examples.vgrade.main(): return None
-
-Demonstrates creating a vertical gradient with
-NumPy python. The app will create a new gradient every half
-second and report the time needed to create and display the
-image. If you're not prepared to start working with the
-NumPy arrays, don't worry about the source for this one :]
-<END>
-
-
-
-eventlist.main
-display pygame events
-pygame.examples.eventlist.main(): return None
-
-Eventlist is a sloppy style of pygame, but is a handy
-tool for learning about pygame events and input. At the
-top of the screen are the state of several device values,
-and a scrolling list of events are displayed on the bottom.
-
-This is not quality 'ui' code at all, but you can see how
-to implement very non-interactive status displays, or even
-a crude text output control.
-<END>
-
-
-
-
-arraydemo.main
-show various surfarray effects
-pygame.examples.arraydemo.main(arraytype=None): return None
-
-Another example filled with various surfarray
-effects. It requires the surfarray and image modules to
-be installed. This little demo can also make a good starting
-point for any of your own tests with surfarray
-
-If arraytype is provided then use that array package. Valid
-values are 'numeric' or 'numpy'. Otherwise default to NumPy,
-or fall back on Numeric if NumPy is not installed. As a program
-surfarray.py accepts an optional --numeric or --numpy flag. (New pygame 1.9.0)
-<END>
-
-
-
-sound.main
-load and play a sound
-pygame.examples.sound.main(file_path=None): return None
-
-Extremely basic testing of the mixer module. Load a
-sound and play it. All from the command shell, no graphics.
-
-If provided, use the audio file 'file_path', otherwise use a
-default file.
-
-sound.py optional command line argument: an audio file
-<END>
-
-
-
-sound_array_demos.main
-play various sndarray effects
-pygame.examples.sound_array_demos.main(arraytype=None): return None
-
-If arraytype is provided then use that array package. Valid
-values are 'numeric' or 'numpy'. Otherwise default to NumPy,
-or fall back on Numeric if NumPy is not installed.
-
-Uses sndarray and NumPy ( or Numeric) to create offset faded copies of the
-original sound. Currently it just uses hardcoded values for the
-number of echos and the delay. Easy for you to recreate as 
-needed. Run as a program sound_array_demos.py takes an optional
-command line option, --numpy or --numeric, specifying which array package
-to use.
-<END>
-
-
-
-liquid.main
-display an animated liquid effect
-pygame.examples.liquid.main(): return None
-
-This example was created in a quick comparison with the
-BlitzBasic gaming language. Nonetheless, it demonstrates a quick
-8-bit setup (with colormap).
-<END>
-
-
-
-glcube.main
-display an animated 3D cube using OpenGL
-pygame.examples.glcube.main(): return None
-
-Using PyOpenGL and pygame, this creates a spinning 3D
-multicolored cube.
-<END>
-
-
-
-scrap_clipboard.main
-access the clipboard
-pygame.examples.scrap_clipboard.main(): return None
-
-A simple demonstration example for the clipboard support.
-<END>
-
-
-
-
-mask.main
-display multiple images bounce off each other using collision detection
-pygame.examples.mask.main(*args): return None
-
-Positional arguments:
-    one or more image file names.
-
-This pygame.masks demo will display multiple moving sprites bouncing
-off each other. More than one sprite image can be provided.
-
-If run as a program then mask.py takes one or more image files
-as command line arguments.
-<END>
-
-
-
-
-testsprite.main
-show lots of sprites moving around
-pygame.examples.testsprite.main(update_rects = True, use_static = False, use_FastRenderGroup = False, screen_dims = [640, 480], use_alpha = False, flags = 0): return None
-
-Optional keyword arguments:
-    update_rects - use the RenderUpdate sprite group class
-    use_static - include non-moving images
-    use_FastRenderGroup - Use the FastRenderGroup sprite group
-    screen_dims - pygame window dimensions
-    use_alpha - use alpha blending
-    flags - additional display mode flags
-
-Like the testsprite.c that comes with sdl, this pygame version shows 
-lots of sprites moving around.
-
-If run as a stand-alone program then no command line arguments are taken.
-<END>
-
-
-
-
-headless_no_windows_needed.main
-write an image file that is smoothscaled copy of an input file
-pygame.examples.headless_no_windows_needed.main(fin, fout, w, h): return None
-
-arguments:
-    fin - name of an input image file
-    fout - name of the output file to create/overwrite
-    w, h - size of the rescaled image, as integer width and height
-
-How to use pygame with no windowing system, like on headless servers.
-
-Thumbnail generation with scaling is an example of what you can do with pygame.
-
-NOTE: the pygame scale function uses mmx/sse if available, and can be run 
-in multiple threads.
-
-If headless_no_windows_needed.py is run as a program it takes the following
-command line arguments:
-    -scale inputimage outputimage new_width new_height
-    eg. -scale in.png outpng 50 50
-<END>
-
-
-
-
-fastevents.main
-stress test the fastevents module
-pygame.examples.fastevents.main(): return None
-
-This is a stress test for the fastevents module.
-
-*Fast events does not appear faster!*
-
-So far it looks like normal pygame.event is faster by up to two times.
-So maybe fastevent isn't fast at all.
-
-Tested on windowsXP sp2 athlon, and freebsd.
-
-However... on my debian duron 850 machine fastevents is faster.
-<END>
-
-
-
-
-overlay.main
-play a .pgm video using overlays
-pygame.examples.overlay.main(fname): return None
-
-Play the .pgm video fila a path fname.
-
-If run as a program overlay.py takes the file name as a command line argument.
-<END>
-
-
-
-blend_fill.main
-demonstrate the various surface.fill method blend options
-pygame.examples.blend_fill.main(): return None
-
-A interactive demo that lets one choose which BLEND_xxx option to apply to a surface.
-<END>
-
-
-cursors.main
-display two different custom cursors
-pygame.examples.cursors.main(): return None
-
-Display an arrow or circle with crossbar cursor.
-<END>
-
-
-
-pixelarray.main
-display various pixelarray generated effects
-pygame.examples.pixelarray.main(): return None
-
-Display various pixelarray generated effects.
-<END>
-
-
-
-
-scaletest.main
-interactively scale an image using smoothscale
-pygame.examples.scaletest.main(imagefile, convert_alpha=False, run_speed_test=True): return None
-
-arguments:
-    imagefile - file name of source image (required)
-    convert_alpha - use convert_alpha() on the surf (default False)
-    run_speed_test - (default False)
-
-A smoothscale example that resized an image on the screen.
-Vertical and horizontal arrow keys are used to change the width and
-height of the displayed image. If the convert_alpha option is True
-then the source image is forced to have source alpha, whether or
-not the original images does. If run_speed_test is True then a
-background timing test is performed instead of the interactive scaler.
-
-If scaletest.py is run as a program then the command line options are:
-    ImageFile [-t] [-convert_alpha]
-    [-t] = Run Speed Test
-    [-convert_alpha] = Use convert_alpha() on the surf.
-<END>
-
-
-
-midi.main
-run a midi example
-pygame.examples.midi.main(mode='output', device_id=None): return None
-
-Arguments:
-    mode - if 'output' run a midi keyboard output example
-              'input' run a midi event logger input example
-              'list' list available midi devices
-           (default 'output')
-    device_id - midi device number; if None then use the default midi input or
-                output device for the system
-
-The output example shows how to translate mouse clicks or computer keyboard
-events into midi notes. It implements a rudimentary button widget and state
-machine.
-
-The input example shows how to translate midi input to pygame events.
-
-With the use of a virtual midi patch cord the output and input examples can
-be run as separate processes and connected so the keyboard output is displayed
-on a console.
-
-new to pygame 1.9.0
-<END>
-
-
-
-scroll.main
-run a Surface.scroll example that shows a magnified image
-pygame.examples.scroll.main(image_file=None): return None
-
-This example shows a scrollable image that has a zoom factor of eight.
-It uses the Surface.scroll function to shift the image on the display
-surface. A clip rectangle protects a margin area. If called as a function,
-the example accepts an optional image file path. If run as a program
-it takes an optional file path command line argument. If no file
-is provided a default image file is used.
-
-When running click on a black triangle to move one pixel in the direction
-the triangle points. Or use the arrow keys. Close the window or press ESC
-to quit.
-<END>
-
-
-
-movieplayer.main
-play an MPEG movie
-pygame.examples.moveplayer.main(filepath): return None
-
-A simple movie player that plays an MPEG movie in a Pygame window. It showcases
-the pygame.movie module. The window adjusts to the size of the movie image. It
-is given a boarder to demonstrate that a movie can play autonomously in a sub-
-window. Also, the file is copied to a file like object to show that not just
-Python files can be used as a movie source.
-
-The pygame.movie module is problematic and may not work on all systems. It is
-intended to replace it with an ffmpeg based version.
-<END>
-<END>
+pygame.examples
+module of example programs
+
+These examples should help get you started with pygame. Here is a
+brief rundown of what you get. The source code for these examples
+is in the public domain. Feel free to use for your own projects.
+
+There are several ways to run the examples. First they can be run
+as stand-alone programs. Second they can be imported and their
+main() methods called (see below). Finally, the easiest way is
+to use the python -m option:
+
+   python -m pygame.examples.&lt;example name&gt; &lt;example arguments&gt;
+
+eg:
+
+   python -m pygame.examples.scaletest someimage.png
+
+Resources for the examples are found in the pygame/examples/data
+subdirectory.
+
+We're always on the lookout for more examples and/or example
+requests. Code like this is probably the best way to start
+getting involved with python gaming.
+
+This page is adapted from the original examples readme.txt by:
+    Pete Shinners
+    shredwheat@mediaone.net
+
+Further references
+
+  pySDL    : <a href="http://pysdl.sourceforge.net">http://pysdl.sourceforge.net<a/>
+  SDL      : <a href="http://www.libsdl.org">http://www.libsdl.org<a/>
+  aliens.c : <a href="http://www.libsdl.org/projects/aliens">http://www.libsdl.org/projects/aliens<a/>
+
+examples as a package is new to pygame 1.9.0.
+<SECTION>
+
+
+
+aliens.main
+play the full aliens example
+pygame.aliens.main(): return None
+
+This started off as a port of the SDL demonstration,
+Aliens. Now it has evolved into something sort of resembling
+fun. This demonstrates a lot of different uses of sprites and
+optimized blitting. Also transparency, colorkeys, fonts, sound,
+music, joystick, and more. (PS, my high score is 117! goodluck)
+<END>
+
+
+
+oldalien.main
+play the original aliens example
+pygame.examples.oldalien.main(): return None
+
+This more closely resembles a port of the SDL Aliens
+demo. The code is a lot simpler, so it makes a better starting
+point for people looking at code for the first times. These
+blitting routines are not as optimized as they should/could be,
+but the code is easier to follow, and it plays quick enough.
+<END>
+
+
+
+stars.main
+run a simple starfield example
+pygame.examples.stars.main(): return None
+
+A simple starfield example. You can change the center of
+perspective by leftclicking the mouse on the screen.
+<END>
+
+
+
+chimp.main
+hit the moving chimp
+pygame.examples.chimp.main(): return None
+
+This simple example is derived from the line-by-line tutorial
+that comes with pygame. It is based on a 'popular' web banner.
+Note there are comments here, but for the full explanation,
+follow along in the tutorial.
+<END>
+
+
+
+
+moveit.main
+display animated objects on the screen
+pygame.examples.moveit.main(): return None
+
+This is the full and final example from the Pygame Tutorial,
+"How Do I Make It Move". It creates 10 objects and animates
+them on the screen.
+
+Note it's a bit scant on error checking, but it's easy to read. :]
+Fortunately, this is python, and we needn't wrestle with a pile of
+error codes.
+<END>
+
+
+
+
+fonty.main
+run a font rendering example
+pygame.examples.fonty.main(): return None
+
+Super quick, super simple application demonstrating
+the different ways to render fonts with the font module
+<END>
+
+
+
+vgrade.main
+display a vertical gradient
+pygame.examples.vgrade.main(): return None
+
+Demonstrates creating a vertical gradient with
+NumPy python. The app will create a new gradient every half
+second and report the time needed to create and display the
+image. If you're not prepared to start working with the
+NumPy arrays, don't worry about the source for this one :]
+<END>
+
+
+
+eventlist.main
+display pygame events
+pygame.examples.eventlist.main(): return None
+
+Eventlist is a sloppy style of pygame, but is a handy
+tool for learning about pygame events and input. At the
+top of the screen are the state of several device values,
+and a scrolling list of events are displayed on the bottom.
+
+This is not quality 'ui' code at all, but you can see how
+to implement very non-interactive status displays, or even
+a crude text output control.
+<END>
+
+
+
+
+arraydemo.main
+show various surfarray effects
+pygame.examples.arraydemo.main(arraytype=None): return None
+
+Another example filled with various surfarray
+effects. It requires the surfarray and image modules to
+be installed. This little demo can also make a good starting
+point for any of your own tests with surfarray
+
+If arraytype is provided then use that array package. Valid
+values are 'numeric' or 'numpy'. Otherwise default to NumPy,
+or fall back on Numeric if NumPy is not installed. As a program
+surfarray.py accepts an optional --numeric or --numpy flag. (New pygame 1.9.0)
+<END>
+
+
+
+sound.main
+load and play a sound
+pygame.examples.sound.main(file_path=None): return None
+
+Extremely basic testing of the mixer module. Load a
+sound and play it. All from the command shell, no graphics.
+
+If provided, use the audio file 'file_path', otherwise use a
+default file.
+
+sound.py optional command line argument: an audio file
+<END>
+
+
+
+sound_array_demos.main
+play various sndarray effects
+pygame.examples.sound_array_demos.main(arraytype=None): return None
+
+If arraytype is provided then use that array package. Valid
+values are 'numeric' or 'numpy'. Otherwise default to NumPy,
+or fall back on Numeric if NumPy is not installed.
+
+Uses sndarray and NumPy ( or Numeric) to create offset faded copies of the
+original sound. Currently it just uses hardcoded values for the
+number of echos and the delay. Easy for you to recreate as 
+needed. Run as a program sound_array_demos.py takes an optional
+command line option, --numpy or --numeric, specifying which array package
+to use.
+<END>
+
+
+
+liquid.main
+display an animated liquid effect
+pygame.examples.liquid.main(): return None
+
+This example was created in a quick comparison with the
+BlitzBasic gaming language. Nonetheless, it demonstrates a quick
+8-bit setup (with colormap).
+<END>
+
+
+
+glcube.main
+display an animated 3D cube using OpenGL
+pygame.examples.glcube.main(): return None
+
+Using PyOpenGL and pygame, this creates a spinning 3D
+multicolored cube.
+<END>
+
+
+
+scrap_clipboard.main
+access the clipboard
+pygame.examples.scrap_clipboard.main(): return None
+
+A simple demonstration example for the clipboard support.
+<END>
+
+
+
+
+mask.main
+display multiple images bounce off each other using collision detection
+pygame.examples.mask.main(*args): return None
+
+Positional arguments:
+    one or more image file names.
+
+This pygame.masks demo will display multiple moving sprites bouncing
+off each other. More than one sprite image can be provided.
+
+If run as a program then mask.py takes one or more image files
+as command line arguments.
+<END>
+
+
+
+
+testsprite.main
+show lots of sprites moving around
+pygame.examples.testsprite.main(update_rects = True, use_static = False, use_FastRenderGroup = False, screen_dims = [640, 480], use_alpha = False, flags = 0): return None
+
+Optional keyword arguments:
+    update_rects - use the RenderUpdate sprite group class
+    use_static - include non-moving images
+    use_FastRenderGroup - Use the FastRenderGroup sprite group
+    screen_dims - pygame window dimensions
+    use_alpha - use alpha blending
+    flags - additional display mode flags
+
+Like the testsprite.c that comes with sdl, this pygame version shows 
+lots of sprites moving around.
+
+If run as a stand-alone program then no command line arguments are taken.
+<END>
+
+
+
+
+headless_no_windows_needed.main
+write an image file that is smoothscaled copy of an input file
+pygame.examples.headless_no_windows_needed.main(fin, fout, w, h): return None
+
+arguments:
+    fin - name of an input image file
+    fout - name of the output file to create/overwrite
+    w, h - size of the rescaled image, as integer width and height
+
+How to use pygame with no windowing system, like on headless servers.
+
+Thumbnail generation with scaling is an example of what you can do with pygame.
+
+NOTE: the pygame scale function uses mmx/sse if available, and can be run 
+in multiple threads.
+
+If headless_no_windows_needed.py is run as a program it takes the following
+command line arguments:
+    -scale inputimage outputimage new_width new_height
+    eg. -scale in.png outpng 50 50
+<END>
+
+
+
+
+fastevents.main
+stress test the fastevents module
+pygame.examples.fastevents.main(): return None
+
+This is a stress test for the fastevents module.
+
+*Fast events does not appear faster!*
+
+So far it looks like normal pygame.event is faster by up to two times.
+So maybe fastevent isn't fast at all.
+
+Tested on windowsXP sp2 athlon, and freebsd.
+
+However... on my debian duron 850 machine fastevents is faster.
+<END>
+
+
+
+
+overlay.main
+play a .pgm video using overlays
+pygame.examples.overlay.main(fname): return None
+
+Play the .pgm video fila a path fname.
+
+If run as a program overlay.py takes the file name as a command line argument.
+<END>
+
+
+
+blend_fill.main
+demonstrate the various surface.fill method blend options
+pygame.examples.blend_fill.main(): return None
+
+A interactive demo that lets one choose which BLEND_xxx option to apply to a surface.
+<END>
+
+
+cursors.main
+display two different custom cursors
+pygame.examples.cursors.main(): return None
+
+Display an arrow or circle with crossbar cursor.
+<END>
+
+
+
+pixelarray.main
+display various pixelarray generated effects
+pygame.examples.pixelarray.main(): return None
+
+Display various pixelarray generated effects.
+<END>
+
+
+
+
+scaletest.main
+interactively scale an image using smoothscale
+pygame.examples.scaletest.main(imagefile, convert_alpha=False, run_speed_test=True): return None
+
+arguments:
+    imagefile - file name of source image (required)
+    convert_alpha - use convert_alpha() on the surf (default False)
+    run_speed_test - (default False)
+
+A smoothscale example that resized an image on the screen.
+Vertical and horizontal arrow keys are used to change the width and
+height of the displayed image. If the convert_alpha option is True
+then the source image is forced to have source alpha, whether or
+not the original images does. If run_speed_test is True then a
+background timing test is performed instead of the interactive scaler.
+
+If scaletest.py is run as a program then the command line options are:
+    ImageFile [-t] [-convert_alpha]
+    [-t] = Run Speed Test
+    [-convert_alpha] = Use convert_alpha() on the surf.
+<END>
+
+
+
+midi.main
+run a midi example
+pygame.examples.midi.main(mode='output', device_id=None): return None
+
+Arguments:
+    mode - if 'output' run a midi keyboard output example
+              'input' run a midi event logger input example
+              'list' list available midi devices
+           (default 'output')
+    device_id - midi device number; if None then use the default midi input or
+                output device for the system
+
+The output example shows how to translate mouse clicks or computer keyboard
+events into midi notes. It implements a rudimentary button widget and state
+machine.
+
+The input example shows how to translate midi input to pygame events.
+
+With the use of a virtual midi patch cord the output and input examples can
+be run as separate processes and connected so the keyboard output is displayed
+on a console.
+
+new to pygame 1.9.0
+<END>
+
+
+
+scroll.main
+run a Surface.scroll example that shows a magnified image
+pygame.examples.scroll.main(image_file=None): return None
+
+This example shows a scrollable image that has a zoom factor of eight.
+It uses the Surface.scroll function to shift the image on the display
+surface. A clip rectangle protects a margin area. If called as a function,
+the example accepts an optional image file path. If run as a program
+it takes an optional file path command line argument. If no file
+is provided a default image file is used.
+
+When running click on a black triangle to move one pixel in the direction
+the triangle points. Or use the arrow keys. Close the window or press ESC
+to quit.
+<END>
+
+
+
+movieplayer.main
+play an MPEG movie
+pygame.examples.moveplayer.main(filepath): return None
+
+A simple movie player that plays an MPEG movie in a Pygame window. It showcases
+the pygame.movie module. The window adjusts to the size of the movie image. It
+is given a boarder to demonstrate that a movie can play autonomously in a sub-
+window. Also, the file is copied to a file like object to show that not just
+Python files can be used as a movie source.
+
+The pygame.movie module is problematic and may not work on all systems. It is
+intended to replace it with an ffmpeg based version.
+<END>
+<END>
-"""pygame.midi
-pygame module for interacting with midi input and output.
-
-The midi module can send output to midi devices, and get input
-from midi devices.  It can also list midi devices on the system.
-
-Including real midi devices, and virtual ones.
-
-It uses the portmidi library.  Is portable to which ever platforms
-portmidi supports (currently windows, OSX, and linux).
-
-This uses pyportmidi for now, but may use its own bindings at some
-point in the future.  The pyportmidi bindings are included with pygame.
-
-New in pygame 1.9.0.
-"""
-
-
-#TODO:
-#    - finish writing tests.
-#        - likely as interactive tests... so you'd need to plug in a midi device.
-#    - create a background thread version for input threads.
-#        - that can automatically inject input into the event queue
-#          once the input object is running.  Like joysticks.
-
-
-
-
-import pygame
-import pygame.locals
-
-import atexit
-
-
-#
-MIDIIN = pygame.locals.USEREVENT + 10
-MIDIOUT = pygame.locals.USEREVENT + 11
-
-_init = False
-_pypm = None
-
-
-__all__ = [ "Input",
-            "MIDIIN",
-            "MIDIOUT",
-            "MidiException",
-            "Output",
-            "get_count",
-            "get_default_input_id",
-            "get_default_output_id",
-            "get_device_info",
-            "init",
-            "midis2events",
-            "quit",
-            "time",
-           ]
-
-__theclasses__ = ["Input", "Output"]
-
-
-def init():
-    """initialize the midi module
-    pygame.midi.init(): return None
-    
-    Call the initialisation function before using the midi module.
-    
-    It is safe to call this more than once.
-    """
-    global _init, _pypm
-    if not _init:
-        import pygame.pypm
-        _pypm = pygame.pypm
-
-        _pypm.Initialize()
-        _init = True
-        atexit.register(quit)
-
-
-def quit():
-    """uninitialize the midi module
-    pygame.midi.quit(): return None
-
-
-    Called automatically atexit if you don't call it.
-
-    It is safe to call this function more than once.
-    """
-    global _init, _pypm
-    if _init:
-        # TODO: find all Input and Output classes and close them first?
-        _pypm.Terminate()
-        _init = False
-        del _pypm
-        #del pygame._pypm
-
-def _check_init():
-    if not _init:
-        raise RuntimeError("pygame.midi not initialised.")
-
-def get_count():
-    """gets the number of devices.
-    pygame.midi.get_count(): return num_devices
-
-
-    Device ids range from 0 to get_count() -1
-    """
-    _check_init()
-    return _pypm.CountDevices()
-
-
-
-
-def get_default_input_id():
-    """gets default input device number
-    pygame.midi.get_default_input_id(): return default_id
-    
-    
-    Return the default device ID or -1 if there are no devices.
-    The result can be passed to the Input()/Ouput() class.
-    
-    On the PC, the user can specify a default device by
-    setting an environment variable. For example, to use device #1.
-    
-        set PM_RECOMMENDED_INPUT_DEVICE=1
-    
-    The user should first determine the available device ID by using
-    the supplied application "testin" or "testout".
-    
-    In general, the registry is a better place for this kind of info,
-    and with USB devices that can come and go, using integers is not
-    very reliable for device identification. Under Windows, if
-    PM_RECOMMENDED_OUTPUT_DEVICE (or PM_RECOMMENDED_INPUT_DEVICE) is
-    *NOT* found in the environment, then the default device is obtained
-    by looking for a string in the registry under:
-        HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Input_Device
-    and HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Output_Device
-    for a string. The number of the first device with a substring that
-    matches the string exactly is returned. For example, if the string
-    in the registry is "USB", and device 1 is named
-    "In USB MidiSport 1x1", then that will be the default
-    input because it contains the string "USB".
-    
-    In addition to the name, get_device_info() returns "interf", which
-    is the interface name. (The "interface" is the underlying software
-    system or API used by PortMidi to access devices. Examples are
-    MMSystem, DirectX (not implemented), ALSA, OSS (not implemented), etc.)
-    At present, the only Win32 interface is "MMSystem", the only Linux
-    interface is "ALSA", and the only Max OS X interface is "CoreMIDI".
-    To specify both the interface and the device name in the registry,
-    separate the two with a comma and a space, e.g.:
-        MMSystem, In USB MidiSport 1x1
-    In this case, the string before the comma must be a substring of
-    the "interf" string, and the string after the space must be a
-    substring of the "name" name string in order to match the device.
-    
-    Note: in the current release, the default is simply the first device
-    (the input or output device with the lowest PmDeviceID).
-    """
-    return _pypm.GetDefaultInputDeviceID()
-
-
-
-
-def get_default_output_id():
-    """gets default output device number
-    pygame.midi.get_default_output_id(): return default_id
-    
-    
-    Return the default device ID or -1 if there are no devices.
-    The result can be passed to the Input()/Ouput() class.
-    
-    On the PC, the user can specify a default device by
-    setting an environment variable. For example, to use device #1.
-    
-        set PM_RECOMMENDED_OUTPUT_DEVICE=1
-    
-    The user should first determine the available device ID by using
-    the supplied application "testin" or "testout".
-    
-    In general, the registry is a better place for this kind of info,
-    and with USB devices that can come and go, using integers is not
-    very reliable for device identification. Under Windows, if
-    PM_RECOMMENDED_OUTPUT_DEVICE (or PM_RECOMMENDED_INPUT_DEVICE) is
-    *NOT* found in the environment, then the default device is obtained
-    by looking for a string in the registry under:
-        HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Input_Device
-    and HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Output_Device
-    for a string. The number of the first device with a substring that
-    matches the string exactly is returned. For example, if the string
-    in the registry is "USB", and device 1 is named
-    "In USB MidiSport 1x1", then that will be the default
-    input because it contains the string "USB".
-    
-    In addition to the name, get_device_info() returns "interf", which
-    is the interface name. (The "interface" is the underlying software
-    system or API used by PortMidi to access devices. Examples are
-    MMSystem, DirectX (not implemented), ALSA, OSS (not implemented), etc.)
-    At present, the only Win32 interface is "MMSystem", the only Linux
-    interface is "ALSA", and the only Max OS X interface is "CoreMIDI".
-    To specify both the interface and the device name in the registry,
-    separate the two with a comma and a space, e.g.:
-        MMSystem, In USB MidiSport 1x1
-    In this case, the string before the comma must be a substring of
-    the "interf" string, and the string after the space must be a
-    substring of the "name" name string in order to match the device.
-    
-    Note: in the current release, the default is simply the first device
-    (the input or output device with the lowest PmDeviceID).
-    """
-    _check_init()
-    return _pypm.GetDefaultOutputDeviceID()
-
-
-def get_device_info(an_id):
-    """ returns information about a midi device
-    pygame.midi.get_device_info(an_id): return (interf, name, input, output, opened) 
-
-    interf - a text string describing the device interface, eg 'ALSA'.
-    name - a text string for the name of the device, eg 'Midi Through Port-0'
-    input - 0, or 1 if the device is an input device.
-    output - 0, or 1 if the device is an output device.
-    opened - 0, or 1 if the device is opened.
-
-    If the id is out of range, the function returns None.
-    """
-    _check_init()
-    return _pypm.GetDeviceInfo(an_id) 
-
-
-class Input(object):
-    """Input is used to get midi input from midi devices.
-    Input(device_id)
-    Input(device_id, buffer_size)
-
-    buffer_size -the number of input events to be buffered waiting to 
-      be read using Input.read() 
-    """
-
-    def __init__(self, device_id, buffer_size=4096):
-        """
-        The buffer_size specifies the number of input events to be buffered 
-        waiting to be read using Input.read().
-        """
-        _check_init()
- 
-        if device_id == -1:
-            raise MidiException("Device id is -1, not a valid output id.  -1 usually means there were no default Output devices.")
-            
-        try:
-            r = get_device_info(device_id)
-        except TypeError:
-            raise TypeError("an integer is required")
-        except OverflowError:
-            raise OverflowError("long int too large to convert to int")
-
-        # and now some nasty looking error checking, to provide nice error 
-        #   messages to the kind, lovely, midi using people of whereever.
-        if r:
-            interf, name, input, output, opened = r
-            if input:
-                try:
-                    self._input = _pypm.Input(device_id, buffer_size)
-                except TypeError:
-                    raise TypeError("an integer is required")
-                self.device_id = device_id
-
-            elif output:
-                raise MidiException("Device id given is not a valid input id, it is an output id.")
-            else:
-                raise MidiException("Device id given is not a valid input id.")
-        else:
-            raise MidiException("Device id invalid, out of range.")
-
-
-
-
-    def _check_open(self):
-        if self._input is None:
-            raise MidiException("midi not open.")
-
-
-
-    def close(self):
-        """ closes a midi stream, flushing any pending buffers.
-        Input.close(): return None
-
-        PortMidi attempts to close open streams when the application
-        exits -- this is particularly difficult under Windows.
-        """
-        _check_init()
-        if not (self._input is None):
-            self._input.Close()
-        self._input = None
-
-
-
-    def read(self, num_events):
-        """reads num_events midi events from the buffer.
-        Input.read(num_events): return midi_event_list
-
-        Reads from the Input buffer and gives back midi events.
-        [[[status,data1,data2,data3],timestamp],
-         [[status,data1,data2,data3],timestamp],...]
-        """
-        _check_init()
-        self._check_open()
-        return self._input.Read(num_events)
-
-
-    def poll(self):
-        """returns true if there's data, or false if not.
-        Input.poll(): return Bool
-
-        raises a MidiException on error.
-        """
-        _check_init()
-        self._check_open()
-
-        r = self._input.Poll()
-        if r == _pypm.TRUE:
-            return True
-        elif r == _pypm.FALSE:
-            return False
-        else:
-            err_text = GetErrorText(r)
-            raise MidiException( (r, err_text) )
-
-
-
-
-class Output(object):
-    """Output is used to send midi to an output device
-    Output(device_id)
-    Output(device_id, latency = 0)
-    Output(device_id, buffer_size = 4096)
-    Output(device_id, latency, buffer_size)
-
-    The buffer_size specifies the number of output events to be 
-    buffered waiting for output.  (In some cases -- see below -- 
-    PortMidi does not buffer output at all and merely passes data 
-    to a lower-level API, in which case buffersize is ignored.)
-
-    latency is the delay in milliseconds applied to timestamps to determine
-    when the output should actually occur. (If latency is < 0, 0 is 
-    assumed.)
-
-    If latency is zero, timestamps are ignored and all output is delivered
-    immediately. If latency is greater than zero, output is delayed until
-    the message timestamp plus the latency. (NOTE: time is measured 
-    relative to the time source indicated by time_proc. Timestamps are 
-    absolute, not relative delays or offsets.) In some cases, PortMidi 
-    can obtain better timing than your application by passing timestamps 
-    along to the device driver or hardware. Latency may also help you 
-    to synchronize midi data to audio data by matching midi latency to 
-    the audio buffer latency.
-
-    """
-
-    def __init__(self, device_id, latency = 0, buffer_size = 4096):
-        """Output(device_id)
-        Output(device_id, latency = 0)
-        Output(device_id, buffer_size = 4096)
-        Output(device_id, latency, buffer_size)
-
-        The buffer_size specifies the number of output events to be 
-        buffered waiting for output.  (In some cases -- see below -- 
-        PortMidi does not buffer output at all and merely passes data 
-        to a lower-level API, in which case buffersize is ignored.)
-
-        latency is the delay in milliseconds applied to timestamps to determine
-        when the output should actually occur. (If latency is < 0, 0 is 
-        assumed.)
-
-        If latency is zero, timestamps are ignored and all output is delivered
-        immediately. If latency is greater than zero, output is delayed until
-        the message timestamp plus the latency. (NOTE: time is measured 
-        relative to the time source indicated by time_proc. Timestamps are 
-        absolute, not relative delays or offsets.) In some cases, PortMidi 
-        can obtain better timing than your application by passing timestamps 
-        along to the device driver or hardware. Latency may also help you 
-        to synchronize midi data to audio data by matching midi latency to 
-        the audio buffer latency.
-        """
-     
-        _check_init()
-        self._aborted = 0
-
-        if device_id == -1:
-            raise MidiException("Device id is -1, not a valid output id.  -1 usually means there were no default Output devices.")
-            
-        try:
-            r = get_device_info(device_id)
-        except TypeError:
-            raise TypeError("an integer is required")
-        except OverflowError:
-            raise OverflowError("long int too large to convert to int")
-
-        # and now some nasty looking error checking, to provide nice error 
-        #   messages to the kind, lovely, midi using people of whereever.
-        if r:
-            interf, name, input, output, opened = r
-            if output:
-                try:
-                    self._output = _pypm.Output(device_id, latency)
-                except TypeError:
-                    raise TypeError("an integer is required")
-                self.device_id = device_id
-
-            elif input:
-                raise MidiException("Device id given is not a valid output id, it is an input id.")
-            else:
-                raise MidiException("Device id given is not a valid output id.")
-        else:
-            raise MidiException("Device id invalid, out of range.")
-
-    def _check_open(self):
-        if self._output is None:
-            raise MidiException("midi not open.")
-
-        if self._aborted:
-            raise MidiException("midi aborted.")
-
-
-    def close(self):
-        """ closes a midi stream, flushing any pending buffers.
-        Output.close(): return None
-
-        PortMidi attempts to close open streams when the application
-        exits -- this is particularly difficult under Windows.
-        """
-        _check_init()
-        if not (self._output is None):
-            self._output.Close()
-        self._output = None
-
-    def abort(self):
-        """terminates outgoing messages immediately
-        Output.abort(): return None
-
-        The caller should immediately close the output port;
-        this call may result in transmission of a partial midi message.
-        There is no abort for Midi input because the user can simply
-        ignore messages in the buffer and close an input device at
-        any time.
-        """
-
-        _check_init()
-        if self._output:
-            self._output.Abort()
-        self._aborted = 1
-
-
-
-
-
-    def write(self, data):
-        """writes a list of midi data to the Output
-        Output.write(data)
-
-        writes series of MIDI information in the form of a list:
-             write([[[status <,data1><,data2><,data3>],timestamp],
-                    [[status <,data1><,data2><,data3>],timestamp],...])
-        <data> fields are optional
-        example: choose program change 1 at time 20000 and
-        send note 65 with velocity 100 500 ms later.
-             write([[[0xc0,0,0],20000],[[0x90,60,100],20500]])
-        notes:
-          1. timestamps will be ignored if latency = 0.
-          2. To get a note to play immediately, send MIDI info with
-             timestamp read from function Time.
-          3. understanding optional data fields:
-               write([[[0xc0,0,0],20000]]) is equivalent to
-               write([[[0xc0],20000]])
-
-        Can send up to 1024 elements in your data list, otherwise an 
-         IndexError exception is raised.
-        """
-        _check_init()
-        self._check_open()
-
-        self._output.Write(data)
-
-
-    def write_short(self, status, data1 = 0, data2 = 0):
-        """write_short(status <, data1><, data2>)
-        Output.write_short(status)
-        Output.write_short(status, data1 = 0, data2 = 0)
-
-        output MIDI information of 3 bytes or less.
-        data fields are optional
-        status byte could be:
-             0xc0 = program change
-             0x90 = note on
-             etc.
-             data bytes are optional and assumed 0 if omitted
-        example: note 65 on with velocity 100
-             write_short(0x90,65,100)
-        """
-        _check_init()
-        self._check_open()
-        self._output.WriteShort(status, data1, data2)
-
-
-    def write_sys_ex(self, when, msg):
-        """writes a timestamped system-exclusive midi message.
-        Output.write_sys_ex(when, msg)
-
-        msg - can be a *list* or a *string*
-        when - a timestamp in miliseconds
-        example:
-          (assuming o is an onput MIDI stream)
-            o.write_sys_ex(0,'\\xF0\\x7D\\x10\\x11\\x12\\x13\\xF7')
-          is equivalent to
-            o.write_sys_ex(pygame.midi.time(),
-                           [0xF0,0x7D,0x10,0x11,0x12,0x13,0xF7])
-        """
-        _check_init()
-        self._check_open()
-        self._output.WriteSysEx(when, msg)
-
-
-    def note_on(self, note, velocity=None, channel = 0):
-        """turns a midi note on.  Note must be off.
-        Output.note_on(note, velocity=None, channel = 0)
-
-        Turn a note on in the output stream.  The note must already
-        be off for this to work correctly.
-        """
-        if velocity is None:
-            velocity = 0
-
-        if not (0 <= channel <= 15):
-            raise ValueError("Channel not between 0 and 15.")
-
-        self.write_short(0x90+channel, note, velocity)
-
-    def note_off(self, note, velocity=None, channel = 0):
-        """turns a midi note off.  Note must be on.
-        Output.note_off(note, velocity=None, channel = 0)
-
-        Turn a note off in the output stream.  The note must already
-        be on for this to work correctly.
-        """
-        if velocity is None:
-            velocity = 0
-
-        if not (0 <= channel <= 15):
-            raise ValueError("Channel not between 0 and 15.")
-
-        self.write_short(0x80 + channel, note, velocity)
-
-
-    def set_instrument(self, instrument_id, channel = 0):
-        """select an instrument, with a value between 0 and 127
-        Output.set_instrument(instrument_id, channel = 0)
-
-        """
-        if not (0 <= instrument_id <= 127):
-            raise ValueError("Undefined instrument id: %d" % instrument_id)
-
-        if not (0 <= channel <= 15):
-            raise ValueError("Channel not between 0 and 15.")
-
-        self.write_short(0xc0+channel, instrument_id)
-
-
-
-def time():
-    """returns the current time in ms of the PortMidi timer
-    pygame.midi.time(): return time
-
-    The time is reset to 0, when the module is inited.
-    """
-    return _pypm.Time()
-
-
-
-def midis2events(midis, device_id):
-    """converts midi events to pygame events
-    pygame.midi.midis2events(midis, device_id): return [Event, ...]
-
-    Takes a sequence of midi events and returns list of pygame events.
-    """
-    evs = []
-    for midi in midis:
-
-        ((status,data1,data2,data3),timestamp) = midi
-
-        e = pygame.event.Event(MIDIIN,
-                               status=status,
-                               data1=data1,
-                               data2=data2,
-                               data3=data3,
-                               timestamp=timestamp,
-                               vice_id = device_id)
-        evs.append( e )
-
-
-    return evs
-
-
-
-
-
-class MidiException(Exception):
-    """exception that pygame.midi functions and classes can raise
-    MidiException(errno)
-    """
-    def __init__(self, value):
-        self.parameter = value
-    def __str__(self):
-        return repr(self.parameter)
-
-
-
+"""pygame.midi
+pygame module for interacting with midi input and output.
+
+The midi module can send output to midi devices, and get input
+from midi devices.  It can also list midi devices on the system.
+
+Including real midi devices, and virtual ones.
+
+It uses the portmidi library.  Is portable to which ever platforms
+portmidi supports (currently windows, OSX, and linux).
+
+This uses pyportmidi for now, but may use its own bindings at some
+point in the future.  The pyportmidi bindings are included with pygame.
+
+New in pygame 1.9.0.
+"""
+
+
+#TODO:
+#    - finish writing tests.
+#        - likely as interactive tests... so you'd need to plug in a midi device.
+#    - create a background thread version for input threads.
+#        - that can automatically inject input into the event queue
+#          once the input object is running.  Like joysticks.
+
+
+
+
+import pygame
+import pygame.locals
+
+import atexit
+
+
+#
+MIDIIN = pygame.locals.USEREVENT + 10
+MIDIOUT = pygame.locals.USEREVENT + 11
+
+_init = False
+_pypm = None
+
+
+__all__ = [ "Input",
+            "MIDIIN",
+            "MIDIOUT",
+            "MidiException",
+            "Output",
+            "get_count",
+            "get_default_input_id",
+            "get_default_output_id",
+            "get_device_info",
+            "init",
+            "midis2events",
+            "quit",
+            "time",
+           ]
+
+__theclasses__ = ["Input", "Output"]
+
+
+def init():
+    """initialize the midi module
+    pygame.midi.init(): return None
+    
+    Call the initialisation function before using the midi module.
+    
+    It is safe to call this more than once.
+    """
+    global _init, _pypm
+    if not _init:
+        import pygame.pypm
+        _pypm = pygame.pypm
+
+        _pypm.Initialize()
+        _init = True
+        atexit.register(quit)
+
+
+def quit():
+    """uninitialize the midi module
+    pygame.midi.quit(): return None
+
+
+    Called automatically atexit if you don't call it.
+
+    It is safe to call this function more than once.
+    """
+    global _init, _pypm
+    if _init:
+        # TODO: find all Input and Output classes and close them first?
+        _pypm.Terminate()
+        _init = False
+        del _pypm
+        #del pygame._pypm
+
+def _check_init():
+    if not _init:
+        raise RuntimeError("pygame.midi not initialised.")
+
+def get_count():
+    """gets the number of devices.
+    pygame.midi.get_count(): return num_devices
+
+
+    Device ids range from 0 to get_count() -1
+    """
+    _check_init()
+    return _pypm.CountDevices()
+
+
+
+
+def get_default_input_id():
+    """gets default input device number
+    pygame.midi.get_default_input_id(): return default_id
+    
+    
+    Return the default device ID or -1 if there are no devices.
+    The result can be passed to the Input()/Ouput() class.
+    
+    On the PC, the user can specify a default device by
+    setting an environment variable. For example, to use device #1.
+    
+        set PM_RECOMMENDED_INPUT_DEVICE=1
+    
+    The user should first determine the available device ID by using
+    the supplied application "testin" or "testout".
+    
+    In general, the registry is a better place for this kind of info,
+    and with USB devices that can come and go, using integers is not
+    very reliable for device identification. Under Windows, if
+    PM_RECOMMENDED_OUTPUT_DEVICE (or PM_RECOMMENDED_INPUT_DEVICE) is
+    *NOT* found in the environment, then the default device is obtained
+    by looking for a string in the registry under:
+        HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Input_Device
+    and HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Output_Device
+    for a string. The number of the first device with a substring that
+    matches the string exactly is returned. For example, if the string
+    in the registry is "USB", and device 1 is named
+    "In USB MidiSport 1x1", then that will be the default
+    input because it contains the string "USB".
+    
+    In addition to the name, get_device_info() returns "interf", which
+    is the interface name. (The "interface" is the underlying software
+    system or API used by PortMidi to access devices. Examples are
+    MMSystem, DirectX (not implemented), ALSA, OSS (not implemented), etc.)
+    At present, the only Win32 interface is "MMSystem", the only Linux
+    interface is "ALSA", and the only Max OS X interface is "CoreMIDI".
+    To specify both the interface and the device name in the registry,
+    separate the two with a comma and a space, e.g.:
+        MMSystem, In USB MidiSport 1x1
+    In this case, the string before the comma must be a substring of
+    the "interf" string, and the string after the space must be a
+    substring of the "name" name string in order to match the device.
+    
+    Note: in the current release, the default is simply the first device
+    (the input or output device with the lowest PmDeviceID).
+    """
+    return _pypm.GetDefaultInputDeviceID()
+
+
+
+
+def get_default_output_id():
+    """gets default output device number
+    pygame.midi.get_default_output_id(): return default_id
+    
+    
+    Return the default device ID or -1 if there are no devices.
+    The result can be passed to the Input()/Ouput() class.
+    
+    On the PC, the user can specify a default device by
+    setting an environment variable. For example, to use device #1.
+    
+        set PM_RECOMMENDED_OUTPUT_DEVICE=1
+    
+    The user should first determine the available device ID by using
+    the supplied application "testin" or "testout".
+    
+    In general, the registry is a better place for this kind of info,
+    and with USB devices that can come and go, using integers is not
+    very reliable for device identification. Under Windows, if
+    PM_RECOMMENDED_OUTPUT_DEVICE (or PM_RECOMMENDED_INPUT_DEVICE) is
+    *NOT* found in the environment, then the default device is obtained
+    by looking for a string in the registry under:
+        HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Input_Device
+    and HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Output_Device
+    for a string. The number of the first device with a substring that
+    matches the string exactly is returned. For example, if the string
+    in the registry is "USB", and device 1 is named
+    "In USB MidiSport 1x1", then that will be the default
+    input because it contains the string "USB".
+    
+    In addition to the name, get_device_info() returns "interf", which
+    is the interface name. (The "interface" is the underlying software
+    system or API used by PortMidi to access devices. Examples are
+    MMSystem, DirectX (not implemented), ALSA, OSS (not implemented), etc.)
+    At present, the only Win32 interface is "MMSystem", the only Linux
+    interface is "ALSA", and the only Max OS X interface is "CoreMIDI".
+    To specify both the interface and the device name in the registry,
+    separate the two with a comma and a space, e.g.:
+        MMSystem, In USB MidiSport 1x1
+    In this case, the string before the comma must be a substring of
+    the "interf" string, and the string after the space must be a
+    substring of the "name" name string in order to match the device.
+    
+    Note: in the current release, the default is simply the first device
+    (the input or output device with the lowest PmDeviceID).
+    """
+    _check_init()
+    return _pypm.GetDefaultOutputDeviceID()
+
+
+def get_device_info(an_id):
+    """ returns information about a midi device
+    pygame.midi.get_device_info(an_id): return (interf, name, input, output, opened) 
+
+    interf - a text string describing the device interface, eg 'ALSA'.
+    name - a text string for the name of the device, eg 'Midi Through Port-0'
+    input - 0, or 1 if the device is an input device.
+    output - 0, or 1 if the device is an output device.
+    opened - 0, or 1 if the device is opened.
+
+    If the id is out of range, the function returns None.
+    """
+    _check_init()
+    return _pypm.GetDeviceInfo(an_id) 
+
+
+class Input(object):
+    """Input is used to get midi input from midi devices.
+    Input(device_id)
+    Input(device_id, buffer_size)
+
+    buffer_size -the number of input events to be buffered waiting to 
+      be read using Input.read() 
+    """
+
+    def __init__(self, device_id, buffer_size=4096):
+        """
+        The buffer_size specifies the number of input events to be buffered 
+        waiting to be read using Input.read().
+        """
+        _check_init()
+ 
+        if device_id == -1:
+            raise MidiException("Device id is -1, not a valid output id.  -1 usually means there were no default Output devices.")
+            
+        try:
+            r = get_device_info(device_id)
+        except TypeError:
+            raise TypeError("an integer is required")
+        except OverflowError:
+            raise OverflowError("long int too large to convert to int")
+
+        # and now some nasty looking error checking, to provide nice error 
+        #   messages to the kind, lovely, midi using people of whereever.
+        if r:
+            interf, name, input, output, opened = r
+            if input:
+                try:
+                    self._input = _pypm.Input(device_id, buffer_size)
+                except TypeError:
+                    raise TypeError("an integer is required")
+                self.device_id = device_id
+
+            elif output:
+                raise MidiException("Device id given is not a valid input id, it is an output id.")
+            else:
+                raise MidiException("Device id given is not a valid input id.")
+        else:
+            raise MidiException("Device id invalid, out of range.")
+
+
+
+
+    def _check_open(self):
+        if self._input is None:
+            raise MidiException("midi not open.")
+
+
+
+    def close(self):
+        """ closes a midi stream, flushing any pending buffers.
+        Input.close(): return None
+
+        PortMidi attempts to close open streams when the application
+        exits -- this is particularly difficult under Windows.
+        """
+        _check_init()
+        if not (self._input is None):
+            self._input.Close()
+        self._input = None
+
+
+
+    def read(self, num_events):
+        """reads num_events midi events from the buffer.
+        Input.read(num_events): return midi_event_list
+
+        Reads from the Input buffer and gives back midi events.
+        [[[status,data1,data2,data3],timestamp],
+         [[status,data1,data2,data3],timestamp],...]
+        """
+        _check_init()
+        self._check_open()
+        return self._input.Read(num_events)
+
+
+    def poll(self):
+        """returns true if there's data, or false if not.
+        Input.poll(): return Bool
+
+        raises a MidiException on error.
+        """
+        _check_init()
+        self._check_open()
+
+        r = self._input.Poll()
+        if r == _pypm.TRUE:
+            return True
+        elif r == _pypm.FALSE:
+            return False
+        else:
+            err_text = GetErrorText(r)
+            raise MidiException( (r, err_text) )
+
+
+
+
+class Output(object):
+    """Output is used to send midi to an output device
+    Output(device_id)
+    Output(device_id, latency = 0)
+    Output(device_id, buffer_size = 4096)
+    Output(device_id, latency, buffer_size)
+
+    The buffer_size specifies the number of output events to be 
+    buffered waiting for output.  (In some cases -- see below -- 
+    PortMidi does not buffer output at all and merely passes data 
+    to a lower-level API, in which case buffersize is ignored.)
+
+    latency is the delay in milliseconds applied to timestamps to determine
+    when the output should actually occur. (If latency is < 0, 0 is 
+    assumed.)
+
+    If latency is zero, timestamps are ignored and all output is delivered
+    immediately. If latency is greater than zero, output is delayed until
+    the message timestamp plus the latency. (NOTE: time is measured 
+    relative to the time source indicated by time_proc. Timestamps are 
+    absolute, not relative delays or offsets.) In some cases, PortMidi 
+    can obtain better timing than your application by passing timestamps 
+    along to the device driver or hardware. Latency may also help you 
+    to synchronize midi data to audio data by matching midi latency to 
+    the audio buffer latency.
+
+    """
+
+    def __init__(self, device_id, latency = 0, buffer_size = 4096):
+        """Output(device_id)
+        Output(device_id, latency = 0)
+        Output(device_id, buffer_size = 4096)
+        Output(device_id, latency, buffer_size)
+
+        The buffer_size specifies the number of output events to be 
+        buffered waiting for output.  (In some cases -- see below -- 
+        PortMidi does not buffer output at all and merely passes data 
+        to a lower-level API, in which case buffersize is ignored.)
+
+        latency is the delay in milliseconds applied to timestamps to determine
+        when the output should actually occur. (If latency is < 0, 0 is 
+        assumed.)
+
+        If latency is zero, timestamps are ignored and all output is delivered
+        immediately. If latency is greater than zero, output is delayed until
+        the message timestamp plus the latency. (NOTE: time is measured 
+        relative to the time source indicated by time_proc. Timestamps are 
+        absolute, not relative delays or offsets.) In some cases, PortMidi 
+        can obtain better timing than your application by passing timestamps 
+        along to the device driver or hardware. Latency may also help you 
+        to synchronize midi data to audio data by matching midi latency to 
+        the audio buffer latency.
+        """
+     
+        _check_init()
+        self._aborted = 0
+
+        if device_id == -1:
+            raise MidiException("Device id is -1, not a valid output id.  -1 usually means there were no default Output devices.")