Document REPL and warn if unavailable

* Add documentation on the REPL
* Add documentation on installing, and installing the REPL
* Print a warning if the REPL is not installed
* Add a repr for Actor

doc/index.rst

@@ -41,6 +41,7 @@ User Guide
     :maxdepth: 2
 
     installation
+    repl
     ide-mode
     other-libs
     changelog

doc/installation.rst

@@ -1,20 +1,89 @@
 Installing Pygame Zero
 ======================
 
-On desktop systems
-~~~~~~~~~~~~~~~~~~
+Included with Mu
+----------------
+
+The `Mu IDE <https://codewith.mu>`_, which is aimed at beginners, includes a
+version of Pygame Zero.
+
+You will need to `switch mode <https://codewith.mu/en/tutorials/1.0/modes>`_
+into Pygame Zero mode to use it. Then type in a program and
+`use the Play button <https://codewith.mu/en/tutorials/1.0/pgzero>`_ to run it
+with Pygame Zero.
+
+.. note::
+
+    The version of Mu included with Pygame Zero may not be the latest version!
+    You can find which version is installed by running this code in Mu::
+
+        import pgzero
+        print(pgzero.__version__)
+
+
+Stand-alone installation
+------------------------
+
+First of all, you need **Python 3** installed! This is usually installed
+already if you are using **Linux** or a **Raspberry Pi**. You can download it
+from `python.org <https://www.python.org/>` on other systems.
+
+
+Windows
+'''''''
+
+To install Pygame Zero, use **pip**. At a `command prompt`__, type
+
+.. __: https://www.lifewire.com/how-to-open-command-prompt-2618089
 
 ::
 
     pip install pgzero
 
-This will also install Pygame. Pre-compiled Pygame packages are available to pip
-for Windows & Linux (32-bit and 64-bit), and for Mac OS (64-bit only). If you
-have a different system, you'll need to find a way to install pygame first. Make
-sure you are using Python 3 not Python 2.
 
-On Raspberry Pi
-~~~~~~~~~~~~~~~
+Mac
+'''
+
+In a Terminal window, type
+
+::
+
+   pip install pgzero
+
+
+Linux
+'''''
+
+In a terminal window, type
+
+::
+
+   sudo pip install pgzero
+
+
+Some Linux systems call it ``pip3``; if the above command printed something
+like ``sudo: pip: command not found`` then try::
+
+    sudo pip3 install pgzero
+
+Sometimes pip is not installed and needs to be installed. If so try this before
+running the above commands again::
+
+
+    sudo python3 -m ensurepip
+
+
+.. _install-repl:
+
+Installing the REPL
+-------------------
+
+:doc:`Pygame Zero's REPL <repl>` is an optional feature. This can be enabled
+when installing with ``pip`` by adding ``pgzero[repl]`` to the pip command
+line::
+
+    pip install pgzero[repl]
+
+If you aren't sure if you have the REPL installed, you can still run this
+command (it won't break anything if it is installed!).
 
-pgzero has been installed by default since the release of Raspbian Jessie in
-September 2015!

doc/repl.rst

@@ -0,0 +1,54 @@
+Using the REPL (Read-Evaluate-Print Loop)
+=========================================
+
+The REPL allows you to interact with a running Pygame Zero game using Python
+commands. As you type it will offer suggestions based on variables that exist
+in your program. This can be useful for debugging your game or tuning how difficult it is.
+
+.. image:: _static/repl.png
+
+REPL is short for a Read-Evaluate-Print Loop; it means:
+
+1. **Read** a line of code typed by you
+2. **Evaluate** the code
+3. **Print** the result
+4. **Loop** back to step 1!
+
+This is an *optional feature* that may need to :ref:`be installed
+<install-repl>` if it was not originally installed with Pygame Zero. If you try
+using the REPL, Pygame Zero will let you know if it is not installed.
+
+
+Running a Pygame Zero program with the REPL
+-------------------------------------------
+
+If you normally run your Pygame Zero program using the terminal, add ``--repl``
+to the command line when running ``pgzrun``. For example, if your game is in
+a file called ``mygame.py``, run::
+
+    pgzrun --repl mygame.py
+
+
+Using the REPL
+--------------
+
+Python code that you type at the REPL is evaluated as if you had typed it into
+your game file.
+
+For example, if your game file contains the code ::
+
+    alien = Actor('alien', pos=(54, 60))
+
+    def draw():
+        screen.clear()
+        alien.draw()
+
+
+Then at the REPL you could type ``alien`` to see the alien object::
+
+    >>> alien
+    <Actor 'alien' pos=(54, 60)>
+
+You can set attributes on the ``alien`` object and see it move::
+
+    >>> alien.x = 90

pgzero/actor.py

@@ -105,6 +105,13 @@ def __setattr__(self, attr, value):
     def __iter__(self):
         return iter(self._rect)
 
+    def __repr__(self):
+        return '<{} {!r} pos={!r}>'.format(
+            type(self).__name__,
+            self._image_name,
+            self.pos
+        )
+
     def _handle_unexpected_kwargs(self, kwargs):
         unexpected_kwargs = set(kwargs.keys()) - self.EXPECTED_INIT_KWARGS
         if not unexpected_kwargs:

pgzero/runner.py

@@ -6,14 +6,18 @@
 import os
 import sys
 import warnings
-from optparse import OptionParser
+import argparse
 from types import ModuleType
 
 from .game import PGZeroGame, DISPLAY_FLAGS
 from . import loaders
 from . import builtins
 
 
+# The base URL for Pygame Zero documentation
+DOCS_URL = 'http://pygame-zero.readthedocs.io/en/stable'
+
+
 def _check_python_ok_for_pygame():
     """If we're on a Mac, is this a full Framework python?
 
@@ -57,26 +61,43 @@ def _substitute_full_framework_python():
     os.execv(framework_python, ['python', '-m', 'pgzero'] + sys.argv[1:])
 
 
-def main():
 
+def main():
     # Pygame won't run from a normal virtualenv copy of Python on a Mac
     if not _check_python_ok_for_pygame():
         _substitute_full_framework_python()
 
-    parser = OptionParser()
-    parser.add_option(
+    parser = argparse.ArgumentParser()
+    try:
+        import ptpython
+    except ImportError:
+        replhelp = argparse.SUPPRESS
+        have_repl = False
+    else:
+        replhelp = "Show a REPL for interacting with the game while it is running."
+        have_repl = True
+    parser.add_argument(
         '--repl',
         action='store_true',
-        help="Show a REPL for interacting with the game while it is running."
+        help=replhelp
     )
-    options, args = parser.parse_args()
-
-    if len(args) != 1:
-        parser.error("You must specify which module to run.")
+    parser.add_argument(
+        'script',
+        help='The name of the Pygame Zero game to run'
+    )
+    args = parser.parse_args()
+    if args.repl and not have_repl:
+        sys.exit(
+            "Error: Pygame Zero was not installed with REPL support.\n"
+            "\n"
+            "Please read\n"
+            "{}/installation.html#install-repl\n"
+            "for instructions on how to install this feature.".format(DOCS_URL)
+        )
 
     if __debug__:
         warnings.simplefilter('default', DeprecationWarning)
-    path = args[0]
+    path = args.script
 
     with open(path) as f:
         src = f.read()
@@ -95,7 +116,7 @@ def main():
 
     prepare_mod(mod)
     exec(code, mod.__dict__)
-    run_mod(mod, repl=options.repl)
+    run_mod(mod, repl=args.repl)
 
 
 def prepare_mod(mod):

setup.py

@@ -36,12 +36,16 @@
     },
     install_requires=install_requires,
     extras_require=extras_require,
-    python_requires='>3',
+    python_requires='>=3.4',
     classifiers=[
         'Development Status :: 5 - Production/Stable',
         'Intended Audience :: Education',
         'License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)',
         'Programming Language :: Python :: 3 :: Only',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7',
         'Topic :: Education',
         'Topic :: Games/Entertainment',
     ],