Commits

Lenard Lindstrom committed edac9c6

some doc updates for test tags and python -m option

Comments (0)

Files changed (5)

docs/ref/examples.html

   <tr><td><a href="examples.html#pygame.examples.movieplayer.main">pygame.examples.movieplayer.main</a> - <font size=-1>play an MPEG movie</font></td><td>play an MPEG movie</td></tr>
 </table></small></ul>
 <p>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. </p>
-<p>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 prefered way is with the <tt>pygame.examples.go</tt> module: </p>
-<p>python -c "import <tt>pygame.examples.go"</tt> <example name> <example arguments> </p>
-<p>To list available examples: </p>
-<p>python -c "import <tt>pygame.examples.go"</tt> --list </p>
-<p>Resources for the examples are found in the pygame/examples/data subdirectory. </p>
+<p>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: </p>
+<pre>   python -m pygame.examples.&lt;example name&gt; &lt;example arguments&gt;
+</pre><p>eg: </p>
+<pre>   python -m pygame.examples.scaletest someimage.png
+</pre><p>Resources for the examples are found in the pygame/examples/data subdirectory. </p>
 <p>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. </p>
 <p>This page is adapted from the original examples <tt>readme.txt</tt> by: </p>
 <pre>    Pete Shinners
 <ul><small><table>
   <tr><td><a href="tests.html#pygame.tests.run">pygame.tests.run</a> - <font size=-1>Run the Pygame unit test suite</font></td><td>Run the Pygame unit test suite</td></tr>
 </table></small></ul>
-<p><tt>A</tt> quick way to run the test suite package from the command line is by importing the go submodule: </p>
-<p>python -c "import <tt>pygame.tests.go"</tt> [&lt;test options&gt;] </p>
-<p>Command line option --help displays a usage message. Available options correspond to the <tt>pygame.tests.run</tt> arguments. </p>
+<p><tt>A</tt> quick way to run the test suite package from the command line is to import the go submodule with the Python -m option: </p>
+<pre>  python -m pygame.tests.go [&lt;test options&gt;]
+</pre><p>Command line option --help displays a usage message. Available options correspond to the <tt>pygame.tests.run</tt> arguments. </p>
 <p>The xxxx_test submodules of the tests package are unit test suites for individual parts of Pygame. Each can also be run as a main program. This is useful if the test, such as cdrom_test, is interactive. </p>
 <p>For Pygame development the test suite can be run from a Pygame distribution root directory. Program <tt>run_tests.py</tt> is provided for convenience, though <tt>test/go.py</tt> can be run directly. </p>
+<p>Module level tags control which modules are included in a unit test run. Tags are assigned to a unit test module with a corresponding <tt>&lt;name&gt;_tags.py</tt> module. The tags module has the global __tags__, a list of tag names. For example, <tt>cdrom_test.py</tt> has a tag file <tt>cdrom_tags.py</tt> containing a tags list that has the 'interactive' string. The 'interactive' tag indicates <tt>cdrom_test.py</tt> expects user input. It is excluded from a <tt>run_tests.py</tt> or <tt>pygame.tests.go</tt> run. Two other tags that are excluded are 'ignore' and 'subprocess_ignore'. These two tags indicate unit tests that will not run on a particular platform, or for which no corresponding Pygame module is available. The test runner will list each excluded module along with the tag responsible. </p>
 <!--COMMENTS:pygame.tests--> &nbsp;<br> 
 
 

examples/go.py

-"""Load and run a Pygame example program
-
-python -c "import pygame.examples.go" <example name> [<example args>]
-
-Commend line option --list displays a list or example programs.
-
-python -c "import pygame.examples.go" --list
-
-"""
-
-import sys
-import os
-
-
-examples_dir = os.path.dirname(__file__)
-if __name__ != '__main__' and (len(sys.argv) == 1 or sys.argv[0] != '-c'):
-    print ("usage:\n%s" % __doc__)
-elif sys.argv[1] == '--list':
-    import glob
-    for filename in glob.glob(os.path.join(examples_dir, '*.py')):
-        name = os.path.splitext(os.path.basename(filename))[0]
-        if name not in ('go', '__init__'):
-            print (name)
-else:
-    program_name = sys.argv[1]
-    if not program_name.lower().endswith('.py'):
-        program_name += '.py'
-    del sys.argv[1]
-    _go__name__ = __name__
-    __name__ = '__main__'
-    try:
-        exec (open(os.path.join(examples_dir, program_name)).read())
-    finally:
-        __name__ = _go__name__
-
-
 
 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 prefered way is
-with the pygame.examples.go module:
+main() methods called (see below). Finally, the easiest way is
+to use the python -m option:
 
-python -c "import pygame.examples.go" <example name> <example arguments>
+   python -m pygame.examples.&lt;example name&gt; &lt;example arguments&gt;
 
-To list available examples:
+eg:
 
-python -c "import pygame.examples.go" --list
+   python -m pygame.examples.scaletest someimage.png
 
 Resources for the examples are found in the pygame/examples/data
 subdirectory.
 Pygame unit test suite package
 
 A quick way to run the test suite package from the command line
-is by importing the go submodule:
+is to import the go submodule with the Python -m option:
 
-python -c "import pygame.tests.go" [&lt;test options&gt;]
+  python -m pygame.tests.go [&lt;test options&gt;]
 
 Command line option --help displays a usage message. Available options
 correspond to the pygame.tests.run arguments.
 For Pygame development the test suite can be run from a Pygame 
 distribution root directory. Program run_tests.py is provided for convenience,
 though test/go.py can be run directly.
+
+Module level tags control which modules are included in a unit test run.
+Tags are assigned to a unit test module with a corresponding &lt;name&gt;_tags.py
+module. The tags module has the global __tags__, a list of tag names. For
+example, cdrom_test.py has a tag file cdrom_tags.py containing a tags list
+that has the 'interactive' string. The 'interactive' tag indicates
+cdrom_test.py expects user input. It is excluded from a run_tests.py or
+pygame.tests.go run. Two other tags that are excluded are 'ignore' and
+'subprocess_ignore'. These two tags indicate unit tests that will not run
+on a particular platform, or for which no corresponding Pygame module is
+available. The test runner will list each excluded module along with the
+tag responsible.
 <SECTION>