wxPython/demo/data/wxPackage.html

   1 <?xml version="1.0" encoding="iso-8859-1" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   6 <meta name="generator" content="Docutils 0.2.8: http://docutils.sourceforge.net/" />
   7 <title>The wxPython wx Package</title>
   8 <meta name="author" content="Patrick K. O'Brien" />
   9 <meta name="organization" content="Orbtech" />
  10 <meta name="date" content="2003-05-08" />
  11 <link rel="stylesheet" href="default.css" type="text/css" />
  12 </head>
  13 <body>
  14 <div class="document" id="the-wxpython-wx-package">
  15 <h1 class="title">The wxPython wx Package</h1>
  16 <h2 class="subtitle" id="or-how-to-survive-the-new-wx-namespace-changes">Or, how to survive the new wx namespace changes.</h2>
  17 <table class="docinfo" frame="void" rules="none">
  18 <col class="docinfo-name" />
  19 <col class="docinfo-content" />
  20 <tbody valign="top">
  21 <tr><th class="docinfo-name">Author:</th>
  22 <td>Patrick K. O'Brien</td></tr>
  23 <tr><th class="docinfo-name">Contact:</th>
  24 <td><a class="first last reference" href="mailto:pobrien&#64;orbtech.com">pobrien&#64;orbtech.com</a></td></tr>
  25 <tr><th class="docinfo-name">Organization:</th>
  26 <td><a class="first last reference" href="http://www.orbtech.com/">Orbtech</a></td></tr>
  27 <tr><th class="docinfo-name">Date:</th>
  28 <td>2003-05-08</td></tr>
  29 <tr><th class="docinfo-name">Revision:</th>
  30 <td>1.1.2.4</td></tr>
  31 </tbody>
  32 </table>
  33 <div class="contents topic" id="contents">
  34 <p class="topic-title"><a name="contents">Contents</a></p>
  35 <ul class="simple">
  36 <li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li>
  37 <li><a class="reference" href="#why-change-anything" id="id2" name="id2">Why change anything?</a></li>
  38 <li><a class="reference" href="#what-does-the-new-wx-package-do" id="id3" name="id3">What does the new wx package do?</a></li>
  39 <li><a class="reference" href="#will-any-of-this-effect-my-existing-code" id="id4" name="id4">Will any of this effect my existing code?</a></li>
  40 <li><a class="reference" href="#how-does-the-new-wx-package-work" id="id5" name="id5">How does the new wx package work?</a></li>
  41 <li><a class="reference" href="#what-about-all-the-other-modules-like-grid-html-and-stc" id="id6" name="id6">What about all the other modules, like grid, html, and stc?</a></li>
  42 <li><a class="reference" href="#how-do-i-use-this-new-wx-package" id="id7" name="id7">How do I use this new wx package?</a></li>
  43 <li><a class="reference" href="#what-are-the-issues-with-converting-old-code-to-use-the-new-wx-package" id="id8" name="id8">What are the issues with converting old code to use the new wx package?</a></li>
  44 <li><a class="reference" href="#where-can-i-find-example-programs-using-the-new-wx-syntax" id="id9" name="id9">Where can I find example programs using the new wx syntax?</a></li>
  45 </ul>
  46 </div>
  47 <div class="section" id="introduction">
  48 <h1><a class="toc-backref" href="#id1" name="introduction">Introduction</a></h1>
  49 <p>Big things sometimes come in small packages.  This is certainly true
  50 of the new wx package, which is being introduced in wxPython 2.4.1 as
  51 a way to allow the &quot;wx&quot; prefix to be dropped from the names of all
  52 wxPython classes, functions, and constants.  This document should
  53 answer all the questions you might have concerning the new wx package.
  54 If not, feel free to contact the author.  I hope you like the new wx
  55 package as much as I do.</p>
  56 </div>
  57 <div class="section" id="why-change-anything">
  58 <h1><a class="toc-backref" href="#id2" name="why-change-anything">Why change anything?</a></h1>
  59 <p>This change is being made for a couple of reasons.  The first reason
  60 is to discourage the use of <tt class="literal"><span class="pre">import</span> <span class="pre">*</span></tt>, which is a dangerous
  61 technique that can create name conflicts and bloated namespaces.</p>
  62 <p>The second reason is to remove what some perceive to be a &quot;wart.&quot;  For
  63 example, the following code is rather ugly in that the &quot;wx&quot; prefix on
  64 the wxFrame class name is no longer useful when you're using the wx
  65 module prefix:</p>
  66 <pre class="literal-block">
  67 from wxPython import wx
  68
  69 class Frame(wx.wxFrame)
  70 </pre>
  71 <p>The new wx package allows you to write code like this, instead:</p>
  72 <pre class="literal-block">
  73 import wx
  74
  75 class Frame(wx.Frame)
  76 </pre>
  77 <p>The third reason is that the wxWindows project intends to do the same
  78 thing (implement a new wx namespace and drop the &quot;wx&quot; prefix) and we
  79 want wxPython to lead the way.</p>
  80 </div>
  81 <div class="section" id="what-does-the-new-wx-package-do">
  82 <h1><a class="toc-backref" href="#id3" name="what-does-the-new-wx-package-do">What does the new wx package do?</a></h1>
  83 <p>As a way of getting to this new syntax as quickly as possible, the
  84 code in this new wx package was created.  What it does is alter the
  85 existing wx namespace dynamically.  By making the changes on-the-fly
  86 at runtime, we can try out the new syntax before any permanent changes
  87 are made to the underlying class library.  The downside of making
  88 these changes at runtime is that there is a slight delay when you
  89 <tt class="literal"><span class="pre">import</span> <span class="pre">wx</span></tt>; the upside is that you can start using the new syntax
  90 now.</p>
  91 </div>
  92 <div class="section" id="will-any-of-this-effect-my-existing-code">
  93 <h1><a class="toc-backref" href="#id4" name="will-any-of-this-effect-my-existing-code">Will any of this effect my existing code?</a></h1>
  94 <p>No.  Your existing code will continue to work and be supported for
  95 some time.  It will be up to you to decide when to switch to the new
  96 syntax.  But all new documentation and code examples will use the new
  97 syntax.  So don't wait too long.  You wouldn't want anyone calling you
  98 old-fashioned, would you?</p>
  99 </div>
 100 <div class="section" id="how-does-the-new-wx-package-work">
 101 <h1><a class="toc-backref" href="#id5" name="how-does-the-new-wx-package-work">How does the new wx package work?</a></h1>
 102 <p>It's pretty simple, and pretty clever.  The wx directory contains an
 103 <tt class="literal"><span class="pre">__init__.py</span></tt> file, making it a Python package.  (In contrast, the
 104 old wxPython.wx module is a module, not a package.)  When you <tt class="literal"><span class="pre">import</span>
 105 <span class="pre">wx</span></tt> the code in the <tt class="literal"><span class="pre">__init__.py</span></tt> file is executed, and that's
 106 where all the magic takes place.  Let's take a look at the code inside
 107 the <tt class="literal"><span class="pre">__init__.py</span></tt> file:</p>
 108 <pre class="literal-block">
 109 &quot;&quot;&quot;wx package
 110
 111 Provides a way to drop the wx prefix from wxPython objects.&quot;&quot;&quot;
 112
 113 __author__ = &quot;Patrick K. O'Brien &lt;pobrien&#64;orbtech.com&gt;&quot;
 114 __cvsid__ = &quot;$Id$&quot;
 115 __revision__ = &quot;$Revision$&quot;[11:-2]
 116
 117 from wxPython import wx
 118
 119 import types
 120
 121 d_new = globals()
 122 d_old = wx.__dict__
 123
 124 for old, obj in d_old.items():
 125     if type(obj) is types.ModuleType or old.startswith('_'):
 126         # Skip modules and private names.
 127         continue
 128     new = old
 129     if old.startswith('EVT_'):
 130         # Leave name unmodified; add to the new wx namespace.
 131         d_new[new] = obj
 132     elif old.startswith('wxEVT_'):
 133         # Leave name unmodified; add to the new wx namespace.
 134         d_new[new] = obj
 135     else:
 136         if old.startswith('wx'):
 137             # Remove the 'wx' prefix.
 138             new = old[2:]
 139         # Add to the new wx package namespace.
 140         d_new[new] = obj
 141
 142 del d_new
 143 del d_old
 144 del new
 145 del obj
 146 del old
 147 del types
 148
 149 del wx
 150
 151 </pre>
 152 <p>Namespaces in Python are implemented as dictionaries.  The dictionary
 153 used to create the wx package's namespace is accessible using the
 154 <tt class="literal"><span class="pre">globals()</span></tt> function.  The dictionary used to create the old
 155 wxPython.wx module's namespace is <tt class="literal"><span class="pre">wx.__dict__</span></tt>.  Once we have these
 156 two dictionaries, it's a simple matter of iterating through one,
 157 changing the names, adding the renamed object to the other dictionary,
 158 and cleaning up a few local variables and imported modules.  Voila!</p>
 159 </div>
 160 <div class="section" id="what-about-all-the-other-modules-like-grid-html-and-stc">
 161 <h1><a class="toc-backref" href="#id6" name="what-about-all-the-other-modules-like-grid-html-and-stc">What about all the other modules, like grid, html, and stc?</a></h1>
 162 <p>There's more to wxPython than just the wx namespace.  And we've got
 163 those extra modules covered as well.  For each of those modules (as
 164 well as the lib package) we've got matching modules in the new wx
 165 package.  Let's take a look at a few of them.</p>
 166 <p>Here is <tt class="literal"><span class="pre">html.py</span></tt>:</p>
 167 <pre class="literal-block">
 168 &quot;&quot;&quot;Provides a way to drop the wx prefix from wxPython objects.&quot;&quot;&quot;
 169
 170 __author__ = &quot;Patrick K. O'Brien &lt;pobrien&#64;orbtech.com&gt;&quot;
 171 __cvsid__ = &quot;$Id$&quot;
 172 __revision__ = &quot;$Revision$&quot;[11:-2]
 173
 174 import wx
 175 from wx import prefix
 176
 177 from wxPython import html
 178 prefix.rename(d_new=globals(), d_old=html.__dict__)
 179 del html
 180
 181 del prefix
 182 del wx
 183
 184 </pre>
 185 <p>And here is <tt class="literal"><span class="pre">lib/dialogs.py</span></tt>:</p>
 186 <pre class="literal-block">
 187 &quot;&quot;&quot;Provides a way to drop the wx prefix from wxPython objects.&quot;&quot;&quot;
 188
 189 __author__ = &quot;Patrick K. O'Brien &lt;pobrien&#64;orbtech.com&gt;&quot;
 190 __cvsid__ = &quot;$Id$&quot;
 191 __revision__ = &quot;$Revision$&quot;[11:-2]
 192
 193 import wx
 194 from wx import prefix
 195
 196 from wxPython.lib import dialogs
 197 prefix.rename(d_new=globals(), d_old=dialogs.__dict__)
 198 del dialogs
 199
 200 del prefix
 201 del wx
 202
 203 </pre>
 204 <p>As you can see, they both rely on the <tt class="literal"><span class="pre">prefix.rename()</span></tt> function
 205 defined in <tt class="literal"><span class="pre">prefix.py</span></tt>:</p>
 206 <pre class="literal-block">
 207 &quot;&quot;&quot;Renaming utility.
 208
 209 Provides a way to drop the wx prefix from wxPython objects.&quot;&quot;&quot;
 210
 211 __author__ = &quot;Patrick K. O'Brien &lt;pobrien&#64;orbtech.com&gt;&quot;
 212 __cvsid__ = &quot;$Id$&quot;
 213 __revision__ = &quot;$Revision$&quot;[11:-2]
 214
 215 import types
 216
 217 def rename(d_new, d_old):
 218     for old, obj in d_old.items():
 219         if type(obj) is types.ModuleType or old.startswith('_'):
 220             # Skip modules and private names.
 221             continue
 222 ##         mod = d_old['__name__']
 223 ##         if hasattr(obj, '__module__') and not obj.__module__.startswith(mod):
 224 ##             # Skip objects imported from other modules, except those
 225 ##             # related to the current module, such as stc_.
 226 ##             continue
 227         new = old
 228         if old.startswith('EVT_') or old.startswith('wxEVT_'):
 229             # Leave these names unmodified.
 230             pass
 231         elif old.startswith('wx'):
 232             new = old[2:]
 233         if new:
 234             d_new[new] = d_old[old]
 235
 236 </pre>
 237 <p>Again, the technique is very similar to the one used by the wx
 238 package.</p>
 239 </div>
 240 <div class="section" id="how-do-i-use-this-new-wx-package">
 241 <h1><a class="toc-backref" href="#id7" name="how-do-i-use-this-new-wx-package">How do I use this new wx package?</a></h1>
 242 <p>The wx package is automatically created when you install wxPython
 243 version 2.4.1 or higher.  So all you have to do is:</p>
 244 <pre class="literal-block">
 245 import wx
 246 </pre>
 247 </div>
 248 <div class="section" id="what-are-the-issues-with-converting-old-code-to-use-the-new-wx-package">
 249 <h1><a class="toc-backref" href="#id8" name="what-are-the-issues-with-converting-old-code-to-use-the-new-wx-package">What are the issues with converting old code to use the new wx package?</a></h1>
 250 <p>Obviously, you need to change your import statements from:</p>
 251 <pre class="literal-block">
 252 from wxPython import wx
 253 </pre>
 254 <p>or:</p>
 255 <pre class="literal-block">
 256 from wxPython.wx import *
 257 </pre>
 258 <p>to:</p>
 259 <pre class="literal-block">
 260 import wx
 261 </pre>
 262 <p>Then you need to refer to wx attributes without a &quot;wx&quot; prefix, such
 263 as:</p>
 264 <pre class="literal-block">
 265 class MyFrame(wx.Frame):
 266 </pre>
 267 <p>In most cases, existing code can be modified with a simple search and
 268 replace.</p>
 269 <p>One extra issue you might run into when converting existing code is
 270 that the wx.__version__ attribute is no longer available, since the
 271 new wx namespace doesn't include any private attributes from the old
 272 wxPython.wx namespace.  The solution is to use the wx.VERSION_STRING
 273 attribute, which was introduced in wxPython 2.4.1.</p>
 274 </div>
 275 <div class="section" id="where-can-i-find-example-programs-using-the-new-wx-syntax">
 276 <h1><a class="toc-backref" href="#id9" name="where-can-i-find-example-programs-using-the-new-wx-syntax">Where can I find example programs using the new wx syntax?</a></h1>
 277 <p>Example programs are included in the wxPython/samples/wx_examples
 278 directory, and are documented in the <a class="reference" href="wxPythonExamples.html">wxPythonExamples</a> documentation
 279 file.  Also, all the code in the py package uses the new wx syntax.
 280 You can learn more about these in the <a class="reference" href="PyManual.html">PyManual</a>.</p>
 281 </div>
 282 </div>
 283 <hr class="footer"/>
 284 <div class="footer">
 285 <a class="reference" href="wxPackage.txt">View document source</a>.
 286 Generated on: 2003-06-04 18:07 UTC.
 287 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 288 </div>
 289 </body>
 290 </html>