clinja 1.2.2

A jinja command line interface

A jinja CLI.

clinja is a versatile command line interface for jinja.

Instalation

clinja should run just fine on Windows, macOS and Linux, to install open up a terminal and run:

pip install clinja

As always, it's a good idea to use a virtual env, or maybe consider using pipx.

To generate <tab> completion for your shell run:

# Bash:
clinja completions bash > /etc/bash_completion.d/clinja.bash-completion

# Bash (Homebrew)
clinja completions bash > $(brew --prefix)/etc/bash_completion.d/clinja.bash-completion

# Fish:
clinja completions fish > ~/.config/fish/completions/clinja.fish

# Fish (Homebrew)
clinja completions fish > $(brew --prefix)/share/fish/vendor_completions.d/clinja.fish

# Zsh
clinja completions zsh > /somewhere/in/your/fpath/_clinja

# Zsh (Homebrew)
clinja completions zsh > $(brew --prefix)/share/zsh/site-functions/_clinja

Dependencies

clinja relies on the following dependencies:

• python3
• jinja: the templating engine.
• click: for the command line interface and completion.
• myopy: to run the dynamic source python file.

How it works

When you run clinja on a template containing some jinja variables to fill in, clinja will fetch values for these variables from 2 sources.

The static source

The static source is simply a json file which contains unchanging, static, key value pairs, a la cookiecutter's cookiecutter.json file. This is where you would want to add your name, email, username etc. You have full control over these values and can easily manage the stored values using clinja.

The dynamic source

This is where things get a bit more interesting, clinja can also get values from a so called dynamic source, check the wiki for some examples. This source is a python file, with a few variables provided to it at run time. The provided variables are:

TEMPLATE  # Pathlib Path to the template, is None when using stdin.
DESTINATION  # Pathlib Path to the destination, is None when using stdout.
RUN_CWD  # Pathlib Path, Directory were the clinja command was run.
STATIC_VARS  # Dictionary of static variables.
DYNAMIC_VARS  # Dictionary of dynamic variables, initially empty, populated by the dynamic file.

With this file you can do some nifty things, such as automatically determining the name of the git repo in which the completed template will live in. Any values computed in this file should be added to the DYNAMIC_VARS dict.

Missing variables

When clinja runs into a variable it can't get from either the static or the dynamic source, it will prompt you for a value, and offer to store it in the static file for later use.

Usage

$ clinja --help
Usage: clinja [OPTIONS] COMMAND [ARGS]...

  A versatile jinja command line interface.

  Clinja uses two sources to find values for jinja variables. A
  static source, which is just a json file, and a dynamic
  source, which is a python source file. Clinja populates the static
  source with user entered values. Whereas the dynamic variables are
  computed at run time by the python file.

  In short:

      Clinja stores all static variables in:
      /home/lcoyle/.config/clinja/static.json

      Clinja's dynamic variables are computed by the python file:
      /home/lcoyle/.config/clinja/dynamic.py

Options:
  --help  Show this message and exit.

Commands:
  add         Add a variable to static storage.
  completion  Generate autocompletion for your shell.
  list        List stored static variable(s).
  remove      Remove stored static variable(s).
  run         Run jinja on a template.
  test        Test run your dynamic.py file.

Static variables:

To manage the static variables, use the subcommands: clinja add, clinja remove and clinja list. They should be self explanatory.

Dynamic variables:

$ clinja test --help
Usage: clinja test [OPTIONS]

  Test run your dynamic.py file.

  Run your dynamic.py file using mock values.

  template, destination, run_cwd and static_vars are provided to the
  dynamic.py file in their respective variable names.

Options:
  --template PATH     mock template path.
  --destination PATH  mock template path.
  --run_cwd PATH      mock current working directory path.
  --static_vars TEXT  mock json format static variables.
  --help              Show this message and exit.

The clinja test subcommand is provided to help setup and test your dynamic source. It allows you to provide any values to the dynamic source's input variables, run the dynamic.py file and will print out the results.

Run jinja

$ clinja run --help
Usage: clinja run [OPTIONS] [TEMPLATE] [DESTINATION]

  Run jinja on a template.

  TEMPLATE (optional, default: stdin): template file on which to run jinja,
  if using stdin, --prompt is set to "never".

  DESTINATION (optional, default: stdout): output destination.

Options:
  --prompt [always|missing|never]
                                  When to prompt for variable values.
  -d, --dry-run                   Dry run, won't write any files or change/add
                                  any static values.

  --help                          Show this message and exit.

--prompt

• Using --prompt always, will use the values fetched from both sources as defaults and prompt you for each variable's value, giving you a chance to overwrite.
• Using --prompt missing, will only prompt you for the variables it can't find a value for.
• Using --prompt never, will never prompt and will fail if clinja encounters a variable for which it has no value.

-d

The -d flag will do a dry run, no files will be written and your static source will not change.

_{This is part 2 of my ongoing personal mission to improve template handling from the command line, see part 1: tmpl.}