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 :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 Big things sometimes come in small packages.  This is certainly true
  24 of the new wx package, which is being introduced in wxPython 2.4.1 as
  25 a way to allow the "wx" prefix to be dropped from the names of all
  26 wxPython classes, functions, and constants.  This document should
  27 answer all the questions you might have concerning the new wx package.
  28 If not, feel free to contact the author.  I hope you like the new wx
  29 package as much as I do.
  30
  31
  32 Why change anything?
  33 ====================
  34
  35 This change is being made for a couple of reasons.  The first reason
  36 is to discourage the use of ``import *``, which is a dangerous
  37 technique that can create name conflicts and bloated namespaces.
  38
  39 The second reason is to remove what some perceive to be a "wart."  For
  40 example, the following code is rather ugly in that the "wx" prefix on
  41 the wxFrame class name is no longer useful when you're using the wx
  42 module prefix::
  43
  44     from wxPython import wx
  45
  46     class Frame(wx.wxFrame)
  47
  48 The new wx package allows you to write code like this, instead::
  49
  50     import wx
  51
  52     class Frame(wx.Frame)
  53
  54 The third reason is that the wxWindows project intends to do the same
  55 thing (implement a new wx namespace and drop the "wx" prefix) and we
  56 want wxPython to lead the way.
  57
  58
  59 What does the new wx package do?
  60 ================================
  61
  62 As a way of getting to this new syntax as quickly as possible, the
  63 code in this new wx package was created.  What it does is alter the
  64 existing wx namespace dynamically.  By making the changes on-the-fly
  65 at runtime, we can try out the new syntax before any permanent changes
  66 are made to the underlying class library.  The downside of making
  67 these changes at runtime is that there is a slight delay when you
  68 ``import wx``; the upside is that you can start using the new syntax
  69 now.
  70
  71
  72 Will any of this effect my existing code?
  73 =========================================
  74
  75 No.  Your existing code will continue to work and be supported for
  76 some time.  It will be up to you to decide when to switch to the new
  77 syntax.  But all new documentation and code examples will use the new
  78 syntax.  So don't wait too long.  You wouldn't want anyone calling you
  79 old-fashioned, would you?
  80
  81
  82 How does the new wx package work?
  83 =================================
  84
  85 It's pretty simple, and pretty clever.  The wx directory contains an
  86 ``__init__.py`` file, making it a Python package.  (In contrast, the
  87 old wxPython.wx module is a module, not a package.)  When you ``import
  88 wx`` the code in the ``__init__.py`` file is executed, and that's
  89 where all the magic takes place.  Let's take a look at the code inside
  90 the ``__init__.py`` file:
  91
  92 .. include:: ../wx/__init__.py
  93    :literal:
  94
  95 Namespaces in Python are implemented as dictionaries.  The dictionary
  96 used to create the wx package's namespace is accessible using the
  97 ``globals()`` function.  The dictionary used to create the old
  98 wxPython.wx module's namespace is ``wx.__dict__``.  Once we have these
  99 two dictionaries, it's a simple matter of iterating through one,
 100 changing the names, adding the renamed object to the other dictionary,
 101 and cleaning up a few local variables and imported modules.  Voila!
 102
 103
 104 What about all the other modules, like grid, html, and stc?
 105 ===========================================================
 106
 107 There's more to wxPython than just the wx namespace.  And we've got
 108 those extra modules covered as well.  For each of those modules (as
 109 well as the lib package) we've got matching modules in the new wx
 110 package.  Let's take a look at a few of them.
 111
 112 Here is ``html.py``:
 113
 114 .. include:: ../wx/html.py
 115    :literal:
 116
 117 And here is ``lib/dialogs.py``:
 118
 119 .. include:: ../wx/lib/dialogs.py
 120    :literal:
 121
 122 As you can see, they both rely on the ``prefix.rename()`` function
 123 defined in ``prefix.py``:
 124
 125 .. include:: ../wx/prefix.py
 126    :literal:
 127
 128 Again, the technique is very similar to the one used by the wx
 129 package.
 130
 131
 132 How do I use this new wx package?
 133 =================================
 134
 135 The wx package is automatically created when you install wxPython
 136 version 2.4.1 or higher.  So all you have to do is::
 137
 138     import wx
 139
 140
 141 What are the issues with converting old code to use the new wx package?
 142 =======================================================================
 143
 144 Obviously, you need to change your import statements from::
 145
 146     from wxPython import wx
 147
 148 or::
 149
 150     from wxPython.wx import *
 151
 152 to::
 153
 154     import wx
 155
 156 Then you need to refer to wx attributes without a "wx" prefix, such
 157 as::
 158
 159     class MyFrame(wx.Frame):
 160
 161 In most cases, existing code can be modified with a simple search and
 162 replace.
 163
 164 One extra issue you might run into when converting existing code is
 165 that the wx.__version__ attribute is no longer available, since the
 166 new wx namespace doesn't include any private attributes from the old
 167 wxPython.wx namespace.  The solution is to use the wx.VERSION_STRING
 168 attribute, which was introduced in wxPython 2.4.1.
 169
 170
 171 Where can I find example programs using the new wx syntax?
 172 ==========================================================
 173
 174 Example programs are included in the wxPython/samples/wx_examples
 175 directory, and are documented in the wxPythonExamples_ documentation
 176 file.  Also, all the code in the py package uses the new wx syntax.
 177 You can learn more about these in the PyManual_.
 178
 179 .. _wxPythonExamples: wxPythonExamples.html
 180 .. _PyManual: PyManual.html