Templ8

A powerful, extensible templating engine.

Status

Source	Shields
Project
Health
Publishers
Repository
Activity

Installing

pip install templ8

Usage

Templ8 3.0.0

optional arguments:
  -h, --help             show this help message and exit.
  --output               output directory.
  --settings-file        input file path.
  --dry-run              don't make any changes.
  --silent               don't output any logs.
  --debug                output debug logs.
  --clear-top-level      remove top level files.
  --logical-grouping     flatten render context.
  --skip-core-templates  skip core templates.
  --collection-sources   where to look for collections.
  --collections          collection names.
  --includes             path names to include.
  --excludes             path names to exclude.
  --loader-paths         where to look for Jinja includes.
  --render-context       jinja context variables.

Settings file

You can specify which collections of templates to generate in a yaml file:

.template.yml

output_dir: .

collections:
  - common

render_context:
  name: templ8
  description: A powerful, extensible templating engine.

Output files

The engine will generate a project and Jinja templates will be populated with the given render context variables.

README.md

# Templ8

A powerful, extensible templating engine.

Motivation

It's simple to write custom Jinja templates but to be able to use them across projects we need:

• Render context values that can be set in a config file.
• Default variables for each collection of templates.
• A way to include and exclude paths.
• A Mechanism for renaming folders according to the target project.
• Initialization scripts that we can define for each collection.

Templ8 aims to provide a maintainable templating engine supporting all these necessary features.

Example

/
└── example
    ├── metadata.json
    ├── README.md.j2
    └── src
        └── main.py

We can write a collection's metadata:

metadata.json

{
  "name": "example",
  "default_variables": {
    "version": "0.1.0"
  },
  "renames": [
    {
      "segment": "src",
      "token": "package_name"
    }
  ],
  "initializations": [
    {
      "cmd": "echo Hello World!",
      "cwd": "."
    }
  ]
}

And some templates for the collection:

README.md.j2

# {{ verbose_name | default( name | title_case ) }}

In any place we want to use our collection we can write a settings file:

.template.yml

output: .

collections:
  - example

collections_sources:
  - ... # path to example collection

render_context:
  name: example
  package_name: example_package

Templ8 will generate:

/
└── output
    ├── README.md
    └── example_package
        └── main.py

README.md

# Example

Community maintained collections

/
...
└── core
    ├── common
    ├── packages
    |   ├── cpp
    |   ├── csharp
    |   ├── java
    |   ├── javascript
    |   ├── purescript
    |   ├── python
    |   └── typescript
    ├── microservices
    |   ├── blazor
    |   ├── angular
    |   ├── django
    |   ├── flask
    |   ├── halogen
    |   ├── react
    |   ├── spring
    |   └── vue
    └── deployments
        ├── ansible
        └── terraform

Additional features

• By default we look for a settings file at .template.yml or .templ8.yml.

• Template schemas and rename tokens are parsed ahead of time to check for missing render context before stating a templating run.

• Custom loader_paths for Jinja 'includes' directives can be specified.

• Top level files can be set to be cleared.

• Render context can be sub grouped. The logical_grouping option causes render context to be flattened a level before parsing.

loader_paths: List[str] # Loader paths for Jinja inclusion tags.
collection_source: List[str] # Custom collection source paths.
clear_top_level: bool # Clear top level files.
logical_grouping: bool # Logical input sub-grouping.

Structure

To control the amount of state in play classes are only used to instantiate data containers. Methods are separated out as freely accessible services.

This breaks apart monolithic classes and makes the project easier to test.

Tests

To run unit and e2e tests:

grunt test

Documentation

This repository's documentation is hosted on readthedocs.

Tooling

To run linters:

grunt lint

To run formatters:

grunt format

Continuous integration

This repository uses github actions to lint and test each commit. Formatting tasks and writing/generating documentation must be done before committing new code.

Versioning

This repository adheres to semantic versioning standards. For more information on semantic versioning visit SemVer.

Bump2version is used to version and tag changes. For example:

bump2version patch

Changelog

Please read this repository's CHANGELOG for details on changes that have been made.

Contributing

Please read this repository's guidelines on contributing for details on the process for submitting pull requests. Moreover, our code of conduct declares our collaboration standards.

Contributors

• Joel Lefkowitz - Initial work - Joel Lefkowitz

Remarks

Lots of love to the open source community!