Many websites carry a theme across their various pages, which is often
achieved by including a common header or footer. The include module provides
exactly this functionality, and more. For example, it can also be used to
define dynamic site-wide constants, and other similar globals that can not
otherwise be initialized with static include directives (due to their dynamic
nature). For example, language specific constants may be selected dynamically
from the required language include file, based on a GET or POST language
parameter or, better yet, from the Accept-Language request header. This module
also provides other functions that are similar in nature. For example, it can
currently pretty print Spyce code. In the future, it will be able to generate
the Spyce and Spyce Powered logo, and possibly other similar trinkets.
spyce( file, [context] ): Dynamically includes the specified
file, and processes it as Spyce code. The return value is that of the
included Spyce file. One can optionally provide a context value to
the included file. If omitted, the value defaults to None. All currently
imported modules are passed along into the included file without
re-initialization. However, for each explicit [[.import ]] tag in the included file, a new
module is initialized and also finalized up at the end of processing. The
include module provides three fields for use inside included files:
include.context: This field stores the value passed in at the
point of inclusion. Note that if the value is one that is passed by
reference (as is the case with object, list, and dictionary types), then
the context may be used to pass information back to the including file, in
addition to the return value.
include.vars: If the include context is of type dictionary,
then the vars field is initialized, otherwise it is None. The vars field
provides attribute-based access to the context dictionary, merely for
convenience. In other words, self.vars.x is
equivalent to self.context['x'].
include.fromFile: stores the name of the file name from which
this file was included.
Note that either the locals() or globals() dictionaries may be passed in as
include contexts. However, be advised that due to Python optimizations of
local variable access, any updates to the locals() dictionary may not be
reflected in the local namespace under all circumstances and all versions of
Python. In fact, this is the reason why the context has been made explicit,
and does not simply grab the locals() dictionary. It may, however, safely be
used for read access. With respect to the globals() dictionary, it is not
advised to pollute this
namespace.
dump( file, [binary] ): Contents of the file are
returned. If the binary parameter is true, the file is opened in
binary mode. By default, text mode is used.
spycecode( file ): Contents of the file are returned
as HTML formatted Spyce code.
The example below (taken from this documentation file), uses a common header
template only requiring two context variables to change the title and the
highlighted link:
By convention, included files are given the extension .spi.
Below we contrast the difference between static and dynamic includes. A
dynamic include is included on each request; a static include is inserted at
compile time. A static include runs in the same context, while a dynamic
include has a separate context.