e71a8700c4
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_4_BRANCH@20357 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
145 lines
4.4 KiB
Plaintext
145 lines
4.4 KiB
Plaintext
=========================
|
|
The wxPython wx Package
|
|
=========================
|
|
|
|
--------------------------------------------------
|
|
Or, how to survive the new wx namespace changes.
|
|
--------------------------------------------------
|
|
|
|
:Author: Patrick K. O'Brien
|
|
:Contact: pobrien@orbtech.com
|
|
:Date: $Date$
|
|
:Revision: $Revision$
|
|
|
|
.. contents::
|
|
|
|
|
|
.. Add a link to wxExamples.html
|
|
|
|
|
|
|
|
Introduction
|
|
============
|
|
|
|
Big things sometimes come in small packages. This is certainly true
|
|
of the new wx package, which is being introduced as a transition to
|
|
allow the "wx" prefix to be dropped from the names of all wxPython
|
|
classes, functions, and constants.
|
|
|
|
|
|
Why change anything?
|
|
====================
|
|
|
|
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.
|
|
|
|
|
|
What does the new wx package do?
|
|
================================
|
|
|
|
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.
|
|
|
|
|
|
Will any of this effect my existing code?
|
|
=========================================
|
|
|
|
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?
|
|
|
|
|
|
How does the new wx package work?
|
|
=================================
|
|
|
|
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:
|
|
|
|
.. include:: ../wx/__init__.py
|
|
:literal:
|
|
|
|
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!
|
|
|
|
|
|
What about all the other modules, like grid, html, and stc?
|
|
===========================================================
|
|
|
|
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``:
|
|
|
|
.. include:: ../wx/html.py
|
|
:literal:
|
|
|
|
And here is ``lib/dialogs.py``:
|
|
|
|
.. include:: ../wx/lib/dialogs.py
|
|
:literal:
|
|
|
|
As you can see, they both rely on the ``prefix.rename()`` function
|
|
defined in ``prefix.py``:
|
|
|
|
.. include:: ../wx/prefix.py
|
|
:literal:
|
|
|
|
Again, the technique is very similar to the one used by the wx
|
|
package.
|
|
|
|
|
|
How do I use it?
|
|
================
|
|
|
|
The wx package is created when you install wxPython. So you can start
|
|
using it now. Examples are included in the wx/examples directory,
|
|
which includes an examples.txt documentation file. Here is the source
|
|
code for ``hello.py``, a simple program that displays a wxPython
|
|
graphic inside a frame:
|
|
|
|
.. include:: ../samples/wx_examples/hello/hello.py
|
|
:literal:
|
|
|
|
Good luck. I hope you like the new wx package as much as I do.
|
|
|
|
Pat
|