The Format

Config

The config is comprised of a single file install.cfg.It has two parts delimited by ------ (6 or more -). Both parts should be developed in different files for language server support. The language of the first part is YAML and for the second is Jinja.

Schema

The first section of the config is a json-Schema. It can be written in JSON or to JSON capabilites restricted YAML. The schema is restricted to the following draft version: https://json-schema.org/draft/2020-12/schema.

For functional usage the schema needs to include the following properties:

  • $id is used as identifier for the exact python package.

  • title are used for pretty print option names.

  • description is used for the options help message.

Here are the exact steps to adding a description and a pretty print name to enum values (for web-installation-instruction):

  1. Indent the schema with the key schema.

  2. Add pretty and description keys.

  3. Create lists like key: Pretty Key.

title and description from within the schema overwrite pretty and description outside of the schema.

schema:
  name: installation-instruction
  type: object
  properties:
    method:
      enum:
        - pipx
        - pip
pretty:
  pipx: Pipx
  pip: Pip
description:
  pipx: Installs python packages into virtual environments.
  pip: Standard python package manager.

The schema is tested by the Draft202012Validator from the jsonschema python package.

For the package to set the default os to the running system, give the property which specified the os the name __os__.

__os__:
  - windows
  - linux
  - macos

Jinja template

In the second part of the file a Jinja template is written. When installing the package, each rendered line is executed individually after each other.

echo "Hello"
echo "World!"

For a command with multible endparts wrapping with {% call command() %} and {% endcall %} essentially removes all line breaks for convenience.

{% call command() %}
{% if greeting == "conda" %}
    hello
    {% if person == "world" %}
        World!
    {% else %}
        Nobody!
    {% endif %}
{% endif %}
{% endcall %}

If you wish to stop the render from within the template you can use the macro raise. ({{ raise("no support!") }}.)

{% if greeting == "conda" %}
    hello
    {% if person == "world" %}
        World!
    {% else %}
        {{ raise("World is not greeted!") }}
    {% endif %}
{% endif %}