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, 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