wxPython/docs/PyManual.txt

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