Importing MySQL for Python

The name of the project MySQL for Python is the current version of a project that began under the rubric MySQLdb. Consequently, unlike most Python modules, the MySQL for Python module is not called by its name, but by its historic handle. To import the module, insert the following into a Python program or simply type it in a following Python shell:

import MySQLdb

To make working with the module easier, you can also import it with an alias:

import MySQLdb as mysql

This allows us to use mysql instead of MySQLdb when we access parts of the module.

When you do this, several things will occur. You need not be concerned about most of them, but you should be aware that MySQLdb depends upon a module called _mysql. The _mysql module is largely a Python adaptation of the MySQL C API.

Tip

This is important to note because it is this API that you will access through MySQL for Python.

MySQL for Python is a wrapper for accessing the _mysql API. A wrapper is essentially a system of macros, or trusted code, that allows you to do common tasks quickly. It allows you to program without having to repeat commonly used or accessed variables and functions. The _mysql module is a powerful and proven way of accessing a MySQL database. However, controlling it within a Python program can pose a challenge for some, like driving a Formula 1 car for the first time. So consider MySQL for Python as a system that allows you to harness the power of a Formula 1 racing car even if you're merely driving a Hyundai.

Unlike some systems of macros, MySQL for Python still allows you to access the classes and functions of _mysql. This is due to the nature of Python's import functionality.

Accessing online help when you need it

As with other modules, Python is able to provide online help about MySQL for Python. In the following sections, we look at the MySQLdb and _mysql modules in greater depth using Python's built-in help() function.

MySQLdb

After importing MySQLdb, you can read over the documentation that accompanies the module. In a Python shell, type:

help(MySQLdb)

You will then see a manual page detailing all of the functions and classes of MySQL for Python. It is well worth giving this a cursory read to familiarize yourself with the module. In the course of this book, we will cover most of these items from various angles.

As the help page indicates, MySQLdb includes the following modules:

• connections: Initiating, maintaining, and closing a connection to MySQL

• cursors: Managing the execution of queries

• converters: For converting between MySQL data types as well as between data types in MySQL and Python

• times: Converting date and time values between MySQL and Python

Each of these is abstracted to the point of its own module in the source tree. Without a doubt, the most important part of the module is connections.py, without which we could not interface with MySQL. Where the others are static, the conversion module, convertors.py, allows you to define your own convertor on-the-fly.

The MySQLdb module itself has only one operating class that does not pertain to errors—DBAPISet. This is MySQLdb's internal object class for processing data. To interface with MySQL, however, we use functions. Of the several listed at the end of the MySQLdb help page, one uses connect() in every MySQLdb program.

At first glance, it may here be confusing to see that MySQLdb seems to have three ways of connecting with a database. In the list of functions, these are as follows:

• connect()

• Connection

• Connect

Knowing the ins and outs of these functions is not necessary. It is, however, important to know that they exist and to recognize that the latter two are simply different ways of transferring data to the first. Connect() then passes the arguments to the connections. Connection() class, MySQLdb's MySQL database connection class, in the connections.py module.

_mysql

In looking over the module, you may also note that reference is made to the _mysql module, but it is not explicitly detailed. This is because it is a dependency and not part of the module itself. However, you can access the documentation for _mysql without importing it directly by using the MySQLdb namespace:

help(MySQLdb._mysql)

In the previous discussion about connections.Connection(), we stopped following the trail of the connection and any ensuing data transmission where MySQLdb stopped. In reality, however, the data does not stop there. When a connection or operational request is received by connections.Connection(), it is processed and passed to _mysql and subsequently to the MySQL API in C to perform it.

To handle this interface, _mysql uses two classes:

• connection

• result

The first is used to establish communication with MySQL and thus returns a connection object. The second, as the name implies, returns a set containing the results from a MySQL command that a program sends. These results can be either the query results or an error. _mysql naturally passes the error to the calling process. In the case of MySQLdb, we then have a comprehensive toolbox to handle the errors that may arise.