moban - 模板 Any template, any data in any location¶
Author: | C.W. and its contributors (See contributors.rst) |
---|---|
Issues: | http://github.com/moremoban/moban/issues |
License: | MIT |
Version: | 0.6.5 |
Generated: | Oct 12, 2019 |
moban started with bringing the high performance template engine (JINJA2) for web into static text generation. It has been used in pyexcel and coala project to keep documentation consistent across the documentations of individual libraries in the same organisation.
moban can use other python template engine: mako, handlebars, velocity, haml, slim and tornado, can read other data format: json and yaml, and can access both template file and configuration file in any location: zip, git, pypi package, s3, etc.
Please look at our issues. We have many more template engines and data format on the road map.
All use cases are documented here
Installation¶
You can install it via pip:
$ pip install moban
or clone it and install it:
$ git clone http://github.com/moremoban/moban.git
$ cd moban
$ python setup.py install
Quick start¶
$ export HELLO="world"
$ moban "{{HELLO}}"
Warning: Both data.yml and /.../.moban.cd/data.yml does not exist
Warning: Attempting to use environment vars as data...
Templating {{HELLO}}... to moban.output
Templated 1 file.
$ cat moban.output
world
Or
$ export HELLO="world"
$ echo "{{HELLO}}" | moban
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:
{{hello}}
moban.output will contain:
world
Please note that data.yml will take precedence over environment variables.
Work with files in a git repo¶
gitfs2 is installed by default since v0.6.1
You can do the following with moban:
$ moban -t 'git://github.com/moremoban/pypi-mobans.git!/templates/_version.py.jj2' \
-c 'git://github.com/moremoban/pypi-mobans.git!/config/data.yml' \
-o _version.py
Info: Found repo in /Users/jaska/Library/Caches/gitfs2/repos/pypi-mobans
Templating git://github.com/moremoban/pypi-mobans.git!/templates/_version.py.jj2 to _version.py
Templated 1 file.
$ cat _version.py
__version__ = "0.1.1rc3"
__author__ = "C.W."
Work with files in a python package¶
pypifs is installed by default since v0.6.1
You can do the following with moban:
$ moban -t 'pypi://pypi-mobans-pkg/resources/templates/_version.py.jj2' \
-c 'pypi://pypi-mobans-pkg/resources/config/data.yml' \
-o _version.py
Collecting pypi-mobans-pkg
....
Installing collected packages: pypi-mobans-pkg
Successfully installed pypi-mobans-pkg-0.0.7
Templating pypi://pypi-mobans-pkg/resources/templates/_version.py.jj2 to _version.py
Templated 1 file.
$ cat _version.py
__version__ = "0.1.1rc3"
__author__ = "C.W."
Work with S3 and other cloud based file systems¶
Please install fs-s3fs:
$ pip install fs-s3fs
Then you can access your files in s3 bucket:
$ moban -c s3://${client_id}:${client_secrect}@moremoban/s3data.yml \
-o 'zip://my.zip!/moban.output' {{hello}}
$ unzip my.zip
$ cat moban.output
world
Where the configuration sits in a s3 bucket, the output is a file in a zip. The content of s3data.yaml is:
hello: world
CLI documentation¶
usage: moban [-h] [-c CONFIGURATION] [-t TEMPLATE] [-o OUTPUT]
[-td [TEMPLATE_DIR [TEMPLATE_DIR ...]]] [-cd CONFIGURATION_DIR]
[-m MOBANFILE] [-g GROUP] [--template-type TEMPLATE_TYPE]
[-d DEFINE [DEFINE ...]] [-e EXTENSION [EXTENSION ...]] [-f]
[--exit-code] [-V] [-v]
[template]
Static text generator using any template, any data and any location.
positional arguments:
template string templates
optional arguments:
-h, --help show this help message and exit
-c CONFIGURATION, --configuration CONFIGURATION
the data file
-t TEMPLATE, --template TEMPLATE
the template file
-o OUTPUT, --output OUTPUT
the output file
Advanced options:
For better control
-td [TEMPLATE_DIR [TEMPLATE_DIR ...]], --template_dir [TEMPLATE_DIR [TEMPLATE_DIR ...]]
add more directories for template file lookup
-cd CONFIGURATION_DIR, --configuration_dir CONFIGURATION_DIR
the directory for configuration file lookup
-m MOBANFILE, --mobanfile MOBANFILE
custom moban file
-g GROUP, --group GROUP
a subset of targets
--template-type TEMPLATE_TYPE
the template type, default is jinja2
-d DEFINE [DEFINE ...], --define DEFINE [DEFINE ...]
to supply additional or override predefined variables,
format: VAR=VALUEs
-e EXTENSION [EXTENSION ...], --extension EXTENSION [EXTENSION ...]
to to TEMPLATE_TYPE=EXTENSION_NAME
-f force moban to template all files despite of
.moban.hashes
Developer options:
For debugging and development
--exit-code tell moban to change exit code
-V, --version show program's version number and exit
-v show verbose, try -v, -vv
Exit codes¶
By default:
- 0 : no error
- 1 : error occured
With –exit-code:
- 0 : no changes
- 1 : has changes
- 2 : error occured
Tutorial¶
Please clone the moban repository as the data mentioned in the tutorial are stored in examples folder.
- Level 1 Jinja2 on command line
- Level 2: template inheritance
- Level 3: data override
- Level 4: single command
- Level 5: custom configuration
- Level 6: Complex Configuration
- Level 7: Custom jinja filters, tests and globals
- Level 8: Pass a folder full of templates
- level 9: moban dependency as pypi package
- level 10: moban dependency as git repo
- Level 11: use handlebars
- Level 12: use template engine extensions
- Level 13: any data override any data
- Level 14: custom data loader
- Level 15: template copying becomes an action plugin in targets
- Level 16: group targets by their template type
- Level 17: force template type
- Level 18: User defined template types
- Level 19: select a group target to run
- Level 20: templates, files in a zip or tar
- Level 21: template copying from a zip to a zip
For more complex use case, please look at its usage in pyexcel project
Developer Guide¶
Change log¶
0.6.4 - 4.10.2019¶
Updated
- Command options have been grouped. –template_type became –template-type
- Increment gitfs2 to version 0.0.2. gitfs#4
0.6.2 - 15.09.2019¶
Added
0.6.0 - 10.09.2019¶
Added
- #205: support pyFilesystem2
- #185: -v will enable moban application logging for development. And -V is for version.
- #325: -vv show debug trace
- #126: Allow mobanfile to include data from arbitrary config files
- #256: jinja2-cli parity: ‘-d hello=world’ to define custom variable on cli
Updated
- #275: fix moban 0.4.5 test failures on openSUSE Tumbleweed
0.5.0 - 14.07.2019¶
Updated
- #277: Restored dependency git-url-parse, replacing incompatible giturlparse which was used during moban 0.4.x
- #281: Fixed unicode support on Python 2.7
- #274: Updated ruamel.yaml dependency pins to restore support for Python 3.4, and prevent installation of versions that can not be installed on Python 3.7
- #285: Fixed CI testing of minimum requirements
- #271: Fixed repository caching bug preventing branch switching
- #292: Reformatted YAML files according to yamllint rules
- #291: Fixed filename typos in README
- #280: Added CI to ensure repository is in sync with upstream
- #280: sync setup.py from pypi-mobans
0.4.3 - 16.03.2019¶
Removed
- #253: symbolic link in regression pack causes python setup.py to do recursive include
Added
- #209: Alert moban user when git is not available and is used.
Updated
- #261: since moban group template files per template type, this fill use first come first register to order moban group
0.4.2 - 08.03.2019¶
Added
- #234: Define template parameters on the fly inside targets section
- #62: select a group target to run
Updated
- #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.
- #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¶
Added
0.3.10 - 03.02.2019¶
Added
- #174: Store git cache in XDG_CACHE_DIR
- #107: Add -v to show current moban version
- #164: support additional data formats
Updated
0.3.9 - 18-1-2019¶
Updated
0.3.8 - 12-1-2019¶
Updated
- #141: disable file permissions copy feature and not to check file permission changes on windows.
- #154: introduce first ever positional argument for string base template.
- #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¶
Updated
0.3.6 - 30-12-2018¶
Updated
0.3.5 - 10-12-2018¶
Updated
- #37: moban will report line number where the value is empty and the name of mobanfile. Switch from pyyaml to ruamel.yaml.
0.3.4 - 18-11-2018¶
Added
- global variables to store the target and template file names in the jinja2 engine
- moban-handlebars is tested to work well with this version and above
Updated
- Template engine interface has been clarified and documented
0.3.3 - 05-11-2018¶
Added
- alternative and expanded syntax for requires, so as to accomendate github submodule recursive
0.3.2 - 04-11-2018¶
Added
- configuration dirs may be located by requires, i.e. configuration files may be in a python package or git repository.
0.3.1 - 02-11-2018¶
Added
- #97: requires will clone a repo if given. Note: only github, gitlab, bitbucket for now
0.3.0 - 27-18-2018¶
Added
- #89: Install pypi-hosted mobans through requires syntax
Updated
- #96: Fix for FileNotFoundError for plugins
- various documentation updates
Removed
- #88: removed python 2.6 support
- removed python 3.3 support
0.2.4 - 14-07-2018¶
Added
0.2.3 - 10-07-2018¶
Added
0.2.2 - 16-06-2018¶
Added
- #31: create directory if missing during copying
Updated
- #28: if a template has been copied once before, it is skipped in the next moban call
0.2.1 - 13-06-2018¶
Updated
- templates using the same template engine will be templated as a group
- update lml dependency to 0.0.3
0.2.0 - 11-06-2018¶
Added
- #18: file exists test
- #23: custom jinja plugins
- #26: repr filter
- #47: allow the expansion of template engine
- #58: allow template type per template
Updated
- #34: fix plural message if single file is processed
0.1.4 - 29-May-2018¶
Updated
0.1.1 - 08-Jan-2018¶
Added
- the ability to present a long text as multi-line paragraph with a custom upper limit
- speical filter expand github references: pull request and issues
- #15: fix templating syntax to enable python 2.6
0.0.9 - 24-Nov-2017¶
Added
- #11, recognize .moban.yaml as well as .moban.yml.
- #9, preserve file permissions of the source template.
- -m option is added to allow you to specify a custom moban file. kinda related to issue 11.
Updated
- 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¶
Added
- #8, verify the existence of custom template and configuration directories. default .moban.td, .moban.cd are ignored if they do not exist.
Updated
- Colorize error messages and processing messages. crayons become a dependency.
0.0.7 - 19-Jul-2017¶
Added
- Bring the visibility of environment variable into jinja2 templating process: #7
0.0.6 - 16-Jun-2017¶
Added
- added ‘-f’ flag to force moban to template all files despite of .moban.hashes
Updated
- 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¶
Added
- 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.
- Added summary reports