Pyxer 0.6.2
Yet another Python Framework
(C)opyright by Dirk Holtwick, Germany
dirk.holtwick@gmail.com
http://www.pyxer.net
The Pyxer Server is a very simple Python Web Framework that aims to makes starting a new project as easy as it can be. It still works respecting the MVC concept but the files can be mixed in one directory. For a high end solution you should maybe consider using Pylons, Django, TurboGears and similar.
This work is inspired by http://pythonpaste.org/webob/do-it-yourself.html.
The Google App Engine (GAE) in version 1.1 offers a very restricted Python environment and the developer as to ship arround a lot of limitations. Pyxer helps on this point by providing solutions that also work together with the WSGI Framework Paste by Ian Bicking. This way you get the best from both sides: GAE and Paste. To achieve this, some other common third party tools are used like WebOb and VirtualEnv also by Ian Bicking. The templating s based on Genshi.
Install Pyxer using easy_install
from SetupTools:
$ easy_install pyxer
All required packages (webob
, html5lib
, beaker
) should be installed automatically if needed.
If you want to use Google App Engine you have to install it separately.
At first set up a new Pyxer project using the Pyxer command line tool like this:
$ pyxer init myexample
In the newly created directory myexample
you will find a directory structure like the following (on Windows bin
will be called Scripts
):
bin/ public/ lib/
Place your files in the public
directory.
To start the server you may choose between the Paster-Engine:
$ xpaster serve
Or the GAE-Engine:
$ xgae serve
Or use Pyxer command line tool again to use the default engine (which is WSGI from Python standard lib):
$ pyxer serve
But you may also use Pyxer without using the command line tools e.g. like this:
$ paster serve development.ini
For a simple "Hello World" just put an index.html
file into the public
directory with the following content:
Hello World
This works just like a static server. To use a controller put the file __init__.py
into the same directory with the following
content:
@controller def index(): return "Hello World"
Controller, templates and static files are placed in the same
directory (usually public
). First Pyxer looks for a matching controller. A controller is defined in the __init__.py
file and decorated by using @controller
which is defined in pyxer.base
.
from pyxer.base import * @controller def index(): return "Hello World"
This controller adds the GET
and POST
parameters as arguments to the function call (like in CherryPy):
from pyxer.base import * @expose def index(name="unknown"): return "Your name is " + name
If no matching controller can be found the one named default
will be called:
from pyxer.base import * @controller def default(): return "This is path: " + request.path
This example can be called via /
or /index
.
To use a Pyxer template with this file you may use the render()
function or just return None
(that is the same as
not using return
) and the matching template will be used, in this
case index.html
. The available objects in the template
are the same as used by Pylons: c
= context, g
= globals and h
= helpers.
from pyxer.base import * @controller def index(): c.title = "Hello World"
By default a Genshi like templating language is used and output is specified as xhtml-strict
. You may want to change that for certain documents e.g. to render a plain text:
from pyxer.base import * @controller(output="plain") def index(): c.title = "Hello World"
Or use another template:
from pyxer.base import * @controller(template="test.html", output="html") def index(): c.title = "Hello World"
Or use your own renderer:
from pyxer.base import * def myrender(): result = request.result return "The result is: " + repr(result) @controller(render=myrender) def index(): return 9 + 9
To return data as JSON just return a dict or list object from your controller:
from pyxer.base import *
@controller
def index():
return dict(success=True, msg="Everything ok")
Session are realized using the Beaker package. You can use the variable session
to set and get values. To store the session data use session.save()
. Here is a simple example of a counter:
from pyxer.base import *
@controller
def index():
c.ctr = session.get("ctr", 0)
session["ctr"] = c.ctr + 1
session.save()
??? XXX
#Looks for a controller (foo.bar:bar)
If the controller returns a dictionary this will be applied to template (step 2)
To publish your project to GAE you may also use the Pyxer command line tool. First check if your app.yaml
file contains the right informations like the project name and version infos. Then just do like this:
$ xgae upload
Be aware that Pyxer first needs to fix the paths to be relative instead of absolute to make them work on the GAE environment. If you choose not to use Pyxer for uploading you have to do this fix up explicitly before you upload your application like this:
$ xgae fix
The routing in Pyxer is based on some conventions by default but can be extended in a very flexible and easy way. By default all public project data is expected to be found in the folder public
. If you just put static content there it will behave like you expect it from a normal webserver.
To add controllers to it, start by creating the __init__.py
file. This makes the folder become a Python package and Pyxer routing will at first evaluate this one before looking for static content.
The easiest controller looks like this:
@controller def index(): return "Hello World"
This will be called with the following URLs:
http://<domain>/
http://<domain>/index
http://<domain>/index.html
http://<domain>/index.htm
If the controller has another name as index
, these corresponding URLs will match:
http://<domain>/<controller>
http://<domain>/<controller>.html
http://<domain>/<controller>.htm
There is one other special controller named default
. If this one exists all non matching request will be passed to this controller.
If you have sub packages in your public
folder like foo
and foo.bar
, these will be matched by the corresponding path and in this package the rules described before will apply:
http://<domain>/foo/bar/...
Everything that does not match will be considered static content. Pyxer tries to match the path relatively to the last matched package.
If you need more sophisticated routing or want to include external packages that are not placed under the public
folder you may add your own routing. This is as simple as adding this line to your global space of your module:
router = Router()
Important! The name of this object has to be router
by convention!
To add your own ...
router.add("content-{name}", "content")
This matches all URL starting with content-
while the rest will be saved in req.urlvars
as key called name
. For example the URL /content-myentry
will result in a call of the controller content
where req.urlvars["name"]=="myentry"
.
For more complicated routes you may also use the add_re
method, which offers more flexibility. Here is an example that matches the rest of the path after "content/" and passes the value to the controller via req.urlvars["path"]
:
router.add_re("^content/(?P<path>.*?)$", controller="index", name="_content")
In your templates you should try to often use the h.url()
helper. It calculates a URL relative to the matched routes base. For example if we take a look at the add_re
routing example we can see that the path
component is under the content component. Let's say we have a controller called edit
we like to call from the page created by index
, then we can not write it like this:
<a href="edit?path=$c.path">Edit</a>
That does not always work because this page could have been called via index?path=xyz
or via content/xyz
. To make sure we are get the correct URL corresponding to our modules controller we could write it like this:
<a href="${h.url('edit?path=' + c.path)}>Edit</a>
Or even better using the feature of h.url
that lets you append GET parameters as named arguments of the helper function:
<a href="${h.url('edit', path=c.path)}>Edit</a>
If you use redirect
it will call the url
helper too so that relative parts will be translated to absolute ones.
Pyxer offers yet another templating language that is very close to Genshi and Kid. Beause Genshi did not work with Google App Engine when Pyxer was started, the new templating tools have been implemented.
The default templating works similar to most known other
templating languages. Variables and expressions are realized like $<varname>
(where <varname>
may
contain dots!) and ${<expression>}
:
Hello ${name.capitalize()}, you won $price. $item.amount times $item.name.
These are also known form templating languages like Genshi and Kid. They are used like this:
<div py:if=”name.startswith('tom ')”>Welcome $name</div>
Or this:
<div py:for=”name in sorted(c.listOfNames)”>Welcome $name</div>
These are the available commands. They behave like the Genshi equivalents:
If HTML comments start with "!" they are ignored for output:
<!--! Invisible --> <!-- Visible in browsers -->
The implementation of layout templates is quite easy. Place the py:layout
command in the <html>
tag and pass a Template object. For loading you can use the convenience function load()
.
<html py:layout="load('layout.html')"> ... </html>
In the template file you can then access the original template stream with the global variable top
. Use CSS selection or XPATH to access elements. Example:
<html> <title py:content="top.css('title')"></title> <body> <h1><a href="/">Home</a> / ${top.select('//title/text()')}</h1> <div class="content">
${top.css('body *')} </div> </body> </html>
XPath
XPath is supported like it is in Genshi.
CSS Selectors
CSS Selectors ending with *
(notice the space) return just the inner texts and elements of the matched pattern.
You are free to use any database model you like. For GAE you do not have much choice. But for other engines I recommend using Elixir. You should try to separate your controller stuff from your database stuff by creating a Python module called model.py
. For a GAE project this may look like this:
from google.appengine.ext import db from google.appengine.api import users class GuestBook(db.Model): name = db.StringProperty() date = db.DateTimeProperty(auto_now_add=True)
While using Elixir you can start like this:
xxx
XXX See the GuestBook example for a complete demo.
To make deployment of GAE projects easy a virtual environment (VM) is created. If you start GAE via xgae
or paster via xpaster
these virtual environments will automatically be used. Pyxer determines the root of the VM by looking for the app.yaml
file. If you have to enter the VM for installing packages or for other reasons you may do it like this:
$ pyxer vm (vm)$ easy_install html5lib (vm)$ exit
You can also use the usual functions as described in virtualenv by Ian Bicking.
$ Scripts\activate.bat
$ easy_install SomePackageName $ deactivate
And for other Unix like system like this:
$ source bin/activate $ easy_install SomePackageName $ deactivate
If you decide to develop Pyxer you may run into the following problem: each project comes with an own virtual machine (VM) and its own installation of Pyxer in it. So if you change the development version it will have no effect on your installation. Therefore a command pyxer
is added that synchronizes the Pyxer installation in the VM with the development version:
$ pyxer pyxer
BTW: To install the development version using SetupTools do like this:
$ cd <Path_to_development_version_of_Pyxer> $ python setup.py develop
You will have to repeat this each time the version of Pyxer changes, because otherwise the command line tools do not work.
Since a Pyxer project is based on Paster, writing test cases is quite the same. The most simple test looks like this. (We asume that the test file to will be placed in the root of the project. For normal testing you have do add the root directory, where app.yaml
is placed, to sys.path
and modify the loadapp
argument.):
from paste.deploy import loadapp from paste.fixture import TestApp import os.path app = TestApp(loadapp('config:%s' % os.path.abspath('development.ini'))) res = app.get("/") assert ('<body' in res)
For more informations about testing look here http://pythonpaste.org/testing-applications.html.
xxx
xxx
If you have installed mod_python
the deployment of your project is as simple as writing the following five lines. Just copy them to your sites configuration and adjust the absolute path to the development.ini
:
<Location "/">
SetHandler python-program
PythonHandler paste.modpython
PythonOption paste.ini /<absolute_path_to_ini_file>/development.ini
</Location>
Pyxer configuration is placed in the configuration file used by Paster or GAE respectively development.ini
or gae.ini
. If both are not available Pyxer looks into pyxer.ini
. Example:
[pyxer] session = beaker
XXX
Pyxer uses support different so called "engines" to publish a project. Most of them need own configurations and a well prepare environment to work fine. These are very specific to each of these engines and Pyxer tries to make the setup as easy as possible
Common options:
--host=HOST
(default: 127.0.0.1) --port=PORT
(default: 8080) $ pyxer serve
Options:
--reload
XXXWith the virtual machine:
$ xpaster serve --reload
Without the virtual machine:
$ paster serve development.ini
$ xgae serve
To make websites safe against abuse Pyxer integrates support for reCaptcha. You have to register your web sites URL for free there to get a private and public key. To use them see the following demo:
from pyxer import recaptcha CAPTCHA_PUBLIC = "XXX" CAPTCHA_PRIVATE = "XXX" @expose def myform(**kw): # This creates the HTML code for the captcha input field c.captcha = recaptcha.html(CAPTCHA_PUBLIC) # Do some more form stuff here pass # Test if the captcha has been correct if recaptcha.test(CAPTCHA_PRIVATE): # Do something like storing the data into the database pass # After success jump to another page return redirect("success_info")
The corresponding template myform.html
could look like this:
<form action=""> <!-- add more input fields here --> $c.captcha <input type="submit" /> </form>
Handling of timezones is tricky in Python and on GAE. Therefore I will give a little introduction how this can be done quite easy. First you should install pytz like this:
$ pyxer vm (vm)$ easy_install pytz
If you want to show a datetime from Googles datastore you can now do like this in your templates:
Local time ${h.strftime(entry.added, '%H:%M', 'Europe/Berlin')}
Simple upload GAE:
@expose
def upload(image=None): if image is not None: Images(image=db.Blob(image.file.read())).put()
Simple out:
@expose def show(): image = Images.all().get() #???
if image.image:
response.headers['Content-Type'] = 'image/jpeg'
response.body_file.write(image.image)
return "NO IMAGE"
index
: Name of the root controllerdefault
: Name of the collecting controllerrouter
: Name of the routing objectsession
: Session req
, request
resp
, response
cache
c
g
h
config