Metadata-Version: 2.1
Name: simple_template
Version: 0.3
Summary: Simple placeholder filling template library.
Author: James Frost
License: BSD0
Project-URL: Source, https://github.com/Fraetor/simple_template
Classifier: License :: OSI Approved :: Zero-Clause BSD (0BSD)
Classifier: Topic :: Text Processing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENCE

# simple_template

A templating library for simple placeholder filling. Useful when the full might
of [Jinja](https://palletsprojects.com/p/jinja/) and friends is unnecessary.

## Installation

<!-- TODO: Fill in URLs. -->

simple_template can be installed from [PyPI]() or [conda-forge]().

```sh
# Install from PyPI.
pip install simple_template
# Install from conda-forge
conda install -c conda-forge simple_template
```

## Usage

The module contains two functions, and one Exception.

### `simple_template.render(template: str, /, **variables) -> str`

Render the template with the provided variables.

The template should contain placeholders that will be replaced. These
placeholders consist of the placeholder name within double curly braces. The
name of the placeholder should be a valid python identifier. Whitespace
between the braces and the name is ignored. E.g.: `{{ placeholder_name }}`

An exception will be raised if there are placeholders without corresponding
values. It is acceptable to provide unused values; they will be ignored.

#### Parameters

template: str\
Template to fill with variables.

**variables: Any\
Keyword arguments for the placeholder values. The argument name should be the
same as the placeholder's name. You can unpack a dictionary of value with
`render(template, **my_dict)`.

#### Returns

rendered_template: str\
Filled template.

#### Raises

TemplateError\
Value not given for a placeholder in the template.

TypeError\
If the template is not a string, or a variable cannot be casted to a string.

#### Examples

```py
>>> template = "<p>Hello {{myplaceholder}}!</p>"
>>> simple_template.render(template, myplaceholder="World")
"<p>Hello World!</p>"
```

### `simple_template.render_file(template_path: str, /, **variables) -> str`

Render a template directly from a file.

Otherwise the same as `simple_template.render()`.

#### Examples

```py
>>> simple_template.render_file("/path/to/template.html", myplaceholder="World")
"<p>Hello World!</p>"
```

### `simple_template.TemplateError()`

Rendering a template failed due a placeholder without a value.


## Licence

simple_template is licenced under the BSD0 licence, so you can do whatever you
like with it. See the full licence text in the [LICENCE](LICENCE) file.
