TurboGears 2.3 Hidden Gems #3 – Minimal Mode

Recently it has been pointed out to me that the Wikipedia TurboGears page was pretty outdate, so I ended up reading and updating a few sections. As that page reported a “2.x Components” section where Pylons was listed, I wasn’t sure what to do as it is not a component of TurboGears anymore since 2.3. Should I create a new “2.3+ Compoenents” section? Should I explain that it was used before? Then I realized that many people probably don’t even know that it got replaced and that gave me the idea of writing a blog post about the TurboGears2 Minimal Mode which is what replaced most of the Pylons functionalities in 2.3.

For people that didn’t follow TurboGears recent evolutions, the Minimal Mode is actually a micro-framework like configuration of TurboGears2 which has been available since version 2.3.

Minimal Mode was actually created as a side-effect of TurboGears becoming independent from Pylons while the team was also working on a major framework speed-up. Apart from the speed gain and opening the way to Python3, through Pylons removal, Minimal Mode proved itself to be quite convenient for rapidly prototyping Apps, HTTP APIs or showcase small examples. This is particularly visibile through the various Snippets that got created in Runnable.io TurboGears category.

The impact of the refactoring that lead to minimal mode is actually clear when comparing the TurboGears2 dependencies on a recent release


to the more than forty dependencies of one of the earliest 2.x releases


The new internal core made possible to greatly reduce dependencies to those that were really needed. Removing a few and moving some, that were only needed when special features were enabled, to the application itself.

By default TurboGears2 starts in full-stack mode, expecting the application to reside in a python package and enabling all the features that are commonly available to TurboGears2 applications. For backward compatibility reasons, minimal mode must be enabled explicitly through the minimal=True option. This ensures that all the apps created before 2.3 continue to work while the framework can be used as a micro-framework with minimum effort.

Another requirement is that the root controller must be explicitly passed, as TurboGears looks for it in the application package, and as we have no package configured it won’t be able to find any.

config = AppConfig(minimal=True, root_controller=RootController())

While tg.devtools and the gearbox quickstart command can continue to be used to create full stack applications, creating a minimal mode app is as easy as installing the TurboGears2 package itself and creating an application with any root controller (see TurboGears Documentation for a complete tutorial)

from tg import expose, TGController, AppConfig

class RootController(TGController):
    def index(self):
        return 'Hello World'

config = AppConfig(minimal=True, root_controller=RootController())

application = config.make_wsgi_app()

then the application can be served with a WSGI compatible server

from wsgiref.simple_server import make_server

print "Serving on port 8080..."
httpd = make_server('', 8080, application)

If people need additional features that TurboGears usually provide like sessions, caching, authentication, database, helpers and so on… they can enable them with a bunch of options available through the AppConfig object and only in that case additional dependencies like Beaker or SQLAlchemy are required.

The recently released 2.3.7 explicitly worked on making minimal mode easier to use, especially when database is involved. Before 2.3.7 you were required to have a package for your application from where the model could be imported, but now the model can actually be any object that exposes an init_model function. The TurboGears tutorial actually uses a Bunch object which is in fact a dictionary.

After playing around with the minimal mode for a bunch of small projects I realized that while many projects start small they quickly tend to became big, and being able to switch from a micro-framework to a full stack framework when needed, without actually changing framework at all, has proved a valuable feature. One that totally adheres the TurboGears mission of being “the web-framework that scales with you” 🙂

As not many people, even in TurboGears community, were comfortable with minimal mode I hope this post clarified a bit what it is minimal mode and how you can benefit from it.

Leave a Reply

Your email address will not be published. Required fields are marked *