TurboGears is one of several web frameworks for Python that are available. The most popular by far is Django. Where I work, we chose TurboGears because of its integration with SQLAlchemy which supports composite keys. At that time, Django did not support that feature and I am not sure if it does yet. Anyway, I develop almost exclusively on a Windows box and have found the TurboGears’ documentation on the subject a little confusing. So here’s how I do it.

Note: We’ll be using TurboGears 2.1 in this tutorial

Getting Started

We’re going to make sure Python is set up right first. Open a command window by going to Start –> Run and then typing “cmd” and pressing enter. Try typing “python” (without the quotes) in there and hitting your enter. If you see the Python shell, then we’re halfway there. If you don’t, then we need to modify some settings.

Modifying Your Path

On Windows, I have found that it helps a LOT to modify my Path settings by adding my Python path and the path to the Scripts folder to my Path. Here’s how you do it:

1. Right-Click “My Computer” and choose Properties (Windows XP) or you may have to go digging in Control Panel on Windows 7 and do a “Show All Control Panel Items” from the path bar and look for System. You should see something like this:

   

2. Go to the Advanced tab and press the Environmental Variable button to see something like the following:

   

3. You will see two types of variables here. In the bottom section are System Variables. Scroll down to the one labeled Path and at the end of that, add the following two lines: ;C:\Python26;C:\Python26\Scripts (adjust as necessary according to your version of Python and its location) Note that each entry is separated by a semi-colon, so make sure you do that too or this will not work!

Installing Prerequisites

Once that’s done, we need to make sure you have SetupTools installed. Go to the Python Package Index and download it if you know you don’t already have it as SetupTools will install a little script known as easy_install that will make getting TurboGears setup a breeze. Just scroll to the end of the page and pick the exe that corresponds to your Python version. You cannot install an egg unless you already have this installed, so I don’t know why they have eggs on there to begin with.

Once that’s done, open a new command window and try typing in the following: easy_install. You should receive an error like this: “error: No urls, filenames, or requirements specified (see –help)” If you do, then you’ve got it installed and on your path. Good job!

The TurboGears people recommend installing virtualenv to help keep your primary Python installation (PyPI) as pristine as possible. It also helps when you need to experiment with different versions of software that you don’t want to break current projects. How does this work? Well, virtualenv creates a little virtual workspace for you on your machine where it puts a copy of Python and installs all the software into that virtual place for you to play with. It’s a development sandbox! Since you now have easy_install, we’ll use that to install it. In your command window, type: easy_install virtualenv

That will cause easy_install to go out on the internet and try to download and install virtualenv from PyPI. It should look something like this:

If it completed successfully, then we’re ready to create a virtual environment for our TurboGears install. Change directories to a location that you’d like to do this in. On Windows 7, you’ll probably have security issues if you try to do this outside of your Documents or similar Collections folders, so you should stick with one of those. For this tutorial, we’ll create it in My Documents.

Once you’re there, type the following: virtualenv –no-site-packages example

This will create a folder that’s labeled “example” with several folders inside it. You should see the following on your screen:

The –no-site-packages command will prevent the virtual environment from inheriting anything from the system Python’s site-packages folder. Now change directory into your example folder in the command window and type the following: Scripts\activate.bat (see screenshot below)

Installing & Setting Up TurboGears

Now your virtual environment is active and ready to rock. You can tell because each line is now prefixed with the name of the folder you’re in, which in this case is “example”. You can install Turbogears at this point as your virtual environment also has Setup Tools installed. However, this install is a little different as we will be specifying a specific URL. Type the following (you may want to check the TurboGears website to see if the URL has been updated since the writing of this post):


easy_install.exe -i http://www.turbogears.org/2.1/downloads/current/index tg.devtools


Depending on the speed of your PC and your connection, this will take a while. TurboGears is a mashup of a large number of 3rd party Python packages. You can watch it install or you can go get a drink or make a phone call while you wait. Once that’s finished, we’re nearly done.

Note: All the packages should be installing to your virtual space’s lib folder, NOT your default Python’s. If the latter is happening, you probably don’t have the virtual environment activated

Creating a TurboGears Workspace

One of the packages we installed earlier was Python Paste. TurboGears uses this package to bootstrap a new TurboGears application. So in your activated virtual environment, type the following command:


paster quickstart example


Note: If your path to the “example” folder has a space in it, you will receive an error about needing the PyWin32 library installed. Very annoying.

When you run this, you will need to answer 3 questions. The first is what to name the project. The default is the same name as the folder. Note that the project name has to be in lowercase. Then it asks if you’d like to use Mako templates. What it doesn’t say is that if you choose no (which is the default), you will get Genshi templates instead. That’s up to you. Mako looks and feels more “pythonic” from what I’ve seen of it, so I’d recommend it unless you already know Genshi or something like Genshi. The last question is whether or not you want authentication, which will give you a simple admin interface that you can login to, the default of which is “yes”. You can experiment with these or just take the defaults.

The next step is to change directories into your new project directory and then type the following in at the command line:


python setup.py develop


This adds your project to the virtual environment and also downloads a few packages to install alongside it that might be useful in your development. I don’t really know how these help you, but it seems to be a requirement of sorts according to TurboGear’s documentation.

The next to last step is to input the following into your command line window:


paster setup-app development.ini


This will initiate your database, which is basically just creating and populating with some default information for the security / authentication you agreed to. If you didn’t install that stuff or don’t want to run this step, you don’t have to. But you won’t be able to login unless you do.

Finally, you need to type the following:


paster serve development.ini


Now you will have a fully functioning website that’s running on http://localhost:8080/ (or http://127.0.0.1:8080) . If you load up your browser and navigate to that you should see something like this:

Wrapping Up

Now you should know how to install and setup a TurboGears web application. The sky’s the limit after all that work. You’ll need to start reading the documentation, add a dash of javascript and a bit of CSS and you’ll have a cool website in no time. Good luck and have fun!

This week’s Python news covers new modules, updates to old modules, a newish Python Magazine (no, not that one!), an update on what’s going on with the new wxPython and more!

• “TurboGears Joins the Pylons Project” (Alt title: TurboGears Becomes TurboPyramid). I think the title says it all…and no, they didn’t really rename the project.
• wxPython’s “Project Phoenix” gets an update – this gives an update on how Robin Dunn is moving away from SWIG to make it easier to do documentation and the Python 3 port.
• Michael Foord’s new “e” module makes a debut…read all about it on his blog
• PET: Issue #1 – English translation of a magazine created by the Argentina Python Users Group. Yes, this is kind of old news, but I thought it was really cool and it needs YOUR support!

.

• The PSF blog talks about high schoolers using Python to program robots under the guidance of Vern Ceder
• PyCrypto gets a Python 3 port courtesy of Thorsten Behrens. Check out the thread and download your copy to help find any bugs!

That’s it for this week. Next time we’ll be in 2011! That’s amazing! Anyway, I hope you have a nice holiday and you’ll let me know of any Python news that I should talk about for the next post. Thanks!

On Thursday, July 1st, we had our July Pyowa meeting. It was hosted by Matt Morrison at the IMT Group’s building in Des Moines, IA. We had our largest attendance ever with a total of 15 men showing up. Tavern Pizza and pop were served, which was also a first…we’ve had pop before, just not any food!

We had two presentations. The first was an around 70 minutes in length and covered introductory materials about Django, a full-stack web framework written in Python. It was given by our host and he also included anecdotes about how his company uses Django and what challenges that has presented him. Next up we had a quick talk about TurboGears, another web framework. TurboGears is actually a collection of various Python modules that have been pieced together, which makes it much more modular than Django. However, Django has a lot more users behind it and there are some definite advantages to having everything builtin. Anyway, the TurboGears presentation covered a group of different web sites (or web applications) that the presenter had created. It was interesting to compare and contrast the two frameworks and see how they differed or stayed the same.

We are currently looking for presenters for our August and September meetings, so if you want to talk about how you’re using Python now, in the past or even what you plan to do with it in the future, let me know by emailing me or in the comments!

Last month I found some issues with the TurboGears 2 documentation and the guys on the TG IRC channel told me I should download the docs and do something about it. Alas, I didn’t know what I was doing, but with their guidance I got the code and it was mostly set up. Then my work got in the way and I forgot all about it. Yesterday I got into another conversation about the sad shape the docs are in on the same IRC channel and this time I decided to do it right. Here’s how you can get set up so you can help too!

If you just want to jump in, read the short directions at the end.

First, you need to have virtualenv and setuptools installed in your default python install. Virtualenv allows you to create a “virtual” environment with it’s own copy of python and a virgin set of libraries. Why would you want to do this? Because it makes experimenting with packages much easier. You can download and try anything you like without screwing up your main installation and if you find you don’t like the package, you just delete the folder that contains the virtual environment. Setuptools is needed for easy_install purposes, which is something that TurboGears utilitizes a lot.

Once you have that stuff downloaded and installed, open up a command window (or shell) and navigate to a location where you’d like to create a virtual environment. Then type the following where “exampleFolder” is the name of the folder you want to create the virtual environment in.


virtualenv --no-site-packages exampleFolder


The “–no-site-packages” flag tells virtualenv that you do not want to copy your entire tree of site-packages from your main python installation. I recommend this as I have lots of stuff in my site-packages that I don’t want in my virtualenv.

Next, you need Sphinx and you can’t just use the current 0.6.2 version as it doesn’t work right with the TG2 (as of 07/16/2009). Instead, you’ll need 0.6.2+, which you can get here. To download the source from bitbucket, you’ll need Mercurial. I recommend getting the command line version as the GUI tended to mess up file open dialogs on my Windows box due to the way Mercurial did shell overlays (it also screwed up WingWare IDE). This may be fixed now. Once you have Mercurial, follow the “hg clone” directions on the site linked above. Then change directories until your inside the source and run “python setup.py install” to install Sphinx.

The next step is to get the docs themselves. You have two choices. You can go with the ones on TG2′s main website, or you can get mpedersen’s set. Just so you know, mpedersen is the IRC handle of the guy who has volunteered to lead the effort in the documentation clean-up. The only difference is that his set will have fixes already in it along with a todo list on each page. I recommend his so that the duplication of effort will be at the minimum. You use the same “hg clone” command there as you did for the hacked Sphinx source in the last step.

The next to last step is to download the TG2-dev source and install it. Here’s the Mercurial command to get the source:


hg clone http://bitbucket.org/mramm/tg-21/


Now just install it like you did with Sphinx above. Note that the dev code depends on SqlAlchemy and doesn’t install it automagically, so be sure to easy_install that as well.

We’re almost there now. The last step is to build the docs. To do this, navigate into the “docs” sub-folder of the docs you downloaded and run the following command (or if you’re on Linux, use “make html”):


sphinx-build -b html -d _build/doctrees . _build/html


Now you can browse the html versions of the docs! Remember, to edit the docs, you must edit the rst files, not the html ones. When you’re ready to contribute them back, you’ll use the “hg push” command. I haven’t done this part, so hit up mpedersen on the turbogears IRC channel for more info.

To recap, here’s a short list of what you need to do:

1) Create a clean virtualenv and activate it
2) Download Sphinx 0.6.2+ from https://bitbucket.org/birkenfeld/sphinx-06/
3) Get the docs from the main website or from mpedersen
4) The dev source depends on SqlAlchemy, so easy_install that
5) Get the TG2-dev source and install it
6) Go into the downloaded TG2 docs sub-folder and run
“sphinx-build -b html -d _build/doctrees . _build/html”
(without the quotes)
7) And you’re done!

Last week, I embarked on an adventure into the world of web application programming. Since my work place uses Python as much as possible and my boss likes TurboGears, I chose it for this endeavor. I have worked through various TurboGears tutorials and thought it looked pretty cool. However, it doesn’t take long to discover that there is a lot of undocumented functionality. In this case, I needed a web application that could access multiple databases. I knew SqlAlchemy could do it and since TG2 uses SqlAlchemy, I figured it would too. In this article you will get to travel down the rabbit hole with me as I explain how I figured it out.

When you go looking for help, the first article Google is likely to return is Mark Ramm’s blog post about how easy it is to do. However, Ramm does not actually explain how to do it. Another fellow on the TurboGears Google Group posted a link to the Pylons way of setting up multiple databases. If you go there, you’ll find out that the first step is set up multiple SqlAlchemy URLs in your config file, which in the case of TurboGears is your development.ini file. All you need to do is add one or more SqlAlchemy URLs to the [app:main] section.

So, instead of this:


sqlalchemy.url = sqlite:///%(here)s/devdata.db


You would do something like this:


sqlalchemy.first.url=mssql://user:password@ntsql.servername.com/database
sqlalchemy.second.url=sqlite:///%(here)s/devdata.db


Notice that you add to the dot notation to make the URLs unique. I think the “sqlalchemy” and “url” parts are required at the beginning and the end, but the rest can be whatever you want. If that was all you needed to do, this would indeed be an easy setup. However, we have a couple more files to modify. The next part was pretty tricky. I discovered that there’s some comments on multiple databases in the model folder’s __init__.py file. It claims that you need to create a new MetaData object, which is true, but the commented out example is misleading. In the example, the metadata is not bound to an engine object. Without that info, the metadata object will be basically useless. I then noticed the init_model method which is there for reflection purposes. Upon further digging, I found that you needed to modify it to pass in the engines needed for your various databases, This is where I ended up putting my new metadata object. Technically, you could create it before the method and then just make it global, but I didn’t need that in my test case. Change yours as needed. Following are the changes I needed to make:

# Global session manager: DBSession() returns the Thread-local
# session object appropriate for the current web request.
maker = sessionmaker(autoflush=True, autocommit=False,
                     extension=ZopeTransactionExtension())
DBSession = scoped_session(maker)
 
maker2 = sessionmaker(autoflush=True, autocommit=False,
                      extension=ZopeTransactionExtension())
secondSession = scoped_session(maker2)
 
def init_model(engineOne, engineTwo):
    """Call me before using any of the tables or classes in the
    model."""
 
    DBSession.configure(bind=engineOne)
 
    secondSession.configure(bind=engineTwo)
 
    # you only need this metadata
    # if you want to autoload a table
    second_metadata = MetaData(engineTwo)

The last file that should be edited is the “app_cfg.py” located in the config folder. Here you need to subclass the “AppConfig” object to override the “setup_sqlalchemy” method. This is required only if you have modified your init_model method (above) to accept multiple engines. If you do not do this, you’ll receive a lovely traceback about your method needing additional parameters. Here’s my code:

from pylons import config as pylons_config
from tg.configuration import config
 
class MyAppConfig(AppConfig):
    def setup_sqlalchemy(self):
        """Setup SQLAlchemy database engine."""
        from sqlalchemy import engine_from_config
        engineOne = engine_from_config(pylons_config, 'sqlalchemy.first.')
        engineTwo = engine_from_config(pylons_config, 'sqlalchemy.second.')
        config['pylons.app_globals'].engineOne = engineOne
        config['pylons.app_globals'].sa_engine = engineTwo
        # Pass the engine to initmodel, to be able to introspect tables
        init_model(engineOne, engineTwo)
 
base_config = MyAppConfig()

It should be noted here that the default websetup.py file is hardwired to use a variable called “sa_engine” when you’re using authentication. Thus, I assign one of the engines to that variable above. You could also go into websetup.py and just edit it as needed to accept whatever customizations are required. I do not know if there are additional files that need to be modified as this I ended up just changing the variable name above rather than mess with additional issues like this one.

Once all that is done, you should be good to go. On the TurboGears IRC, one of the members there mentioned a way to use multiple databases by “calling setup twice”. He didn’t explain how this worked, so I don’t know if it is simpler, but if you want to investigate this method and report back, that’s fine by me. I went ahead and created some dummy files with my changes so you can see then in context. They are downloadable below:

Sample files as zip or tar