agen¶
A very simple code generator.
- Free software: MIT license
- Documentation: https://agen.readthedocs.com/en/ .
Features¶
- Simple and very simple API
- Custom
Jinja Env
supported - Could be used as Command-Line-Tools
No Template
agen don’t provide any template. It’s only provide some function, to make code to be a template. If you need any public template, please use the awesome open source tool, Cookiecutter .
Why agen?
agen is so lightweight, that could be perfectly integrated into your project in minutes.
I like Cookiecutter (It’s so cool and so awesome), but most of it’s features are too heavyweight for me.
Installation¶
Install with pip:
pip install agen
Install with source code:
clone https://github.com/yufeiminds/agen.git
cd agen
python setup.py install
Quickstart Guide¶
In agen, use jinja2 as template engine for rendering, so, any feature of jinja2 template will be found in agen .
File Generation¶
from agen import (
string_render,
render,
generate,
generate_dir
)
# Render text from a templated string
string_render('{{key}}', {'key': 'value'})
> 'value'
cat template.py
> {{key}}
# Render text from a template file
render('template.py', {'key': 'value'})
> 'value'
# Generate file from a template file
generate('template.py', 'output.py', {'key': 'value'})
# Content of output.py
value
Directory Generation¶
If we have a directory like this:
directory
├── __init__.py
└── {{key}}.py
call generate_dir
function:
generate_dir('directory', 'mydir', {'key': 'value'})
will generate
mydir
├── __init__.py
└── value.py
Every pure text file will be render by template engine. context
{'key': 'value'}
also will be rendered automatically.
Command Line Tool¶
Basic Usage¶
agen also implement a very simple command line tool, use for rendering the local template easily, but it only could be used on *UNIX operation system.
Usage: agen [OPTIONS] [NAMES]...
Options:
-o, --out PATH Output path or directory
-s, --source PATH Source path or directory
-c, --context PATH Path of context file
--help Show this message and exit.
With no argument,agen will search local template directory, eg. on *NIX operation system, this directory are usually at:
$ agen
--------------------------------------------
agen Library
see -> /Users/yufeili/.agen/templates
--------------------------------------------
directory repo single.txt
The simplest way to call:
$ agen -s template_path -o ouput_path -c context.json
Sure, .yaml
also can be used as context
file. If the out
option wasn’t provided, it will prompt for input on screen (defualt is
current directory).
Full Example¶
You can specific three kinds of directory or file as the source
.
Single File¶
$ agen -s single.txt -o output.txt -c context.json
Directory¶
Any directory, such as
directory
├── __init__.py
└── {{key}}.py
both could be source
, it also support to use template variable to
render the output file name.
$ agen -s directory -o myapp -c context.json
This command will create a directory named myapp
, and processing
recursively all files under the directory
, output to myapp
base
on origin structure.
Repository¶
Note
agen is not designed as a command line tool, so for generating repository, recommend to use the awesome Cookiecutter .
If there is an inner folder in a directory, and the directory has a
agen.json
or agen.yaml
, it will be judged as a
Repo
,
repo
├── README.md
├── agen.json
└── {{name}}
├── __init__.py
└── {{name}}.py
The default behavior of this tool will be changed, assuming this Repo
$ agen -s repo -o output -c context.json
- This command will create a folder has the same name with inner
directory to
output
directory, if the name of folder is a template string, it will be compiled as standard string then create a folder, the other behavior same asdirectory
. - The
context
is not required. If it wasn’t provided, it will load theagen.[json|yaml]
file, and prompt user for input.
Example¶
For context {'key': 'value'}
,output is current
directory, current value:
.
└── value
├── __init__.py
└── value.py
Local Template Directory¶
Use option argument NAMES
, could get files path from local templates
directory as source
. The following two calls are equivalent in
*NIX systems:
$ agen -s ~/.agen/templates/single.txt
$ agen single.txt
Credits¶
- Author : Yufei Li yufeiminds@gmail.com
- Contact me: @yufeiminds (Facebook)、@YufeiMinds (Sina Weibo)
Indices and tables¶
API Guide¶
Here is the API reference for agen.
-
agen.
string_render
(string, context, jinja_env=None)¶ Straight to render a template string.
Parameters: - string – a template string
- context – context variable will be render
Returns: string be rendered
-
agen.
render
(template_file, context=None, jinja_env=None)¶ Render string from
jinja2
template file.Parameters: - template_file – path of template file.
- context – context dictionary
- jinja_env –
jinja2.Environment
object.
Returns: rendered text
-
agen.
generate
(template_file, out, context=None, jinja_env=None)¶ Generate a pure text file from
jinja2
template file.Parameters: - template_file – path of template file.
- out – path of output file
- context – context dictionary
- jinja_env –
jinja2.Environment
object.
-
agen.
generate_dir
(directory, out, context=None, jinja_env=None)¶ Generate a directory from
jinja2
template directory.Parameters: - template_file – path of template file.
- out – path of output file
- context – context dictionary
- jinja_env –
jinja2.Environment
object.