Follow this guide to get Reahl installed in your development environment and to get a skeleton web application going.
This version of Reahl requires at least version 2.7 of Python. We’re excited about Python 3, but changing over to Python 3 is a big job which we still have to get to!
A Reahl application uses a number of other projects. Some of these are programming frameworks and libraries that you’d also have to understand to be able to use Reahl. A basic knowledge of each of these tools will be a benefit if you want to follow this tutorial. (Where relevant, the tutorial does point this out, so there’s no need to rush off and learn them all right now...)
The most important projects you should know about are:
There are also projects that are used totally behind the scenes, and you need not understand anything about them except how to get them installed on your platform. The most visible of these is a database back-end. For this purpose SQLite and PostgreSQL are currently supported. SQLite is used throughout the tutorial. You need not understand much about SQLite in order to follow the tutorial though. Just ensure that it has been installed.
In order to install Reahl, you need some non-Python software installed on your system first. Installing these will differ from platform to platform. If you are on Ubuntu (or another Debian-based distribution of Linux), all these can be installed by simply issuing:
sudo apt-get install python-virtualenv # For virtualenv - see below sudo apt-get install python-dev gcc cython # To be able to compile Python modules implemented in C (WebTest, SQLAlchemy, etc) sudo apt-get install libsqlite3-0 # Sqlite sudo apt-get install libxml2-dev libxslt-dev # Header files for compiling WebTest
If you’re not on a Debian-based distro, you will have to find and install equivalents for your platform.
For a development environment, it is recommended to run Reahl within a sandboxed Python environment provided by virtualenv. Doing this means that your main Python installation is left in the state it currently is, and that you do not need permissions of restricted users to install all the extra Python packages.
Virtualenv should have been installed with the packages listed above, allowing you to create a new virtualenv with:
This creates a new directory ./reahl_env with an isolated Python environment inside it.
In order to work inside that isolated environment, you need to execute the following on the command line:
After activating your new environment, the prompt of the command line changes to reflect the environment that is currently active.
With your virtualenv activated, Reahl can be installed into it by issuing the following command:
pip install reahl[sqlite,dev,doc]
This may run a while, as it installs all of the projects Reahl depends on as well. Some of these dependencies are installed and built from source, hence, this process needs all the non-Python packages mentioned above to be installed before you pip install Reahl itself.
In Reahl, everything – even your web application – is a component. The very first thing to do in order to create a web application is thus to create an empty component and specify which other components it depends on.
To do that, create an empty directory (for example called hello) and put a file inside it called .reahlproject:
hello | `-- .reahlproject
The presence of the .reahlproject file in a directory alerts the reahl script (a tool used while in development) that the directory contains a Reahl component. The contents of .reahlproject is XML which, in its most basic form, merely lists the other components that this one depends on. The following example contains a list of all the Reahl components needed for a basic web application:
<project type="egg"> <deps purpose="run"> <egg name="reahl-component"/> <egg name="reahl-web"/> <egg name="reahl-sqlalchemysupport"/> <egg name="reahl-web-elixirimpl"/> </deps> </project>
These are all the necessary components for a basic web application:
The Reahl component infrastructure is really just a thin layer built upon Python eggs and the Python distribute package.
If you are familiar with Python Eggs, you would know that a programmer usually creates a file called setup.py in the root directory of a new Python Egg. This file contains a bit of Python code and information about the Egg. It is usually executed via Python as a command line program which can perform a number of special operations on a Python Egg.
In Reahl, setup.py has been replaced by .reahlproject and the reahl script. That just means a less complicated file and more functionality.
However, any Reahl component is still a Python Egg, and as with all Eggs, it should be prepared for use in a development environment. This is done by executing the following from within the newly created hello directory:
reahl setup -- develop -N
Programmers familiar with Python Eggs would immediately recognise that this is equivalent to what you’d do for a Python Egg with a setup.py: python setup.py develop -N
The reahl setup command runs normal setup.py functionality, passing the parameters following after the “--” on to setup.py.
The most basic running Reahl web application one can build is an application with an empty home page. Here is an example of just such a program – you can put it in a file hello.py inside the hello directory:
from reahl.web.fw import Region from reahl.web.ui import TwoColumnPage class HelloApp(Region): def assemble(self): self.define_main_window(TwoColumnPage) self.define_view(u'/', title=u'Home')
In Reahl, a web application has a single main window which contains the basic layout of the web site and the elements that would be present on all pages. (Think header, footer, etc.)
A basic web application is a single Region. The code above shows how this Region is created by deriving a new class from Region. Such a class should have an assemble method inside of which the basic structure of the application is defined.
A Reahl application has a configuration directory which may contain many configuration files. This is because any given Reahl application consists of a number of components – each of which needs its own configuration file. The vast majority of configuration information is defaulted sensibly though, which means only a small number of configuration items (and files) are necessary for a given application.
By convention the configuration directory used for development forms part of its source code, and is called etc.
You can see what configuration is needed by using the reahl-control script. First, create an empty directory underneath that of your component, named etc. Then try out the following command:
reahl-control listconfig --missing --files --info etc
Executing this yields a listing of missing configuration settings and states for each setting where it should be set and what it means:
Listing config for ./etc web.site_root web.config.py The Region class to be used as the root of the web application
Luckily, there’s only one missing setting. Hence, we need to add the file web.config.py, and specify one setting inside it.
Adding this file brings the total files needed so far to:
hello |-- etc | `-- web.config.py |-- hello.py `-- .reahlproject
As one may surmise from the name of the config file, Reahl config files contain Python code. Inside these files, you can use dotted notation to access or set different configuration settings. Here is what is needed in the web.config.py for our example project:
from hello import HelloApp web.site_root = HelloApp
You can see info about all the configuration settings used by executing:
reahl-control listconfig --files --info etc
Or, to see the other possibilities related to listconfig, use:
reahl-control listconfig -h etc
Before the web application can be started, you need to create a database for it. This is necessary for any web application because the web framework itself uses a database. By default, Reahl uses the SQLite database.
Here we first create the database user, then the database itself and finally the database tables needed:
reahl-control createdbuser etc reahl-control createdb etc reahl-control createdbtables etc
When running these commands you will notice warnings logged to the console. You can safely ignore these for now. Some config values are defaulted in ways that will only work in development, but may cause problems in a production environment. These warnings are meant to alert a user of such “dangerous” default config values.
It is not necessary to install a web server in your development environment. To run your application just execute the following from the main hello directory:
reahl serve etc
You should now be able to point your browser to http://localhost:8000 and see a page which looks empty and is titled “Home”.
You can get a local copy of this example by using the reahl script:
reahl example tutorial.hello
You can also see what other examples are available by running: