wxPython/docs/wxPackage.txt

   1 =========================
   2  The wxPython wx Package
   3 =========================
   4
   5 --------------------------------------------------
   6  Or, how to survive the new wx namespace changes.
   7 --------------------------------------------------
   8
   9 :Author: Patrick K. O'Brien
  10 :Author: Robin Dunn
  11 :Contact: pobrien@orbtech.com
  12 :Organization: Orbtech_
  13 :Date: $Date$
  14 :Revision: $Revision$
  15
  16 .. _Orbtech: http://www.orbtech.com/
  17
  18 .. contents::
  19
  20
  21 Introduction
  22 ============
  23
  24 In the begining there was Python, and Python had modules, and Python
  25 was good.  But after a time Guido looked on Python and saw that Python
  26 needed organizational assistance, and so Guido took code from Python's
  27 side and created Packages and then Python was very good.  About this
  28 time wxPython was reborn, and wxPython used Packages, but being young
  29 and trying to use a new technology wxPython did not know how to use
  30 Packages effectivly.  wxPython was good, but dreamed of being much
  31 better...
  32
  33 Now many years later, after tons of code reorganization and build
  34 hacking wxPython has reached that goal.  In version 2.4.1 a prototype
  35 of this new structure was introduced that dynamically built at import
  36 time a new toplevel package named simply "wx" that contained all the
  37 items from wxPython.wx but with the names edited to remove the wx
  38 prefix.  Now in 2.5 the final phase of that switcheroo has been
  39 completed and the *real* classes, functions and constants are now
  40 located in the wx package, leaving some compatibility modules in
  41 wxPython.wx.  This document should answer all the questions you might
  42 have concerning the new wx package.  Please also take a look at the
  43 `2.5 Migration Guide`_ to see notes about other big differences in
  44 this release.
  45
  46 .. _2.5 Migration Guide: MigrationGuide.html
  47
  48 Why change anything?
  49 ====================
  50
  51 This change is being made for a couple of reasons.  The first reason
  52 is to discourage the use of ``import *``, which is a dangerous
  53 technique that can create name conflicts and bloated namespaces.
  54
  55 The second reason is to remove what some perceive to be a "wart."  For
  56 example, the following code is rather ugly in that the "wx" prefix on
  57 the wxFrame class name is no longer useful when you're using the wx
  58 module prefix::
  59
  60     from wxPython import wx
  61
  62     class Frame(wx.wxFrame)
  63
  64 The new wx package allows you to write code like this, instead::
  65
  66     import wx
  67
  68     class Frame(wx.Frame)
  69
  70 The third reason is that the wxWindows project has considered doing
  71 the same thing (implement a new wx namespace and drop the "wx" prefix)
  72 and we want wxPython to lead the way.
  73
  74
  75 What does the new wx package do?
  76 ================================
  77
  78 As mentioned in the Introduction, wxPython 2.4.1 introduced a way of
  79 getting to this new syntax as quickly as possible.  It would import
  80 the old names (like "wxFrame") from the old package and then create new
  81 names in the wx package  without the wx prefix, (like "Frame".)
  82 Starting with wxPython 2.5 the renaming is moved up to the wxPython
  83 build step, so the real classes and etc. are actually named with the
  84 new name (like "Frame") and are located in the new wx package.
  85
  86 For compatibility the old wxPython package still exists, but now it is
  87 populated with modules that simply import the new names and then
  88 "reverse-renames" them to the old names.  It probably sounds a bit
  89 complicated, but it is mostly automated and so it  doesn't cause
  90 problems in most cases.
  91
  92
  93 Will any of this effect my existing code?
  94 =========================================
  95
  96 No.  Your existing code will continue to work and be supported for
  97 some time.  It will be up to you to decide when to switch to the new
  98 syntax.  But all new documentation and code examples will use the new
  99 syntax.  So don't wait too long.  You wouldn't want anyone calling you
 100 old-fashioned, would you?
 101
 102 When you import from wxPython.wx and use a class with the old name,
 103 such as wxButton, you are actually using the wx.Button class.  I
 104 expect that the vast majority of the existing code should work fine
 105 using this scheme.  The only things that may cause problems is if your
 106 old code is depending on some of the implemtation details, or if you
 107 are using other things that have changed in the API.  See the
 108 `Migration Guide`_ for more details.
 109
 110 .. _Migration Guide: MigrationGuide.html
 111
 112
 113 What about all the other modules, like grid, html, and stc?
 114 ===========================================================
 115
 116 There's more to the old wxPython than just the wxPython.wx module.
 117 And we've got those extra modules covered as well.  Each of those
 118 modules (as well as the lib subpackage) has been moved to the new wx
 119 package and reverse-renamers have been placed in the wxPython package
 120 as needed.
 121
 122
 123 How do I use this new wx package?
 124 =================================
 125
 126 The wx package is automatically created when you install wxPython
 127 version 2.4.1 or higher.  So all you have to do is::
 128
 129     import wx
 130
 131
 132 What are the issues with converting old code to use the new wx package?
 133 =======================================================================
 134
 135 Obviously, you need to change your import statements from::
 136
 137     from wxPython import wx
 138
 139 or::
 140
 141     from wxPython.wx import *
 142
 143 to::
 144
 145     import wx
 146
 147 Then you need to refer to wx attributes without a "wx" prefix, such
 148 as::
 149
 150     class MyFrame(wx.Frame):
 151
 152 In most cases, existing code can be modified with a simple search and
 153 replace.
 154
 155
 156
 157 Where can I find example programs using the new wx syntax?
 158 ==========================================================
 159
 160 The wxPython demo application and most of the sample apps have been
 161 converted to use the new ``import wx`` style of programming with
 162 wxPython, so there are lots of examples to look at and to play with.
 163 Here is one of them, it is the ``simple`` sample.
 164
 165
 166 .. include:: ../samples/simple/simple.py
 167    :literal:
 168