-
The wxPython wx Package
-
Or, how to survive the new wx namespace changes.
-
-
-
-
-| Author: |
-Patrick K. O'Brien |
|---|
-| Contact: |
-pobrien@orbtech.com |
|---|
-| Organization: |
-Orbtech |
|---|
-| Date: |
-2003-05-08 |
|---|
-| Revision: |
-1.1.2.4 |
|---|
-
-
-
-
-
-
Big things sometimes come in small packages. This is certainly true
-of the new wx package, which is being introduced in wxPython 2.4.1 as
-a way to allow the "wx" prefix to be dropped from the names of all
-wxPython classes, functions, and constants. This document should
-answer all the questions you might have concerning the new wx package.
-If not, feel free to contact the author. I hope you like the new wx
-package as much as I do.
-
-
-
-
This change is being made for a couple of reasons. The first reason
-is to discourage the use of import *, which is a dangerous
-technique that can create name conflicts and bloated namespaces.
-
The second reason is to remove what some perceive to be a "wart." For
-example, the following code is rather ugly in that the "wx" prefix on
-the wxFrame class name is no longer useful when you're using the wx
-module prefix:
-
-from wxPython import wx
-
-class Frame(wx.wxFrame)
-
-
The new wx package allows you to write code like this, instead:
-
-import wx
-
-class Frame(wx.Frame)
-
-
The third reason is that the wxWindows project intends to do the same
-thing (implement a new wx namespace and drop the "wx" prefix) and we
-want wxPython to lead the way.
-
-
-
-
As a way of getting to this new syntax as quickly as possible, the
-code in this new wx package was created. What it does is alter the
-existing wx namespace dynamically. By making the changes on-the-fly
-at runtime, we can try out the new syntax before any permanent changes
-are made to the underlying class library. The downside of making
-these changes at runtime is that there is a slight delay when you
-import wx; the upside is that you can start using the new syntax
-now.
-
-
-
-
No. Your existing code will continue to work and be supported for
-some time. It will be up to you to decide when to switch to the new
-syntax. But all new documentation and code examples will use the new
-syntax. So don't wait too long. You wouldn't want anyone calling you
-old-fashioned, would you?
-
-
-
-
It's pretty simple, and pretty clever. The wx directory contains an
-__init__.py file, making it a Python package. (In contrast, the
-old wxPython.wx module is a module, not a package.) When you import
-wx the code in the __init__.py file is executed, and that's
-where all the magic takes place. Let's take a look at the code inside
-the __init__.py file:
-
-"""wx package
-
-Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-from wxPython import wx
-
-import types
-
-d_new = globals()
-d_old = wx.__dict__
-
-for old, obj in d_old.items():
- if type(obj) is types.ModuleType or old.startswith('_'):
- # Skip modules and private names.
- continue
- new = old
- if old.startswith('EVT_'):
- # Leave name unmodified; add to the new wx namespace.
- d_new[new] = obj
- elif old.startswith('wxEVT_'):
- # Leave name unmodified; add to the new wx namespace.
- d_new[new] = obj
- else:
- if old.startswith('wx'):
- # Remove the 'wx' prefix.
- new = old[2:]
- # Add to the new wx package namespace.
- d_new[new] = obj
-
-del d_new
-del d_old
-del new
-del obj
-del old
-del types
-
-del wx
-
-
-
Namespaces in Python are implemented as dictionaries. The dictionary
-used to create the wx package's namespace is accessible using the
-globals() function. The dictionary used to create the old
-wxPython.wx module's namespace is wx.__dict__. Once we have these
-two dictionaries, it's a simple matter of iterating through one,
-changing the names, adding the renamed object to the other dictionary,
-and cleaning up a few local variables and imported modules. Voila!
-
-
-
-
There's more to wxPython than just the wx namespace. And we've got
-those extra modules covered as well. For each of those modules (as
-well as the lib package) we've got matching modules in the new wx
-package. Let's take a look at a few of them.
-
Here is html.py:
-
-"""Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-from wx import prefix
-
-from wxPython import html
-prefix.rename(d_new=globals(), d_old=html.__dict__)
-del html
-
-del prefix
-del wx
-
-
-
And here is lib/dialogs.py:
-
-"""Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-from wx import prefix
-
-from wxPython.lib import dialogs
-prefix.rename(d_new=globals(), d_old=dialogs.__dict__)
-del dialogs
-
-del prefix
-del wx
-
-
-
As you can see, they both rely on the prefix.rename() function
-defined in prefix.py:
-
-"""Renaming utility.
-
-Provides a way to drop the wx prefix from wxPython objects."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import types
-
-def rename(d_new, d_old):
- for old, obj in d_old.items():
- if type(obj) is types.ModuleType or old.startswith('_'):
- # Skip modules and private names.
- continue
-## mod = d_old['__name__']
-## if hasattr(obj, '__module__') and not obj.__module__.startswith(mod):
-## # Skip objects imported from other modules, except those
-## # related to the current module, such as stc_.
-## continue
- new = old
- if old.startswith('EVT_') or old.startswith('wxEVT_'):
- # Leave these names unmodified.
- pass
- elif old.startswith('wx'):
- new = old[2:]
- if new:
- d_new[new] = d_old[old]
-
-
-
Again, the technique is very similar to the one used by the wx
-package.
-
-
-
-
The wx package is automatically created when you install wxPython
-version 2.4.1 or higher. So all you have to do is:
-
-import wx
-
-
-
-
-
Obviously, you need to change your import statements from:
-
-from wxPython import wx
-
-
or:
-
-from wxPython.wx import *
-
-
to:
-
-import wx
-
-
Then you need to refer to wx attributes without a "wx" prefix, such
-as:
-
-class MyFrame(wx.Frame):
-
-
In most cases, existing code can be modified with a simple search and
-replace.
-
One extra issue you might run into when converting existing code is
-that the wx.__version__ attribute is no longer available, since the
-new wx namespace doesn't include any private attributes from the old
-wxPython.wx namespace. The solution is to use the wx.VERSION_STRING
-attribute, which was introduced in wxPython 2.4.1.
-
-
-
-
Example programs are included in the wxPython/samples/wx_examples
-directory, and are documented in the wxPythonExamples documentation
-file. Also, all the code in the py package uses the new wx syntax.
-You can learn more about these in the PyManual.
-
-
-
Example Programs Using wxPython
-
A survival guide for the post-wx-prefixed world.
-
-
-
-
-
This document illustrates example programs using wxPython. All the
-examples make use of the new wx package syntax introduced in wxPython
-2.4.1, which is a bit different than older examples you might come
-across.
-
-
-
-
If something hits you on the head, don't run around screaming that the
-sky is falling. Instead, take a close look and see if it wasn't a
-"wx" prefix that hit you. Apparently, they're dropping off wxPython
-class names like flies dropping dead in the scorching heat of a
-summer's day.
-
Yes, the world is changing, and even our little wxPython world must
-change with it. Then again, I'm not fond of pesky summertime flies,
-and I'm not too upset that the "wx" prefixes are going to bite the
-dust. I think it's for the best. But, being the kind, considerate
-person that I am, I decided to write this guide to make the wx
-namespace transition easier for everyone, even Chicken Little.
-
-
Note
-
Say what?
-
If you have no idea what I mean by the "wx namespace transition,"
-consider yourself lucky. You can simply use these examples to
-learn wxPython in its current state (beginning with wxPython
-version 2.4.1). All you need to know is that previous wxPython
-code used a slightly different syntax that some folks (including
-me) considered ugly. So we changed it. And that's when the sky
-starting falling...
-
If you want more of the technical details, read the wx package
-documentation.
-
-
Rather than simply tell you that everything will be okay, I
-decided to show you that everything will be okay. To do that,
-I've created a bunch of example programs using the new wx package. I
-hope you like them.
-
-
-
-
It doesn't get much simpler than this. Every wxPython program needs
-an application and a frame. To encourage good coding habits, I've
-split them into separate modules. They don't do much, but they're a
-good starting point.
-
I include a simple App class in the frame module because the PyWrap
-"wrapper" utility (pywrap) only works with modules that contain an
-application class. So including a simple one in each of your frame
-modules allows you to use the PyWrap runtime wrapper and debug your
-frames independent of your full application.
-
Here is the module (frame.py) that defines the frame class:
-
-#!/usr/bin/env python
-
-"""Basic frame class, with App for testing."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-
-class Frame(wx.Frame):
- """Frame class."""
-
- def __init__(self, parent=None, id=-1, title='Title',
- pos=wx.DefaultPosition, size=(400, 200)):
- """Create a Frame instance."""
- wx.Frame.__init__(self, parent, id, title, pos, size)
-
-class App(wx.App):
- """Application class."""
-
- def OnInit(self):
- self.frame = Frame()
- self.frame.Show()
- self.SetTopWindow(self.frame)
- return True
-
-def main():
- app = App()
- app.MainLoop()
-
-if __name__ == '__main__':
- main()
-
-
-
And here is the module (app.py) that defines the application class
-and imports the frame from frame.py:
-
-#!/usr/bin/env python
-
-"""Basic application class."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-
-from frame import Frame
-
-class App(wx.App):
- """Application class."""
-
- def OnInit(self):
- self.frame = Frame()
- self.frame.Show()
- self.SetTopWindow(self.frame)
- return True
-
-def main():
- app = App()
- app.MainLoop()
-
-if __name__ == '__main__':
- main()
-
-
-
-
-
-
This program displays an image file (wxPython.jpg) inside a frame
-sized to match the graphic.
-
-
-
-
Here is the source code for hello.py:
-
-#!/usr/bin/env python
-
-"""Hello, wxPython! program."""
-
-__author__ = "Patrick K. O'Brien <pobrien@orbtech.com>"
-__cvsid__ = "$Id$"
-__revision__ = "$Revision$"[11:-2]
-
-import wx
-
-class Frame(wx.Frame):
- """Frame class that displays an image."""
-
- def __init__(self, image, parent=None, id=-1,
- pos=wx.DefaultPosition, title='Hello, wxPython!'):
- """Create a Frame instance and display image."""
- temp = image.ConvertToBitmap()
- size = temp.GetWidth(), temp.GetHeight()
- wx.Frame.__init__(self, parent, id, title, pos, size)
- self.bmp = wx.StaticBitmap(parent=self, id=-1, bitmap=temp)
-
-class App(wx.App):
- """Application class."""
-
- def OnInit(self):
- wx.InitAllImageHandlers()
- image = wx.Image('wxPython.jpg', wx.BITMAP_TYPE_JPEG)
- self.frame = Frame(image)
- self.frame.Show()
- self.SetTopWindow(self.frame)
- return True
-
-def main():
- app = App()
- app.MainLoop()
-
-if __name__ == '__main__':
- main()
-
-
-
-
-
The wxPython Tutorial
-
How to get up and running with wxPython
-
-
-
-
-| Author: |
-Patrick K. O'Brien |
|---|
-| Contact: |
-pobrien@orbtech.com |
|---|
-| Organization: |
-Orbtech |
|---|
-| Date: |
-2003-07-02 |
|---|
-| Revision: |
-1.2 |
|---|
-| License: | wxWindows Free Documentation Licence, Version 3 |
-
|---|
-
-
-
-
-
-
This is a tutorial for the wxPython GUI toolkit. It uses the new wx
-package syntax that was introduced in wxPython 2.4.1.
-
-
-
-
wxPython is a GUI toolkit for the Python programming language. It
-allows Python programmers to create programs with a graphical user
-interface for Windows, Linux, and Mac OS X.
-
-
-
-
This document adheres to the same license as the other documentation
-that comes with wxWindows:
-
- wxWindows Free Documentation Licence, Version 3
- ===============================================
-
- Copyright (c) 1998 Julian Smart, Robert Roebling et al
-
- Everyone is permitted to copy and distribute verbatim copies
- of this licence document, but changing it is not allowed.
-
- WXWINDOWS FREE DOCUMENTATION LICENCE
- TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
- 1. Permission is granted to make and distribute verbatim copies of this
- manual or piece of documentation provided any copyright notice and this
- permission notice are preserved on all copies.
-
- 2. Permission is granted to process this file or document through a
- document processing system and, at your option and the option of any third
- party, print the results, provided a printed document carries a copying
- permission notice identical to this one.
-
- 3. Permission is granted to copy and distribute modified versions of this
- manual or piece of documentation under the conditions for verbatim
- copying, provided also that any sections describing licensing conditions
- for this manual, such as, in particular, the GNU General Public Licence,
- the GNU Library General Public Licence, and any wxWindows Licence are
- included exactly as in the original, and provided that the entire
- resulting derived work is distributed under the terms of a permission
- notice identical to this one.
-
- 4. Permission is granted to copy and distribute translations of this
- manual or piece of documentation into another language, under the above
- conditions for modified versions, except that sections related to
- licensing, including this paragraph, may also be included in translations
- approved by the copyright holders of the respective licence documents in
- addition to the original English.
-
- WARRANTY DISCLAIMER
-
- 5. BECAUSE THIS MANUAL OR PIECE OF DOCUMENTATION IS LICENSED FREE OF CHARGE,
- THERE IS NO WARRANTY FOR IT, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
- EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
- PARTIES PROVIDE THIS MANUAL OR PIECE OF DOCUMENTATION "AS IS" WITHOUT
- WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
- PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF
- THE MANUAL OR PIECE OF DOCUMENTATION IS WITH YOU. SHOULD THE MANUAL OR
- PIECE OF DOCUMENTATION PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
- NECESSARY SERVICING, REPAIR OR CORRECTION.
-
- 6. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
- ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
- REDISTRIBUTE THE MANUAL OR PIECE OF DOCUMENTATION AS PERMITTED ABOVE, BE
- LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
- CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
- MANUAL OR PIECE OF DOCUMENTATION (INCLUDING BUT NOT LIMITED TO LOSS OF
- DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
- PARTIES OR A FAILURE OF A PROGRAM BASED ON THE MANUAL OR PIECE OF
- DOCUMENTATION TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
- OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
-
-
-
-
-
