ANN: EmPy 4.1 -- a powerful, robust and mature templating system for Python

[Erik Max Francis]

I'm pleased to announce the release of EmPy 4.1.

The 4._x_ series is a modernization of the software and a revamp of
the EmPy system to update its feature set and make it more consistent
with the latest Python versions and practices.  EmPy 4._x_ was also
relicensed to BSD.

The 4._x_ series adds new markups, including inline comments,
backquote literals, chained if-then-else extended expression,
functional expressions, support for modern Pythonic controls,
stringized and multiline significators, named escapes, diacritics,
icons, and emojis.

It adds support for configuration objects (replacing options
dictionaries); native support for Unicode, file buffering, reference
counted `sys.stdout` proxies and error dispatchers and handlers; fixes
several serious bugs; has a set of full unit and system tests, an
extensive builtin help system; and the online documention has been
rewritten and expanded.

Attempts have been made to make EmPy 4._x_ as backward compatible as
is practical.  Most common markup has not changed; the only changes
being removal of `repr` (in favor of backquote literals) as well as
literal close parenthesis, bracket and brace markup; in-place markup
has changed syntax (to make way for emojis); and custom markup is now
parsed more sensibly.

Most backward-incompatible changes are in the embedding interface.
The `Interpreter` constructor and global `expand` function now require
keyword arguments to prevent further backward compatibility problems,
though effort has been made to make the behavior as backward
compatible as possible.  The supported environment variables have
changed, as well as the filter, diversion and hook APIs, and options
dictionaries no longer exist (in deference to configurations).

For a comprehensive list of changes from 3._x_ to 4._x_, see:
<http://www.alcyone.com/software/empy/ANNOUNCE.html#changes>


## Introduction:  Welcome to EmPy!

[EmPy](http://www.alcyone.com/software/empy/) is a powerful, robust and 
mature
templating system for inserting Python code in template text.  EmPy
takes a source document, processes it, and produces output.  This is
accomplished via expansions, which are signals to the EmPy system
where to act and are indicated with markup.  Markup is set off by a
customizable prefix (by default the at sign, `@`).  EmPy can expand
arbitrary Python expressions, statements and control structures in
this way, as well as a variety of additional special forms.  The
remaining textual data is sent to the output, allowing Python to be
used in effect as a markup language.

EmPy also supports hooks, which can intercept and modify the behavior
of a running interpreter; diversions, which allow recording and
playback; filters, which are dynamic and can be chained together; and
a dedicated user-customizable callback markup.  The system is highly
configurable via command line options, configuration files, and
environment variables.  An extensive API is also available for
embedding EmPy functionality in your own Python programs.

EmPy also has a supplemental library for additional non-essential
features (`emlib`), a documentation building library used to create
this documentation (`emdoc`), and an extensive help system (`emhelp`)
which can be queried from the command line with the main executable
`em.py` (`-h/--help`, `-H/--topics=TOPICS`).  The base EmPy
interpreter can function with only the `em.py`/`em` file/module
available.

EmPy can be used in a variety of roles, including as a templating
system, a text processing system (preprocessing and/or
postprocessing), a simple macro processor, a frontend for a content
management system, annotating documents, for literate programming, as
a souped-up text encoding converter, a text beautifier (with macros
and filters), and many other purposes.


### Markup overview

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`, `@sequence[index]`,
`@function(arguments...)`, `@function{markup}{...}` and
combinations.  Full-fledged statements are embedded with `@{...}`.
Control flow in terms of conditional or repeated expansion is
available with `@[...]`.  A `@` followed by any whitespace character
(including a newline) expands to nothing, allowing string
concatenations and line continuations.  Line comments are indicated
with `@#...` including the trailing newline.  `@*...*` allows inline
comments.  Escapes are indicated with `@\...`; diacritics with
`@^...`; icons with `@|...`; and emoji with `@:...:`.  `@%...`,
`@%!...`, `@%%...%%` and `@%%!...%%` indicate "significators,"
which are distinctive forms of variable assignment intended to specify
per-document identification information in a format easy to parse
externally, _e.g._, to indicate metadata.  In-place expressions are
specified with `@$...$...$`.  Context name and line number changes
can be made with `@?...` and `@!...`, respectively.  `@<...>`
markup is customizable by the user and can be used for any desired
purpose.  `` @`...` `` allows literal escaping of any EmPy markup.
And finally, a `@@` sequence (the prefix repeated once) expands to a
single literal at sign.

The prefix defaults to `@` but can be changed with
the command line option `-p/--prefix=CHAR` (_environment variable:_ 
`EMPY_PREFIX`, _configuration variable:_ `prefix`).


### Getting the software

The current version of EmPy is 4.1.

The official URL for this Web site is 
<http://www.alcyone.com/software/empy/>.

The latest version of the software is available in a tarball here:
<http://www.alcyone.com/software/empy/empy-latest.tar.gz>.

The software can be installed through PIP via this shell command:

```
% python3 -m pip install empy
```


For information about upgrading from 3._x_ to 4._x_, see
<http://www.alcyone.com/software/empy/ANNOUNCE.html#changes>.


### Requirements

EmPy works with any modern version of Python.  Python version 3._x_ is
expected to be the default and all source file references to the
Python interpreter (_e.g._, the bangpath of the .py scripts) use
`python3`.  EmPy also has legacy support for versions of Python going
back all the way to 2.3, with special emphasis on 2.7 regardless of
its end-of-life status.  It has no dependency requirements on any
third-party modules and can run directly off of a stock Python
interpreter.

EmPy will run on any operating system with a full-featured Python
interpreter; this includes, but is probably not limited to, Linux,
Windows, and macOS (Darwin).  Using EmPy requires knowledge of the
[Python language](https://www.python.org/).

EmPy is also compatible with several different Python implementations:

| Implementation | Supported versions | Description |
| --- | --- | --- |
| CPython | 2.3 to 2.7; 3.0 and up | Standard implementation in C |
| PyPy | 2.7; 3.2 and up | Implementation with just-in-time compiler |
| IronPython | 2.7; 3.4 and up | Implementation for .NET CLR and Mono |
| Jython | 2.7 (and up?) | Implementation for JVM |

It's probable that EmPy is compatible with earlier versions than those
listed here (potentially going all the way back to 2.3), but this has
not been tested.

Only a few .py module file(s) are needed to use EmPy; they can be
installed system-wide through a distribution package, a third-party
module/executable, or just dropped into any desired directory in the
`PYTHONPATH`.  A minimal installation need only install the em.py
file, either as an importable module and an executable, or both,
depending on the user's needs.

EmPy also has optional support for several [third-party
modules](#third-party-emoji-modules); see [Emoji
markup](#emoji-markup) for details.

The testing system included (the test.sh script and the tests and
suites directories) is intended to run on Unix-like systems with a
Bourne-like shell (_e.g._, sh, bash, zsh, etc.).  EmPy is routinely
tested with all supported versions of all available interpreters.

If you find an incompatibility with your Python interpreter or
operating system, [let me know](#reporting-bugs).


### License

This software is licensed under
[BSD (3-Clause)](https://opensource.org/licenses/bsd-3-clause/).


### Recent release history (since 3._x_)

4.1 (2024 Mar 24)

: Add support for extension markup `@((...))`, `@[[...]]`,
   `@{{...}}`, `@<...>`, etc., with custom callbacks retained for
   backward compatibility; add `@[match]` control support; add
   interpreter cores for overriding interpreter behavior; add more
   command line option toggles; add notion of verbose/brief errors;
   more uniform error message formatting; various documentation
   updates.

4.0.1 (2023 Dec 24)

: Add root context argument, serializers, and idents to interpreter;
   fix `setContext...`  methods so they also modify the currents stack;
   better backward compatibility for `expand` function and
   `CompatibilityError`; fix inconsistent stack usage with `expand`
   method; add error dispatchers, cleaner error handling and
   `ignoreErrors`; have `expand` method/function raise
   exceptions to caller; eliminate need for `FullContext` class
   distinct from `Context`; support comments in "clean" controls; add
   `--no-none-symbol` option; add clearer errors for removed literal
   markup; add `Container` support class in `emlib`; hide non-standard
   proxy attributes and methods; support string errors (why not);
   update and expand tests; help subsystem and documentation updates.

4.0 (2023 Nov 29)

: A major revamp, refresh, and modernization.  Major new features
   include inline comments `@*...*`; backquote literals `` @`...`
   ``; chained if-then-else expressions; functional expressions
   `@f{...}`; full support for `@[try]`, `@[while ...]` and `@[with
   ...]`  control markup; `@[defined ...]` control markup; stringized
   and multiline significators; named escapes `@\^{...}`; diacritics
   `@^...`; icons `@|...`; emojis `@:...:`; configurations; full
   Unicode and file buffering support; proxy now reference counted;
   hooks can override behavior; many bug fixes; an extensive builtin
   help system (`emhelp`); and rewritten and expanded documentation in
   addition to a dedicated module (`emdoc`).  Changes include
   relicensing to BSD, interpreter constructor now requires keyword
   arguments, `-d/--delete-on-error` instead of "fully buffered files";
   cleaned up environment variables; "repr" markup replaced with emoji
   markup; remove literal markups `@)`, `@]`, `@}`; context line
   markup `@!...` no longer pre-adjusts line; custom markup `@<...>`
   now parsed more sensibly; filter shortcuts removed; context now
   track column and character count; auxiliary classes moved to `emlib`
   module; use `argv` instead of `argc` for interpreter arguments.  See
   [Full list of changes between EmPy 3._x_ and
 
4._x_](http://www.alcyone.com/software/empy/ANNOUNCE.html#all-changes) 
for a more
   comprehensive list.

-- 
Erik Max Francis && max at alcyone.com && http://www.alcyone.com/max/
  San Jose, CA, USA && 37 18 N 121 57 W && Skype erikmaxfrancis
   Maybe this world is another planet's Hell.
    -- Aldous Huxley