{ "info": { "author": "Andre Lehmann", "author_email": "aisberg@posteo.de", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: Developers", "Intended Audience :: System Administrators", "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)", "Operating System :: POSIX", "Programming Language :: Python :: 3 :: Only", "Topic :: System :: Systems Administration", "Topic :: Utilities" ], "description": "# Templer - templating with Jinja2\n\nThis is a Python 3 module for rendering template files using [Jinja2](http://jinja.pocoo.org/). Sources for variables is the environment and context files.\n\nThe documentation of the Jinja2 syntax can be found [here](http://jinja.pocoo.org/docs/dev/templates/).\n\n**Features:**\n* templating using Jinja2\n* providing variables via environment variables and context files\n* using YAML for context files\n* easy definition of default values\n* dynamic context files (render context files themselves)\n\n**Table of contents**\n\n\n- [Installation](#installation)\n- [Usage](#usage)\n\t- [Environment Variables](#environment-variables)\n\t- [Context Files](#context-files)\n\t- [Templates](#templates)\n\t- [Examples](#examples)\n- [Extra Jinja2 Filters](#extra-jinja2-filters)\n- [License](#license)\n\n\n\n---\n\n## Installation\n\nInstall directly from Github:\n```\npip install git+https://github.com/Aisbergg/python-templer@v1.1.4\n```\n\nInstall from PyPi:\n```\npip install Templer\n```\n\n## Usage\n\n```\nusage: templer [-c CONTEXTFILE] [-d] [-r] [-f] [-h] [-i] [-m FILE_MODE] [-t]\n [-v] [--version]\n template [template ...] destination\n\nRender template files with the power of Jinja2\n\npositional arguments:\n template File to be rendered. Path can be either a file or\n directory containing multiple files (*.j2)\n destination Destination for the rendered file(s)\n\noptional arguments:\n -c CONTEXTFILE, --contextfile CONTEXTFILE\n Context file to be used for rendering. Path can be\n either a file or directory containing multiple files\n (*.yml). The option can be used multiple times to\n specify multiple paths\n -d, --dynamic-contextfiles\n Render the context files like the templates before\n parsing them\n -r, --remove-templates\n Delete the templates after rendering\n -f, --force Overwrite existing files\n -h, --help Show this help message and exit\n -i, --ignore-undefined-variables\n Ignore undefined variables\n -m FILE_MODE, --mode FILE_MODE\n File mode for rendered files\n -t, --defaults-type-check\n Check if the environment variables match the data type\n of the defaults specified in a context file\n -v, --verbose Enable verbose mode (-vv for debug mode)\n --version Prints the program version and quits\n\n```\n\nThere are two sources for variables that are used to render the templates. The first source is the system environment and the second one the context files.\n\n### Environment Variables\n\nWhen an env is defined like `FOO=BAR` it can be used as `{{ FOO }}` or `{{ env.FOO }}` in the template file.\n\n### Context Files\n\nThe intend of the context files is to be the main source for default variables while the environment variables add dynamic to the rendering. Thus the context files can provide a generic default configuration and the environment variables used to customize it.\n\nThe context files are written in nice, human-readable YAML. When desired the context files can also be rendered using the environment variables and Jinja2 before parsing them.\n\nHere is an extensive example with all features explained:\n```yaml\n# Using the YAML syntax the definition of static variables is simple. Following\n# lines create three different variables that can be used in the templates like\n# `{{ static.var1 }}`.\nstatic:\n var1: \"foo\"\n var2: 1\n var3: True\n\n# When the option `--dynamic-contextfiles` is supplied, then the context will be\n# rendered with Jinja2 using the environment variables before parsing its\n# content.\ndynamic:\n var4: \"{{ VAR4 | default('bar') }}\"\n var5: {{ 1.0 if VAR5 == 'True' else 2.0 }}\n\n# A handy shortcut for defining defaults for variables is the `defaults`\n# section. `defaults` is a mapping where every key represents a default for a\n# variable. The format is simply: `VARIABLE: DEFAULT_VALUE`\n# Thus the environment variables will be checked if a variable with the name\n# `VARIABLE` is defined and if not it will be declared and set to the value\n# `DEFAULT_VALUE`. Templer takes the data type of the `DEFAULT_VALUE` into\n# account and tries to parse the given environment variable accordingly.\n# When the option `--defaults-type-check` is supplied, a failure in parsing the\n# right data type will result in an error and program termination.\ndefaults:\n # type string\n VAR6: \"some string\"\n # type bool\n VAR7: False\n # type int\n VAR8: 1\n # type float\n VAR9: 3.0\n # type list (env must be specified in json format like: [\"a\", \"b\", \"c\"])\n VAR10:\n - \"foo\"\n - \"bar\"\n - \"uff\"\n\n # ----------------------------------------------------------------------------\n # To simplify some more use cases there are a couple of special defaults\n # available:\n\n # Type: Choice\n # This type checks a user choice against a list of possible choices. If the\n # given choice is not in the list, then an error is thrown. In the following\n # example a given env `VAR11=c` is considered a valid choice. A value like\n # `VAR11=z` is considered invalid and therefore the program will terminate.\n VAR11:\n type: choice # type of special defaults\n default: b # default choice\n case_sensitive: False # optional (default: false)\n strip: True # optional (default: true)\n choices: # list of available choices\n - a\n - b\n - c\n\n # Type: List\n # This type extends the simple 'list' default, so lists don't have to be\n # defined as json list. Instead a delimiter can be defined to split up a\n # string into a list:\n VAR12:\n type: list\n delimiter: \",\" # delimiter for splitting the string\n strip: True # optional (default: true)\n default: # default list to use\n - a\n - b\n - c\n\n # Type: Variation\n # This type adds different variations of default values. In the following\n # example there are three variation (`SMALL`, `MEDIUM`, `LARGE`) defined. A\n # variation is used when the related environment variable is defined. So for\n # example if `SMALL=''` is defined then the variables `VAR13: 1` and\n # `VAR14: \"a\"` will be used.\n SMALL:\n type: variation\n defaults: # can be same structure as the main `defaults`\n VAR13: 1\n VAR14: \"a\"\n MEDIUM:\n type: variation\n defaults:\n VAR13: 10\n VAR14: \"aaa\"\n LARGE:\n type: variation\n defaults:\n VAR13: 100\n VAR14: \"aaaaaaaaa\"\n```\n\n### Templates\n\nThe templates are rendered with Jinja2 using the variables defined in the context files and environment. Therefore any Jinja2 specific syntax can be used.\n\nMultiple templates can be rendered at ones by either providing paths to multiple files or a path to a directory which might contain multiple template files. When a path to a directory is supplied then it will be searched for files with the extensions `.j2` or `.jinja2`. Those will be rendered and put under the destination path while the directory structure is preserved.\n\n### Examples\n\nRender a single template file using only the environment variables (`examples/1`):\n```bash\nNOUN=fool templer -f template.ini.j2 rendered.ini\n```\n\nRender multiple templates with the use of a context file (`examples/2`):\n```bash\ntempler -f -c context.yml templates/ rendered/\n```\n\nA fully featured example that is described in the [Context File section](#context-files) (`examples/3`):\n```bash\nVAR4=ui VAR5=True VAR8=3 VAR11=b VAR12=\"1,2,3\" LARGE=0 templer -d -f -c context.yml template.ini.j2 rendered.ini\n```\n\nAn example that is used in production (`examples/4`):\n```bash\nexport NGINX_TLS_CERT=''\nexport NGINX_TLS_KEY=''\nexport PHPMYADMIN_BLOWFISH_SECRET=\"$(