How to use PyHP =============== PyHP is an hypertext preprocessor: actually, its name is a pseudoacronym standing for Python Hypertext Preprocessor (something like PHP). Its common use is associated to markup languages like HTML and XHTML to produce dynamical web pages. The mod_pyhp module for Apache is the engine of the preprocessor: it parses text included in the input file, generating a Python script then executed by the Python interpreter '''server side''', creating a web page as output. ------------------------------------------- Getting started: installing the PyHP module ------------------------------------------- To setup the PyHP module you need an Apache2, APR libraries and build tools installation. Once having that, you can download the PyHP source code from the PyHP Sourceforge SVN repository. If you have a Subversion client installed, you can easily get the code with the command: :: svn checkout https://pyhp.svn.sourceforge.net/svnroot/pyhp pyhp If you prefer to browse the source using a web browser, you can take a look at http://pyhp.svn.sourceforge.net/viewvc/pyhp/ After getting the PyHP source code, you should compile and install it directly from the directory you just created downloading the code with the typical commands: :: autoreconf -i ./configure make sudo make install This ease is provided by the autotools-based compiling system. After installation, you need to do some basic setting up: actually, we need to tell Apache to load the PyHP module and associate it with some file extension, in order to have at least the .pyhp files processed by the PyHP module. Just add these lines to the Apache configuration file: :: LoadModule pyhp_module /usr/lib/apache2/modules/mod_pyhp.so AddType application/x-httpd-pyhp .pyhp Since the module recognise files to be processed by the MIME type specification, you also need to specify an Add Type clause, as shown above. If you wish to associate the PyHP module with other files extension, you can add other Add Type lines, for example: :: AddType application/x-httpd-pyhp .txt At this point, you just need to restart Apache to get the PyHP module working on your system. Actually, it will run with the default configuration: to set customised options, see the ConfigurationOptions section. ----------------- Writing PyHP code ----------------- PyHP and its preprocessor module combined with HTML/XHTML are used to produce dynamical web pages, merging the static content comfortably defined with the hypertext markup language with contents generated by the execution of Python script(s). HTML (or XHTML) documents are text files requested by client's browser and given by an HTTP server (like Apache). You can easily define Python scripts to be (pre)processed by the PyHP module directly into the text of your web page using special start and end tags: the tag and the tag. ------------------------------------- Discovering the special tag ------------------------------------- The easiest way to put Python code into your web page is using the special tag. Let's give an example. :: Hi, the time is
Welcome! Acceding this file with our browser, we will get an output like this: :: Hi, the time is Wed Apr 30 11:07:55 2008 Welcome! The tag let you insert inline Python code. You can open, close and reopen a pyhp tag how many times you desire. As this tag specify the processor to "enter" and "exit" to and from a special status in which the code is interpreted and executed, it's incoerent to nest other tags inside the first one, and this is not supported. From now and on, you can use every standard Python command into your PyHP scripts to build the page content you want to dinamically show. .. note:: Since the use of PyHP assumes at least a general knowledge and use of the Python programming language, this guide will not provide information about the use of Python structures and functionalities, such as dictionaries and their methods. For a specific guide about Python programming language, please refer to http://www.python.org or any manual publicly available as free resource on the world wide web or printed books sold by every library interested in computer science. .. note:: Within using Python commands, you should remember that when you print some output, it will be put inside an HTML document: this means that when you format the output text, you should do in the HTML way. For instance, ``print "My message string"`` won't feed a new line: to do that, you should use something like ``print '%s
' % "My message string"`` to make it work as you desire. ---------------------------------- Using the special tag ---------------------------------- Writing a more complex page or application could become difficult without segmenting and organizing the code. As web applications are often divided into multiple pages, we can use and combine multiple PyHP scripts and call or include them from other ones. To include a PyHP script saved onto a file, you can use the special ```` tag, with the following syntax: :: When the PyHP processor analyses the page, it imports the content of the specified .pyhp file (both absolute and relative paths are supported) and then parses and executes the code inside it, guaranteeing the variable's names scope accessibility. Let's give an example. Having two files: :hi.pyhp: :: :main.pyhp: ::
Welcome! executing the main.pyhp script we will obtain: :: Hi! Welcome! The include processor tracks included document, avoiding multiple nested execution of the same script file that would lead to circular inclusions. Since in systems like Unix compliant operating systems, same files might be referred by differents position (e.g. using links in different paths), it is requested to pay attention avoiding dangerous unwanted circular inclusions. For this reason, it is suggested to include "library" files using their complete path, in order to make the preprocessor understand if one of those files are already included or not. Writing your PyHP code, remember the behaviour of the Python indentation system: including a .pyhp file into another should respect the indentation of the includer one, or the PyHP/Python interpreter won't understand the bounds of your code blocks. To avoid this issue, it is suggested to begin writing PyHP code indenting from the beginning of the line following the ``