How you get MySQL for Python depends on your operating system and the level of authorization you have on it. In the following subsections, we walk through the common operating systems and see how to get MySQL for Python on each.
Package managers are used regularly on Linux, but none come by default with Macintosh and Windows installations. So users of those systems can skip this section.
A package manager takes care of downloading, unpacking, installing, and configuring new software for you. In order to use one to install software on your Linux installation, you will need administrative privileges.
Administrative privileges on a Linux system can be obtained legitimately in one of the following three ways:
Log into the system as the root user (not recommended)
Switch user to the root user using
suUse
sudoto execute a single command as the root user
The first two require knowledge of the root user's password. Logging into a system directly as the root user is not recommended due to the fact that there is no indication in the system logs as to who used the root account. Logging in as a normal user and then switching to root using su is better because it keeps an account of who did what on the machine and when. Either way, if you access the root account, you must be very careful because small mistakes can have major consequences. Unlike other operating systems, Linux assumes that you know what you are doing if you access the root account and will not stop you from going so far as deleting every file on the hard drive.
Unless you are familiar with Linux system administration, it is far better, safer, and more secure to prefix the sudo command to the package manager call. This will give you the benefit of restricting use of administrator-level authority to a single command. The chances of catastrophic mistakes are therefore mitigated to a great degree.
Tip
More information on any of these commands is available by prefacing either man or info before any of the preceding commands (su, sudo).
Which package manager you use depends on which of the two mainstream package management systems your distribution uses. Users of RedHat or Fedora, SUSE, or Mandriva will use the RPM Package Manager (RPM) system. Users of Debian, Ubuntu, and other Debian-derivatives will use the apt suite of tools available for Debian installations. Each package is discussed in the following:
If you use SUSE, RedHat, or Fedora, the operating system comes with the yum package manager. You can see if MySQLdb is known to the system by running a search (here using sudo):
sudo yum search mysqldb
If yum returns a hit, you can then install MySQL for Python with the following command:
sudo yum install mysqldb
If you use Mandriva, you will need to use the urpm package manager in a similar fashion. To search use urpmq:
sudo urpmq mysqldb
And to install use urpmi:
sudo urpmi mysqldb
Whether you run a version of Ubuntu, Xandros, or Debian, you will have access to aptitude, the default Debian package manager. Using sudo we can search for MySQLdb in the apt sources using the following command:
sudo aptitude search mysqldb
On most Debian-based distributions, MySQL for Python is listed as python-mysqldb.
Once you have found how apt references MySQL for Python, you can install it using the following code:
sudo aptitude install python-mysqldb
Using a package manager automates the entire process so you can move to the section Importing MySQL for Python.
Windows users will need to use the older 1.2.2 version of MySQL for Python. Using a web browser, go to the following link:
http://sourceforge.net/projects/mysql-python/files/
This page offers a listing of all available files for all platforms. At the end of the file listing, find mysql-python and click on it. The listing will unfold to show folders containing versions of MySQL for Python back to 0.9.1. The version we want is 1.2.2.
Note
Windows binaries do not currently exist for the 1.2.3 version of MySQL for Python. To get them, you would need to install a C compiler on your Windows installation and compile the binary from source.
This is outside the purpose of the present book, but tips for how to do this are contained in the README file that accompanies the 1.2.3 version.
Click on 1.2.2 and unfold the file listing. As you will see, the Windows binaries are differentiated by Python version—both 2.4 and 2.5 are supported. Choose the one that matches your Python installation and download it. Note that all available binaries are for 32-bit Windows installations, not 64-bit.
After downloading the binary, installation is a simple matter of double-clicking the installation EXE file and following the dialogue. Once the installation is complete, the module is ready for use. So go to the section Importing MySQL for Python.
One of the easiest ways to obtain MySQL for Python is as an egg file, and it is best to use one of those files if you can. Several advantages can be gained from working with egg files such as:
They can include metadata about the package, including its dependencies
They allow for the use of egg-aware software, a helpful level of abstraction
Eggs can, technically, be placed on the Python executable path and used without unpacking
They save the user from installing packages for which they do not have the appropriate version of software
They are so portable that they can be used to extend the functionality of third-party applications
One of the best known egg utilities—Easy Install, is available from the PEAK Developers' Center at http://peak.telecommunity.com/DevCenter/EasyInstall. How you install it depends on your operating system and whether you have package management software available. In the following section, we look at several ways to install Easy Install on the most common systems.
On Ubuntu you can try the following to install the easy_install tool (if not available already):
shell> sudo aptitude install python-setuptools
On RedHat or CentOS you can try using the yum package manager:
shell> sudo yum install python-setuptools
On Mandriva use urpmi:
shell> sudo urpmi python-setuptools
You must have administrator privileges to do the installations just mentioned.
If you do not have access to a Linux package manager, but nonetheless have a Unix variant as your operating system (for example, Mac OS X), you can install Python's setuptools manually. Go to:
http://pypi.python.org/pypi/setuptools#files
Download the relevant egg file for your Python version.
When the file is downloaded, open a terminal and change to the download directory. From there you can run the egg file as a shell script. For Python 2.5, the command would look like this:
sh setuptools-0.6c11-py2.5.egg
This will install several files, but the most important one for our purposes is easy_install, usually located in /usr/bin.
On Windows, one can download the setuptools suite from the following URL:
http://pypi.python.org/pypi/setuptools#files
From the list located there, select the most appropriate Windows executable file.
Once the download is completed, double-click the installation file and proceed through the dialogue. The installation process will set up several programs, but the one important for our purposes is easy_install.exe. Where this is located will differ by installation and may require using the search function from the Start Menu.
On 64-bit Windows, for example, it may be in the Program Files (x86) directory. If in doubt, do a search. On Windows XP with Python 2.5, it is located here:
C:\Python25\Scripts\easy_install.exe
Note that you may need administrator privileges to perform this installation. Otherwise, you will need to install the software for your own use. Depending on the setup of your system, this may not always work.
Installing software on Windows for your own use requires the following steps:
Copy the setuptools installation file to your Desktop.
Right-click on it and choose the runas option.
Enter the name of the user who has enough rights to install it (presumably yourself).
After the software has been installed, ensure that you know the location of the easy_install.exe file. You will need it to install MySQL for Python.
After installing EasyInstall, you still need to install the MySQL for Python egg. The egg files for MySQL for Python can be downloaded from the following URL:
http://sourceforge.net/projects/mysql-python/files/
There you will see a list of all available files relevant to MySQL for Python.
Which one you use depends on your operating system and your installed Python version. Currently, the only egg files available for MySQL for Python version 1.2.3c1 are for Linux running either Python 2.5 or 2.6. Mac users should use a tarball (tar.gz) file as discussed in the next section.
To get an egg file for Windows, click on the MySQL-python directory and select the 1.2.2 version. This is the same directory used for the Windows binaries discussed earlier in this chapter. This time, however, you need to select an egg for Windows that fits either Python 2.4 or 2.5. There is no 2.6 version.
Once you have the egg file for MySQL for Python, you simply need to invoke EasyInstall over the newly-downloaded egg file. How you do that will depend on the permissions you have for your operating system.
With administrator permissions, you can simply call the EasyInstall binary. For Linux, it will look like this:
shell> easy_install <name of egg file>
For Windows, you will use a command similar to this one:
C:\Python25\Scripts\easy_install.exe <name of egg file>
Note that you must have administrator privileges to do this. Otherwise, Windows users will have to install the software locally. Linux users can use sudo.
EasyInstall will then unpack the archive, install it in your default Python installation folders, and configure it for immediate use.
For Windows users, if you had to install setuptools locally, you may also require a local installation of Python itself in order to install MySQL for Python. See the section On Microsoft Windows under Installing egg-handling software, for help with this. If you need to go through this process, all of your configurations will be local, so you are best to use full path command-line calls.
If your system has MySQL, Python, and setuptools, but you still don't have administrative access, it is advisable to unpack the egg file manually and call it as a local module. To do this, use an archiving program to unzip the file.
The content listing for the Windows egg will look like this:
Egg-infoMySQLdb_mysql_exceptions.py_mysql_exceptions.pyc_mysql.py_mysql.pyc_mysql.pyd
And the Linux egg unpacks to the following files:
Egg-infoMySQLdb_mysql_exceptions.py_mysql_exceptions.pyc_mysql.py_mysql.pyc_mysql.so
With the exception of the egg-info directory, the contents are the basic ingredients of a Python module and can be imported locally if one's program resides in the same directory as the files are located.
Due to the need for certain programming libraries, this method of installation applies only to users of Unix-derived operating systems. This method involves installing from the source files and so requires the necessary C libraries to compile a binary version. Windows users should therefore use one of the other methods discussed previously.
If you cannot use egg files or if you use an earlier version of Python, you should use the tar.gz file, a tar and gzip archive. The tar.gz archive follows the Linux egg files in the file listing. The current version of MySQL for Python is 1.2.3c1, so the file we want is as following:
MySQL-python-1.2.3c1.tar.gz
This method is by far more complicated than the others. If at all possible, use your operating system's installation method or an egg file.
This version of MySQL for Python is compatible up to Python 2.6. It is worth noting that MySQL for Python has not yet been released for Python 3.0 or later versions. In your deployment of the library, therefore, ensure that you are running Python 2.6 or earlier. As noted, Python 2.5 and 2.6 have version-specific releases. Prior to Python 2.4, you will need to use either a tar.gz version of the latest release or use an older version of MySQL for Python. The latter option is not recommended.
Most Unix-derived operating systems (Linux, Mac) come with the tar and gzip utilities pre-installed. For users of these systems, unpacking the archive is as simple as the following command:
shell> tar xvzf MySQL-python-1.2.3c1.tar.gz
The archive will then unpack into a directory called MySQL-python-1.2.3c1.
Windows users can use any of the following archive programs to unpack the tarball:
PowerArchiver 6.1
7-Zip
WinZip
Once the file is unpacked, you need to ensure that you have the program mysql_config in your path. For Mac users, this usually comes with the MySQL installation itself. For Linux, if you are using bash or another shell with command-line completion, you can check this by typing the following in a terminal:
shell> mysql_conf
Then press the tab key. If the command is completed to mysql_config, there are no issues, otherwise your operating system does not know of any such command, and you need to either find it or install it.
An alternative way of checking is to use the whereis command. Type the following from the command-line:
shell> whereis mysql_config
If it is installed, the system will return its location. Then echo your current PATH value by typing:
shell> echo $PATH
and compare the results. If the location of mysql_config is one of the values in your path, there are no issues otherwise, we need to either find it or install it.
The mysql_config program comes with the MySQL client development libraries. If you have these installed, check the directory that holds the MySQL client binary (use whereis mysql if necessary). If you are unsure, you can check with a package manager using the following commands:
shell> aptitude search mysql | grep client | grep dev
This will work for Debian-based systems. Users of RPM-based systems should substitute either yum search or urpmq for aptitude search. This query will return results for the development files and for the MySQL client, and you can then see if the appropriate package is installed. If it is not, you can install it with the install argument (for either aptitude or yum) or by using urpmi.
If the mysql_config program is installed, but is outside your path, you need to indicate its location to the MySQL for Python setup configuration. Navigate to the MySQL-python-1.2.3c1 directory and open the file site.cfg in your favorite text editor. The file is not large, and the following section is easily seen as the second part of the file:
#The path to mysql_config #Only use this if mysql_config is not on your PATH,or you have some weird setup that requires it #mysql_config = /usr/local/bin/mysql_config
If mysql_config is outside of your path, uncomment the last line of the part cited here and enter the correct path. So, if mysql_config is installed to:
/usr/local/bin/mysql/bin/mysql_config
The last line should read:
mysql_config = /usr/local/bin/mysql/bin/mysql_config
Then save the file and close it.
Next, we should build the package using the instructions that came with it in setup.py. Use the following command to attempt a build without installing it:
shell> python setup.py build
If the process goes through without error, which it usually does, the build is successful. If there is an error, it usually involves the lack of a module or software package. In which case, confirm that you have all the prerequisites needed for the task by checking the list in the readme file that comes with the archive.
Note
Be sure to read the readme file that comes with the source code. It contains a lot of help on the installation process.
Once the build is successful, installation can be done with the following command:
shell> python setup.py install