µWeb¶

µWeb is a Python software package designed to provide a flexible, lightweight, but powerful base to build web applications on top of. It can tie in to mod_python for Apache, or run stand-alone, using Python's included BaseHTTPServer package.

µWeb provides an MVC like environment, built around three core philosophies:

1. as little boilerplate as possible;
2. as little Magic™ as possible;
3. and separation by convention, not brute force.

These philisophies overlap more than a little with the Zen of Python, which is not a coincidence.

Installation¶

Details on how to install µWeb can be found on the installation page.

Components¶

µWeb is a framework that consists of mix of components building from a low-level standalone server on top of BaseHTTPServer to a refined template parser and database abstraction model.

Request Router¶

The Request Router is the entry point of the µWeb framework. Any HTTP request seen by the server is passed through here, from which it is delegated to the proper handler.

PageMaker and Response (Controller)¶

PageMaker provides the controller part of the MVC approach. Each web request ends on a specific method of the PageMaker. From here, request information can be viewed (cookies, query arguments and POST data), and databases used to gather data to fulfill the request. Upon completion, a raw string or a more complex Response object may be returned.

TemplateParser (View)¶

Templates allow for a separation of presentation and logic, allowing you to move large parts of HTML or other output to a separate file. The TemplateParser replaces all the tags left in the template with the given output, which can be simple variables, or the use of multi-level database objects. Also, as an added benefit, the default output of TemplateParser is such that any text fed into the template, is automatically made safe for HTML output.

Database abstraction (Model)¶

The µWeb database model provides a Record class which provides for a smart interaction with your database tables. Creating a simple Record subclass for each of your (main) database tables allows you:

• to load database record by their primary key value;
• automatic retrieval of 1-1 or n-1 relations;
• creating, updating or deleting of records.

HTTP Request abstraction¶

The Request class ensures that, no matter the server that accepts the request (Apache or BaseHTTPServer), the various parts further on in the framework have access to header information, query arguments, cookies and POST data in a structured manner. More information on the client, server and other environment variables is also available here.

µWeb Standalone Server¶

Standalone is a module that allows µWeb to function outside the presence of Apache and mod_python. This is easy for local testing, or low volume websites.

Common errors when building uweb projects¶

As with any software package, some things tend to go awry for most new users, so we've made a list of them, and their solution.

Implementation¶

Initialize uweb project¶

The easy way to initialize uweb is to type

uweb init [your project name]

This creates a folder in your current directory with the project name.
When you don't pick a name uweb uses 'uweb_project' by default.
You probably want pick a nice name because this is what makes your project unique like a little snow flake.

uweb init snowflake

--------------------------------------------
initializing uweb
--------------------------------------------
cloning uweb source
setting up router
setting up apache config
--------------------------------------------
initialization complete - have fun with uweb
--------------------------------------------

This generates the snowflake uweb project and generates a folder named 'snowflake' in your current directory. The snowflake project contains multiple folders and files.
In the next chapter we'll activate our project locally.

If you already have a project with the same name, uweb gives you a warning and cancels initialization.

Project already excist, use -f (force) to wipe project.

If you somehow completely ruined your project and want a clean start add the 'f' (force) flag to remove your project and execute a clean initialization.

uweb init snowflake -f

The same effect can be recreated by deleting the project and initializing uweb as usual.

Start/stop local webserver¶

uweb works with router files. A router usually represents a domain. To start a webserver navigate to your router (in the project's router folder) and type 'start'.

python /home/user/snowflake/router/snowflake.py start

Next you can open up your browser and navigate to:

http://localhost:8082/

Uweb uses port 8082 locally by default.
This brings you to the default uweb page which contains the text 'Hello µWeb'.
This means you have successfully setup and started your own uweb project.

To stop you local server, replace the 'start' command with 'stop'

python /home/user/snowflake/router/snowflake.py stop

When you make updates in your router, uweb usually don't update your changes manually.
Type 'restart' to restart your local server with the new configurations.

python /home/user/snowflake/router/snowflake.py restart

Setting up uweb in apache¶

To setup uweb in apache, copy the apache.conf (in the root of your project) to your available apache sites.
Uweb its default domain is your project name followed by local.

ServerName  [project_name].local

change this to the desired domain name.

ServerName  snowflake.com

Next add this domain to your hosts and reload apache.
Now your uweb project should work in Apache.

Warning
Renaming/moving your project will result in a broken apache config file.
When you rename your project, please also adjust the apache.conf file to the new name / location

Quick router controls¶

Starting and stopping uweb routers stakes some time.
That's why uweb does have some nifty functionallity which makes navigating to routers obsolete.

uweb [sites|start|stop|restart|add|remove] -n [project name]

Each project you create is added to je uweb router location file.
This file contains the router locations of all your uweb project.
Calling the sites argument will display all projects and there route locations

$ uweb sites
snowflake: /home/codehunger/snowflake/router/snowflake.py

In this example you see only one uweb project.
This project is called 'snowflake' and the router location is '/home/codehunger/snowflake/router/snowflake.py'

To start the 'snowflake' router you can simpely call uweb to start the snowflake router.

$ uweb start -n snowflake
Starting ...

The n option should contain the name of your project.
This could also be used to

restart the router:

$ uweb restart -n snowflake
Stopping ...
Starting ...

stop the router:

$ uweb stop -n snowflake
Stopping ...

When you add a uweb website (from a repository for example), uweb need to be updated.
To add a path to the uwebsites use the 'add' argument.

$ uweb sites
snowflake: /home/codehunger/snowflake/router/snowflake.py
$ uweb add -n foreign_snowflake -r /home/codehunger/foreign_snowflake/router/snowflake.py
$ uweb sites
foreign_snowflake: /home/codehunger/foreign_snowflake/router/snowflake.py
snowflake: /home/codehunger/snowflake/router/snowflake.py

The -n option contains the project name.
The -r is the router location.

In this example a project is added to the uweb sites.
As you can see 'uweb sites' first printed 1 record and after adding a new site it printed 2 records.

When you move your project the router links are not directing to your router anymore.
You can update your router location with the -f (force) flag.

$ uweb add -f -n foreign_snowflake -r /home/bob/snowflake/router/snowflake.py

This updates the 'foreign_snowflake' record with a new router location.
The previous router location is overwritten by the new location.