# template-specialize
[](https://pypi.org/project/template-specialize/)
[](https://pypi.org/project/template-specialize/)
[](https://github.com/craigahobbs/template-specialize/blob/main/LICENSE)
[](https://pypi.org/project/template-specialize/)
**template-specialize** is a command-line tool for rendering
[Jinja2](https://jinja.palletsprojects.com/en/3.0.x/templates/)
templates.
## Render a Template File
For example, consider this Markdown name tag template, "nametag.md":
~~~ jinja2
## Hello, my name is
# {{name}}
{% if title is defined %}
### {{title}}
{% endif %}
~~~
To render the template, execute template-specialize as follows:
~~~
$ template-specialize nametag.md nametag-roy.md -k name 'Roy Hobbs' -k title 'The best there ever was'
~~~
Afterward, the output file contains the rendered template:
~~~
## Hello, my name is
# Roy Hobbs
### The best there ever was
~~~
## Render a Directory Template
You can also render directories of templates to an output directory:
~~~
$ template-specialize template/ output/ -k name value
~~~
## Built-In Template Variables
The following template variables are always defined:
- `now` - the current datetime object
## Environment Files
template-specialize was originally created to "specialize" web service configuration files for different runtime
environments. Environment files are JSON files that allow for the definition of inheritable, structured template
configuration values. Consider the following environments file:
~~~ javascript
{
"base": {
"values": {
"service_name": "my-service"
}
},
"test_base": {
"parents": ["base"],
"values": {
"db_host": "test-db-host"
}
},
// The test environment
"test": {
"parents": ["test_base"],
"values": {
"db_name": "test-db"
}
},
// The live/production environment
"live": {
"parents": ["base"],
"values": {
"db_host": "live-db-host",
"db_name": "live-db"
}
}
}
~~~
To render a template file using an environment, specify the environment file (or files) and the environment name with
which to render the template:
~~~
$ template-specialize config-template.json config.json -c environments.json -e test
~~~
To view the template configuration data use the "--dump" argument:
~~~
$ template-specialize config-template.json config.json -c environments.json -e test --dump
{
"db_host": "test-db-host",
"db_name": "test-db",
"service_name": "my-service"
}
~~~
## Renaming and Deleting Output Files
When specializing a template directory, it is sometimes necessary to rename an output file or directory. For example,
consider a Python project template with the following structure:
~~~
.
|-- README.md
|-- package-name.txt
|-- pyproject.toml
|-- setup.cfg
`-- src
|-- __init__.py
|-- package_name
| |-- __init__.py
| `-- package_name.py
`-- tests
|-- __init__.py
`-- test_package_name.py
~~~
As part of the specialization, we'd like to rename the "package_name" directory, the "package_name.py" file, and the
"test_package_name.py" file to the specialized package name. To accomplish this, we add the "package-name.txt' utility
file and call the "template_specialize_rename" Jinja2 extension:
~~~ jinja2
{# Rename template files #}
{% template_specialize_rename 'src/tests/test_package_name.py', 'test_' + package_name + '.py' %}
{% template_specialize_rename 'src/package_name/package_name.py', package_name + '.py' %}
{% template_specialize_rename 'src/package_name', package_name %}
{# Delete the package-name.txt utility template file #}
{% template_specialize_rename 'package-name.txt' %}
~~~
First, the "template_specialize_rename" extension is used to rename the package output files and directories. Finally,
since we don't want the empty utility file in the output, we delete it using the "template_specialize_rename" extension
with no second argument. Here's an example usage of our Python project template:
~~~
$ template-specialize python-package my-package -k package_name my_package
~~~
This command produces the following specialized template output with appropriately named package source directory and
source files:
~~~
.
|-- README.md
|-- pyproject.toml
|-- setup.cfg
`-- src
|-- __init__.py
|-- my_package
| |-- __init__.py
| `-- my_package.py
`-- tests
|-- __init__.py
`-- test_my_package.py
~~~
## AWS Parameter Store
template-specialize can retrieve template values from
[AWS Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)
using
[botocore](https://pypi.org/project/botocore/).
Here's an example of a JSON configuration file with a Parameter Store secret:
~~~ jinja2
{
"my_secret": {% filter tojson %}{% aws_parameter_store 'parameter-name' %}{% endfilter %}
}
~~~
botocore is usually configured using
[environment variables](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-environment-variables).
## Usage
~~~
usage: template-specialize [-h] [-c FILE] [-e ENV] [-k KEY VALUE] [--dump]
SRC DST
positional arguments:
SRC the source template file or directory
DST the destination file or directory
options:
-h, --help show this help message and exit
-c FILE the environment files
-e ENV the environment name
-k KEY VALUE, --key KEY VALUE
add a template key and value
--dump dump the template variables
~~~
## Development
This package is developed using [python-build](https://github.com/craigahobbs/python-build#readme).
It was started using [python-template](https://github.com/craigahobbs/python-template#readme) as follows:
~~~
template-specialize python-template/template/ template-specialize/ -k package template-specialize -k name 'Craig A. Hobbs' -k email 'craigahobbs@gmail.com' -k github 'craigahobbs' -k noapi 1
~~~
Raw data
{
"_id": null,
"home_page": "https://github.com/craigahobbs/template-specialize",
"name": "template-specialize",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "jinja2, template, render, specialize",
"author": "Craig A. Hobbs",
"author_email": "craigahobbs@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/66/e7/dc634eac8cca5be8721f6c86637d6f48fe30b109386f3f3b89edec158450/template_specialize-1.5.1.tar.gz",
"platform": null,
"description": "# template-specialize\n\n[](https://pypi.org/project/template-specialize/)\n[](https://pypi.org/project/template-specialize/)\n[](https://github.com/craigahobbs/template-specialize/blob/main/LICENSE)\n[](https://pypi.org/project/template-specialize/)\n\n**template-specialize** is a command-line tool for rendering\n[Jinja2](https://jinja.palletsprojects.com/en/3.0.x/templates/)\ntemplates.\n\n\n## Render a Template File\n\nFor example, consider this Markdown name tag template, \"nametag.md\":\n\n~~~ jinja2\n## Hello, my name is\n\n# {{name}}\n{% if title is defined %}\n### {{title}}\n{% endif %}\n~~~\n\nTo render the template, execute template-specialize as follows:\n\n~~~\n$ template-specialize nametag.md nametag-roy.md -k name 'Roy Hobbs' -k title 'The best there ever was'\n~~~\n\nAfterward, the output file contains the rendered template:\n\n~~~\n## Hello, my name is\n\n# Roy Hobbs\n\n### The best there ever was\n~~~\n\n\n## Render a Directory Template\n\nYou can also render directories of templates to an output directory:\n\n~~~\n$ template-specialize template/ output/ -k name value\n~~~\n\n\n## Built-In Template Variables\n\nThe following template variables are always defined:\n\n- `now` - the current datetime object\n\n\n## Environment Files\n\ntemplate-specialize was originally created to \"specialize\" web service configuration files for different runtime\nenvironments. Environment files are JSON files that allow for the definition of inheritable, structured template\nconfiguration values. Consider the following environments file:\n\n~~~ javascript\n{\n \"base\": {\n \"values\": {\n \"service_name\": \"my-service\"\n }\n },\n \"test_base\": {\n \"parents\": [\"base\"],\n \"values\": {\n \"db_host\": \"test-db-host\"\n }\n },\n\n // The test environment\n \"test\": {\n \"parents\": [\"test_base\"],\n \"values\": {\n \"db_name\": \"test-db\"\n }\n },\n\n // The live/production environment\n \"live\": {\n \"parents\": [\"base\"],\n \"values\": {\n \"db_host\": \"live-db-host\",\n \"db_name\": \"live-db\"\n }\n }\n}\n~~~\n\nTo render a template file using an environment, specify the environment file (or files) and the environment name with\nwhich to render the template:\n\n~~~\n$ template-specialize config-template.json config.json -c environments.json -e test\n~~~\n\nTo view the template configuration data use the \"--dump\" argument:\n\n~~~\n$ template-specialize config-template.json config.json -c environments.json -e test --dump\n{\n \"db_host\": \"test-db-host\",\n \"db_name\": \"test-db\",\n \"service_name\": \"my-service\"\n}\n~~~\n\n\n## Renaming and Deleting Output Files\n\nWhen specializing a template directory, it is sometimes necessary to rename an output file or directory. For example,\nconsider a Python project template with the following structure:\n\n~~~\n.\n|-- README.md\n|-- package-name.txt\n|-- pyproject.toml\n|-- setup.cfg\n`-- src\n |-- __init__.py\n |-- package_name\n | |-- __init__.py\n | `-- package_name.py\n `-- tests\n |-- __init__.py\n `-- test_package_name.py\n~~~\n\nAs part of the specialization, we'd like to rename the \"package_name\" directory, the \"package_name.py\" file, and the\n\"test_package_name.py\" file to the specialized package name. To accomplish this, we add the \"package-name.txt' utility\nfile and call the \"template_specialize_rename\" Jinja2 extension:\n\n~~~ jinja2\n{# Rename template files #}\n{% template_specialize_rename 'src/tests/test_package_name.py', 'test_' + package_name + '.py' %}\n{% template_specialize_rename 'src/package_name/package_name.py', package_name + '.py' %}\n{% template_specialize_rename 'src/package_name', package_name %}\n\n{# Delete the package-name.txt utility template file #}\n{% template_specialize_rename 'package-name.txt' %}\n~~~\n\nFirst, the \"template_specialize_rename\" extension is used to rename the package output files and directories. Finally,\nsince we don't want the empty utility file in the output, we delete it using the \"template_specialize_rename\" extension\nwith no second argument. Here's an example usage of our Python project template:\n\n~~~\n$ template-specialize python-package my-package -k package_name my_package\n~~~\n\nThis command produces the following specialized template output with appropriately named package source directory and\nsource files:\n\n~~~\n.\n|-- README.md\n|-- pyproject.toml\n|-- setup.cfg\n`-- src\n |-- __init__.py\n |-- my_package\n | |-- __init__.py\n | `-- my_package.py\n `-- tests\n |-- __init__.py\n `-- test_my_package.py\n~~~\n\n\n## AWS Parameter Store\n\ntemplate-specialize can retrieve template values from\n[AWS Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)\nusing\n[botocore](https://pypi.org/project/botocore/).\n\nHere's an example of a JSON configuration file with a Parameter Store secret:\n\n~~~ jinja2\n{\n \"my_secret\": {% filter tojson %}{% aws_parameter_store 'parameter-name' %}{% endfilter %}\n}\n~~~\n\nbotocore is usually configured using\n[environment variables](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html#using-environment-variables).\n\n\n## Usage\n\n~~~\nusage: template-specialize [-h] [-c FILE] [-e ENV] [-k KEY VALUE] [--dump]\n SRC DST\n\npositional arguments:\n SRC the source template file or directory\n DST the destination file or directory\n\noptions:\n -h, --help show this help message and exit\n -c FILE the environment files\n -e ENV the environment name\n -k KEY VALUE, --key KEY VALUE\n add a template key and value\n --dump dump the template variables\n~~~\n\n\n## Development\n\nThis package is developed using [python-build](https://github.com/craigahobbs/python-build#readme).\nIt was started using [python-template](https://github.com/craigahobbs/python-template#readme) as follows:\n\n~~~\ntemplate-specialize python-template/template/ template-specialize/ -k package template-specialize -k name 'Craig A. Hobbs' -k email 'craigahobbs@gmail.com' -k github 'craigahobbs' -k noapi 1\n~~~\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Command-line tool for rendering Jinja2 templates",
"version": "1.5.1",
"project_urls": {
"Homepage": "https://github.com/craigahobbs/template-specialize"
},
"split_keywords": [
"jinja2",
" template",
" render",
" specialize"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b35e19cb05f9540ff03749577e075bd353ff62c051bd0cdae3d5401b9b6bc3f0",
"md5": "c9be2b63e1243357a83ff0c4ada7c68b",
"sha256": "ba8979cce9f14e097df38b4436adb3c982b0b2b45ec481cfdfa700340cce7e09"
},
"downloads": -1,
"filename": "template_specialize-1.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9be2b63e1243357a83ff0c4ada7c68b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9073,
"upload_time": "2024-10-02T17:04:54",
"upload_time_iso_8601": "2024-10-02T17:04:54.495616Z",
"url": "https://files.pythonhosted.org/packages/b3/5e/19cb05f9540ff03749577e075bd353ff62c051bd0cdae3d5401b9b6bc3f0/template_specialize-1.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "66e7dc634eac8cca5be8721f6c86637d6f48fe30b109386f3f3b89edec158450",
"md5": "0ef79c924c05e0f982ff8ff15e5be30d",
"sha256": "4d5d1fafd72f8bc248fce5f9584f6c1073ae24b4b303b9acbc26b3eb48fc9ac8"
},
"downloads": -1,
"filename": "template_specialize-1.5.1.tar.gz",
"has_sig": false,
"md5_digest": "0ef79c924c05e0f982ff8ff15e5be30d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9684,
"upload_time": "2024-10-02T17:04:55",
"upload_time_iso_8601": "2024-10-02T17:04:55.482419Z",
"url": "https://files.pythonhosted.org/packages/66/e7/dc634eac8cca5be8721f6c86637d6f48fe30b109386f3f3b89edec158450/template_specialize-1.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-02 17:04:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "craigahobbs",
"github_project": "template-specialize",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "template-specialize"
}
JSON
