Dependencies

• setuptools
• decoratortools
• WebOb
• flup (for fcgi and scgi servers)
• CherryPy (for its http server)

An Example

Typical usage:

>>> from skunk.cache import *
>>> mycache=DiskCache('/tmp/mycache')
>>> cache=CacheDecorator(mycache, defaultPolicy=YES)
>>> @cache(expiration="5m")
... def foo(x, y):
...    print "actually calculating ...."
...    return x + y
>>> foo(5, 5)
actually calculating ....
10
>>> foo(5, 5)
10

Normally you'd want to use the decorator, but you can also the same result by using the call() method of a cache object:

>>> from skunk.cache import *
>>> mycache=MemoryCache()
>>> def foo(x, y):
...    print "actually calculating ...."
...    return x+ y
>>> entry=mycache.call(foo, (100, 50), FORCE)
actually calculating ....
>>> entry.value
150

Cache Policies and Expiration

When you call a function via the cache, you can specify one of several cache policies:

NO

This bypasses the cache, neither reading from it nor writing to it.

YES

This accepts a valid (unexpired) cache entry, and if one is not found, will create one.

FORCE

This forces recalculation and creates a new cache entry regardless of whether there was a valid unexpired one before.

OLD

This will return any data found in the cache, regardless of whether it is expired.

DEFER

This will, if a cache entry is expired, return it anyway and then schedule a recalculation of the function by placing it on a queue. It is up to the user's application to handle the queue.

The cache expiration -- how long the cache entry should live -- can be specified either by the caller, by passing an expiration parameter, or by the callee, by setting an __expiration__ attribute on itself or on the value it returns. The expiration can be specified either as a duration, an absolute or relative expiration time, or a list of such values, expressed in a number of possible formats.

To specify a duration, a string may be used containing a sequence of integer-letter pairs specifying units of time:

N [d|h|m|s]

cache for N days|hours|minutes|seconds

You may use any combination of these integer-letter pairs, in any order, and the durations will be summed. For example, "3h2m8s" means "three hours, two minutes and eight seconds".

You may wish to cache a value until a particular (absolute) time. You can use a value that directly represents an absolute timestamp for this, such as a datetime.datetime or mx.DateTime.DateTimeType instance. Or you can use a string in the format yyyy-mm-dd[:hh:mm[:ss]].

You can also specify a relative time, with objects like mx.DateTime.RelativeDateTime and dateutil.relativedelta.relativedelta, and with strings like hh:mm[:ss] or :mm[:ss]

And finally, you can use a list or tuple of such values, freely intermixed; the nearest future time of those indicated will be the effective value.

For example, if the expiration is stated as:

(':00', ':30', '5m')

and the current time is 2:34 PM, the effective expiration will be 2:39 PM. But if the current time is 2:29 PM, the expiration will be 2:30 PM.

Introduction

The version of STML described here is largely but not completely backwards-compatible variant of the version implemented in SkunkWeb 3 (hereafter called "STML3"). The most important differences will be noted below.

STML is an extensible, tag-based templating language based on (and compiled to) Python, especially well-suited for dynamic generation of HTML or XML in web applications. It is tightly wedded to the skunk.components library, which permits code to be broken up into separate reusable components that can be invoked with arguments like functions, returning string output or arbitrary Python data, and the skunk.cache library, which permits the return values of such invocations to be cached in a highly flexible and easily controlled manner.

The Structure of STML Tags

STML tags are delimited by the character sequences <: and :>. Between these delimiters, the first word is the tag name which identifies what tag is being called:

<:halt:>

The tag name may be followed by a number of tag attributes:

<:val expr=`3` fmt="plain":>

In the above, the first attribute has the name expr and the value `3`, and the second the name fmt and the value "plain". The value `3`, written between backticks, is a Python expression, and is equivalent to the Python value 3. Any valid Python expression (without backticks) may be used wherever STML accepts expressions, and are always written between backticks [1]. The value "plain" is a simply a string; it would be equivalent to write `"plain"`, `'plain'`, 'plain', or (since in this case the string between quotes contains no whitespace) simply the bare word plain.

STML tags usually expect attributes in a default order, and if when using the tag you write the attributes in that order, you can leave out the attribute names. The following is equivalent to the previous example:

<:val `3` plain:>

(Note that this is a bit different than markup languages like HTML and XML, in which attribute order, unlike element order, is not significant.) However, if you specify the attribute names, you can state them in any order:

<:val fmt=plain expr=`3`:>

Some attributes are optional and are defined as having default values; in this example, fmt is optional, and the default value is equivalent to plain, so you could simply write:

<:val `3`:>

Some tags accept arbitrary keyword arguments:

<:component foo.comp
            x=`y/2.0`
            d=`range(4)`
            p="this could go on and on...":>

Again along the lines of SGML-based markup like HTML and XML, STML tags are of two basic syntactical types: block and empty. Block tags open a block which will be parsed in the context of the tag, and must be closed by a matching tag with the same tagName, but preceded by a forward slash. For instance, the template below has one block tag and one empty tag:

<:filter:>
   This is some text inside a block.
<:/filter:>
<:break:>

Setting and Showing Things

<:set name value:>

<:set x "hello":>

x="hello"

<:default name value:>

<:default x `myObj`:>

try:
    x
except NameError:
    x=myObj

<:del name:>

del name

<:call expr:>

<:call `x=4`:>

<:val:> expr fmt=`None`:>

<:val `myVar` fmt=xml:>

<:import module [names] [as=name]:>

<:filter name=`None` fmt=`None`:><:/filter:>
<:spool name fmt=`None`:><:/spool:>

<:filter fmt=`str.upper`:>
   this will get output in upper case.
<:/filter:>

<:args [arg1 arg2...] [arg3=val3 arg4=val4 ...]:>

<:args bopper nougat parsley=yum servings=`(int,5)`:>

bopper : None
nougat : 'pumpkin'
parsley : 'yum'
servings : 20

bopper : 'frisbee'
nougat : None
parsley : 'yum'
servings : 5

from skunk.util.argextract import extra_args
locals().update(extract_args(REQUEST.params.mixed(),
                             'bopper',
                             'nougat',
                             parsley='yum',
                             servings=(int, 5)))

Flow Control

<:if expr:>
[<:elif expr:>] ...
[<:else:>]
<:/if:>

<:try:>
<:except [exc]:>
[<:else:>]
<:/try:>

<:try:>
<:finally:>
<:/try:>

<:raise [exc]:>

<:for expr [name=sequence_item]:>
[<:break:>]
[<:continue:>]
[<:else:>]
<:/for:>

<:while expr :>
[<:break:>]
[<:continue:>]
[<:else:>]
<:/while:>

STML's flow control facilities mirror those of Python itself almost exactly. The following Python:

try:
    v==0
    while not v:
        for i in p:
            try:
                v=i.value
            except AttributeError:
                continue
            else:
                break
        else:
            break
    if v > m:
        do_bigger()
    elif v==m:
        do_the_same()
    else:
        do_smaller()
finally:
   cleanup()

would be translated into STML as:

<:try:>
   <:set v `0`:>
   <:while `not v`:>
     <:for `p` i:>
        <:try:>
           <:set v `i.value`:>
        <:except `AttributeError`:>
           <:continue:>
        <:else:>
          <:break:>
        <:/try:>
     <:else:>
        <:break:>
     <:/for:>
   <:/while:>
   <:if `v>m`:>
      <:call `do_bigger`:>
   <:elif `v==m`:>
      <:call `do_the_same()`:>
   <:else:>
      <:call `do_smaller()`:>
   <:/if:>
<:finally:>
   <:call `cleanup()`:>
<:/try:>

The major differences to note are:

• indentation is not significant in STML (although, as in all languages, careful indentation helps legibility).
• <:try:>, <:for:>, and <:while:> are block tags, and must be closed like any other block tag.
• instead of Python's for sequence_item in sequence, STML drops the in, reverses the sequence_item and sequence, and makes sequence_item optional (it defaults to "sequence_item").

Comments

<:* ... *:>
<:#:><:/#:>
<:comment:><:/comment:>

The three comment tags are of two types. <:#:> and <:comment:> are synonymous; they are regular STML block tags that generate no code, but any stml within the tags will be parsed and must be well-formed. The <:* and *:> tags are not, strictly speaking, tag at all, but a special comment syntax supported directly by the STML lexer. Any text between the tags will be ignored. Therefore, <:* is better suited for temporarily commenting out blocks of STML that may be syntactically incorrect.

STML3 also included a ``<:doc:>`` tag for the purpose of adding documentation to templates.

Component Tags

<:component compname [arg1=value arg2=value ...] [__args__= argdict] [cache=no|yes|old|force] :>
<:datacomp varname compname [arg1=value arg2=value ...] [__args__= argdict] [cache=no|yes|old|force] :>
<:include compname:>
<:compargs [arg1 arg2...] [arg3=val3 arg4=val4 ...]:>
<:cache until="datespec"| duration="timespec":>
<:halt:>

The <:component:> tag calls string components and outputs the results (to the output stream OUTPUT in the current namespace). The <:datacomp:> tag calls data components and places the returned value in varname. <:include:> calls an include component and outputs the results (to OUTPUT).

String and data components accept component arguments, and can be cached; includes cannot. Component arguments can be passed by keyword in the component tag, or as a dictionary with the reserved keyword __args__. The desired cache policy can be specified with the reserved keyword cache; acceptable values are skunk.cache.CachePolicy instances and the strings 'no', 'yes', 'old', 'force'.

To ensure that the correct component arguments have been passed to a component, and to set default values, the <:compargs:> tag may be used. This will compare the component arguments used in a particular call with a signature given in the tag.

The <:cache:> tag sets the expiration for the component, in case it is called with a CachePolicy that honors it. [add documentation of the formats accepted for this -- TO BE DONE.]

STML3 also includes a ``<:return:>`` tag which can be used to return values from data components written in STML. ``skunk.stml`` does not support writing data components in STML, and hence does not implement ``<:return:>``.

Layout Templates

STML supports sharing common layouts through layout templates and slots, a very simple system that accomplishes much of what other templating engines achieve through template inheritance.

A layout template is an STML component that renders a complete document, but with empty slots in it that can be filled in various ways.

A slot is a named placeholder in such a template.

At render time, the templating engine will look for a dictionary named SLOTS in the current namespace to populate these slots; if not found, it will create a slot dictionary by looking at the slot configuration (see below).

If no data is found for a particular slot, or if the data is None or an empty string, no output will be produced for that slot. If the data is a string, that string will be output. If it is a callable, it will be called with any arguments you have specified in the template, and the output inserted.

This system is implemented through two tags: <:slot:> and <:calltemplate:>.

<:slot slotname [kwarg=val ...]:>

The slot tag is a placeholder for a slot in the layout template; it should be given a unique slotname. Any additional parameters passed in will be available to any code that runs to render the slot.

<:calltemplate [template=None] [slotmap=SLOTS] [kwarg=val ...]:>

The calltemplate tag is used for STML documents that want to invoke the layout template; in typical use it is called without arguments at the very end of the document.

Logging

<:debug msg [arg1 args2 ...]:>
<:info msg [arg1 args2 ...]:>
<:warn msg [arg1 args2 ...]:>
<:error msg [arg1 args2 ...]:>
<:exception msg [arg1 args2 ...]:>

STML's log tags using Python's logging module to call the standard log methods (debug, info, warn, error, and exception) on the user logger, which by default is named USER (a different name can be assign by setting the configuration variable userLogger).

<:debug "attempting precarious function call":>
<:info "received request from IP %s" `ip`:>
<:warn "possible breakin attempt: %s %s" `ip` `user`:>
<:error "that wasn't supposed to happen":>
<:exception "exception handling order:":>

To access the logger programmatically:

from skunk.userlogger import getUserLogger
logger=getUserLogger()
logger.setLevel(logging.DEBUG)
logger.debug("hello from Python")

Or as a shortcut for logging from Python components:

# imports debug, info, warn, error, exception
from skunk.userlogger import *
debug("I think I'm about to make a boo-boo....")
error("Darn, I was right!")

Using Other Tag Libraries

<:use tagdict [prefix=name]:>

STML may be extended by other tag libraries. A tag library is simply a mapping of tag names to tag classes (including just those tags which should appear at the top level and that do not need to be nested in another tag).

The STML parser may be invoked with an extended set of tags that incorporates other libraries, but it may also be desirable to extend the vocabulary of available tags within an STML component; the <:use:> tag accomplishes this. Tags imported by this means are only available within the component, subsequent to the <:use:> call; they are not inherited by any nested components and do not affect the global tag dictionary.

For clarity, or to prevent name conflicts between tag names in different libraries, it is possible to specify a prefix when using a tag library. In use, the namespace will look like an xml namespace prefix:

<:use zapper.stmltags prefix=zapper:>
<:zapper:mogrify foo=`1`:>

The <:use:> tag does not generate any code at runtime; the inclusion of the tag library happens at parse time. Therefore, the tagdict argument must be a string, not a Python expression (which only has meaning at runtime). Tag libraries must be defined in importable Python modules, and specified by their __name__ attribute.

STML3 does not have a ``<:use:>`` tag, and does not permit colons in tag names.

Controllers

A controller is any object, typically a module or class instance, with callable attributes exposed as actions (request handlers).

Since the routing framework may allow clients to choose the name of the action, we follow the example of CherryPy and require that action methods be explicitly marked as exposed, by setting their exposed attribute to a true value:

# the controller framework will execute this,
# as it is exposed
def an_action():
    return webob.Response(body="Hello, World!")
an_action.explosed=True

# it will not deign to execute this, however
def wannabe():
    return "Greetings, universe!"

This is normally done by using the @expose() decorator:

from skunk.web import expose

@expose()
def an_action():
    return "how convenient"

@expose() can also be used to set attributes on the response:

@expose(content_type='text/plain')
def plain():
    return "how dry I am"

The controller framework automatically tries to adapt return values to a WSGI application, most commonly a webob.Response. If a callable is directly returned, no adaptation is necessary; the callable is assumed to be a WSGI application and is invoked as such. Otherwise, the following types are adapted:

• None, in which case Context.response is returned
• a string, which is set to the body of Context.response and the latter is returned
• a unicode string (similar)
• if Context.response.content_type is application/json and the returned type is list, tuple, or dict, the returned data will be marshalled into JSON and put in Context.response, which is then returned.
• a list, tuple or generator becomes Context.response.app_iter
• an integer is taken to be an HTTP status code and a default error response is generated. An invalid code will cause an error. N.B.: Context.response is not used to generate the response; the purpose of this shortcut is to make it simple to send vanilla error codes, dispensing with any previous response initialization.

Anything else is turned in a string with str().

It is also possible to generate a response by raising a webob.exc.HTTPException. Note that if you do this, or if you explicitly return a WSGI application other than Context.response, the latter object will not be used to serve the request, and any state it may have will be irrelevant.

@expose()
@template()
def hello_world():
    return dict(message="Perhaps this isn't the best time to talk.")

STML Active Pages

@TBD

Running SkunkWeb Applications

Discuss here:

• conf variables for running a server, including wsgiPipeline
• bootstrap()