Myghty's primary feature is it's Python Server Page (PSP) system. Individual templates are generated into pure Python modules which become the method of serving the content. Myghty creates real Python modules from templates, which are regular .py files with corresponding .pyc bytecode files. These modules can also be generated in memory only, if desired.

Myghty templates allow full Python syntax to be embedded amongst HTML or other markup, and keeps intact the full syntax and indentation scheme of Python, even within very markup-interactive sections of code. Myghty also lets you organize embedded Python code in ways that minimize its intrusion upon markup. Python embedded within markup is clearly denoted via <%python> tags or the more interactive "%" syntax:

 
 <%python>
     def somefunc():
         return True
 </%python>
 
 % if somefunc():
 <p>
     hello!
 </p>
 % # end for

Read more about Myghty syntax in Embedding Python in HTML.

Python sections can optionally have scope attributes specified, with values such as "global", "request", "init" and "cleanup", which cause the contained python code to execute at specific points in the template's execution, regardless of where they are placed in the template. This allows flexible organization of template code and a very distinct separation of Python and markup. Read more about Myghty code scope in Scoped <%python> Blocks.

Myghty allows you to organize Python code and markup into smaller sub-units of a page called Components. Consider a page like this:

                        +--------------------+
                        |    |    toolbar    |
                        |    +---------------|
                        |  header            |
                        |--------------------|
                        |        |           |
                        | left   |           |
                        | nav    | content   |
                        |        |           |
                        |        |           |
                        |--------------------|
                        |        footer      |
                        +--------------------+

Each subsection of this page is a likely candidate to be its own component. The overall template is referred to as the top-level component, and contains any number of subcomponents, which are effectively semi-autonomous units of code within a larger template file. They have their own namespaces, passed-in argument lists, buffering and caching attributes, etc. Components normally send their output to the current output stream, but can also be called as Python functions with return values, or their output content can be grabbed into a string as the return value.

All components are capable of calling any other component within the same template, and also of calling another template to be executed inline, or even the subcomponents contained within other templates, which are known as methods. With these functions, the page above can be organized into any variety of HTML/python code-snippets either within a single template file or across any combination of template and/or method library files:

           components.myt
        +-----------------+                                      
        |                 |                              page.myt
        |                 |       header.myt        +---------------+
        |  +-----------+  |    +---------------+    |   **********  |
        |  | toolbar   |--------------->*****  |------> **********  |
        |  +-----------+  |    |    header     |    |               |
        |                 |    +---------------+    | **            |
        |    +------+     |                         | **    page    |
        |    |      |     |                         | **   content  |
        |    | left | ------------------------------->**            |
        |    | nav  |     |                         | **            |
        |    |      |     |                         |               |
        |    +------+     |                         | +-----------+ |
        |                 |                         | |  footer   | |
        +-----------------+                         | +-----------+ |
                                                    +---------------+
                                       
                                    

Components are called via the <& &> tag construct, and also support "open-tag/close-tag" behavior via the <&| &></&> syntax, known as a component call with content. The content within the tags is enclosed into its own Python function that is callable by the component code, allowing custom tags with full control of execution to be created.

Read more about Myghty components in Components.

Myghty introduces a convenient environment-agnostic way to mix regular Python modules with template code known as Module Components. The same component model that applies to templates can be applied to regular Python objects and functions, either by explicitly subclassing the ModuleComponent class in a manner similar to a Servlet, or by configuring Myghty to implicitly resolve any regular Python function, callable object, or plain object instance into a FunctionComponent (version 0.98).

Module Components serve primarily as the "controller" stage in a request, the initial entry point for a request that handles data loading and state changes, and then passes control onto a template for display. As they are also fully capable component objects, they can also just as easily be embedded within templates, either by themselves or wrapped around further sub-content, to allow the creation of module-based tag libraries.

A big advantage to using Module Components for controller code is that the application remains completely portable to any environment, including mod_python, any WSGI environment, or non-web oriented environments.

Read more about Myghty Module Components in Module Components.

Any top level component can also be inherited by another top level component. This means the execution of pages can be implicitly or explicitly "wrapped" by an enclosing template, which can control the execution and content embedding of its "subtemplate" at any point in its execution. In the diagram below, a content-based HTML file is enclosed by a file providing a standardized layout, which is enclosed by another file that provides session authentication code and management:

        /lib/authenticate.myt
        +------------------+
        |% authenticate()  |
        |-------------------             /autohandler
        |                  |         +-----------------+                
        |                            |      header     |    /foo/content.myt
        |                            |-----------------|      +--------+
        |    m.call_next() --->      |                        |        |
        |                            |   m.call_next() --->   |content |
        |                            |                        |        |
        |                  |         |-----------------|      +--------+
        |------------------|         |      footer     |                
        |% cleanup()       |         +-----------------+                
        +------------------+

The methods of a parent template are also inherited by the child and can also be overridden, allowing a sub-template to change the behavior of its parent. Layout and behavior of individual groups of templates, directories, or entire sites can be managed through a concise and centralized group of inheritable templates.

Read more about Inheritance in Inheritance.

Myghty is written with fast performance and highly concurrent service in mind. A flexible cache API, supporting in-memory, file, DBM and Memcached backends allows quick re-delivery of complicated pages. Buffering can be completely disabled, for an entire site or just individual pages, to send template output to directly to the client. Expensive cache and compilation operations are process- and thread-synchronized to prevent data corruption and redundant computation. A configurable least-recently-used cache holds only the most heavily used components in memory, deferring less used ones to be loaded again from .pyc files. Filesystem checks can be disabled as well, allowing complete in-memory operation. Large chunks of plain text are distilled into large, multi-line write() statements to minimize method call overhead for large and mostly static pages.

• Session object support - can write session data into memory, plain or DBM files, or Memcached.
• Direct connectors for mod_python, CGI, WSGI, Python Paste, SimpleHTTPServer. As the Interpreter object is a lightweight object with no external dependencies whatsoever, any Python application or application server can invoke any series of Myghty components with just one line of code.
• A super-configurable ruleset driven URI resolution architecture allowing many options for resolving URI's both externally and within templates. Allows any combination of resolution directly to templates, Module Components, or any plain Python function or object instance. Special rules exist to route non-existent URI's to specific components, to cache the results of URI resolution for higher performance, and to execute conditionally based on contextual information.
• Cache API and implementation, can cache component output and any other data structure in memory, in plain files, DBM files, or Memcached. Includes a "busy lock" feature that allows a slow re-generation method to execute while the old data continues to be returned to other threads and processes. New cache implementations can be added fairly easily.
• Flexible global namespaces allow components to have any number of custom "global" variables.
• Special code blocks allow the construction of code that is local to the current request, or local to the current thread. A ThreadLocal object is supplied as well for safe management of thread-sensitive resources such as databases.
• Fine grained control of buffering - the buffering of textual output as it is delivered to the client can controlled at the application, page, or component level.
• Custom filtering functions can be defined for the output any component, within the source of the component via the <%filter> tag.
• Full featured error handling and reporting. errors can be logged to the Apache logs or standard error, caught by application code, and/or reported to the browser screen. stack traces are delivered showing original template line numbers.

• Python 2.3.3 or greater. There is an issue with weakrefs (Python bug id 839548) prior to that version which impacts stability.
• For production webserver usage, a server environment that supports one of: CGI, WSGI, or mod_python.
• For mod_python usage, Apache 1.3/mod_python 2.7 (or greater) or Apache 2.0/mod_python 3.1 (or greater).
• Tested platforms: Linux (RedHat 6.2, RedHat 9), Mac OSX, Solaris, Windows 2000. Prefork and worker MPMs tested on Apache 2.0.
• Familiarity with the webserver being used and whatever plug-in architecture being used.

Myghty includes an out-of-the-box instant-gratification examples/documentation server you can run directly from the distribution files, which listens on port 8000 by default. Extract the distribution from its .tar.gz file. Then run the server as follows:

cd /path/to/Myghty-X.XX/
python ./tools/run_docs.py

Then point a webbrowser to the location http://localhost:8000/. An alternative port can be specified on the command line, e.g. python ./tools/run_docs.py 8100.

The demo server is a handy tool to browse through a release without having to perform an install. The underlying HTTP server implementation can also be handy for development and prototyping.

Myghty now installs with setuptools, which is the next generation of the standard Python distutils module. Its basic usage is the same as that of distutils. Switch to the user account under which Python is installed, and run:

cd /path/to/Myghty-X.XX/
python setup.py install

This installer also installs Myghty in a version-specific location, such as "site-packages/Myghty-0.99-py2.3.egg/". If you have installed a version of Myghty prior to 0.99, the distutils-based installation, which lives in "site-packages/myghty", will produce a conflict message when running setup.py. After installation, you should delete the old install, either manually or via the command python ez_setup.py -D myghty.

This documentation can also be generated into flat html files that are browseable directly from the filesystem. Myghty can create these files by running the genhtml.py utility:

cd /path/to/Myghty-X.XX/doc
python genhtml.py

Myghty now includes a few Python Paste templates, which are pre-built Myghty applications that can install themselves into a runnable application. Python 2.4 is required to run Python Paste.

Myghty's standard install procedure will automatically download and install all Python Paste components, which are also available at http://pythonpaste.org/download. Also required is WSGIUtils, which must be installed from a particular .egg file format, via:

python ez_setup.py http://pylons.groovie.org/files/WSGIUtils-0.6-py2.4.egg

When Python Paste is installed, it will install the script "paster" into the standard Python scripts location. Insure that this location is in your path. Then to set up a Paste Template, just do:

cd /target/directory
paster create --template=myghty_simple myproject
cd myproject
        paster serve server.conf

The myghty_simple template is a very small four-template configuration, which will by default listen on port 8080. Also included is myghty_modulecomponent, which shows off a more controller-oriented configuration, and myghty_routes, which builds a new Rails-like "Routes" configuration.

When a new Paste Template project is created, the file <projectname>/server.conf illustrates the general Paste options, such as the server listening port. Myghty-specific configuration information is in <projectname>/<projectname>/webconfig.py.

There is also a generic tool for running any Myghty template either to standard output or to a file. The command is as follows:

python tools/gen.py --help

usage: gen.py [options] files...

options:
  -h, --help            show this help message and exit
  --croot=COMPONENT_ROOT
                        set component root (default: ./)
  --dest=DESTINATION    set destination directory (default: ./)
  --stdout              send output to stdout
  --datadir=DATADIR     set data directory (default: dont use data directory)
  --ext=EXTENSION       file extension for output files (default: .html)
  --source              generate the source component to stdout

The standalone handler is a web server built off of Python's BaseHTTPServer class, and is great for local workstation development and testing. Here is a quick example to simply serve pages from the current directory - place the following code into a file run_server.py:

#!/usr/local/bin/python

import myghty.http.HTTPServerHandler as HTTPServerHandler

# create the server.
httpd = HTTPServerHandler.HTTPServer(
    # port number to listen on.
    port = 8080,
    
    # HSHandler list.  indicates paths where the file should be interpreted
    # as a Myghty component request.
    # Format is a list of dictionaries, each maps a regular expression  matching a URI
    # to an instance of HTTPServerHandler.HSHandler, containing the arguments for
    # a Myghty interprter.  for HTTP requests of type "text/*", this list is matched
    # first against the incoming request URI.  
    handlers = [
        {'.*\.myt' : HTTPServerHandler.HSHandler(data_dir = './cache', component_root = './')},
    ],

    # document root list.  indicates paths where the file should be served
    # like a normal file, with the appropriate MIME type set as the content-type.
    # These are served for all non "text/*" HTTP requests, and all
    # incoming URIs that do not match the list of handlers above.
    docroot = [{'.*' : './'}],
    
)       
        
# run the server
httpd.serve_forever()

Then, in that same directory, place another file, called index.myt:

<html>
<head><title>Test Page</title></head>
<body>
    Welcome to Myghty !
</body>
</html>

To run the server, type:

python ./run_server.py

and point a web browser to http://localhost:8080/index.myt. The data directory ./cache will be automatically created to store data files.

Other examples of the Standalone handler are available in examples/shoppingcart/run_cart.py for a straightforward example, or tools/run_docs.py for an advanced example that also makes use of custom resolution strategies.

Serving Myghty template files directly via CGI can be achieved with the myghty.cgi utility located in the /tools directory. This program is a simple interface to the CGIHandler, which converts the "path-info" of the requested URI into a Myghty component call. The script's configuration information is present within the top half of the script itself, to allow the most straightforward configuration, although it could certainly be modified to load configuration information from any other source such as other Python modules or configuration files.

It requires configuration of the component root, data directory, and optionally additional Python libraries to run. Other configuration parameters can be added to the handle() call as well. The cgi handler will handle requests of the form:

http://<domain>/<cgi-bin directory>/myghty.cgi/<uri of template>.

The script is below. Modify the appropriate lines and copy the myghty.cgi program into your webserver's cgi-bin directory for a basic cgi-based template handler. For usage within custom CGI scripts, see the next section detailing programmatic methods of calling Myghty.

#!/usr/local/bin/python

# myghty cgi runner.  place in cgi-bin directory and address Myghty templates
# with URLs in the form:

# http://mysite.com/cgi-bin/myghty.cgi/path/to/template.myt

# component root.  this is where the Myghty templates are.
component_root = '/path/to/croot'

# data directory.  this is where Myghty puts its object files.
data_dir = '/path/to/datadir'

# libraries.  Put paths to additional custom Python libraries here.
lib = ['/path/to/custom/libraries']

import sys
[sys.path.append(path) for path in lib]

import myghty.http.CGIHandler as handler

handler.handle(component_root=component_root, data_dir=data_dir)

This section assumes familiarity with basic Apache configuration. Myghty includes a handler known as myghty.http.ApacheHandler which can interpret requests from the mod_python request object. This handler can be configured directly within the httpd.conf file of Apache, using regular Apache configuration file directives to configure its options. Alternatively, the ApacheHandler can be used within an external Python module that defines its own mod_python handler, which allows most of the configuration of the handler to be stated within a Python file instead of the httpd.conf file. The first method, described in this section, is expedient for a straightforward Myghty template service, or a simple view-controller setup. While the full range of configurational options can be present directly in http.conf stated as Apache configuration directives, including Python imports, functions, and datastructures, the syntax of embedding Python into conf directives can quickly become burdensome when configuring an application with a complex resolution stream. Therefore it is recommended that Apache users also become familiar with programmatic configuration, described in the section ApacheHandler.

Myghty configuration parameters are written in the Apache httpd.conf file as "Myghty" plus the parameter name in InitialCaps. The full range of configuration parameters in None may be used. The values (right-hand side of the configuration directive) are Python evaluable expressions. In the simplest case, this is just a string, which is mostly easily identified as r"<string>" so that Apache does not strip the quotes out. Any Python structure can be used as the value, such as a list, dictionary, lambda, etc., as long as the proper Apache conf escaping is used.

Below is a straightforward example that routes all Apache requests for files with the extension ".myt" to the Myghty ApacheHandler:

# associate .myt files with mod_python
# mod_python 3.1 uses 'mod_python'
AddHandler mod_python .myt

# or for mod_python 2.7 use 'python-program'
# AddHandler python-program .myt

# set the handler called by mod_python to be the Myghty ApacheHandler
PythonHandler myghty.ApacheHandler::handle

# set python library paths - this line is used to indicate
# additional user-defined library paths.  this path is not required for the 
# Myghty templates themselves.
PythonPath "sys.path+[r'/path/to/my/libraries']"

# set component root.
# for this example, an incoming URL of http://mysite.com/files/myfile.myt 
# will be resolved as: /path/to/htdocs/files/myfile.myt
PythonOption MyghtyComponentRoot r"/path/to/htdocs"

# data directory where myghty will write its object files,
# as well as session, cache, and lock files
PythonOption MyghtyDataDir r"/path/to/writeable/data/directory/"

# other options - simply write as 'Myghty' with the param name in
# InitialCaps format, values should be legal python expressions
# watch out for using quotes "" as apache.conf removes them - 
# use r"value" or '"value"' instead
PythonOption Myghty<paramname> <paramvalue>

When this is done, requests to Apache which refer to pages with the extension .myt will be routed to the ApacheHandler, which will resolve the filename into a component which is then executed.

An additional format for the "MyghtyComponentRoot" parameter, a list of multiple paths, can be specified as a list of dictionaries. An example:

# Multiple Roots, each has a key to identify it,
# and their ordering determines their precedence
PythonOption MyghtyComponentRoot \
    "[  \
         {'components':'/optional/path/to/components'}, \
         {'main':'/path/to/htdocs/htdocs'} \
    ]"

Keep in mind that the MyghtyComponentRoot parameter (normally called component_root) defines filesystem paths that have no relationship to Apache DocumentRoots. From the perspective of Apache, there is only a single mod_python handler being invoked, and it has no awareness of the component_root. This means that any incoming URL which matches the Myghty handler will be matched to a root in the component_root and served as a Myghty template, effectively allowing "access" to files that are not directly access-controlled by Apache. To restrict direct access to Myghty component files which are meant for internal use, an alternate file extension, such as ".myc" can be used, so that while a Myghty component can internally find those files within the component_root, the Apache server has no knowledge of the .myc extension and they are not served. This also requires that the .myc files are kept in a directory or directories separate from any configured Apache DocuementRoots.

Myghty also has the ability to handle directory requests and requests for nonexistent files via various mechanisms, including dhandler and Module Components. However, the example above is configured to only respond to URLs with the specific file extension of ".myt". To handle directory requests without a filename being present, or requests for many different file extensions at once, replace the usage of AddHandler with the Apache SetHandler directive combined with the <FilesMatch>, <LocationMatch>, or <DirectoryMatch> Apache directives. These directives are described in the Apache documentation. For example:

<LocationMatch '/store/.*'>
    SetHandler mod_python
    PythonHandler myghty.ApacheHandler::handle
    PythonPath "sys.path+[r'/path/to/my/libraries']"
    
    # module component directive.  matches regular expressions to Python classes and functions.
    PythonOption MyghtyModuleComponents "[ \
            {'/store/product/.*':store:ProductHandler},\
            {'/store/checkout/.*':store:CheckoutHandler},\
        ]"
    PythonOption MyghtyComponentRoot r"/path/to/htdocs"
    PythonOption MyghtyDataDir r"/path/to/writeable/data/directory/"
</LocationMatch>

The above MyghtyModuleComponents, the apache version of module_components, is just one way to serve module components; there is also module_root, as well as the Routes resolver.

When serving all files within a directory, one should take care that Myghty is not be used to handle binary files, such as images. Also, it might be inappropriate to serve other kinds of text files such as stylesheets (.css files) and javascript files (.js files), even though one could use Myghty templating to serve these. To get around these issues, when straight file-extension matching is not enough, the Myghty and non-Myghty files can be placed in different directories and Apache correspondingly configured to enable Python handling in the Myghty directory only.

For applications running in an HTTP environment, chaining to HTTPHandler is the usual method. An HTTPHandler object has awareness of HTTP requests for any of four different environments, which are WSGI, CGI, mod_python, and the standalone handler. It can construct the appropriate HTTP-aware environment to be delivered to the Interpreter and ultimately onto templates, which then receive an implementation-neutral interface to that environment via the r global object.

All HTTP-based Myghty configurations utilize a subclass of myghty.http.HTTPHandler.HTTPHandler to serve requests. Each HTTP environment has its own module: myghty.http.ApacheHandler, myghty.http.CGIHandler, myghty.http.HTTPServerHandler and myghty.http.WSGIHandler, containing the classes ApacheHandler, CGIHandler, HSHandler, and WSGIHandler, respectively.

As of version 0.98, the recommended way to chain to an HTTPHandler is to first get an instance to a handler via the function get_handler(), and then execute a request on that handler via the method handle(). In previous versions, a single function handle() is used which combines the argument sets of both functions; this function is still available.

The get_handler function retrieves a handler from a registry based on the given interpreter_name, which defaults to 'main' or in the case of Apache uses the http.conf variable "MyghtyInterpreterName". Application-scoped configuration variables are sent to this method which are used to create the initial HTTPHandler object. Once created, subsequent calls with the same interpreter_name will return the same HTTPHandler instance.

HTTPHandler then supplies the method handle() to handle requests, which accepts configurational parameters on a per request basis. Common per-request parameters include the component path or object to serve, the request arguments, and out_buffer to capture component output.

Each handler module has a slightly different calling signature, illustrated below.

The Myghty Interpreter object is the underlying engine that creates Myghty requests and executes them, supplying the necessary services each request needs. The Interpreter can be programmatically instantiated with a full set of configuration parameters and used directly.

While the advantage of using an HTTPHandler in an application is that Myghty components are aware of HTTP-specific information, such as the mod_python request object, HTTP headers, the httpd.conf configuration, etc., an application can also bypass all this by chaining directly to the Interpreter, if templates do not need HTTP awareness and the configuration can be programatically specified.

import myghty.interp as interp
from mod_python import apache

# set up a singleton instance of Interpreter
interpreter = interp.Interpreter(
        data_dir = './cache',
        component_root = './doc/components',
    )

def handle(request):
    # set up some data to send to the template
    data = {
        'foo': 'bar',
        'info' : get_info()
    }

    # call a template
    interpreter.execute('mytemplate.myt', request_args = data, out_buffer = request)

In the above approach, Myghty components are unaware of the HTTP environment, meaning there is no r global variable, and also can't make HTTP return calls or location redirects. A greater amount of responsibility is placed within the controller.

Control lines look like this:

 
 % for x in range(0, 10):
     hello!<br/>
 % # end for

The percent sign must be the very first character on the line, and the rest of the text is interpreted directly as Python code. The whitespace of the line, as well as the presence of a colon at the end of the line, is significant in determining the indentation of subsequent, non-control lines. As in the example above, the "for" statement followed by a colon, sets the indentation to be one level deeper, which causes the html text "hello!" to be iterated within the block created by the Python statement. The block is then closed by placing another control line, containing only whitespace plus an optional comment.

A more involved example:

% for mood in ['happy', 'happy', 'sad', 'sad', 'happy']:
%   if mood == 'happy':

  <img src="happyface.gif"/> Hey There !

%   else:

  <img src="sadface.gif"/> Buzz Off !

% #if statement
% #for loop

Note that the whitespace is not significant in plain HTML or text lines. When this template is converted to Python code, the plain text will be embedded in write statements that are indented properly within the block. Block-closing statements like "else:" and "except:" are also properly interpreted.

Note that a blank control line, i.e. starting with '%', is significant in affecting the whitespace indentation level, whether or not it contains a comment character '#' followed by a comment. To do line-based comments without affecting whitespace, use '#' as the very first character on a line:

% for x in (1,2,3):
    <b>hi <% x %></b>

# a comment

% # a block-closing control line

Comments can also be done with the <%doc> tag described in <%doc>.

A substitution is an embedded python expression, whos evaluated value will be sent to the output stream of the component via a m.write() statement:

Three plus five is: <% 3 + 5 %>

produces:

Three plus five is: 8

Substitutions can also span multiple lines which is handy in conjunction with triple-quoted blocks.

The text of substitutions can also be HTML or URL escaped via the use of flags. For a description of escape flags, see the section Escaping Content.

A python block is a block of pure python code:

<%python>
    user = usermanager.get_user()
    m.write("username is %s" % user.get_name())
</%python>

Code within a %python block is inserted directly into the component's generated Python code, with its whitespace normalized to that of the most recent control line. The %python tags, as well as the code within the tags, can be at any indentation level in relation to the rest of the document, including other %python blocks; it is only necessary that the indentation of the code within the block is internally consistent with itself. See the next section for an example.

There are also variations upon the %python block, where the contained Python code is executed within a specific context of a component's execution, such as initialization, cleanup, or global. These special variations are explained in Scoped <%python> Blocks.

To allow for finer control of the whitespace inherently generated by multiline HTML or Python control structures, the backslash character "\" can be used at the end of any line to suppress newline generation:

<span class="light">\
% for x in (1,2,3):
    [<% x %>]\
%
</span>

<span class="light">[1][2][3]</span>

The interaction of control lines, plain text, and python blocks is regulated by the Myghty engine to create an overall indentation scheme that is functional but also allows HTML and python blocks to be laid out with a high degree of freedom. The following example illustrates the indentation behavior:

<%python>
    forecasts = {
        'monday':'stormy',
        'tuesday':'sunny',
        'wednesday':'sunny', 
        'thursday':'humid',
        'friday':'tornado'
    }

</%python>

% for day in ['monday', 'tuesday', 'wednesday', 'thursday', 'friday']:

    <%python>

    weather = forecasts[day]
    if weather == 'tornado':
        advice = "run for the hills !"
    elif weather == 'stormy':
        advice = "bring an umbrella"
    else:
        advice = "enjoy the day...."
    </%python>

Weather for <% day %>:  <% forecasts[day] %>
Advice: <% advice %>

% # end for

The above block, when compiled, translates into the following Python code, that is then executed to produce the final output:

# BEGIN BLOCK body
m.write('''
''')
# test.myt Line 1

forecasts = {
        'monday':'stormy',
        'tuesday':'sunny',
        'wednesday':'sunny', 
        'thursday':'humid',
        'friday':'tornado'
}


# test.myt Line 11
m.write('''
''')
for day in ['monday', 'tuesday', 'wednesday', 'thursday', 'friday']:
       # test.myt Line 13
       m.write('''
    ''')
       # test.myt Line 14


       weather = forecasts[day]
       if weather == 'tornado':
               advice = "run for the hills !"
       elif weather == 'stormy':
               advice = "bring an umbrella"
       else:
               advice = "enjoy the day...."
       
       # test.myt Line 24
       m.write('''
Weather for ''')
       m.write( day )
       m.write(''':  ''')
       m.write( forecasts[day] )
       m.write('''
Advice: ''')
       # test.myt Line 26
       m.write( advice )
       m.write('''

''')
       # test.myt Line 28
# end for
# END BLOCK body

Usage: <%python scope="component">

Also called: <%python>

A component-scoped block is a regular block of Python that executes within the body of a template, as illustrated in the previous section Python Blocks . Many component-scoped blocks may exist in a template and they will all be executed in the place that they occur. Component scope has two variants, init and cleanup scope, which while still being component scope, execute at specific times in a component's execution regardless of their position in a template. They are described later in this section.

Usage: <%python scope="global">

Also called: <%global>, <%once>

A global-scoped block refers to a section of Python code that is executed exactly once for a component, within the scope of its process. In reality, this usually means code that is executed each time the module is newly loaded or reloaded in the current Python process, as it is called as part of the module import process. Variables that are declared in a global-scoped block are compiled as global variables at the top of the generated module, and thus can be seen from within the bodies of all components defined within the module. Assignment to these variables follows the Python scoping rules, meaning that they will magically be copied into local variables once assigned to unless they are pre-declared in the local block with the Python keyword global.

Global-scoped Python executes only once when a component module is first loaded, as part of its import. As such, it is called slightly outside of the normal request call-chain and does not have the usual access to the the built-in request-scoped variables m, r, ARGS, etc. However, you can access the Request that is corresponding to this very first execution via the static call request.instance(), which will give you the current request instance that is servicing the global-scoped block.

 
 <%python scope="global">
     # declare global variables, accessible
     # across this component's generated module
     
     message1 = "this is message one."
     message2 = "this is message two."
     message3 = "doh, im message three."
 </%python>
 
 <%python>
     # reference the global variables
     m.write("message one: " + message1)
     m.write("message two: " + message2)
     
     # we want to assign to message3,
     # so declare "global" first
     global message3
     
     message3 = "this is message three."
     
     m.write("message three: " + message3)
     
 </%python>

Use a global-scoped Python block to declare constants and resources which are shareable amongst all components within a template file. Note that for a threaded environment, global-scoped section applies to all threads within a process. This may not be appropriate for certain kinds of non-threadsafe resources, such as database handles, certain dbm modules, etc. For thread-local global variable declaration, see the section Thread Scope, or use the Myghty ThreadLocal() object described in Alternative to Thread Scope: ThreadLocal(). Similarly, request-scoped operation is provided as well, described in the section Request Scope.

A global-scoped block can only be placed in a top-level component, i.e. cannot be used within %def or %method.

Usage: <%python scope="init">

Also called: <%init>

Init-scoped Python is python code that is executed once per component execution, before any other local python code or text is processed. It really is just a variant of component scope, since it is still technically within component scope, just executed before any other component-scoped code executes. One handy thing about init scope is that you can stick it at the bottom of a big HTML file, or in any other weird place, and it will still execute before all the other local code. Its recommended as the place for setting up HTTP headers which can only be set before any content and/or whitespace is written (although if autoflush is disabled, this is less of an issue; see The Autoflush Option for more details).

In this example, a login function is queried to detect if the current browser is a logged in user. If not, the component wants to redirect to a login page. Since a redirect should occur before any output is generated, the login function and redirect occurs within an init-scoped Python block:

<%python scope="init">
    # check that the user is logged in, else
    # redirect them to a login page
    if not user_logged_in():
        m.send_redirect("/login.myt", hard = True)
</%python>  

<%doc>rest of page follows....</%doc>   
<html>
    <head>
    ....

Usage: <%python scope="cleanup">

Also called: <%cleanup>

Cleanup-scoped Python is Python code executed at the end of everything else within a component's execution. It is executed within the scope of a try..finally construct so its guaranteed to execute even in the case of an error condition.

In this example, a hypothetical LDAP database is accessed to get user information. Since the database connection is opened within the scope of the component inside its init-scoped block, it is closed within the cleanup-scoped block:

<%args>
    userid
</%args>
<%python scope="init">
    # open a connection to an expensive resource
    ldap = Ldap.connect()
    userrec = ldap.lookup(userid)
</%python>
    
    name: <% userrec['name'] %><br/>
    address: <% userrec['address'] %><br/>
    email: <% userrec['email'] %><br/>
    
<%python scope="cleanup">
    # insure the expensive resource is closed
    if ldap is not None:
        ldap.close()
</%python>

Usage: <%python scope="request">

Also called: <%requestlocal>, <%requestonce> or <%shared>

A request-scoped Python block has similarities to a global-scoped block, except instead of executing at the top of the generated component's module, it is executed within the context of a function definition that is executed once per request. Within this function definition, all the rest of the component's functions and variable namespaces are declared, so that when variables, functions and objects declared within this function are referenced, they are effectively unique to the individual request.

<%python scope="request">
    context = {}
</%python>

% context['start'] = True
<& dosomething &>

<%def dosomething>
% if context.has_key('start'):
    hi
% else:
    bye
</%def>

The good news is, the regular Myghty variables m, ARGS, r etc. are all available within a request-scoped block. Although since a request-scoped block executes within a unique place in the call-chain, the full functionality of m, such as component calling, is not currently supported within such a block.

Request-scoped sections can only be used in top-level components, i.e. cannot be used within %def or %method.

Usage: <%python scope="thread">

Also called: <%threadlocal>, <%threadonce>

A thread-scoped Python block is nearly the same as a Request Scope block, except its defining function is executed once per thread of execution, rather than once per request. In a non-threaded environment, this amounts to once per process. The standard global variables m, r etc. are still available, but their usefulness is limited, as they only represent the one particular request that happens to be the first request to execute within the current thread. Also, like request-scope, variables declared in a thread-scoped block cannot be changed except with pass-by-value techniques, described in Using Pass-By-Value

In this example, a gdbm file-based database is accessed to retreive weather information keyed off of a zipcode. Since gdbm uses the flock() system call, it's a good idea to keep the reference to a gdbm handle local to a particular thread (at least, the thread that opens the database must be the one that closes it). The reference to gdbm is created and initialized within a thread-scoped block to insure this behavior:

<%python scope="thread">
    # use GNU dbm, which definitely doesnt work in 
    # multiple threads (unless you specify 'u')
    import gdbm
    db = gdbm.open("weather.dbm", 'r')
</%python>

<%args>
    zipcode
</%args>

temperature in your zip for today is: <% db[zipcode] %>

Use a thread-scoped block to declare global resources which are not thread-safe. A big candidate for this is a database connection, or an object that contains a database-connection reference, for applications that are not trying too hard to separate their presentation code from their business logic (which, of course, they should be).

Thread-scoped sections can only be used in top-level components, i.e. cannot be used within %def or %method.

m is known as the "request", which represents the runtime context of the template being executed. Its not the same as the HTTP-specific request object r and is mostly agnostic of HTTP. m includes methods for handling output and writing content, calling other components, as well as other services that a template will usually need. The full list of request methods is described in The Request.

ARGS represents a dictionary of all arguments sent to the current component. While a component can specify arguments to be available in the component's namespace via the <%args> tag, the ARGS dictionary contains all arguments supplied to a component regardless of them being named in the <%args> section or not.

In the case of a top-level component called in an HTTP context, ARGS contains the full set of client request parameters. Each field is one of: a string, a list of strings, or for handling file upload objects, a Field object (from the FieldStorage API) or a list of Field objects.

For components called by other components, ARGS contains all the arguments sent by the calling component.

In all cases, the HTTP request arguments, or whatever arguments were originally sent to the request, are available via the request member request_args.

Component arguments are described in Component Arguments - the <%args> tag.

When running Myghty with any of the HTTPHandlers, i.e. ApacheHandler, CGIHandler, WSGIHandler, or HTTPServerHandler, variable r is a reference to either the mod python request object or a compatible emulation object. In the case of ApacheHandler, it is the actual mod_python request. In other cases, it attempts to provide a reasonably compatible interface, including the member variables headers_in, headers_out, err_headers_out, args, content_type, method, path_info, and filename (more can be added...just ask/submit patches). The request object is useful applications that need awareness of HTTP-specific concepts, such as headers and cookies, beyond what the more generic m object provides which attempts to be largely agnostic with regards to HTTP.

Under WSGIHandler, r also contains the member variables environ and start_response, so that an application may also have direct access to WSGI-specific constructs if needed.

s references the Myghty session object. It can also be configured to reference the mod_python session object when running with mod_python 3.1 To use s, you need to turn it on via use_session.

The Myghty session is still available even if s is not configured. See the section Session for full information on the session object.

Myghty supports the addition of any number of global variables that will be compiled into the namespace of all templates. The value of these variables can be specified on a per-application basis or a per-request basis. As of version 0.98, both scopes can be used simultaneously. Per-application globals can be specified via the initial interpreter configurational parameters, or within the httpd.conf file in a mod_python environment. Per-request globals require that the variables be initialized before the Myghty request begins, which requires programmatic "chaining" to the Interpreter via the methods described in Programmatic Configuration.

The two configuration parameters to add global arguments are allow_globals, which specifies a list of global variable names to compile into templates, and global_args, which is a dictionary containing the names of the variables mapped to their desired values. A basic example of programmatic global variables looks like:

import myghty.http.WSGIHandler

def application(environ, start_response):

    handler = myghty.http.WSGIHandler.get_handler(
        allow_globals = ['myglobal'],
        component_root='/path/to/htdocs', 
        data_dir='/path/to/datadirectory'
    )
    
    return handler.handle(
            environ, 
            start_response,
            global_args = {'myglobal' : 'hi'}
    )

Above, all Myghty components will have access to the global variable "myglobal" which has a per-request value of "hi". Note that the allow_globals parameter is only used on the first request, when constructing a new Interpreter object, whereas global_args may be specified for each request.

Another example, using Interpreter:

interpreter = interp.Interpreter(
    allow_globals = ['myglobal'],
    data_dir = '/path/to/datadir',
    component_root = '/foo/components',
)

interpreter.execute("file.myt", 
    global_args = {'myglobal':MyGlobalThingy()}
)

Here is an ApacheHandler example which specifies globals within both scopes:

import myghty.http.ApacheHandler as ApacheHandler

# create per-application global object
appglobal = 'myappglobal'

def handle(req):
    # create per-request global object
    myglob = MyGlobal(req)
    
    handler = ApacheHandler.get_handler(
            req, 
            allow_globals = ['appglobal', 'myglobal'],
            global_args = {'appglobal' : appglobal}
    )
            
    return handler.handle(req, global_args = {'myglobal':myglob})

Here is an application-scoped global added in a mod_python environment via the httpd.conf file:

# specify list of global variable names
PythonOption MyghtyAllowGlobals ['myglobal']

# specify the value of the global variable
PythonOption MyghtyGlobalArgs "{'myglobal':  \
    __import__('mystuff.util').util.MyGlobalThingy()}"

The most basic component operation is to have one template call another. In the simplest sense, this is just an HTML include, like a server side include. To have a template "page.myt" call upon another template "header.myt":

<html>
    <& header.myt &>
    <body>
    ... rest of page
    </body>
</html>

<head>
    <title>header</title>
</head>

Produces:

<html>
<head>
    <title>header</title>
</head>
    <body>
    ... rest of page
    </body>
</html>

When calling components, the path to the component is given as an environment-specific URI, and not an actual filesystem path. While the path can be specified as absolute, it is still determined as relative to one or more of the configured Myghty component roots. Myghty uses the component_root parameter as a list of filesystem paths with which to search for the requested component. If a relative path is used, the path is converted to an absolute path based on its relation to the location of the calling component, and then matched up against the list of component roots.

Components, since they are really Python functions, support argument lists. These arguments are supplied to the top-level component from the client request arguments, such as via a POST'ed form. When a component is called from another component, the calling component specifies its own local argument list to be sent to the called component.

A component can access all arguments that were sent to it by locating them in the ARGS dictionary. More commonly, it can specify a list of arguments it would like to receive as local variables via the <%args> tag:

<%args>
    username
    password
    
    # sessionid defaults to None
    sessionid = None
</%args>
<%python scope="init">
    if sessionid is None:
        sessionid = create_sid()
        
    if password != get_password(username):
        m.send_redirect("loginfailed.myt", hard=True)
</%python>

In the above example, the 'username' and 'password' arguments are required; if they are not present in the argument list sent to this component, an error will be raised. The 'sessionid' argument is given a default value, so it is not required in the argument list.

A component like the one above may be called with a URL such as:

http://foo.bar.com/login.myt?username=john&password=foo&sessionid=57347438

The values sent in an <%args> section are analgous to a Python function being called with named parameters. The above set of arguments, expressed as a Python function, looks like this:

def do_run_component(self, username, password, sessionid = None):

What this implies is that the default value sent for "sessionid" only takes effect within the body of the component. It does not set a default value for "sessionid" anywhere else. Different components could easily set different default values for "sessionid" and they would all take effect if "sessionid" is not present in the argument list.

Components can pass argument lists to other components when called. Below, a component 'showuser.myt' is called by another component 'page.myt':

<%args>
    username
    email
</%args>

Username: <% username %><br/>
Email: <a href="mailto:<% email %>"><% email %></a><br/>

Login information:
<& showuser.myt, username='john', email='jsmith@foo.com' &>

The component call tags "<& &>" take a named-parameter list just like a Python function, and can also have as the very last argument dictionary with ** notation just like in regular Python:

<& comp.myt, arg1=3.7, **ARGS &>

Above, the dictionary ARGS always has a list of all arguments sent to the component, regardless of whether or not they were specified in the <%args> section. This is a way of passing through "anonymous" arguments from a component's caller to its components being called.

A subcomponent is a component defined within a larger template, and acts as a callable "subsection" of that page. Subcomponents support almost all the functionality of a file-based component, allowing Python blocks of init, cleanup and component scope, but not global, request or thread scope.

A subcomponent, albeit a nonsensical one, looks like this:

<%def mycomponent>
    <%args>
        arg1 = 'foo'
        arg2 = 'bar'
    </%args>
    <%python scope="init">
        string = arg1 + " " + arg2
    </%python>
    
    i am mycomponent !
    
    <% string %>
</%def>

A regular subcomponent like this one is always called by another component, i.e. it can never be called directly from the request as a top-level component. Furthermore, subcomponents defined with the <%def> tag are private to the template file they appear in.

The subcomponent has access to all global variables, such as m and r, but it does not have access to the local variables of its containing component. This would include variables specified in the body of the main component, i.e. in init-, cleanup- and component-scoped <%python> blocks. Variables declared in global-, request- and thread-scoped <%python> blocks are available within subcomponents, subject to the restrictions on variables declared in those blocks. Variables declared within the body of a subcomponent remain local to that subcomponent.

A method is similar to a subcomponent, except its functionality is available outside of the file it appears in, and it can take advantage of inheritance from other template files.

<%method imamethod>
    <%args>
        radius
        coeffiecient = .5424
    </%args>
    <%python scope="init">
        foob = call_my_func(radius, coefficient)
    </%python>

    fractional fizzywhatsle: <% foob %>
</%method>

<%closure format_x>
    <%args>
        format = '%d'
    </%args>
    <% format % x %>
</%closure>

%   for x in (1,2,3):
        <& format_x, format='X:%d' &>
%

Closures support the <%args> tag, as well as Init Scope and Cleanup Scope. Closures can also be nested. They currently do not support the "component call with content" calling style but this may be added in the future.

Subcomponents and methods also may specify flags as described in the section <%flags>. The most useful flags for a subcomponent are the trim and autoflush flags, described in Filtering and Flushing (and Escaping).

There are two formats for specifing flags in a subcomponent:

 
 # traditional way
 
 <%def buffered>
     <%flags>
         autoflush=False
     </%flags>
     this is a buffered component
 </%def>
 
 
 # inline-attribute way
 
 <%method hyperlink trim="both">
     <%args>
         link
         name
     </%args>
     
     <a href="<% link %>">name</a>
 </%method>

Subcomponents and methods can also be called with a slightly different syntax, in a way that allows the calling component to specify a contained section of content to be made available to the called component as a Python function. Any subcomponent can query the global m object for a function that executes this content, if it is present. When the function is called, the code sent within the body of the component call with content is executed; this contained code executes within the context and namespace of the calling component.

<&| printme &>
    i am content that will be grabbed by PRINTME.
</&>

The called component can then reference the contained content like this:

<%def printme>
    I am PRINTME, what do you have to say ?<br/>
    <% m.content() %>
</%def>

The method m.content() executes the code contained within the <&| &>/</&> tags in its call to "printme", and returns it as a string. A component may query the request object m for the presense of this function via the method m.has_content().

A component call with content is one of the most powerful features of Myghty, allowing the creation of custom tags that can produce conditional sections, iterated sections, content-grabbing, and many other features. It is similar but not quite the same as the template inheritance methodology, in that it allows the body of a component to be distilled into a callable function passed to an enclosing component, but it involves a client explicitly opting to wrap part of itself in the body of another component call, rather than a client implicitly opting to wrap its entire self in the body of another component call.

The special component calling tags described above are just one way to call components. They can also be called directly off of the request object m, which is handy both for calling components within %python blocks as well as for capturing either the return value or the resulting content of a subcomponent. Component objects can also be directly referenced and executed via these methods.

The full index of request methods and members can be found in The Request.

Instances of Component objects can be accessed many ways from the request object, including the fetch_component method, and the current_component, request_component, and base_component members. The fetch_next method returns the next component in an inheritance chain. Finally, self refers to the current component.

The methods available directly from Component are listed below, followed by the members.

Lets start with hello world. All we need to do is create a new .py file, called hello.py, and place the following function inside it:

def helloworld(m):
    m.write("hello world !")

That is the extent of the module component itself. Since it is a plain function, this is an "implicit" module component.

To call the component, the request object is given a string starting with the prefix "MODULE:", followed by the module name and name of the callable or class, separated by a colon. In a template it is one of the following:

# inline
<& MODULE:hello:helloworld &>

# code
<%python>
    m.comp("MODULE:hello:helloworld")
</%python>

Alternatively (release 0.99b), the "MODULE:" prefix can also be an "at" sign as follows:

<& @hello:helloworld &>

<%python>
    m.comp("@hello:helloworld")
</%python>

Both the module name and the callable/class name can contain any number of periods to represent sub-modules or sub-properties of the module. Suppose helloworld was a property on an object:

hello = object()

def doit(m):
    m.write("hello world !")
    
hello.helloworld = doit

This component can be called as:

<& MODULE:hello:hello.helloworld &>

or just:

<& @hello:hello.helloworld &>

The callable can have any argument list, and even the m variable is optional (though highly recommended). Myghty uses the inspect library to determine the desired arguments based on the callable's signature. (for the performance minded, this is done only once when the component is first loaded). Using the names present in the argument list, Myghty will determine which of the available global variables will be specified, as well as what required and optional component arguments this MC will require. The component arguments are configured in exactly the same way as a template-based component configures its <%ARGS> section.

So to our "hello world" lets add the current and optionally tomorrow's weather:

def helloworld(m, today, tomorrow = None):
    m.write("hello world !  its a %s day today." % today)
    if tomorrow is None:
        m.write("Don't know what it is tomorrow, though.")
    else:
        m.write("But tomorrow, it'll be %s" % tomorrow)

This component can be called like these examples:

# inline shorthand
<& @hello:helloworld, today='sunny' &>

# inline longhand
<& MODULE:hello:helloworld, today='sunny' &>

# code
<%python>
    m.comp("MODULE:hello:helloworld", today='cloudy', tomorrow='rainy')
</%python>

The argument list of a module component may specify any of the standard and/or user-configured global arguments (globals were introduced in Standard Global Variables). All arguments are passed by name, so the ordering is not important:

def handle_request(m, ARGS, r, s, **params):
    # ...

The above component specifies that it will receive the global variables m, ARGS, r, and s. It also defines **params, so all remaining component arguments will be in this dictionary. A callable that defines simply **params will receive all globals and component arguments within the dictionary.

A summary of the various styles of MC are as follows. For each of the below examples, assume the callable exists within a module named mylib.hello:

Explicit MCs as well as implicit MCs based on an object instance have an optional initialization step that is called the first time the object instance is referenced. The method is called on an explicit ModuleComponent subclass as:

And is called on an implicit callable object as:

In the second version, the argument component is an instance of myghty.component.FunctionComponent that is hosting the implicit module component's __call__ method or other method. It is important to note that an object instance with many callable methods will actually have many FunctionComponents created, each one hosting an individual methods...however, the do_component_init() method is only called once with whatever FunctionComponent was first associated with the object.

In previous versions of Myghty, the initialization phase was required for components with arguments, which had to be explicitly declared within this stage. As of version 0.98, explicit declaration of component arguments is optional, and the argument lists are by default determined from the signature of the explicit do_run_component method or the implicit callable.

Explicit specification of an MCs arguments in the init section are as follows:

import myghty.component as component

class MyComponent(component.ModuleComponent):

    def do_component_init(self, **params):
        # component arguments
        self.args = ['arg1', 'arg2']
        
        # required component arguments
        self.required_args = ['arg3', 'arg4']
        
        # request-only arguments
        self.request_args = ['docid']
        
        # required request-only arguments
        self.required_request_args = ['userid']
        
        # subrequest or request arguments
        self.subrequest_args = ['foo']
        
        # required subrequest or request arguments
        self.required_subrequest_args = ['bar']

A component as above would have the do_run_component signature as follows:

def do_run_component(
    self, m, userid, arg3, arg4, bar, 
    docid = None, arg1 = None, arg2 = None, foo = None, **params
    ):

Note that if a module component defines any arguments explicitly in the do_component_init method, all arguments for the do_run_component method must be specified; no automatic introspection of function arguments will occur.

Similarly, <%flags> and <%attr> sections can be achieved like this:

def do_component_init(self, **params):
    # flags
    self.flags = {
        'autoflush':True,
        'trim': 'both'
    }
    
    # attributes
    self.attr = {
        'style':'green',
        'docid':5843
    }

The two most prominent features of an MC used as a controller includes that URI resolution is configured so that one or more URIs result in the component being called directly from a request, and that the component typically uses subrequests to forward execution onto a template, which serves as the view.

Here are two versions of a controller component that is used to pull documents from a database based on the request arguments, and displays them via a template called "documents.myt".

Figure 1: Implicit Style, using a Callable Object

 
 class DocumentManager:

     def do_component_init(self, component):
         # load some application-wide constants via Interpreter attributes.
         # the Interpreter is located via the hosting component.
         self.document_base = component.interpreter.attributes['document_base']
         self.db_string = component.interpreter.attributes['db_connect_string']

     def __call__(self, m, docid = None):

         # if no document id, return '404 - not found'       
         if docid is None:
             m.abort(404)

         # access a hypothetical document database
         docdb = get_doc_db(self.document_base, self.db_string)

         # load document
         document = docdb.find_document(docid)

         # couldnt find document - return '404 - not found'
         if document is None:
             m.abort(404)

         # run template
         m.subexec('documents.myt', document = document, **params)

 documentmanager = DocumentManager()

Figure 2: Explicit Style, with Pre-Declared Arguments

import myghty.component as component

class DocumentManager(component.ModuleComponent):

    def do_component_init(self, **params):
        # load some application-wide constants
        self.document_base = self.interpreter.attributes['document_base']
        self.db_string = self.interpreter.attributes['db_connect_string']

        # establish the argument names we want (optional as of 0.98)
        self.args = ['docid']

    def do_run_component(self, m, ARGS, docid = None, **params):

        # if no document id, return '404 - not found'       
        if docid is None:
            m.abort(404)

        # access a hypothetical document database
        docdb = get_doc_db(self.document_base, self.db_string)
        
        # load document
        document = docdb.find_document(docid)
        
        # couldnt find document - return '404 - not found'
        if document is None:
            m.abort(404)

        # run template
        m.subexec('documents.myt', document = document, **params)

The next section describes the two methods of configuring request URIs to execute "controller" components like this one.

Module components can be used anywhere within the request, either right at the beginning (i.e. a controller) or within the scope of other components already executing. A module component can be fetched and/or called based on its importable module name followed by a path to a callable object, or the name of a class that subclasses myghty.components.ModuleComponent. However, this doesn't work as a URL sent to a webserver. For request-level operation, MCs must be mapped to URIs. This resolution is achieved through two different configuration directives, module_components and module_root. A third option also exists which is to use the new routesresolver resolver object.

Request-handling module components can also be used to perform pre- and post-processing on a request. This means that the information about a request is modified before and/or after the main response is determined. The following two examples both wrap the main body of the request inside of a subrequest.

A module component that performs translations on incoming URI's, and then passes control onto the requested template, looks like this:

def translate_path(self, m, **params):
    path = m.get_request_path()
    path = re.sub('/sitedocs/john/', '/', path)
    m.subexec(path, **params)

A URI configuration for this component might look like:

module_components = [{r'/sitedocs/john/.*\.myt', 'mymodule:translate_path'}]

Path translation is also accomplished in Myghty via the path_translate parameter, and can be controlled in finer detail through the use of custom resolution rules, described in Advanced Resolver Configuration.

An example post processing component, which filters the output of the subrequest before returning data:

import StringIO, re

def filter(self, m, **params):
    # make a buffer
    buf = StringIO.StringIO()

    # create a subrequest using that buffer
    # our templates are located relative to the 
    # request URI underneath '/components'
    subreq = m.create_subrequest('/components' + m.get_request_uri(), out_buffer = buf)

    # execute the subrequest
    ret = subreq.execute()

    # perform a meaningless filter operation on the content
    content = re.sub(r'foo', r'bar', buf.getvalue())            

    # write the content                 
    m.write(content)

This component might be configured as:

module_components = [{r'/sitedocs/john/.*\.myt', 'mymodule:filter'}]

Filtering is also built in to Myghty via the use of <%filter> section, described in Filtering and Flushing (and Escaping).

MCs can also be called from within templates. If an MC is configured to be callable against a URI using module_components or module_root, that URI can also be used within a regular <& &>-style component call. Or, the MODULE: prefix style described previously can be used.

%flags is used to specify special properties of the component, which are significant to the execution of the component in the Myghty environment. Some flags can be inherited from a parent supercomponent, and overridden as well. Current flags are:

• inherit = "/path/to/template" - used in a file-based component only, this flag indicates that this component should inherit from the given template file. This argument can also be None to indicate that this component should not inherit from anything, even the standard autohandler. This flag only applies to the component file that it appears in, and does not affect any super- or subclass components. See the section Inheritance for details.

• autoflush = [True|False] - will override the configuration parameter auto_flush for this individual component. This is mostly useful for a particularly large top-level component, or a filter component that requires the full output text in one chunk. When a comopnent has autoflush disabled, it essentially means that a buffer is placed between the component's output and the ultimate output stream. As a result, the delivery of any component within a buffered component is also going to be buffered - this includes when a superclass component calls m.call_next() or for any subcomponent or method call.

  This flag is also inherited from a superclass component, such as the autohandler. See the section The Autoflush Option for information on auto_flush.

• trim = ["left"|"right"|"both"] - provides automatic left and/or right whitespace trimming for the output of a component. This is the equivalent of a <%filter> section utilizing string.strip() combined with autoflush=False. This allows component source code to be laid out on multiple lines without the whitespace surrounding the component output being presented in the final output. For information on trim, see the section Filtering Whitespace - the Trim Flag.

• use_cache - Enables caching for the component. See Data Caching for further cache options.

• encoding = ["utf-8" | "latin-1" | etc ] - Specifies the character encoding of the component's text file (such as utf-8, etc.). This encoding goes directly to the Python "magic comment" at the top of the generated Python component, so any character set is supported by Myghty templates.

• persistent = [True|False] - overrides the per-interpreter setting of delete_modules to specify that this file-based component should or should not specifically have it's module removed from sys.modules when it has fallen from scope. A file-based component that contains class definitions which may remain active after the component itself has fallen out of use may want to do this.

Flags may be specified via the <%flags> tag, or for subcomponents and methods may be specified as inline attributes within the <%def> or <%method> tags. The <%flags> tag may appear anywhere in a component, or even across multiple %flags sections, and will still take effect before a component is actually executed.

Example: the <%flags> tag:

<%flags>
    inherit = None
    autoflush = True
</%flags>

<%python scope="init">
    ...
</%python>

Example: subcomponent flags as attributes:

<%method getlink trim="both">
    <%init>
    </%init>
    
    <A href="foo.bar">lala</a>
</%method>

%attr simply sets some attributes on the component. These attributes are accessed via the attributes member of the component. Below, two attributes are accessed from a component to provide style information. One uses current_component, and the other uses base_component. The difference is the former always returns the very same component that is currently executing, whereas the latter corresponds to the component at the bottom of the inheritance chain:

<%attr>
    bgcolor = "#FF0000"
    fgcolor = "#FA456A"
</%attr>

<style>
    body {
    background-color: <% m.current_component.attributes['bgcolor'] %>;
    text-color: <% m.base_component.attributes['fgcolor'] %>;
    }       
</style>

# ...

In both cases, if the attribute does not exist in the current component or within futher inheriting child components, it will then traverse upwards via parent components to locate the attribute. For more information on parent/child relationships between components, see the section Inheritance.

%text surrounds a block where Myghty will not parse for control lines, line comments, substitutions, or any other Myghty tag. This allows the placement of free text which is intended to print as is, even if it may contain characters that are normally significant to the Myghty lexer. The %text tag is also essential for writing documentation that illustrates examples of Myghty (or similar) code.

%doc is simply a comment string - the content inside of a <%doc> section is discarded upon compilation. Comments can also be stated on a per-line basis using a '#' character as the very first character on a line, as described in Comment Lines.

A set of pages that all inherit each other is sometimes called the "wrapper chain". The wrapper chain is an actual property of the request, and is determined dynamically for each new request based on what files are present in the filesystem and what inheritance pattern they specify. When a template X inherits from a template Y, and that template in turn inherits from template Z, the wrapper chain is created:

Z -> Y -> X

The request above was called specifying component X as the requested component. X inherits from Y, either via an explicit flag or an autohandler configuration (more on that later), and Y inherits from Z. Therefore a wrapper chain with Z at the beginning and X at the end is created. When the request executes, control is passed to Z first. Z performs its component operations, then programmatically instructs the request to call the next component in the wrapper chain, which is Y. Y does the same thing and calls X, the originally requested component. When X is complete, control passes back to Y, and when Y is complete, control passes back to Z.

The flag used to specify that a component should inherit from another is called "inherit", and is specified in the <%flags> section of the component. The component to inherit from is specified by its component-root-relative URI. When an inherited parent component wants to call its inheriting child, it usually uses the call_next method of the request object. The child is only executed if its inherited parent explicitly does so.

If no "inherit" flag is specified for a page, the page will attempt to inherit from a template in the nearest enclosing directory named "autohandler". Whereas the inherit flag allows a component to explicitly specify its inherited parent, the autohandler mechanism allows the configuration of implicitly inheriting parents. Autohandlers are described in the next section Autohandlers.

In this example, the requested page is called "index.myt", and its inherited parent is called "base.myt". base.myt supplies a standard HTML header and footer, and index.myt supplies the content in the middle of the <body> tags.

<%flags>inherit='/base.myt'</%flags>


I am index.myt

<html>
<body>

<h3>example of content wrapping</h3>

# fetch the next component in the wrapper chain
# and call it
% m.call_next()

</body>
</html>

<html>
<body>

<h3>example of content wrapping</h3>

I am index.myt

</body>
</html>

While the call_next method of request is the simplest way to call the next component in the wrapper chain, the method fetch_next exists to pop the next component off the chain but not execute it, as well as fetch_all which pops off and returns the entire list of components in the wrapper chain.

In the wrapper chain "Z -> Y -> X" described at the beginning of the section, the component X is known as the request component, and is accessible throughout the life of the request via the request_component member of the request. It also is established as the initial "base component" of the request. The base component is accessible via the base_component request member, and it is defined first as the lead requested component in a wrapper chain. When methods in other template files are called, the base component changes to be the file that the method appears in, throughout the life of that method's execution, and upon method completion returns to its previous value.

The base component is also referred to by the special component keyword 'SELF'. This keyword can be used directly via the fetch_component method, but it is more commonly referenced in method component calls, as detailed in the next section.

Methods, first described in Component Methods, are normally called with the <location>:<methodname> syntax, where <location> is the URI or special keyword identifier of a component, and <methodname> is the name of the method to search for. This syntax enables the component to search not only its local method list for the requested method, it also will search its immediate parent for the method if not found, and that parent will continue the search up the wrapper chain.

It is for this reason that the base component and the SELF keyword is of particular value in fetch_component and method calls, since it indicates the innermost component in the current inheritance chain. An template at the end of a wrapper chain (i.e. template Z in the previous section) can specify the SELF keyword when calling a method, and the method will be located from the innermost template first (i.e. component X), and on up the wrapper chain until found.

Similarly, component attributes are located using an inheritance scheme as well. Attributes are referenced via the attributes member of the component object. The attributes dictionary, while it is a regular dictionary interface, will search for requested values in the parent of the component if not found locally.

Here is an example where the parent component is an autohandler, which because of its name, automatically becomes the inherited parent of the child component, as long as the child component does not explicitly specify otherwise.

Both in the parent component as well as the child component that inherits from it specify a method "title". The autohandler can render the title of the page via the "title" method, where it is guaranteed to exist at least in the autohandler's own version of the method, but can be overridden by the inheriting page. Additionally, the autohandler has an <%attr> section indicating the path to a file location. The child page will look in its own attribute dictionary for this location, where it will ultimately come from the inheriting parent.

<%attr>
    # path to some files
    fileroot = '/docs/myfiles'
</%attr>

<html>
<head>
    <title>
#   the "title" method is called here from SELF,
#   so the method will be searched in the base component first,
#   then traverse up the inheritance chain until found
    <& SELF:title &>
    </title>
</head>
<body>

# call the next component in the wrapper chain
% m.call_next()

</body>
</html>

# default "title" method implementation
<%method title>
Welcome to My Site
</%method>

<%python scope="init">
    # locate the file root via a parent attribute
    pr = get_press_releases(fileroot = self.attributes['fileroot'])
</%python>

# specify a title method to override that of the parent's
<%method title>
My Site: Press Releases
</%method>

<h2>Press Releases</h2>

% for release in pr:

#    ... print data ...

%

an autohandler is an optional file, by default named autohandler, that will serve as the base inheriting template for all requests within a directory and its subdirectories. Inheritance is discussed in more detail in the section Inheritance. The basic idea is that the autohandler template executes first; it runs some code and/or outputs some HTML, and then calls a special method to deliver the content of the requested template. When the embedded template has completed its execution, the autohandler can then output some more HTML at the bottom and/or execute cleanup code:

<html>
<head>autohandler demo</head>
<body>
% m.call_next()
</body>
</html>

Autohandlers are searched for first in the current directory, then upwards in the enclosing directories, until the component root is reached. If more than one autohandler is found, they will all be executed within each other, with the most directory-specific autohandler executed at the innermost level. Any page or autohandler can deny the execution of an enclosing autohandler by setting the "inherit" flag to be None.

Autohandlers are ideal for standardized HTML enclosing schemes as above. There are also many more creative uses. An autohandler that automatically protects a whole directory based on a custom login scheme would look something like this:

# autohandler

<%python scope="init">
    # look in the apache request for some kind of 
    # login token
    user = login_manager.check_login(r)
    if not user:
        # redirect out of here, the rest of the content
        # in this page will not be sent
        m.send_redirect("/login.myt", hard=True)

    else:               
        # otherwise, they are ok, deliver content
        m.call_next()
</%python>

A dhandler, otherwise known as a directory handler, is a file, by default named dhandler, that serves requests for which the requested Myghty template can not be located, or for a request that names a directory by itself without a file. dhandlers are searched for similarly to autohandlers, i.e. in the innermost enclosing directory first, then upwards towards the component root. However, only one dhandler is executed at a time. The code within the dhandler has access to the request member dhandler_path which refers to the path information for the requested (but unlocated) component, relative to the path of the current dhandler. It also can call decline which will abort the current dhandler and search up the directory tree for the next enclosing dhandler.

Dhandlers are good for special path-based requests used in places such as news sites who want to have clean URLs that have no query strings, for writing components that process the contents of a directory dynamically, such as image or filesystem browsers, or custom per-directory "file not found" handlers.

Example: content management system. A lot of news sites have fancy URLs with dates and article keywords (sometimes called slugs) specified within them. These URLs sometimes are resolved into database parameters, and the actual content is retrieved from some source that is not the same as a local file with that path scheme. This example extracts tokens from a URI and uses them as parameters to retrieve content.

# Hypothetical URL:
# http://foonews.com/news/2004/10/23/aapl.myt

# dhandler, inside of the web directory /news/

<%python scope="init">
    import re
    
    # get path
    path = m.dhandler_path
    
    # get arguments from the path
    match = re.match(r"(\d+)\/(\d+)\/(\d+)\/(\w+)\.myt", path)
    
    if match:
        (year, month, day, slug) = match.groups()
        
        # look up a news article in a 
        # hypothetical content-management database 
        # based on this parameters from the path
        article = db.lookup(year, month, day, slug)
    else:
        article = None
        
    if article is None:
        # improper URL, or no article found
        m.send_redirect("article_not_found.myt", hard=False)
</%python>

<!-- display the article -->

<h3><% article.get_headline() %></h3>

<% article.get_text() %>