| 1 | =============== |
| 2 | The Py Manual |
| 3 | =============== |
| 4 | |
| 5 | ------------------------- |
| 6 | Py - Served Fresh Daily |
| 7 | ------------------------- |
| 8 | |
| 9 | :Author: Patrick K. O'Brien |
| 10 | :Contact: pobrien@orbtech.com |
| 11 | :Organization: Orbtech_ |
| 12 | :Date: $Date$ |
| 13 | :Revision: $Revision$ |
| 14 | |
| 15 | .. _Orbtech: http://www.orbtech.com/ |
| 16 | |
| 17 | .. contents:: |
| 18 | |
| 19 | |
| 20 | Introduction |
| 21 | ============ |
| 22 | |
| 23 | This document will show you how to use the Py programs and the Py |
| 24 | library of Python source code modules. Py is the new name for the |
| 25 | project that began as PyCrust. Py is officially part of wxPython_, |
| 26 | and includes PyCrust, so PyCrust is no longer distributed separately. |
| 27 | |
| 28 | .. _wxPython: http://www.wxpython.org/ |
| 29 | |
| 30 | |
| 31 | Developer Reference |
| 32 | =================== |
| 33 | |
| 34 | Source code documentation for developers is available at: |
| 35 | |
| 36 | http://www.orbtech.com/www/wx/epydoc/public/wx.py-module.html |
| 37 | |
| 38 | |
| 39 | What is Py? |
| 40 | =========== |
| 41 | |
| 42 | Besides being `a delicious dessert`_, Py is the name for a collection |
| 43 | of whimsically-named Python programs and modules that began as the |
| 44 | PyCrust project. So Py is really several things: a set of standalone |
| 45 | programs, including the original PyCrust program, a library of Python |
| 46 | source code modules that can be used in your own programs, and as many |
| 47 | examples of bad "pie" puns as I can come up with. (If you're going to |
| 48 | do something, you might as well do it all the way, right?) Py uses |
| 49 | Python and wxPython, so it works equally well on Windows, Linux and |
| 50 | Mac OS X. |
| 51 | |
| 52 | .. _a delicious dessert: http://www.wikipedia.org/wiki/Pie |
| 53 | |
| 54 | |
| 55 | PyCrust is dead! Long live Py! |
| 56 | ============================== |
| 57 | |
| 58 | This project began with a program I created called PyCrust - an |
| 59 | interactive, graphical Python shell, developed using the wxPython GUI |
| 60 | toolkit. For about two years, PyCrust was hosted on SourceForge_. |
| 61 | Shortly after I created PyCrust, the wxPython folks started including |
| 62 | it in their distribution. As the PyCrust project grew, it reached a |
| 63 | point where I thought the original PyCrust name was too confining. I |
| 64 | was using the PyCrust code base to develop programs that weren't just |
| 65 | Python shells any more. |
| 66 | |
| 67 | Around that same time, the wxPython folks asked me if I'd be willing |
| 68 | to move all my wxPython-related projects into the `wxPython CVS |
| 69 | repository`_, and become part of the wxPython_/wxWidgets_ developer team. |
| 70 | I decided the time was right to restructure the PyCrust project. |
| 71 | During the move, the PyCrust package was renamed to "py" (lowercase |
| 72 | "p") and the collection of programs and modules as a whole became |
| 73 | known as "Py" (with a capital "P"). |
| 74 | |
| 75 | .. _wxPython CVS repository: http://cvs.wxWidgets.org |
| 76 | .. _SourceForge: http://www.sf.net/projects/pycrust/ |
| 77 | .. _wxWidgets: http://www.wxWidgets.org/ |
| 78 | |
| 79 | The original goal of PyCrust was to be the best interactive, graphical |
| 80 | Python shell (of course, I claimed it was the "flakiest" Python |
| 81 | shell). And that was all I wanted it to be. But little by little I |
| 82 | found myself developing a wider variety of tools for wxPython |
| 83 | applications. Eventually I'll create a debugger (PySlice, perhaps) |
| 84 | and whatever else is needed to one day become a complete wxPython |
| 85 | application development environment (PyFactory?). In the mean time, |
| 86 | PyCrust is still the flakiest Python shell, and the other Py programs |
| 87 | are equally tasty. |
| 88 | |
| 89 | At this point, Py has standalone programs that include Python code |
| 90 | editors (PyAlaCarte and PyAlaMode), interactive Python shells (PyCrust |
| 91 | and PyShell), and a runtime wrapper (PyWrap). The runtime wrapper |
| 92 | utility provides you with runtime introspection capabilities for your |
| 93 | wxPython programs without having to include PyCrust or PyShell in your |
| 94 | program, and without having to alter one line of your source code. |
| 95 | |
| 96 | Py also contains a collection of modules that you can use in your own |
| 97 | wxPython applications to provide similar services, either for your own |
| 98 | use during development, or as an interface for users of your programs. |
| 99 | These modules are the same ones used by all the Py programs. |
| 100 | |
| 101 | |
| 102 | Py standalone programs |
| 103 | ====================== |
| 104 | |
| 105 | These are the standalone applications in the Py collection: |
| 106 | |
| 107 | * PyAlaCarte |
| 108 | * PyAlaMode |
| 109 | * PyCrust |
| 110 | * PyFilling |
| 111 | * PyShell |
| 112 | * PyWrap |
| 113 | |
| 114 | |
| 115 | PyAlaCarte |
| 116 | ========== |
| 117 | |
| 118 | PyAlaCarte is a Python source code editor. It is designed to have a |
| 119 | simple, single-file interface. As a standalone application, it is |
| 120 | good for simple, short editing tasks. But it is really meant to be |
| 121 | more of an example of how to embed the Py editor into a wxPython |
| 122 | application. |
| 123 | |
| 124 | |
| 125 | PyAlaMode |
| 126 | ========= |
| 127 | |
| 128 | PyAlaMode is a Python source code editor. |
| 129 | |
| 130 | |
| 131 | PyCrust |
| 132 | ======= |
| 133 | |
| 134 | PyCrust is an interactive, Python shell. But it's more than just a |
| 135 | shell. It includes a tabbed notebook containing a namespace tree |
| 136 | (PyFilling), and several other things. |
| 137 | |
| 138 | |
| 139 | PyFilling |
| 140 | ========= |
| 141 | |
| 142 | PyFilling is a namespace viewer. It isn't really useful as a |
| 143 | standalone program, but it does illustrate how to make use of the |
| 144 | underlying ``filling`` module. |
| 145 | |
| 146 | |
| 147 | PyShell |
| 148 | ======= |
| 149 | |
| 150 | PyShell is an interactive, Python shell. It shares the same base code |
| 151 | as PyCrust, but doesn't have any of the extra features that appear in |
| 152 | the PyCrust notebook interface. |
| 153 | |
| 154 | .. figure:: screenshots/PyShell.png |
| 155 | |
| 156 | PyShell running on Mandrake Linux. |
| 157 | |
| 158 | |
| 159 | PyWrap |
| 160 | ====== |
| 161 | |
| 162 | PyWrap is a runtime utility that lets you run an existing wxPython |
| 163 | program with a PyCrust frame at the same time. Inside the PyCrust |
| 164 | shell namespace, the local variable ``app`` is assigned to your |
| 165 | application instance. In this way you can introspect your entire |
| 166 | application within the PyCrust shell, as well as the PyFilling |
| 167 | namespace viewer. |
| 168 | |
| 169 | |
| 170 | Py modules |
| 171 | ========== |
| 172 | |
| 173 | Py was designed to be modular. That means graphical code is kept |
| 174 | separate from non-graphical code, and many of the Py modules can be |
| 175 | used by other programs. Likewise, other programs can supply some of |
| 176 | the modules needed by Py. For example, you could supply a customized |
| 177 | interpreter module and plug it in to the PyCrust standalone |
| 178 | application. As long as it supports the minimum functionality |
| 179 | required, PyCrust will work just as well with your interpreter as with |
| 180 | its default interpreter. |
| 181 | |
| 182 | |
| 183 | Projects using Py |
| 184 | ================= |
| 185 | |
| 186 | * `Conflict Solver`_ |
| 187 | * Gnumed_ |
| 188 | * PyGist |
| 189 | * PythonCard_ |
| 190 | * RPy_ |
| 191 | * SciPy_ |
| 192 | * Sim42_ |
| 193 | * wxGasp_ |
| 194 | |
| 195 | .. _Conflict Solver: http://conflictsolver.sourceforge.net/ |
| 196 | .. _Gnumed: http://www.gnumed.org/ |
| 197 | .. _PythonCard: http://www.pythoncard.org/ |
| 198 | .. _RPy: http://rpy.sourceforge.net/ |
| 199 | .. _SciPy: http://www.scipy.org/ |
| 200 | .. _Sim42: http://www.sim42.org/ |
| 201 | .. _wxGasp: http://linus.yorktown.arlington.k12.va.us/CS/APCSC/student_sites/David_Mayo/wxGasp |
| 202 | |
| 203 | |
| 204 | History of changes |
| 205 | ================== |
| 206 | |
| 207 | This section lists all the changes that have been made to the Py |
| 208 | programs and modules, since the beginning. |
| 209 | |
| 210 | .. include:: ../wx/py/CHANGES.txt |
| 211 | |