EmPy 3.3 review
DownloadEmPy is a system for embedding Python expressions and statements in template text; it takes an EmPy source file, processes it, and pr
|
|
EmPy is a system for embedding Python expressions and statements in template text; it takes an EmPy source file, processes it, and produces output.
This is accomplished via expansions, which are special signals to the EmPy system and are set off by a special prefix (by default the at sign, @). EmPy can expand arbitrary Python expressions and statements in this way, as well as a variety of special forms.
Textual data not explicitly delimited in this way is sent unaffected to the output, allowing Python to be used in effect as a markup language. Also supported are callbacks via hooks, recording and playback via diversions, and dynamic, chainable filters. The system is highly configurable via command line options and embedded commands.
Expressions are embedded in text with the @(...) notation; variations include conditional expressions with @(...?...!...) and the ability to handle thrown exceptions with @(...$...). As a shortcut, simple variables and expressions can be abbreviated as @variable, @object.attribute, @function(arguments), @sequence [index], and combinations.
Full-fledged statements are embedded with @{...}. Control flow in terms of conditional or repeated expansion is available with @[...]. A @ followed by a whitespace character (including a newline) expands to nothing, allowing string concatenations and line continuations.
Comments are indicated with @# and consume the rest of the line, up to and including the trailing newline. @% indicate "significators," which are special forms of variable assignment intended to specify per-file identification information in a format which is easy to parse externally.
Context name and line number changes can be done with @? and @! respectively. '@' markups are customizeable by the user and can be used for any desired purpose. Escape sequences analogous to those in C can be specified with @..., and finally a @@ sequence expands to a single literal at sign.
Requirements:
EmPy should work with any version of Python from 1.5.2 onward. It has been tested with all major versions of CPython from 1.5 up, and Jython from 2.0 up (using Java runtimes 1.3 and 1.4). The included test script is intended to run on Unix-like systems with a Bourne shell.
EmPy is intended for embedding Python code in otherwise unprocessed text. Source files are processed, and the results are written to an output file. Normal text is sent to the output unchanged, but markups are processed, expanded to their results, and then written to the output file as strings (that is, with the str function, not repr). The act of processing EmPy source and handling markups is called "expansion."
Code that is processed is executed exactly as if it were entered into the Python interpreter; that is, it is executed with the equivalent of eval (for expressions) and exec (for statements). EmPy is intended to be a very thin (though powerful) layer on top of a running Python system; Python and EmPy files can be mixed together (via command line options) without complications.
By default the embedding prefix is the at sign (@), which appears neither in valid Python code nor commonly in arbitrary texts; it can be overridden with the -p option (or with the empy.setPrefix function).
The prefix indicates to the EmPy interpreter that a special sequence follows and should be processed rather than sent to the output untouched (to indicate a literal at sign, it can be doubled as in @@).
When the interpreter starts processing its target file, no modules are imported by default, save the empy pseudomodule (see below), which is placed in the globals; the empy pseudomodule is associated with a particular interpreter -- in fact, they are the same object -- and it is important that it not be removed from that interpreter's globals, nor that it be shared with other interpreters running concurrently (a name other than empy can be specified with the -m option).
The globals are not cleared or reset in any way. It is perfectly legal to set variables or explicitly import modules and then use them in later markups, e.g., @{import time} ... @time.time(). Scoping rules are as in normal Python, although all defined variables and objects are taken to be in the global namespace.
Indentation is significant in Python, and therefore is also significant in EmPy. EmPy statement markups (@{...}), when spanning multiple lines, must be flush with the left margin. This is because (multiline) statement markups are not treated specially in EmPy and are simply passed to the Python interpreter, where indentation is significant.
Activities you would like to be done before any processing of the main EmPy file can be specified with the -I, -D, -E, -F, and -P options. -I imports modules, -D executes a Python variable assignment, -E executes an arbitrary Python (not EmPy) statement, -F executes a Python (not EmPy) file, and -P processes an EmPy (not Python) file.
These operations are done in the order they appear on the command line; any number of each (including, of course, zero) can be used.
EmPy 3.3 keywords