yehua - Let you focus on code, instead of setup scaffolding

Author:chfw Source code:http://github.com/moremoban/yehua.git Issues:http://github.com/moremoban/yehua/issues License:New BSD License Released:0.1.4 Generated:Sep 15, 2020

Introduction

yehua /’jɛhwa/ is yet another a project template tool for an organisation. It creates a project skeleton, S from the default project template, T, of an organisation. moban, the other tool of moremoban organisation, keeps S in synchronisation with T forever. This use case is what we called: continuous templating.

Cookiecutter users

Yes, we now support cookiecutter templates. It has been requested since 2018 Europython. Simply there is tons of cookiecutter templates out there.

What you do is to replace ‘cookiecutter’ with ‘yh’:

$ pip install yehua[cookiecutter]
$ yh gh:audreyr/cookiecutter-pypackage

And what moremoban promise is, whenever your source template changes, you can synchronize them any time with another moremoban’s command ‘moban’:

$ moban

Yes, you need a separate command, which replaces your effort to synchronize the upstream templates all the time.

What’s different with Yehua

When the scope is a single project, yehua is no different to cookiecutter and PyScaffold. It will create a project skeleton from pypi-mobans, other templates such as cookiecutter templates, yehua mobans.

When the scope is all projects within an organisation, yehua helps tackle information fragmentation problem, because all new projects after its creation, are still in synchronisation with T. For example, removing python 2.7 test in your travis file, can be done either manually by hand or automatically via moban. What’s the difference? The latter is faster and typo-free option. Here is an example.

PyScaffold version 3 has rolled out ‘–update’ option, recognizing the organisational need of continous templating. Why do not yehua join PyScaffold? Well, moremoban organisation started with ‘–update’ at the start so our architecture and vision are closer to that of cookiecutter:

1. we do not want to limit ourselves in pythonsphere. We wanted to serve all IT projects. In our mind, they are all about text templating.
2. we split the tool and the templates, serving the previous statement. People can create npm package template and use yehua+moban for continuous templating. Here are a list of examples:

• pypkg-mobans in pyecharts project
• echarts-js-mobans in echarts-map project

Installation

You can install yehua via pip:

$ pip install yehua

or clone it and install it:

$ git clone https://github.com/moremoban/yehua.git
$ cd yehua
$ python setup.py install

Usage

Simply type in and you are taken care of:

$ yh

It will use pypi-mobans-pkg by default and if it is not installed, it will install latest one. Then pypi-mobans-pkg takes over and will do [these](https://github.com/moremoban/pypi-mobans/blob/dev/yehua.yml) for you:

1. Consult you on your project static information which can update as many as you want to.
2. Create the Python package folder structure
3. Initialize the package as git project

You will simply need to commit it after you will have reviewed the generated files.

Tutorial

Let’s make a python command line utility using yehua. The command will be hello and it prints world.

Step 1 Let’s launch yehua

Step 2 Fill-in the meta data for your project

At the end, yehua generates a folder named ‘hello’, which contains [all necessary files](https://github.com/moremoban/pypi-mobans).

Step 3 Start coding

In above animation, we write up the actual code in hello/main.py

def main():
    print('world')

Why is it enough? yehua generates a command utility python and it has pre-wired to invoke hello.main.main() function. You can find it out in setup.py.

Step 4 Install it

Now all is done. Let’s install it

You can now run hello at your command line.

Step 5 push to github

Suppose you are happy with everything. Please do the following to push it to your github:

$ git commit -am ":sparkle: initial commit"

Then create your project repository in github and do these to push it out:

$ git remote add origin https://github.com/moremoban/hello.git
$ git push origin master

You can find the hello project on github.

Step 7 enable travis

The generated project already has .travis.yml file. What you will need to do is to register with travis.org if you have not done so. And then go to travis and activate your project.

Background

The original problem I was trying to solve is: I would like to place common paragraphs in the documentation of my projects in a central place (pyexcel-mobans), and all projects could reference it dynamically so that when those common paragraphs get updated, the updates can be easily propagated to all relevant projects. The derived problem is: what can I do to a new project? I found myself doing a lot of copy-and-paste a lot, which lead to the creation of “yehua”. Later, John Vandenberg, an active member of coala, suggested extracting the generic sets of pyexcel-mobans to form pypi-mobans, so that a vanilla python package can be created. Why not cookiecutter? Well, I have not heard of it at the time of creation. But it turns out that this project started to pave the way to be the cookiecutter for organisations.

Why to choose “yehua”? Here is the little story behind the choice of name. And this music video would help bridge the cultural gap between you and me.

Documentation

Default use case: scaffolding a python package

yehua reads a configuration file named yehua.yml which then instruct **yehua to ask questions to collect project specific variables, and create the file structures.

It takes a yehua file from command line option, or YEHUA_FILE in the environment variable. If none is found, it resorts to the default yehua.yml file included in the package. And the default yehua.yml create a blank python package.

Default yehua.yml file

Let us go through the default yehua file. And then talk about the customization in the next chapter

configuration section

yehua expects two set of files: templates and static files. configuration section tells where they are relative to yehua.yml file.

In the default use case, the templates are located in yehua/resources/templates and the static files are located in yehua/resources/static.

The files in the static folder will not be templated and will be copied across.

As a rule of thumb, if your file needs user input, please place it in templates folder. Otherwise, please place your files in static folder, which is copied across.

user question section

yehua will then ask a list of questions. The quoted lines are prompted to the end user and the answers are given to the variable names on the left hand side of semi-colon. Here is a simple format:

- holding_variable_name_for_the_answer: "What is most intuitive question for the variable?"

Then “holding_variable_name_for_the_answer” can be used in your template files.

layout section

layout section outlines the folder structure of the resulting project folder. yehua will create the folder layout before generating any outputs.

In this case, a default python package will have tests, docs and .moban.d at its first level. yehua would always create a sub folder named after project_name.

templates section

The files in this section follows this spec:

• templated_target_file: template.file.in.templates.folder

As you can see, yehua would expand project_name for you.

static section

File in this section is simply copied over. Here is the spec:

- relative_file_path: relative_static_file_path_in_static_folder

Template files

Let’s examine the beginning of project.yml in templates folder.

1. project_name
2. organisation
3. author
4. contact
5. company

are unknown to yehua and only the user knows the answer. Hence, it brings us to the next section: user questions

Static files

The static files in yehua/resources/static are copied over by yehua according to the instruction file.

After all actions

The possible extra actions is git-repo-files where you can name the files to be added to a git repo. Here is a list of default files to be added to the file repo:

Custom use case: scaffolding a npm package

As mentioned in previous section, yehua would take a yehua.yml from command line options. This section walk you through creating a npm package, non-python package.

If you are familiar with npm, you can try and compare with yehua:

$ npm init

Evaluation

Please first checkout yehua repository so that you will have the access to example directory. Then make sure you have yehua installed.

yehua.yml for npm package

Let us go through the variant yehua file.

configuration section

configuration:
  template_path: .
  static_path: .
questions:

the current directory where yehua.yml file is, is configured as the folder for templates and static files.

user questions section

questions:
  - project_name: "name:"
  - version: "version:"
  - description: "description:"
  - entry_point: "entry point:"
  - test_command: "test command:"
  - git_repo: "git repository:"
  - keywords: "keywords:"
  - author: "author:"
  - license: "license:"

the questions here are prompted to collect user inputs.

templates section

templates:
  - package.json: package.json.jj2

Now the variables are used in template package.json.jj2 into package.json.

static section

static:
  - index.js: index.js

Now, yehua simply copies index.js to target package folder.

Enterprise use case: scaffolding all projects in your organisation

Previous example shows that you can write up your own yehua.yml and supporting templates and static files and yehua creates the scaffolding for you.

Now in an enterprise context, you as the team lead or the architect would like to propagate the best practices to all new projects. What you can do is to make the yehua.yml and its files into repository. And then you could set:

$ export YEHUA_FILE=/location/to/the/cloned/yehua/repo/yehua.yml

Since then, yehua would always use that yehua file for scaffolding.

if you want to try it now, you could do this:

$ export YEHUA_FILE=/location/to/yehua/repo/examples/npm-init/yehua.yml
$ yehua

License

NEW BSD License