Beginning Python - From Novice To Professional (2005)

Example

To illustrate the various packages, I’ve created a simple example—simpler, even, than the editor example used earlier in the chapter. It’s just a single window containing a single button with the label “Hello” filling the window. When you click the button, it prints out the words “Hello, world!” A simple wxPython version is shown in Listing 12-7.

Listing 12-7. A Simple GUI Example

import wx

def hello(event):

print "Hello, world!"

app = wx.App()

win = wx.Frame(None, title="Hello, wxPython!", size=(200, 100))

button = wx.Button(win, label="Hello") button.Bind(wx.EVT_BUTTON, hello)

win.Show()

app.MainLoop()

In the interest of simplicity, I’m not using any fancy layout features here. The resulting window is shown in Figure 12-6.

Figure 12-6. A simple GUI example

Using Tkinter

Tkinter is an old-timer in the Python GUI business. It is a wrapper around the Tk GUI toolkit (associated with the programming language Tcl). It is included by default in the Windows distribution. The following URLs may be useful:

•http://www.ibm.com/developerworks/linux/library/l-tkprg

•http://www.nmt.edu/tcc/help/lang/python/tkinter.pdf

Example

Here is the GUI example implemented with Tkinter:

from Tkinter import *

def hello(): print 'Hello, world' win = Tk() # Tkinter's 'main window' win.title('Hello, Tkinter! ')

win.geometry('200x100') # Size 200, 200

btn = Button(win, text='Hello ', command=hello) btn.pack(expand=YES, fill=BOTH)

mainloop()

Using Jython and Swing

If you’re using Jython (the Java implementation of Python), packages such as wxPython and Tkinter aren’t available. The only GUI toolkits that are readily available are the Java standard library packages AWT and Swing (Swing is the most recent and considered the standard Java GUI toolkit). The good news is that both of these are automatically available so you don’t have to install them separately. For more information, visit the Jython Web site and look into the Swing documentation written for Java:

•http://www.jython.org

•http://java.sun.com/docs/books/tutorial/uiswing

Example

Here is the GUI example implemented with Jython and Swing:

from javax.swing import * import sys

def hello(event): print 'Hello, world! ' btn = JButton('Hello') btn.actionPerformed = hello

win = JFrame('Hello, Swing!') win.contentPane.add(btn)

def closeHandler(event): sys.exit() win.windowClosing = closeHandler

286 C H A P T E R 1 3 ■ D A T A B A S E S U P P O R T

of all the databases is the same, so a program written to use one of them might easily—in theory—be used with another. The problem with switching between different modules that provide the same functionality (more or less) is usually that their interfaces (APIs) are different. In order to solve this problem for database modules in Python, a standard database API has been agreed upon. The current version of the API (2.0) is defined in PEP 249, Python Database API Specification v2.0 (available from http://python.org/peps/pep-0249.html).

This section gives you an overview of the basics. I won’t cover the optional parts of the API, because they don’t apply to all databases. You can find more information in the PEP mentioned, or in the official Python Database Topic Guide (available from http://python.org/topics/ database). If you’re not really interested in all the API details, you can skip ahead to “Getting Started,” later in this chapter.

Global Variables

Any compliant (that is, compliant with the DB API, version 2.0) database module must have three global variables, which describe the peculiarities of the module. The reason for this is that the API is designed to be very flexible, and to work with several different underlying mechanisms without too much wrapping. If you want your program to work with several different databases, this can be a nuisance, because you have to cover many different possibilities. A more realistic course of action, in many cases, would be to simply check these variables to see that a given database module is acceptable to your program. If it isn’t, you could simply exit with an appropriate error message, for example, or raise some exception. The global variables are summarized in Table 13-1.

Table 13-1. The Module Properties of the Python DB API

The API level (apilevel) is simply a string constant, giving the API version in use. According to the DB API version 2.0, it may either have the value '1.0' or the value '2.0'. If the variable isn’t there, the module is not 2.0-compliant, and you should (according to the API) assume that the DB API version 1.0 is in effect. It also probably wouldn’t hurt to write your code to allow other values here; who knows when, say, version 3.0 of the DB API will come out . . .

The thread safety level (threadsafety) is an integer ranging from 0 to 3, inclusive. 0 means that threads may not share the module at all, and 3 means that the module is completely thread-safe. A value of 1 means that threads may share the module itself, but not connections (see “Connections and Cursors,” later), and 2 means that threads may share modules and connections, but not cursors. If you don’t use threads (which, most of the time, you probably won’t), you don’t have to worry about this variable at all.

The parameter style (paramstyle) indicates how parameters are spliced into SQL queries when you make the database perform multiple similar queries (more on that later). The value 'format' indicates standard string formatting (in the C tradition, as used in Python), so you

insert %s where you want to splice in parameters, for example. The value 'pyformat' indicates extended format codes, as used with dictionary splicing, such as %(foo)s. In addition to these Pythonic styles, there are three ways of writing the splicing fields: 'qmark' means that question marks are used, 'numeric' means fields of the form :1 or :2 (where the numbers are the numbers of the parameters), and 'named' means fields like :foobar, where foobar is a parameter name.

Exceptions

The API defines several exceptions, to make fine-grained error handling possible. However, they’re defined in a hierarchy, so you can also catch several types of exceptions with a single except block. (Of course, if you expect everything to work nicely, and you don’t mind having your program shut down in the unlikely event of something going wrong, you can just ignore the exceptions altogether.)

The exception hierarchy is shown in Table 13-2. The exceptions should be available globally in the given database module. For more in-depth descriptions of these exceptions, please see the API specification (the PEP mentioned previously).

Table 13-2. Exceptions Specified in the DB-API

Connections and Cursors

In order to use the underlying database system, you must first connect to it. For this you use the aptly named function connect. It takes several parameters; exactly which depends on the database. The API defines the parameters in Table 13-3 as a guideline. It recommends that they be usable as keyword arguments, and that they follow the order given in the table. The arguments should all be strings.

288 C H A P T E R 1 3 ■ D A T A B A S E S U P P O R T

Table 13-3. Common Parameters of the connect Function

You’ll see specific examples of using the connect function in the section “Getting Started” later in this chapter, as well as in Chapter 26.

The connect function returns a connection object. This represents your current session with the database. They support the methods shown in Table 13-4.

Table 13-4. Connection Object Methods

The rollback function may not be available, because not all databases support transactions. (Transactions are just sequences of actions.) If it exists, it will “undo” any transactions that have not been committed. The commit function is always available, but if the database doesn’t support transactions, it doesn’t actually do anything. If you close a connection and there are still transactions that have not been committed, they will implicitly be rolled back— but only if the database supports rollbacks! So if you don’t want to rely on this, you should always commit before you close your connection. If you commit, you probably don’t have to worry too much about closing your connection; it’s automatically closed when it’s garbage collected. If you want to be on the safe side, though, a call to close won’t cost you that many keystrokes . . .

The cursor function leads us to another topic: cursor objects. You use cursors to execute SQL queries and to examine the results. Cursors support more methods than connections, and probably will be quite a bit more prominent in your programs. Table 13-5 gives an overview of the cursor methods, and Table 13-6 gives an overview of the attributes.

Table 13-5. Cursor Object Methods

Table 13-6. Cursor Object Attributes

Some of these methods will be explained in more detail in the upcoming text, while some (such as setinputsizes and setoutputsizes) will not be discussed. Please consult the PEP for more details.

Types

In order to interoperate properly with the underlying SQL databases, which may place various requirements on the values inserted into columns of certain types, the DB API defines certain constructors and constants (singletons) used for special types and values. For example, if you want to add a date to a database, it should be constructed with (for example) the Date constructor of the corresponding database connectivity module. That allows the connectivity module to perform any necessary transformations behind the scenes. Each module is required to implement the constructors and special values shown in Table 13-7.