agen

A very simple code generator.

Latest Version Travis CI Status Codecov Status Doc Status

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 as directory .
  • The context is not required. If it wasn’t provided, it will load the agen.[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)

Contribution

Welcome to develop with me!

Fork this repo & develop it.

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.

ChangeLog

Here is all changes history.

Version 0.1.0

Release on Mar. 19 2016.

  • Finish the core apis.
  • Release the docs on RTD.
  • RUN CI and pass it.