agen
=======
A very simple code generator.
.. image:: https://img.shields.io/pypi/v/agen.svg
:target: https://pypi.python.org/pypi/agen/
:alt: Latest Version
.. image:: https://travis-ci.org/yufeiminds/agen.svg?branch=master
:target: https://travis-ci.org/yufeiminds/agen
:alt: Travis CI Status
.. image:: https://codecov.io/github/yufeiminds/agen/coverage.svg?branch=develop
:target: https://codecov.io/github/yufeiminds/agen?branch=master
:alt: Codecov Status
.. image:: https://readthedocs.org/projects/agen/badge/?version=latest
:target: http://agen.readthedocs.org/en/latest/?badge=latest
:alt: Doc Status
- 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 <https://github.com/audreyr/cookiecutter>`__ .
**Why agen?**
agen is so lightweight, that could be perfectly integrated into your
project in minutes.
I like `Cookiecutter <https://github.com/audreyr/cookiecutter>`__ (It's
so cool and so awesome), but most of it's features are too heavyweight
for me.
Installation
------------
Install with pip:
.. code:: shell
pip install agen
Install with source code:
.. code:: shell
clone https://github.com/yufeiminds/agen.git
cd agen
python setup.py install
Quickstart Guide
----------------
In *agen*, use `jinja2 <http://jinja.pocoo.org/docs/>`__ as
template engine for rendering, so, any feature of
`jinja2 <http://jinja.pocoo.org/docs/>`__ template will be found in
*agen* .
File Generation
~~~~~~~~~~~~~~~
.. code-block:: python
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:
.. code:: shell
directory
├── __init__.py
└── {{key}}.py
call ``generate_dir`` function:
.. code-block:: python
generate_dir('directory', 'mydir', {'key': 'value'})
will generate
.. code:: shell
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 <https://github.com/audreyr/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.