Web Application Framework or simply Web Framework represents a collection of libraries and modules, which enables a web application developer to write applications, without having to bother about low level details such as protocols, thread management, etc.
What is TurboGears?
TurboGears is a web application framework written in Python. Originally created by Kevin Dangoor in 2005, its latest version TurboGears (ver 2.3.7) is managed by a group of developers led by Mark Ramm and Florent Aide.
TurboGears follows the Model-View-Controller paradigm as do most modern web frameworks like Rails, Django, Struts, etc.
Model View Controller
MVC is a software design pattern for developing web applications. A Model View Controller pattern is made up of three parts −
Model − The lowest level of the pattern is responsible for maintaining data.
View − This is responsible for displaying all or a portion of data to the user.
Controller − Software Code that controls the interactions between the Model and View.
MVC is popular as it isolates the application logic from the user interface layer and supports separation of concerns. Here, the Controller receives all requests for the application and then works with the Model to prepare any data needed by the View. The View then uses the data prepared by the Controller to generate a final presentable response. The MVC abstraction can be graphically represented as follows −
The Model
The Model is responsible for managing the data of the application. It responds to the request from the view and it also responds to instructions from the controller to update itself.
The View
A presentation of data in a particular format, triggered by a controller's decision to present the data. They are script based templating systems very easy to integrate with AJAX technology.
The Controller
The controller is responsible for responding to the user input and perform interactions on the data model objects. The Controller receives the input, it validates the input and then performs the business operation that modifies the state of the data model.
TurboGears is built on top of a number of libraries and tools. These tools have changed between different versions of TurboGears. The components of current version (ver 2.3.7) are listed below.
SQLAlchemy
It is an open source SQL kit that provides Object relation mapping (ORM) for Python code.
Genshi
This templating engine is used to construct the front-end of TG applications. A web templating system combines a template with a certain data source to render dynamic web pages.
ToscaWidgets
It is a widget library for generating HTML forms with server side controls. Tosca also acts as a middleware to connect with JavaScript widgets and toolkits.
Gearbox
It provides a set of commands to manage projects and server TurboGears applications. TurboGears applications can be deployed on any WSGI compliant web server.
The Web Server Gateway Interface (WSGI) has been adopted as a standard for Python web application development. WSGI is a specification for universal interface between web server and web applications. The wsgiref package is a reference implementation of WSGI. It is used to add WSGI support to web TurboGears web framework. The simple_server module in this package implements a simple HTTP server that serves WSGI applications. We shall be using it to test applications developed during this tutorial.
TurboGears - Environment
Prerequisite
Python 2.6 or higher. Earlier versions of TurboGears were not compliant with Python 3.X. Latest version claims to work well on Python 3.X. However, official documentation of TurboGears is still based on Python 2.7 environment.
The following command installs virtualenv −
pip install virtualenv
This command needs administrator privileges. Add sudo before pip on Linux/Mac OS. If you are on Windows, log in as Administrator. On Ubuntu virtualenv may be installed using its package manager.
Sudo apt-get install virtualenv
Once installed, the new virtual environment is created in a folder.
mkdir newproj
cd newproj
virtualenv venv
To activate corresponding environment, on Linux/OS X
venv/bin/activate
on Windows
venv\scripts\activate
We are now ready to install TurboGears in this environment. A minimal installation of TurboGears is done by following command −
pip install TurboGears2
The above command can be run directly without virtual environment for system wide installation.
To install TurboGears along with development tools, use following command −
pip install tg.devtools
TurboGears - First Program
TurboGears has a minimal mode that makes it possible to create single file applications quickly. Simple examples and services can be built quickly with minimal set of dependencies.
Application class in a TG application is inherited from TGController class. Methods in this class are available for access by @expose decorator from tg module. In our first application, index() method is mapped as root of our application. The TGController class also needs to be imported from tg module.
from tg import expose, TGController
class MyController(TGController):
@expose()
def index(self):
return 'Hello World turbogears'
Next, set the application’s configuration and declare application object. AppConfig class constructor here takes two parameters – minimal attribute set to true and the controller class.
The make_wsgi_app() function here constructs application object.
In order to serve this application, we now need to start the HTTP server. As mentioned earlier, we shall use simple_server module in wsgiref package to set up and start it. This module has make_server() method which requires port number and application object as arguments.
from wsgiref.simple_server import make_server
server = make_server('', 8080, application)
server.serve_forever()
It means that our application is going to be served at port number 8080 of localhost.
The following is the complete code of our first TurboGears application −
app.py
from wsgiref.simple_server import make_server
from tg import expose, TGController, AppConfig
class MyController(TGController):
@expose()
def index(self):
return 'Hello World TurboGears'
config = AppConfig(minimal = True, root_controller = MyController())
application = config.make_wsgi_app()
print "Serving on port 8080..."
server = make_server('', 8080, application)
server.serve_forever()
Run the above script from Python shell.
Python app.py
Enter http://localhost:8080 in browser’s address bar to view ‘Hello World TurboGears’ message.
The tg.devtools of TurboGears contains Gearbox. It is a set of commands, which are useful for management of more complex TG projects. Full stack projects can be quickly created by the following Gearbox command −
gearbox quickstart HelloWorld
This will create a project called HelloWorld.
TurboGears - Dependencies
A TurboGears project contains the following directories −
Config − Where project setup and configuration relies
Controllers − All the project controllers, the logic of web application
i018n − Translation files for the languages supported
Lib − Utility python functions and classes
Model − Database models
Public Static Files − CSS, JavaScript and images
Templates − Templates exposed by our controllers.
Tests − The set of Tests done.
Websetup − Functions to execute at application setup.
How to Install a project
This project now needs to be installed. A setup.py is already provided in project’s base directory. Project dependencies get installed when this script is executed.
Python setup.py develop
By default, following dependencies are installed at the time of project set up −
Beaker
Genshi
zope.sqlalchemy
sqlalchemy
alembic
repoze.who
tw2.forms
tgext.admin ≥ 0.6.1
WebHelpers2
babel
After installation, start serving the project on development server by issuing following command in shell −
Gearbox serve –reload –debug
Follow the above mentioned command to serve a pre-built example project. Open http://localhost:8080 in browser. This readymade sample application gives a brief introduction about TurboGears framework itself.
In this Hello project, the default controller is created in controllers directory as Hello/hello/controllers.root.py. Let us modify root.py with following code −
from hello.lib.base import BaseController
from tg import expose, flash
class RootController(BaseController):
movie = MovieController()
@expose()
def index(self):
return "<h1>Hello World</h1>"
@expose()
def _default(self, *args, **kw):
return "This page is not ready"
Once a basic working application is ready, more views can be added in the controller class. In the Mycontroller class above, a new method sayHello() is added. The @expose() decorator attaches /sayHello URL to it. This function is designed to accept a name as a parameter from the URL.
After starting server through ‘gearbox serve’ command, http://localhost:8080. Hello World message will be displayed in the browser, even if the following URLs are entered −
http://localhost:8080/
http://localhost:8080/index
All these URLs are mapped to RootController.index() method. This class also has _default() method that will be invoked, whenever a URL is not mapped to any specific function. Response to URL is mapped to a function by @expose() decorator.
It is possible to send a parameter to an exposed function from the URL. The following function reads the name parameter from URL.
The following output will be seen in the browser as response to the URL − http://localhost:8080/?name=MVL
Hello MVL
TurboGears automatically maps URL parameters to function arguments. Our RootController class is inherited from BaseController. This is defined as base.py in the lib folder of application.
TGController.__call__ dispatches to the Controller method the request is routed to.
TurboGears - Serving Templates
An Event though HTML content can be returned to the browser, for more advanced output, the use of template engine is always preferred. In a full stack project ‘quickstarted’ by gearbox, Genshi is enabled as the default template renderer. In a minimal application, however Genshi (or any other template engine, such as jinja) needs to be installed and enabled. Genshi template engine permits to write templates in pure xhtml and validates them to detect issues at compile time and prevent serving broken pages.
Templates are referred to by using a dotted notation. In our Hello project a templates directory is provided to store template web pages. Hence sample.html will be referred as hello.templates.sample (extension not mentioned). TurboGears renders this template through an expose decorator to link controller method to it by tg.render_template() function.
The exposed controller function returns a Python dictionary object. This dictionary object is in turn passed on to the linked template. Placeholders in template are filled with dictionary values.
To begin with, let us display a web page with plain html script. The exposed controller returns a null dictionary object as we do not intend to send any data to be parsed inside the HTML script.
How to Creat a Sample HTML
Our sample.html is given below. Ensure that it is stored in templates directory of project.
The following result will be displayed in the browser when a URL http://localhost:8080/sample is entered after starting the web server.
As mentioned above, a dictionary object is sent as collection of parameters to a Genshi template. This template contains ‘place holders’, which are dynamically filled with parameters received from the controller.
Let us change the sample() function to send a dictionary object to the sample template.
Create sample.html in templates folder (templates\sample.html)
<html>
<head>
<title>TurboGears Templating Example</title>
</head>
<body>
<h2>Hello, my name is ${person}!.</h2>
</body>
</html>
In the above HTML code, ${person} is the placeholder. Enter http://localhost:8080/sample?name=MVL as URL in the browser. This URL is mapped to sample() method in our root controller. It returns a dictionary object. This is picked by linked template page sample.html in templates directory. The ${person} is then substituted by MVL in the web page.
It is also possible to access the HTML form data in a controller function. HTML form uses to send form data.
TurboGears - HTTP Methods
Http Protocol is the foundation of data communication in world wide web. Different methods of data retrieval from specified URL are defined in this protocol. Following table summarizes different http methods −
Sr.No.
HTTP Methods & Description
1
GET
Sends data in unencrypted form to the server. Most common method.
2
HEAD
Same as GET, but without response body
3
POST
Used to send HTML form data to server. Data received by POST method is not cached by server.
4
PUT
Replaces all current representations of the target resource with the uploaded content.
5
DELETE
Removes all current representations of the target resource given by a URL
Creating an HTML Form
Let us create an HTML Form and send form data to a URL. Save the following script as login.html
<html>
<body>
<form action = "http://localhost:8080/login" method = "get">
<p>Enter Name:</p>
<p><input type = "text" name = "nm" /></p>
<p><input type = "submit" value = "submit" /></p>
</form>
</body>
</html>
Data entered in this form is to be submitted to ‘/login’ URL. Now create a controller function loginpage() and expose the above html page to it.
In order to receive the form data, provide a login() controller, which has form attributes as its parameters. Here ‘nm’ is name of text input field in login form, the same is used as a parameter of login() function.
@expose("hello.templates.sample")
def login(self, nm):
name = nm
return {'person':name}
As it can be seen, data received from login form is being sent to sample.html template (used earlier). It is parsed by a Genshi template engine to generate the following output −
POST Method
When HTML form uses POST method to dispatch data to the URL in action attribute, the form data is not exposed in URL. The encoded data is received in a dict argument by the controller function. The **kw argument below is the dictionary object holding for data.
HTML form contains two input text fields.
<html>
<body>
<form action = "http://localhost:8080/marks" method = "post">
<p>Marks in Physics:</p>
<p><input type = "text" name = "phy" /></p>
<p>Marks in Maths:</p>
<p><input type = "text" name = "maths" /></p>
<p><input type = "submit" value = "submit" /></p>
</form>
</body>
</html>
The marks() controller receives form data and sends it to sample.html template. Code for root.py is as follows −
<html>
<head>
<title>TurboGears Templating Example</title>
</head>
<body>
<h2>Hello, Welcome to TurboGears!.</h2>
<h3>Marks in Physics: ${phy}.</h3>
<h3>Marks in Maths: ${maths}.</h3>
<h3>Total Marks: ${total}</h3>
</body>
</html>
Start the server (if not already running)
Gearbox server –reload –debug
Enter http://localhost::8080/marksform in browser
The sample.html will render following output −
TurboGears - Genshi Template Language
Genshi is a XML based template language. It is similar to Kid, which used to be the template engine for earlier versions of TurboGears. Genshi as well as Kid are inspired by other well-known template languages like HSLT, TAL and PHP.
A Genshi template consists of processing directives. These Directives are elements and attributes in a template. Genshi directives are defined in a namespace http://genshi.edgewall.org/ . Hence this namespace needs to be declared in the root element of template.
Above declaration means that default namespace is set to XHTML and Genshi directives have ‘py’ prefix.
Genshi Directives
A number of directives are defined in Genshi. Following list enumerates Genshi directives −
py:if
py:choose
py:for
py:def
py:match
py:with
py:replace
py:content
py:attrs
py:strip
Conditional Sections
Genshi provides two directives for conditional rendering of content− py:if and py:choose.
py:if
The contents of this directive’s element will be rendered only if the expression in if clause evaluates to true. Assuming that data in the template context is {‘foo’:True, ‘bar’:’Hello’}, the following directive −
<div>
<b py:if = "foo">${bar}</b>
</div>
will result in
Hello
This output, however would not be rendered if ‘foo’ is set to False.
This directive can also be used as element. In this case <py:if> must be closed by corresponding </py:if>
<div>
<py:if test = "foo">
<b>${bar}</b>
</py:if>
</div>
py:choose
The advanced conditional processing is possible with the use of py:choose in combination with py:when and py:otherwise directives. This feature is similar to switch – case construct in C/C++.
Expression in py:choose directive is checked with different values identified with py:when alternatives and corresponding contents will be rendered. A default alternative can be provided in the form of py:otherwise directive.
The following example illustrates use of py:choose and py:when directives. The HTML form posts data to /marks URL. The marks() function redirects marks and results in the form of a dictionary object to total.html template. The conditional display of result Pass/Fail is achieved by using py:choose and py:when directives.
HTML script of entering marks (marks.html) is as follows −
<html>
<body>
<form action = "http://localhost:8080/marks" method = "post">
<p>Marks in Physics:</p>
<p><input type = "text" name = "phy" /></p>
<p>Marks in Maths:</p>
<p><input type = "text" name = "maths" /></p>
<p><input type = "submit" value = "submit" /></p>
</form>
</body>
</html>
The complete code of root.py is as follows. The marks() controller is sending marks and result to total.html template −
Enter http://localhost::8080/marksform in browser −
The total.html will render following output −
py:for
Element in py:for directive is repeated for each item in an iterable, typically a Python List object. If items = [1,2,3] is present in a template context, it can be iterated upon by following py:for directive −
<ul>
<li py:for = "item in items">${item}</li>
</ul>
The following output will be rendered −
1
2
3
The following example shows HTML form data rendered in total.html template using py:for directive can also be used as follows −
<py:for each = "item in items">
<li>${item}</li>
</py:for>
HTML Form Script
<html>
<body>
<form action = "http://localhost:8080/loop" method="post">
<p>Marks in Physics:</p>
<p><input type = "text" name = "phy" /></p>
<p>Marks in Chemistry:</p>
<p><input type = "text" name = "che" /></p>
<p>Marks in Maths:</p>
<p><input type = "text" name = "maths" /></p>
<p><input type = "submit" value = "submit" /></p>
</form>
</body>
</html>
The loop() controller reads form data and sends it to total.template in the form of a list object.
from hello.lib.base import BaseController
from tg import expose, request
class RootController(BaseController):
@expose("hello.templates.marks")
def marksform(self):
return {}
@expose("hello.templates.temp")
def loop(self, **kw):
phy = kw['phy']
maths = kw['maths']
che = kw['che']
l1 = []
l1.append(phy)
l1.append(che)
l1.append(maths)
return ({'subjects':['physics', 'Chemistry', 'Mathematics'], 'marks':l1})
The temp.html template uses py:for loop to render contents of dict object in the form of a table.
<html xmlns = "http://www.w3.org/1999/xhtml"
xmlns:py = "http://genshi.edgewall.org/" lang = "en">
<body>
<b>Marks Statement</b>
<table border = '1'>
<thead>
<py:for each = "key in subjects"><th>${key}</th></py:for>
</thead>
<tr>
<py:for each = "key in marks"><td>${key}</td></py:for>
</tr>
</table>
</body>
</html>
Start the server (if not already running)
gearbox server –reload –debug
Enter http://localhost::8080/marksform in the browser.
The following output will be displayed in the browser when the above form is submitted.
py:def
This directive is used to create a macro. A macro is a reusable snippet of template code. Much like a Python function, it has a name and can optionally have parameters. Output of this macro can be inserted at any place in a template.
The py:def directive follows the following syntax −
Given bar = ’Bye’ in the context data, it would produce
<div>
Bye
</div>
TurboGears - Includes
Contents of another XML document (especially HTML document) can be included by using inclusion tags in the current document. In order to enable such an inclusion, XInclude namespace must be declared in the root element of the HTML document.
The above declaration specifies that include directive contains ‘xi’ prefix. To add contents of another html page in the current document, use xi:include directive as follows −
<xi:include href = "somepage.html" />
In the following example, root.py contains include() controller, which exposes include.html.
from hello.lib.base import BaseController
from tg import expose, request
class RootController(BaseController):
@expose('hello.templates.include')
def include(self):
return {}
Heading and Footer HTML
In include.html, include namespace is declared and contents of heading.html and footer.html are added. Here is the HTML script of templates\include.html −
Start the development using a gearbox and enter http://localhost:8080/include in the browser. The output rendered will be as shown below −
This way the modular construction of views can be achieved. If the resource mentioned in xi:include directive is not available, an error will be raised. In such a case an alternative resource may be loaded by using xi:fallback.
Before starting the server make sure that templates folder has a heading.html, main.html and footer.html. Enter http://localhost:8082/refinclude in the browser to get the following output
TurboGears - JSON Rendering
The @expose() decorator by default renders html content. However, this can be set to json content type. TurboGears supports json rendering through tg.jsonify.JSONEncoder (**kwargs) class. To render json data simply pass json as content type to expose decorator.
If '/jsondata' URL is entered in browser, it will respond by showing −
{"hello": "World"}
jsonp Rendering
jsonp stands for json with padding. It works similar to json output except for the fact that it provides an application/javascript response with a call to a javascript function providing all the values returned by the controller as function arguments.
To enable jsonp rendering you must first append it to the list of required engines inside your application – config/app_cfg.py −
When accessing /jsonpdata?callback = callme, you should see −
callme({"hello": "World"});
TurboGears - URL Hierarchy
Sometimes, a web application may require a URL structure that is having more than one level. TurboGears can traverse object hierarchy to find appropriate method that can handle your request.
A project ‘quickstarted’ with gearbox has a BaseController class in project’s lib folder. It is available as ‘Hello/hello/lib/base.py’. It serves as base class for all sub controllers. In order to add a sub level of URL in application, design a sub class called BlogController derived from BaseController.
This BlogController has two controller functions, index() and post(). Both are designed to expose a template each, blog.html and post.html.
Note − These templates are put inside a sub folder − templates/blog
class BlogController(BaseController):
@expose('hello.templates.blog.blog')
def index(self):
return {}
@expose('hello.templates.blog.post')
def post(self):
from datetime import date
now = date.today().strftime("%d-%m-%y")
return {'date':now}
Now declare an object of this class in RootController class (in root.py) as follows −
class RootController(BaseController):
blog = BlogController()
Other controller functions for top level URLs will be there in this class as earlier.
When a URL http://localhost:8080/blog/ is entered, it will be mapped to index() controller function inside BlogController class. Similarly, http://localhost:8080/blog/post will invoke post() function.
The code for blog.html and post.html is as below −
Blog.html
<html>
<body>
<h2>My Blog</h2>
</body>
</html>
post.html
<html>
<body>
<h2>My new post dated $date</h2>
</body>
</html>
When a URL http://localhost:8080/blog/ is entered, it will produce the following output −
When a URL http://localhost:8080/blog/post is entered, it will produce the following output −
TurboGears – ToscaWidgets Forms
One of the most essential aspect of any web application is to present the user interface for a user. HTML provides a <form> tag which is used to design an interface. Form’s elements such as text input, radio, select etc. can be appropriately used. Data entered by the user is submitted in the form of Http request message to server side script by either GET or POST method.
Server side script has to recreate the form elements from http request data. So in this effect, the form elements have to be defined twice – once in HTML and again in server side script.
Another disadvantage of using HTML form is that it is difficult (if not impossible) to render the form elements dynamically. HTML itself provides no way to validate user’s input.
ToscaWidgets2
TurboGears relies on ToscaWidgets2, a flexible form rendering and validation library. Using ToscaWidgets, we can define the form fields in our Python script and render them using a HTML template. It is also possible to apply validation to tw2 field.
ToscaWidgets library is a collection of many modules. Some important modules are listed below −
tw2.core − It provides core functionality. Widgets in this module are not meant to be available for end-user.
tw2.forms − This is a basic forms library. It contains widgets for fields, fieldsets and forms.
tw2.dynforms − This contains dynamic forms functionality.
tw2.sqla − This is an interface for SQLAlchemy database.
tw2.forms
It contains a Form class, which acts as a base for custom forms. There is a TableForm class that is useful in rendering fields in a two column table. ListForm presents its fields in an unordered list.
Sr.No.
Fields & Description
1
TextField
A single line text input field
2
TextArea
Multi-line text input field
3
CheckBox
Presents a checkable rectangular box with label
4
CheckBoxList
Multi-selectable group pf check boxes
5
RadioButton
A toggle button to select/deselect
6
RadioButtonList
Group of mutually exclusive Radio buttons
7
PasswordField
Similar to Textfield but input keys are not revealed
8
CalendarDatePicker
Lets the user to choose a date
9
SubmitButton
Button to submit a form
10
ImageButton
Clickable button with an image on top
11
SingleSelectField
Enables selection of single item from a list
12
MultipleSelectField
Enables selection of multiple items from the list
13
FileField
Field for uploading file
14
EmailField
An email input field
15
URLField
An input field to enter URL
16
NumberField
A number spinbox
17
RangeField
A number slider
In the following example, a form using some of these widgets is constructed. While most of these widgets are defined in tw2.forms, CalendarDateField is defined in tw2.Dynforms module. Hence both these modules along with tw2.core are imported in the beginning −
import tw2.core as twc
import tw2.forms as twf
import tw2.dynforms as twd
A ToscaWidgets form is a class derived from tw2.forms.form base class. The required widgets are placed inside a Layout object. In this example, TableLayout is used. The Widgets are rendered in a two column table. First column shows the caption and second column shows the input or selection field.
A TextField object is created using the following constructor −
twf.TextField(size, value = None)
If not mentioned TextField object takes a default size and is initially blank. While declaring TextArea object, the number of rows and columns may be mentioned.
twf.TextArea("",rows = 5, cols = 30)
The NumberField object is a TextField which can accept only digits. Up and down arrows are generated on the right border to increase or decrease the number inside it. Initial value can also be specified as an argument in the constructor.
twf.NumberField(value)
Just to the right of a CalendarDatePicker box, a calendar button is displayed. When pressed a date selector pops up. The user can manually type a date in the box or select from the date selector.
twd.CalendarDatePicker()
EmailField object presents a TextField, but the text in it must be in email format.
EmailID = twf.EmailField()
The following form also has a RadioButtonList. The constructor of this class contains a List object as a value of options parameter. A Radio Button for each option will be rendered. Default selection is specified with the value parameter.
The dropdown list is called as a SingleSelectfield in this ToscaWidgets library. Items in a List object corresponding to options parameter form the drop down list. Visible caption is set as a value of prompt_text parameter.
By default, the form displays a Submit button with its caption as ‘save’. In order to display another caption, create a SubmitButton object and specify it as value parameter.
twf.SubmitButton(value = 'Submit')
The form is submitted to a URL, which is specified as a value of action parameter of the form. By default, the form data is submitted by http POST method.
action = 'URL'
In following code, a form named as AdmissionForm is designed using the above explained widgets. Add this code in root.py before RootController class.
A good Forms widget library should have an input validation feature. For example, the user should be forced to enter data in a mandatory field, or verify if an email field contains a valid email, without resorting to any other programmatic means (like JavaScript function) for validation.
Early versions of ToscaWidgets Forms Library used to rely on FormEncode module for validation support. ToscaWidgets2 now has built-in validation support available in tw2.core module. However, it is still possible to use FormEncode validation techniques.
In order to subject a ToscaWidgets form to validation, @validate decorator is used.
@validate(form, error_handler, validators)
The ’form’ is the ToscaWidgets form object to be validated.
The ‘error-handler’ is the controller method used to handle form errors.
The ‘validators’ are a dictionary object containing FormEncode validators.
Types of Validators
The tw2.core module contains a validator class from which other validators are inherited. It is also possible to design a custom validator based on it. Some of the important validators are described below −
LengthValidator − Check whether a value has a prescribed length. Minimum and maximum limits are defined with min and max parameters. Custom messages for length below and above min and max can be specified as tooshort and toolong parameter.
tw2.core.LengthValidator(min = minval, max = maxval,
msgs = { 'tooshort': (‘message for short length’),
'toolong': (‘message for long length)})
RangeValidator − Usually used along with RangeField. It useful to validate value of a numeric field within minimum and maximum limits. Messages for tooshort and toolong parameters can be customized.
tw2.core.RangeValidator(min = minval, max = maxval,
msgs = { 'tooshort': (‘message for short length’),
'toolong': (‘message for long length)})
IntValidator − This class is derived from the RangeValidator. This is normally used to validate if input in a normal text field is containing integer data. Minimum and maximum limits as well as error messages can be set. Additionally, error message for non-integer input can be specified as ‘notint’ parameter.
tw2.core.IntValidator(msgs = {‘notint’:’Must be Integer’})
OneOfValidator − This validator forces the user to select a value from the available options in the list only.
tw2.core.OneOfValidator(values = [option1, option2,..],
msgs = {‘notinlist’:’Not in List’}}
DateValidator − Very useful to ensure that user input is a valid date. Date format (default is Y-M-D) and error message are customizable. Minimum and maximum date limits can also be specified. DateTimeValidator is also available to verify object of DateTime class.
tw2.core.DateValidator(msgs = {format = ’%Y-%m-%d’,
'baddatetime': ('baddate', ('Must follow date format $format_str'))}
EmailValidator − Validates user input against a valid email address. This class is inherited from a more general RegexValidator.
tw2.core.EmailValidator(msgs = {'badregex': ('bademail',
('Must be a valid email address')) }
UrlValidator − This class is also inherited from RegexValidator. It validates the user input for a valid URL.
tw2.core.UrlValidator(msgs = {'badregex': ('badurl', ('Must be a valid URL’)) }
MatchValidator − Confirms whether the value of one field is matched with the other. This is especially useful, where user is required to choose and confirm a password field. Typical usage of MatchValidator is shown below −
import tw2.core as twc
import tw2.forms as twf
class AdmissionForm(twf.Form):
class child(twf.TableLayout):
validator = twc.MatchValidator('pw', 'pwconfirm')
pw = twf.PasswordField()
pwconfirm = twf.PasswordField()
It is also possible to construct a compound validator, where the validation is desired to succeed, if any one of checks pass. In other cases, you may want validation to succeed, only if the input passes all the checks. For this, tw2.core provides the Any and All validators, which are subclasses of the extendable CompoundValidator.
TurboGears – Flash Messages
TurboGears provides a very convenient messaging system for notifying information to user in a non-obtrusive way. TGFlash class in tg module provides support for flashing messages that are stored in a plain cookie. This class supports fetching flash messages on server side as well as client side through JavaScript.
The render() method of TGFlash class, when used from Python itself, can be invoked from template to render a flash message. If used on JavaScript, it provides a WebFlash object. It exposes payload() and render() methods to fetch current flash message and render it from JavaScript.
When a TurboGears project is created using ‘quickstart’, it has a Master.html template. It contains the definition of a variable of that flash object. Contents of this flash message received from the controller substitutes the marked placeholder in this template.
The tg.flash_obj is the WebFlash object, which is available inside any rendered template by including master.html template. This object permits to retrieve the current flash message and display it.
The Flash messages are stored in a cookie (whose name by default is webflash) by using tg.flash() method. The message and status parameters are then passed to it.
tg.flash('Message', 'status')
If the method that is called flash performs a redirect, then the flash will be visible inside the redirected page. If the method directly exposes a template, then the flash will be visible inside the template itself.
Appearance of flash message can be customized by applying CSS styling to status code. A ‘quickstarted’ project contains error, warning, info and ok status codes customized by a stylesheet public/css/style.css. More status codes with styles can also be added.
This external style sheet needs to be included in the template −
<link rel = "stylesheet" type = "text/css" media = "screen"
href = "${tg.url('/css/style.css')}" />
The configuration of any Flash message support can be achieved by setting parameters for configure() method of TGFlash object or in app_cfg.py (in config folder). The configurable parameters are −
Sr.No.
Parameters & Description
1
flash.cookie_name
Name of the cookie used to store flash messages. Default is webflash.
2
flash.default_status
Default message status if not specified (ok by default)
3
flash.template
Used as the flash template when rendered.
4
flash.allow_html
Turns on/off escaping in flash messages, by default HTML is not allowed.
5
flash.js_call
JavaScript code which will be run when displaying the flash from JavaScript. Default is webflash.render()
6
flash.js_template
string.Template instance used to replace full JavaScript support for flash messages.
pop_payload() − function fetches current flash message, status and related information. Getting the flash message will delete the cookie.
render(container_id, use_js=True) − Render the flash message inside template or provide Javascript support for them.
container_id is the DIV where the messages will be displayed, while use_js switches between rendering the flash as HTML or for JavaScript usage.
status − Get only current flash status, getting the flash status will delete the cookie.
message − Get only current flash message, getting the flash message will delete the cookie.
How to Make a Simple Flash Message?
In the following example, a flash() method is provided in the root controller class. It calls a flash() message which is rendered to the exposed template, flash.html
from hello.lib.base import BaseController
from tg import expose, flash, redirect, request
class RootController(BaseController):
@expose('hello.templates.flash')
def flash(self, user = None):
if user:
flash(message = "Welcome "+user,status = "ok")
else:
flash(message = "Welcome Guest",status = "info")
return {}
The code for making flash.html in the templates folder is as follows
Start the server and enter http://localhost:8080/flash?user=MVL in the browser
Change URL to http://localhost:8080/flash and see the flash message differently formatted as per definition in style.css
TurboGears – Cookies & Sessions
It is often required to hold simple browsing data attached to a user’s browser. Sessions are the most commonly used technique. Session represents data which need not be stored in a more persistent form like disk file or database.
However, sessiondata in TurboGears can be backed by filesystem, database or hashed cookie values. A small amount of session data is generally kept in cookies, but for the larger volume of session data MemCache is used.
MemCache is a system-level daemon. It provides fast access to cached data and is extremely scalable. However, it is intended for use only on secure servers, and hence must be maintained and secured by sysadmin.
Beaker in Session Management
TurboGears uses Beaker for session management. A project quickstarted by gearbox is by default configured to use hashed cookies to store session data.
Each time a client connects, the session middleware (Beaker) will inspect the cookie using the cookie name, which has been defined in the configuration file. If the cookie is not found, it will be set in the browser. On all subsequent visits, the middleware will find the cookie and make use of it.
In order to enable session management, session class should be incorporated in the project by following import statement −
from tg import session
To save the data in a session variable −
session[‘key’] = value
session.save()
To retrieve the session variable −
return session[‘key’]
Note that you need to explicitly save the session in order for your keys to be stored in that session.
The delete() method of the session object will erase all the user sessions −
session.delete()
Even though it’s not customary to delete all the user sessions on any given production environment, you will typically do it for cleaning up after usability or functional tests have been done.
Given below is a simple example to demonstrate sessions. RootController class has a setsession() method which sets a session variable.
from hello.lib.base import BaseController
from tg import expose, session
class RootController(BaseController):
@expose()
def setsession(self):
session['user'] = 'MVL'
session.save()
str = "<b>sessionVariable set to "+session['user']
str = str+"<br><a href = '/getsession'>click here to retrieve</a></b>"
return str
@expose()
def getsession(self):
return "<b>value of session variable retrieved " +session['user'] +"</b>"
Enter http://localhost:8080/setsession
A link in the browser leads to http://localhost:8080/getsession which retrieves and displays the session variable −
TurboGears – Caching
In order to enhance the performance of a web application, especially if it is involved in lengthy operations, caching techniques are used. TurboGears provides two types of caching techniques −
Whole-page Caching
It works at the HTTP protocol level to avoid entire requests to the server by having either the user’s browser, or an intermediate proxy server (such as Squid) intercept the request and return a cached copy of the file.
Application-level Caching
This works within the application server to cache computed values, often the results of complex database queries, so that future requests can avoid needing to re-calculate the values. For web applications, application-level caching provides a flexible way to cache the results of complex queries so that the total load of a given controller method can be reduced to a few user-specific or case-specific queries and the rendering overhead of a template.
Application-level Caching
As mentioned earlier, ‘quickstarted’ TurboGears project is configured to enable Beaker package for caching support. Beaker supports the following back-ends used for cache storage −
memory − Used for per-process storage. It is extremely fast.
filesystem − per-process storage as well as multi-process.
SQLAlchemy database − per-database-server storage. Slower compared to the above given options.
Memcached − multi-server memory based cache.
Controller Caching
For quick controller caching, a cached() decorator is available. The entire controller body is cached depending on various parameters of request. The definition of tg.decorators.cached() decorator is as follows
Specifies the controller parameters used to generate the cache key.
2
expire
Time in seconds before cache expires, Defaults to “never”.
3
Type
dbm, memory, file, memcached, or None.
4
cache_headers
A tuple of header names indicating response headers.
5
invalidate_on_startup
If True, cache is invalidated each time application starts or is restarted.
6
cache_response
response should be cached or not, defaults to True.
Following is an example of controller caching −
@cached(expire = 100, type = 'memory')
@expose()
def simple(self):
return "This is a cached controller!"
Template Level Caching
The Genshi template engine retrieves template from a cache if its contents have not changed. The default size of this cache is 25. By default, automatic reloading of templates is true. In order to improve performance, the following settings can be made in app_cfg.py −
Although it is possible to use SQL in TurboGears application to perform CRUD operations on any relational database, it is advisable to use SQLAlchemy, a Python toolkit is a powerful Object Relation Mapper that gives application developers the full power and flexibility of SQL. In addition to support for SQL based databases through SQLAlchemy, TurboGears also supports MongoDB database though Ming. In this section, the functionality of SQLAlchemy is discussed.
What is ORM (Object Relational Mapping)?
Most programming language platforms are object oriented. The data in RDBMS servers on the other hand is stored as tables. Object relation mapping is a technique of mapping object parameters to underlying RDBMS table structure. An ORM API provides methods to perform CRUD operations without having to write raw SQL statements.
When a TurboGears project is created using ‘quickstart’ command from gearbox toolkit, SQLAlchemy support is enabled by default by the following configuration settings −
The ‘quickstarted’ project also creates a models package within it. For example, a ‘Hello’ project will have Hello\hello\model. The following files are created in this package −
__init__.py − This is where the database access is set up. The application’s model objects are imported in this module. It also has a DBSession - a global session manager and also a DeclarativeBase, which is a base class for all the model classes.
auth.py − This is where the models used by the authentication stack are defined. Additional database models are stored in this package, as a separate module, and added in the __init__.py.
TurboGears – Creating Models
Let us add a student model which will set up a student table in our sqlite database.
Hello\hello\model\student.py
from sqlalchemy import *
from sqlalchemy.orm import mapper, relation, relation, backref
from sqlalchemy import Table, ForeignKey, Column
from sqlalchemy.types import Integer, Unicode, DateTime
from hello.model import DeclarativeBase, metadata, DBSession
from datetime import datetime
class student(DeclarativeBase):
__tablename__ = 'student'
uid = Column(Integer, primary_key = True)
name = Column(Unicode(20), nullable = False, default = '')
city = Column(Unicode(20), nullable = False, default = '')
address = Column(Unicode(100), nullable = False, default = '')
pincode = Column(Unicode(10), nullable = False, default = '')
Now add this model in init_model() function inside __init__.py. This function already contains the auth model in it. Add our student model below it.
# Import your model modules here.
from hello.model.auth import User, Group, Permission
from hello.model.student import student
If you want the table to be initialized with some data at the time of setting up the models, add it in bootstrap.py in websetup package. Add the following statements in the bootstrap() function.
The Models are initialized by running setup-app command of gearbox −
gearbox setup-app
Session object of SQLAlchemy manages all persistence operations of ORM object.
TurboGears – CRUD Operations
The following session methods perform CRUD Operations −
DBSession.add(model object) − inserts a record into mapped table.
DBSession.delete(model object) − deletes record from the table.
DBSession.query(model).all() − retrieves all the records from table (corresponding to a SELECT query).
You can apply filter to the retrieved record set by using a filter attribute. For instance, in order to retrieve records with city = ’Hyderabad’ in students table, use the following statement −
Enter http://localhost:8080/add in the browser after starting the server. The following Student information form will open up in the browser −
The above form is designed to be submitted to the ‘/save_record’ URL. Hence a save_record() function needs to be added in the root.py to expose it. The data from the studentform is received by this function as a dict() object. It is used to add a new record in the student table underlying student model.
Please note that after the successful addition, the browser will be redirected to ‘/listrec’ URL. This URL is exposed by a listrec() function. This function selects all records in the student table and sends them in the form of a dict object to the studentlist.html template. This listrec() function is as follows −
Now revisit the http://localhost:8080/add and enter data in the form. By clicking on the submit button, it will take the browser to studentlist.html. It will also flash a ‘new record added successfully’ message.
TurboGears – DataGrid
The ToscaWidgets contains a DataGrid control which provides a quick way to present data in tabular form. The DataGrid object is declared as follows −
Now, showgrid() function retrieves all the records in student table and exposes the data to grid.html template. First the code for showgrid() function and then grid.html code is given below −
showgrid()
@expose('hello.templates.grid')
def showgrid(self):
data = DBSession.query(student).all()
return dict(page = 'grid', grid = student_grid, data = data)
The following tabular data will be displayed when http://localhost:8080/showlist URL is entered in the browser −
TurboGears – Pagination
TurboGears provides a convenient decorator called paginate() to divide output in the pages. This decorator is combined with the expose() decorator. The @Paginate() decorator takes the dictionary object of query result as argument. In addition, the number of records per page are decided by value of items_per_page attribute. Ensure that you import paginate function from tg.decorators into your code.
Rewrite listrec() function in root.py as follows −
In the studentlist.html template, page navigation is enabled by adding tmpl_context.paginators.entries.pager() below the py:for directive. The code for this template should be as below −
Enter http://localhost:8080/listrec in the browser. The first page of records in the table are displayed. On top of this table, links to page numbers are also seen.
How to Add Pagination Support to Datagrid
It is also possible to add pagination support to datagrid. In the following example, paginated datagrid is designed to display action button. In order to activate action button datagrid object is constructed with following code −
Here the action button is linked to the name parameter of each row in the data grid.
Rewrite the showgrid() function as follows −
@expose('hello.templates.grid')
@paginate("data", items_per_page = 3)
def showgrid(self):
data = DBSession.query(student).all()
return dict(page = 'grid', grid = student_grid, data = data)
The browser shows paginated datagrid as follows −
By clicking the Edit button in the third row, it will redirect to the following URL http://localhost:8080/edit?name=Rajesh+Patil
TurboGears – Admin Access
TurboGears provides the tgext.admin extension, which is powered by tgext.crud and sprox. This Sprox is a package used for the creation of web widgets directly from the database schema. This can be used to automatically create simple administration pages and is the toolkit powering the /admin page in the newly quickstarted applications.
By default, the admin will provide an autogenerated access to all the models imported in your project models/__init__.py.
How to Create TurboGears Admin
The default TurboGears admin is created as an object of AdminController class −
from tgext.admin.controller import AdminController
class RootController(BaseController):
admin = AdminController(model, DBSession, config_type = TGAdminConfig)
This creates an admin for all the models with the default TurboGears admin configuration.
Through the manager, a user has been created during the setup phase. Now, it is possible to get access to the TurboGears Admin at http://localhost:8080/admin The first time this page is accessed, it will ask for authentication. You can simply provide the username and password of the user that the setup-app command created for us −
Username: manager
Password: managepass
In order to login to the quickstarted project, add the following functions to the RootController class (controllers/root.py).
from hello.lib.base import BaseController
from tg import expose, flash, redirect, request,url, lurl
from tg import redirect, validate
from hello import model
from hello.model import DBSession
from tgext.admin.tgadminconfig import BootstrapTGAdminConfig as TGAdminConfig
from tgext.admin.controller import AdminController
from tg.exceptions import HTTPFound
class RootController(BaseController):
admin = AdminController(model, DBSession, config_type = TGAdminConfig)
@expose('hello.templates.index')
def index(self):
return dict(page = 'index')
@expose('hello.templates.login')
def login(self, came_from = lurl('/'), failure = None, login = ''):
if failure is not None:
if failure == 'user-not-found':
flash(_('User not found'), 'error')
elif failure == 'invalid-password':
flash(_('Invalid Password'), 'error')
login_counter = request.environ.get('repoze.who.logins', 0)
if failure is None and login_counter > 0:
flash(_('Wrong credentials'), 'warning')
return dict(page = 'login', login_counter = str(login_counter),
came_from = came_from, login = login)
@expose()
def post_login(self, came_from = lurl('/')):
if not request.identity:
login_counter = request.environ.get('repoze.who.logins', 0) + 1
redirect('/login', params = dict(came_from = came_from,
__logins = login_counter))
userid = request.identity['repoze.who.userid']
flash(('Welcome back, %s!') % userid)
return HTTPFound(location = came_from)
Login to the 'quickstarted' application after starting the server and by visiting http://localhost:8080/login and then enter the manager credentials as displayed above. The browser will display an admin page like the one shown below −
The page shows all the models created in this application. You can click any model to see the listing of entries in it −
The 'New' button on top of this datagrid allows the record to be added. Similarly, action buttons for editing and deleting a record are also provided in actions column of this datagrid. A search box is also displayed to select records conditionally.
TurboGears – Authorization & Authentication
A TurboGears application is created by quickstart and setup-app options of the gearbox toolkit, which has the authorization and authentication support enabled by default. The models declared in auth.py are set up and initialized as per values assigned in bootstrap.py.
The following models are declared in auth.py −
User Model
The User model contains the design of a tg_user table. This table is used by the repose.who package. This repose.who package is a powerful as well as an extensible authentication library for WSGI applications. The structure of a user model is as follows −
The predicates module in tg package contains definitions for predicate checkers. A predicate is a condition that must be met for the user to be able to access the requested source. Such a predicate, or condition, may be made up of more predicates – those are called compound predicates. Action controllers, or controllers, may have only one predicate, be it single or compound.
If a user is not logged in, or does not have the proper permissions, this predicate checker throws a 401 (HTTP Unauthorized), which is caught by the repoze.who middleware to display the login page allowing the user to login, and redirecting the user back to the proper page when they are done.
The different conditions or predicates defined in tg.predicates module are −
Sr.No.
tg.predicates module & Description
1
All
Check if all predicates specified are met
2
Any
Check if at least one of specified predicates are met
3
is_user
Check that the authenticated user's username is the specified one
4
in_group
Check that the user belongs to the specific group.
5
in_all_groups
Check that the user belongs to all of the specified groups.
6
in_any_group
Check that the user belongs to at least one of the specified groups.
7
is_anonymous
Check that the current user is anonymous.
8
has_permission
Check that the current user has the specified permission.
9
has_all_permissions
Check that the current user has been granted all of the specified permissions.
10
has_any_permission
Check that the user has at least one of the specified permissions.
For example, if you have a predicate, which is grant access user belonging to customers group, then you can use the following built-in predicate checker −
from tg.predicates import in_group
p in_group(‘customers’)
The following predicate checker will grant access to ‘root’ user or anybody with ‘manage’ permission −
from tg.predicates import Any, is_user, has_permission
p = Any(is_user('root'), has_permission('manage'),
sg = 'Only administrators can remove blog posts')
TurboGears - Using MongoDB
TurboGears also supports MongoDB document databases. It uses Ming, an Object Document Mapper API. Usage of Ming is very much similar to SQLAlchemy. Ming query language makes it possible to port SQLAlchemy based TurboGears project to Ming.
What is PyMongo
PyMongo is a Python distribution containing tools for working with MongoDB. Ming extends PyMongo providing −
Declarative Models
Schema Validation and Conversion
Schema Evolution
Pure InMemory MongoDB Implementation
Unit of Work
Identity Map
One-To-Many, Many-To-One and Many-To-Many Relations
First of all, you need to download and install MongoDB. The latest distribution of MongoDB can be downloaded from https://www.mongodb.org/downloads
On Windows, start MongoDB server by providing -dbpath option −
C:\mongodb\bin>Mongod --dbpath d:\mongo
D:\mongo folder is designated to store MongoDB database. Server starts listening at http://localhost:27017. Now to start MongoDB shell use the following command −
C:\mongodb\bin>Mongo
Our MongoDB environment is now ready.
Now create a TurboGears project with -ming option −
gearbox quickstart --ming Hello
This quickstarted project will provide an authentication and authorization layer like the one that is provided for the SQLAlchemy version. This application will now try to connect to a server on port 27017 on the local machine. The development.ini file in project folder contains the following settings −
The project folder contains models subfolder which has the following files −
__init__.py − This is where the database access is set up. Your collections should be imported into this module. For example, we shall add student collection in this package.
session.py − This file defines the session of your database connection. You will need to import this each time you have to declare a MappedClass to specify the session to perform queries.
auth.py − This file will be created, if you have enabled authentication and authorization in the quickstart. It defines three collections repoze.who, which further relies on: User, Group, and Permission.
Defining Your Collection
By default, TurboGears configures Ming in a declarative mode. This is similar to the SQLAlchemy declarative support and needs each model to inherit from the MappedClass class.
The MappedClass requires that a __mongometa__ subclass is available inside, which further provides the details regarding the name of the collection storing the documents and the session used to store the documents.
MappedClass also contains definition of fields in the document. Ming’s odm module has definitions of different types of field properties −
FieldProperty
ForeignIdProperty
RelationProperty
The ming.schema module defines the following data types −
ming.schema.Anything
ming.schema.Array
ming.schema.Binary
ming.schema.Bool
ming.schema.Float
ming.schema.Int
ming.schema.ObjectId
ming.schema.Scalar
ming.schema.String
To add the student collection in this model, save the following code as student.py in hello/models folder.
Hello\models\student.py
from ming import schema
from ming.odm import MappedClass
from ming.odm import FieldProperty, ForeignIdProperty
from hello.model import DBSession
Class student(MappedClass):
class __mongometa__:
session = DBSession
name = 'student'
_id = FieldProperty(schema.ObjectId)
name = FieldProperty(schema.String(required = True))
city = FieldProperty(schema.String(if_missing = ''))
address = FieldProperty(schema.String(if_missing = ''))
pincode = FieldProperty(schema.String(if_missing = ''))
Finally, include this model in hello\models\__init__.py
# Import your model modules here.
from hello.model.auth import User, Group, Permission
from hello.model.student import student
To set up these models, run the following gearbox command −
Gearbox setup-app
Start the server with the following gearbox command −
Gearbox serve –reload –debug
Open the homepage of this application (http://localhost:8080/) and login with manager credentials. Admin page of this application will show the list of models set up. (login as manager, password managepass)
The creation of collections can also be verified in MongoDB web interface as well as the MongoDB shell.
The ODMSession is used to perform several database operations using the following functions −
model.query.find()
model.query.find_and_modify()
model.remove()
model.update()
model.flush()
Designing a ToscoWidget Form
We shall now design a ToscoWidget form to enter student data and add it into the table underlying the student model.
Following is the code for creating a studentform.py −
Hello\controllers\studentform.py
import tw2.core as twc
import tw2.forms as twf
class StudentForm(twf.Form):
class child(twf.TableLayout):
name = twf.TextField(size = 20)
city = twf.TextField()
address = twf.TextArea("",rows = 5, cols = 30)
pincode = twf.NumberField()
action = '/save_record'
submit = twf.SubmitButton(value = 'Submit')
In the application's Rootcontroller '/add' URL that calls add() function, which will open the above designed form in the browser. Its submit button then invokes save_record() function. It retrieves the form data and saves it in student table and redirects the application to '/listrec' URL, which exposes the studentlist template.
The root.py for this activity is as follows −
Hello/controllers/root.py
from hello.lib.base import BaseController
from tg import expose, flash, redirect, request,url, lurl
from tg import redirect, validate
from hello import model
from hello.model import DBSession
from hello.model.student import student
from hello.controllers.studentform import StudentForm
class RootController(BaseController):
@expose()
def index(self):
return "<h1>Hello World</h1>"
@expose ("hello.templates.studentlist")
def listrec(self):
entries = student.query.find()
return dict(entries = entries)
@expose('hello.templates.studentform')
def add(self, *args, **kw):
return dict(page = 'studentform', form = StudentForm)
@expose()
def save_record(self, **kw):
newstudent = student(name = kw['name'],city = kw['city'],
address = kw['address'], pincode = kw['pincode'])
DBSession.flush()
flash(message = "new entry added successfully")
redirect("/listrec")
The following templates are created in the templates folder −
Restart the server and enter http://localhost:8080/add in the browser −
Each time the data is added and submit button is pressed, the list of current entries will be displayed.
TurboGears – Scaffolding
Gearbox toolkit contains scaffold command, which is very useful to quickly create new components of TurboGears application. An application generated by quickstart command of gearbox has a skeleton template in the model folder (model.py.template), a templates folder (template.html.template) and a controllers folder (controller.py.template). These ‘.template’ files are used as basis for creating new scaffolds for an application
For example, in order to create a new model named mymodel, simply run the following command −
gearbox scaffold model mymodel
This command will generate model/mymodel.py with newmodel class defined in it.
# -*- coding: utf-8 -*-
"""Mymodel model module."""
from sqlalchemy import *
from sqlalchemy import Table, ForeignKey, Column
from sqlalchemy.types import Integer, Unicode, DateTime, LargeBinary
from sqlalchemy.orm import relationship, backref
from hello.model import DeclarativeBase, metadata, DBSession
class Mymodel(DeclarativeBase):
__tablename__ = 'mymodels'
uid = Column(Integer, primary_key = True)
data = Column(Unicode(255), nullable = False)
user_id = Column(Integer, ForeignKey('tg_user.user_id'), index = True)
user = relationship('User', uselist = False,
backref = backref('mymodels',cascade = 'all, delete-orphan'))
__all__ = ['Mymodel']
The users can now make modifications in the table structure as per their requirement and then import it inside model/__init__.py to make the model available inside the application.
In order to create a model, a controller class to handle it and an index page all these three components can be created simultaneously by the following command.
gearbox scaffold model controller template mymodel
This command will result in controllers\mymodel.py in which the MymodelController class is duly defined.
# -*- coding: utf-8 -*-
"""Mymodel controller module"""
from tg import expose, redirect, validate, flash, url
# from tg.i18n import ugettext as _
# from tg import predicates
from hello.lib.base import BaseController
# from hello.model import DBSession
class MymodelController(BaseController):
# Uncomment this line if your controller requires an authenticated user
# allow_only = predicates.not_anonymous()
@expose('hello.templates.mymodel')
def index(self, **kw):
return dict(page = 'mymodel-index')
To start using this controller, mount it inside your application RootController just to define an instance of MymodelController. Add these lines in the controllers\root.py −
From hello.controller.mymodel import MymodelController
class RootController(BaseController): mymodel = MymodelController()
A template scaffold templates\mymodel.html will also be created in the templates folder. It will act as an index page for ‘/mymodel’ URL.
The generated mymodel.html file in the templates folder will be as follows −
There are three ways in TurboGears to plug behaviors inside the existing applications.
Hook − It is a mechanism by which it is possible to define an event, and notify registered listeners as and when the events are emitted.
Controller Wrapper − It sits between TurboGears and Controller, so that it is possible to extend controller like a decorator. Thus, it can be attached to any third-party controller application.
Application Wrapper − It is similar to any WSGI middleware, but works in TurboGears context only.
Here in this chapter, we will discuss how to use hooks inside an existing application.
Hooks
Hooks are events registered in the application’s configuration file app_cfg.py. Any controller is then hooked to these events by event decorators.
The following hooks are defined in TurboGears −
Sr.No.
Hooks & Description
1
Startup()
application wide only, called when the application starts.
2
shutdown()
application wide only, called when the application exits.
3
configure_new_app
new application got created by the application configurator.
4
before_config(app)
application wide only, called right after creating application, but before setting up options and middleware
5
after_config(app)
application wide only, called after finishing setting everything up.
6
before_validate
Called before performing validation
7
before_call
Called after validation, before calling the actual controller method.
8
before_render
Called before rendering a controller template, output is the controller return value.
9
after_render
Called after finishing rendering a controller template.
Register a Hook
In order to register a Hook, create functions in app_cfg.py and then register them using the following code −
tg.hooks.register(hookane, function, controller)
In the following code, on_startup, on_shutdown and before_render hooks are registered in app_cfg.py.
This will create a tgext.myextension directory, which has a simple sample extension inside.
Run the setup.py inside the directory −
Python setup.py install
The _init_.py file inside tgext/myextension folder contains −
Plugme function − This is the entry point of extension.
SetupExtension class − extension initialization takes place here.
On_startup function − inside the class is a hook registered on __call__ function inside class.
Brief version of the tgext\myextension\__init__.py.
from tg import config
from tg import hooks
from tg.configuration import milestones
import logging
log = logging.getLogger('tgext.myextension')
def plugme(configurator, options = None):
if options is None:
options = {}
log.info('Setting up tgext.myextension extension...')
milestones.config_ready.register(SetupExtension(configurator))
return dict(appid='tgext.myextension')
class SetupExtension(object):
def __init__(self, configurator):
self.configurator = configurator
def __call__(self):
log.info('>>> Public files path is %s' % config['paths']['static_files'])
hooks.register('startup', self.on_startup)
def echo_wrapper_factory(handler, config):
def echo_wrapper(controller, environ, context):
log.info('Serving: %s' % context.request.path)
return handler(controller, environ, context)
return echo_wrapper
self.configurator.register_wrapper(echo_wrapper_factory)
def on_startup(self):
log.info('+ Application Running!')
Once the extension is installed, turn it on by making the following additions in the application's app_cfg.py configuration file.
from tgext.myextension import plugme
plugme(base_config)
If we launch the server using a gearbox server command, the notification of a newly registered extension can be viewed on the console by the following −
14:29:13,250 INFO [tgext.myextension] Setting up tgext.myextension extension...
14:29:13,453 INFO [tgext.myextension] >>> Public files path is c:\tghello\hello\hello\public
14:29:13,453 INFO [tgext.myextension] + Application Running!
Starting Standard HTTP server on http://127.0.0.1:8080
TurboGears - Pluggable Applications
If your extension needs to expose models and controllers, you probably want to have a look at the Pluggable Applications, which are meant to create reusable Turbogears applications that can be plugged inside other applications to extend their features.
Use the following gearbox command to create a pluggable application −
gearbox quickstart-pluggable plugtest
These pluggable applications can define their own −
Controllers − which will be automatically mounted, when the application is purged.
Models − which will be available inside and outside the plugged application.
Helpers − which can be automatically exposed in the ‘H’ object in an application template.
Bootstrap − which will be executed when setup-app is called.
Statics − which will be available at their own private path.
Install this plugtest application and mount the same by making the following modifications in app_cfg.py.
from tgext.pluggable import plug
plug(base_config, plugtest)
TurboGears – RESTful Applications
REST stands for REpresentational State Transfer. REST is web standards based architecture and uses HTTP Protocol for data communication. It revolves around a resource where every component is a resource and a resource is accessed by a common interface using HTTP standard methods. REST was first introduced by Roy Fielding in 2000.
What is a RestController
RestController in TurboGears provides a mechanism to access the request’s method, not just the URL. Standard HTTP verbiage includes: GET, POST, PUT, and DELETE. The RestController supports these, and also adds a few shortcuts for URL dispatch that makes displaying the data as forms and lists, a little easier for the user.
To explain how RESTful works with TurboGears, we are going to define a simple webservice that exposes a list of students.
The code for student model is given below −
model\student.py
# -* - coding: utf-8 -*-
from sqlalchemy import *
from sqlalchemy.orm import mapper, relation, relation, backref
from sqlalchemy import Table, ForeignKey, Column
from sqlalchemy.types import Integer, Unicode, DateTime
from hello.model import DeclarativeBase, metadata, DBSession
from datetime import datetime
class student(DeclarativeBase):
__tablename__ = 'student'
uid = Column(Integer, primary_key = True)
name = Column(Unicode(20), nullable = False, default = '')
city = Column(Unicode(20), nullable = False, default = '')
address = Column(Unicode(100), nullable = False, default = '')
pincode = Column(Unicode(10), nullable = False, default = '')
Now create a controller based on RestController and provide a view function to list out list of students in json format.
Controllers\student.py
from tg import RestController
from tg import expose
from hello import model
from hello.model import DBSession
from hello.model.student import student
from tg.decorators import with_trailing_slash
class StudentController(RestController):
@expose('json')
def get_all(self):
students = DBSession.query(student).all()
return dict(students=students)
Mount this StudentController in RootController of application by incorporating following lines in root.py −
from hello.controllers.student import StudentController
class RootController(BaseController):
students = StudentController()
Going to the http://localhost:8080/students it will provide the list of our students encoded in json format.
We use the post method to define how we go about saving our student to the database. This method gets called whenever the http://localhost:8080/student url is accessed using a POST request −
@expose('json')
def post(self, name, city, address, pincode):
newstudent = student(name = name, city = city, address = address, pincode = pincode)
DBSession.add(newstudent)
DBSession.flush()
return dict(student = newstudent)
Using the get_one() method, we can display one item from the database to the user −
PUT is the method used for updating an existing record using REST −
@expose('json')
def put(self, name = name, city = city, address = address, pincode = pincode, **kw):
newstudent = DBSession.query(student).get(name)
newstudent.name = name
newstudent.city = city
newstudent.address = address
newstudent.pincode = pincode
return dict(student = newstudent)
The work-horse of delete is attached to the post_delete method. Here we actually remove the record from the database, and then redirect back to the listing page −
To switch over from a development environment to a full-fledged production environment, application needs to be deployed on a real web server. Depending upon what you have, there are different options available to deploy a TurboGears web application.
Apache with mod_wsgi
The mod_wsgi is an Apache module developed by Graham Dumpleton. It allows WSGI programs to be served using the Apache web server.
Firstly, install Apache 2.X for your platform, if not done already. Once you have Apache installed, install mod_wsgi. Create and activate Python virtual environment on the server and install TurboGears in it.
Install your application within the application director, then create a script named app.wsgi.
Configure Apache installation as follows −
<VirtualHost *:80>
ServerName www.site1.com
WSGIProcessGroup www.site1.com
WSGIDaemonProcess www.site1.com user = <username>
group = www-data threads = 4 python-path = <pythonpath>
WSGIScriptAlias myapp/app.wsgi
#Serve static files directly without TurboGears
Alias /images
Alias /css
Alias /js
CustomLog
ErrorLog
</VirtualHost>
Restart Apache
Type http://www.site1.com/ on a browser to access the application.
TurboGears under Circus and Chaussette
Circus is a process & socket manager. It can be used to monitor and control processes and sockets. When paired with the Chaussette WSGI server, it can become a powerful tool to deploy your application and manage any related process your applications need.
Using Google AppEngine Launcher, create a new application named mytgapp.
The following files will be created in the specified directory −
app.yaml
favicon.ico
index.yaml
main.py
By default,the created application relies on the Webapp2 framework. To remove this dependency, edit the app.yaml file and delete the following part −
libraries:
- name: webapp2
version: "2.5.2"
Create a temporary virtual environment in a directory named mytgapp and install TurboGears. Create a TurboGears application in it. Now we can proceed editing the main.py file which is started by AppEngine to run our application and actually write a TurboGears application there.
Add the following contents in main.py −
import os
import site
site.addsitedir(os.path.join(os.path.dirname(__file__), 'packages'))
from tg import expose, TGController, AppConfig
class RootController(TGController):
@expose()
def index(self):
return "<h1>Hello World</h1>"
config = AppConfig(minimal = True, root_controller = RootController())
app = config.make_wsgi_app()
Now run the application from AppEngine Launcher and click on browse button to see that application works properly on the localhost.
We have already created a project named mytgapp in the developer console. Now click on the deploy button in the Launcher. After the deployment process is over, http://mytgapp.appspot.com/ visit to view our application online.
