moban - 模板 Yet another jinja2 cli command for static text generation
Generated:Mar 08, 2019

moban brings the high performance template engine (JINJA2) for web into static text generation. It is used in pyexcel project to keep documentation consistent across the documentations of individual libraries.


You can install it via pip:

$ pip install moban

or clone it and install it:

$ git clone
$ cd moban
$ python install

Quick start

$ export HELLO="world"
$ moban "{{HELLO}}"
Warning: Both data.yml and /.../ does not exist
Warning: Attempting to use environment vars as data...
Templating {{HELLO}}... to moban.output
Templated 1 file.
$ cat moban.output

Or simply

$ HELLO="world" moban "{{HELLO}}"

A bit formal example:

$ moban -c data.yml -t my.template
$ cat moban.output

Given data.yml as:

hello: world

and my.template as:


moban.output will contain:


Please note that data.yml will take precedence over environment variables.

the tutorial has more use cases.


usage: moban [-h] [-cd CONFIGURATION_DIR] [-c CONFIGURATION]
             [-td [TEMPLATE_DIR [TEMPLATE_DIR ...]]] [-t TEMPLATE] [-o OUTPUT]
             [-f] [-m MOBANFILE]

Yet another jinja2 cli command for static text generation

positional arguments:
  template              string templates

optional arguments:
  -h, --help            show this help message and exit
                        the directory for configuration file lookup
                        the dictionary file. if not present, moban
                        will try to use environment vars as data
  -td [TEMPLATE_DIR [TEMPLATE_DIR ...]], --template_dir [TEMPLATE_DIR [TEMPLATE_DIR ...]]
                        the directories for template file lookup
  -t TEMPLATE, --template TEMPLATE
                        the template file. this overrides any targets
                        defined in a custom moban file
  -o OUTPUT, --output OUTPUT
                        the output file
  --template_type TEMPLATE_TYPE
                        the template type, default is jinja2
  -f                    force moban to template all files despite of
  --exit-code           tell moban to change exit code
  -m MOBANFILE, --mobanfile MOBANFILE
                        custom moban file

Exit codes

By default:

  • 0 : no error
  • 1 : error occured

With –exit-code:

  • 0 : no changes
  • 1 : has changes
  • 2 : error occured

Built-in Filters


It breaks down the given string into a fixed length paragraph. Here is the syntax:

{% for line in your_string | split_length(your_line_with) %}
{% endfor %}

It is used to keep changelog formatted in CHANGELOG.rst.jjs in pypi-mobans project


It expands simple hashtags into github issues. Here is the syntax:

{{ your_github_string | github_expand }}

It makes it easy to mention github reference in change log in all projects. Here is the place it is applied: CHANGELOG.rst.jjs in pypi-mobans project

Here is Grammar in the changelog.yml:

=============== ==============================
Syntax          Meaning
=============== ==============================
`#1`            moban issues 1
`PR#1`          moban pull request 1
`pyexcel#1`     other project issues 1
`pyexcel#PR#1`  other project pulll request 1
=============== ==============================

More details can be found in moban’s changelog.yml


Returns a single quoted string in the templated file

Built-in Tests


Test if a file exists or not

Change log

0.4.2 - 08.03.2019


  1. #234: Define template parameters on the fly inside targets section
  2. #180: No longer two statistics will be shown in v0.4.x. legacy copy targets are injected into a normal targets. cli target is made a clear priority.
  3. #62: select a group target to run
  4. #244: version 0.4.2 is first version which would work perfectly on windows since 17 Nov 2018. Note that: file permissions are not used on windows. Why the date? because samefile is not avaiable on windows, causing unit tests to fail hence it lead to my conclusion that moban version between 17 Nov 2018 and March 2019 wont work well on Windows.

0.4.1 - 28.02.2019


  1. #235: user defined template types so that custom file extensions, template configurations can be controlled by moban user
  2. #232: the package dependencies have been fine tuning to lower versions, most of them are dated back to 2017.

0.4.0 - 20.02.2019


  1. #165: Copy as plugins


  1. #219: git clone depth set to 2
  2. #186: lowest dependecy on ruamel.yaml is 0.15.5, Jun 2017

0.3.10 - 03.02.2019


  1. #174: Store git cache in XDG_CACHE_DIR
  2. #107: Add -v to show current moban version
  3. #164: support additional data formats


  1. #178: UnboundLocalError: local variable ‘target’ referenced before assignment
  2. #169: uses GitPython instead of barebone git commands

0.3.9 - 18-1-2019


  1. #90: allow adding extra jinja2 extensions., jinja2.ext.loopcontrols are included by default. what’s more, any other template enigne are eligible for extension additions.
  2. #158: Empty file is finally removed

0.3.8 - 12-1-2019


  1. #141: disable file permissions copy feature and not to check file permission changes on windows.
  2. #154: introduce first ever positional argument for string base template.
  3. #157: the exit code behavior changed. for backward compactibility please use –exit-code. Otherwise, moban will not tell if there is any changes.

0.3.7 - 6-1-2019


  1. #146: added a low-setup usage mode via environment variables to moban
  2. #148: include test related files in the package for package validation when distributing via linux system, i.e. OpenSuse

0.3.6 - 30-12-2018


  1. #143: moban shall report permission error and continue the rest of the copying task.
  2. #122: Since 0.3.6, moban is tested on windows and macos too, using azure build pipelines. It is already tested extensively on travis-ci on linux os.

0.3.5 - 10-12-2018


  1. #37: moban will report line number where the value is empty and the name of mobanfile. Switch from pyyaml to ruamel.yaml. - 28-11-2018


  1. #137: missing contributors.rst file

0.3.4 - 18-11-2018


  1. global variables to store the target and template file names in the jinja2 engine
  2. moban-handlebars is tested to work well with this version and above


  1. Template engine interface has been clarified and documented

0.3.3 - 05-11-2018


  1. alternative and expanded syntax for requires, so as to accomendate github submodule recursive

0.3.2 - 04-11-2018


  1. requires shall support configuration dirs. In other words, configuration file could be stored in python package or git repository.

0.3.1 - 02-11-2018


  1. #97: requires will clone a repo if given. Note: only github, gitlab, bitbucket for now

0.3.0 - 27-18-2018


  1. #89: Install pypi-hosted mobans through requires syntax


  1. #96: Fix for FileNotFoundError for plugins
  2. various documentation updates


  1. #88: removed python 2.6 support
  2. removed python 3.3 support

0.2.4 - 14-07-2018


  1. #32: option 1 copy a directory without its subdirectories.
  2. #30: command line template option is ignore when a moban file is present

0.2.3 - 10-07-2018


  1. #76: running moban as a module from python command
  2. #32: copy a directory recusively
  3. #33: template all files in a directory

0.2.2 - 16-06-2018


  1. #31: create directory if missing during copying


  1. #28: if a template has been copied once before, it is skipped in the next moban call

0.2.1 - 13-06-2018


  1. templates using the same template engine will be templated as a group
  2. update lml dependency to 0.0.3

0.2.0 - 11-06-2018


  1. #18: file exists test
  2. #23: custom jinja plugins
  3. #26: repr filter
  4. #47: allow the expansion of template engine
  5. #58: allow template type per template


  1. #34: fix plural message if single file is processed

0.1.4 - 29-May-2018


  1. #21: targets become optional
  2. #19: transfer symlink’s target file’s file permission under unix/linux systems
  3. #16: introduce copy key word in mobanfile

0.1.3 - 12-Mar-2018


  1. handle unicode on python 2

0.1.2 - 10-Jan-2018


  1. #13: strip off new lines in the templated file

0.1.1 - 08-Jan-2018


  1. the ability to present a long text as multi-line paragraph with a custom upper limit
  2. speical filter expand github references: pull request and issues
  3. #15: fix templating syntax to enable python 2.6

0.1.0 - 19-Dec-2017


  1. #14, provide shell exit code

0.0.9 - 24-Nov-2017


  1. #11, recognize .moban.yaml as well as .moban.yml.
  2. #9, preserve file permissions of the source template.
  3. -m option is added to allow you to specify a custom moban file. kinda related to issue 11.


  1. use explicit version name: moban_file_spec_version so that version can be used by users. #10 Please note: moban_file_spec_version is reserved for future file spec upgrade. For now, all files are assumed to be ‘1.0’. When there comes a new version i.e. 2.0, new moban file based on 2.0 will have to include ‘moban_file_spec_version: 2.0’

0.0.8 - 18-Nov-2017


  1. #8, verify the existence of custom template and configuration directories. default, are ignored if they do not exist.


  1. Colorize error messages and processing messages. crayons become a dependency.

0.0.7 - 19-Jul-2017


  1. Bring the visibility of environment variable into jinja2 templating process: #7

0.0.6 - 16-Jun-2017


  1. added ‘-f’ flag to force moban to template all files despite of .moban.hashes


  1. moban will not template target file in the situation where the changes occured in target file than in the source: the template file + the data configuration after moban has been applied. This new release will remove the change during mobanization process.

0.0.5 - 17-Mar-2017


  1. Create a default hash store when processing a moban file. It will save unnecessary file write to the disc if the rendered content is not changed.
  2. Added summary reports

0.0.4 - 11-May-2016


  1. Bug fix #5, should detect duplicated targets in .moban.yml file.

0.0.3 - 09-May-2016


  1. Bug fix #4, keep trailing new lines

0.0.2 - 27-Apr-2016


  1. Bug fix #1, failed to save utf-8 characters

0.0.1 - 23-Mar-2016


  1. Initial release

Indices and tables