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!

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!

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