Metadata-Version: 2.4
Name: hokora
Version: 0.1.0
Summary: A stand-alone renderer for Jinja2 templates
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://gitlab.com/drmoose/hokora
Project-URL: Issues, https://gitlab.com/drmoose/hokora/-/issues
Project-URL: Repository, https://gitlab.com/drmoose/hokora.git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: jinja2
Provides-Extra: check
Requires-Dist: ruff; extra == "check"
Requires-Dist: mypy; extra == "check"
Provides-Extra: toml
Requires-Dist: toml; extra == "toml"
Provides-Extra: yaml
Requires-Dist: PyYAML; extra == "yaml"
Provides-Extra: all
Requires-Dist: hokora[toml,yaml]; extra == "all"
Dynamic: license-file

<!-- vim: set ft=mdjinja et tw=80 cc : -->


# `hokora` is a [Jinja2][jinja-main] standalone template parser

You might be familiar with [Jinja2 templates][jinja-wikipedia] if you've worked
with [Flask][flask], [Ansible][ansible], [Salt][salt] or [dbt][dbt]. `hokora`
is a tool for rendering Jinja templates on the command line, or as part of a
bash pipeline.

`README.md` in this repository is itself generated by hokora, from the
README.md.in.

# Usage
```
usage: hokora [-h] [--context CONTEXT] [--environ] [-C C] [--no-include-env]
              [--no-include-cwd] [--no-include-template-dir]
              [--include INCLUDE] [--autoescape | --no-autoescape]
              [--strip-shebang | --no-strip-shebang]
              [template]

Hokora: Standalone Jinja2 template renderer

positional arguments:
  template              path to template to render

options:
  -h, --help            show this help message and exit
  --autoescape, --no-autoescape
                        whether to escape HTML entities in jinja expressions
  --strip-shebang, --no-strip-shebang
                        remove the first line of the output if it is a bash
                        shebang

Jinja Context Variables:
  --context, -c CONTEXT
                        Read the given file for context values to supply as
                        jinja variables. Use key=filename if you want to
                        namespace the data, like {{key.somevar}}. See
                        AVAILABLE CONTEXT FORMATS below for supported file
                        extensions.
  --environ, -e         Make environment variables available as jinja
                        variables

Template search paths:
  -C C                  Change directories to this folder and interpret all
                        paths as relative to it.
  --no-include-env      Don't parse $JINJA_TEMPLATE_DIRS for include folders
  --no-include-cwd      Don't include the current working directory in the
                        search path
  --no-include-template-dir
                        Don't include the template's folder in the search
                        path.
  --include, -I INCLUDE
                        Add this folder to the template include path


ENVIRONMENT VARIABLES

  $JINJA_TEMPLATE_DIRS
    A :-separated list of additional template include paths, which
    will be searched to handle {%extends %}, {%include %} and {%import %}
    tags unless --no-include-env is passed at the command line.

  $HOKORA_MODULES
    Additional python modules (honoring $PYTHONPATH) to import at load time.
    These can be used to extend the functionality of hokora if they contain
    subclasses of DataFormat or HokoraFeature.


AVAILABLE CONTEXT FORMATS

  json                {{ ... | json }}                                *.json
  python              {{ ... | python }}            *.py, *.pyc, *.pyd, *.so
  pickle              {{ ... | pickle }}                     *.pkl, *.pickle
  toml                {{ ... | toml }}                                *.toml
  yaml                {{ ... | yaml }}                         *.yaml, *.yml

```

# Installation

`hokora` requires Python 3.10 or better.

## Standalone script via [`uv`][uv]

If you're on a Unix-like operating system, the [`./hokora`](./hokora) script
in the root of this repo can just be copied into `~/.local/bin` or some
appropriate place on your `$PATH`. `uv` will reach out to gitlab and grab the
latest version the first time you run it.

## Local install via [`pipx`][pipx]

```bash
pipx install git+https://gitlab.com/drmoose/hokora
```

## Local install via [`pip`][pip]

`pip` versions below 24.0.0, which, sadly, includes [the one on ubuntu
22.04 Jammy][jammy-pip] (although this is fixed on 24.04 Noble and beyond),
cannot install a `pyproject.toml`-based project correctly from gitlab. It'll
get installed [under the name UNKNOWN instead][old-pip-unknown]. To work
around this, upgrade pip before attempting to install.

```bash
python3 -m pip install --upgrade pip
python3 -m pip install git+https://gitlab.com/drmoose/hokora
```


# Metadata

## License

hokora is licensed under a [BSD 3-Clause License](./COPYING), like Jinja itself.

hokora's icon is licensed under [creative commons attribution share-alike 4.0
international][ccbysa4] with a hat tip to wikimedia user Immanuelle who made
the [original][icon-upstream].


## Name

Jinja itself [says][jinja-faq-name] it's named for a [Shinto
shrine][shrine-wikipedia] because the word "template" sounds vaguely like the
word "temple." Well, two can play the Wikipedia game. A
[_Hokora_][hokora-wikipedia] is a miniature Shinto shrine, and `hokora` is a
miniature wrapper around Jinja.


## Contributing

Issues and MRs are welcome.

- The `main` branch is kept stable. Tinker in topic branches.
- Don't edit `README.md` directly; edit `README.md.in`.
- Update version numbers as necessary. Follow [semver][semver]
- Make sure your code is sane:

  ```bash
  ruff format
  ruff check
  mypy --check-untyped-defs .
  ```


<!-- `links -->

[jinja-main]: https://jinja.palletsprojects.com
[jinja-example]: https://jinja.palletsprojects.com/en/stable/templates/#synopsis
[jinja-wikipedia]: https://en.wikipedia.org/wiki/Jinja_(template_engine)
[jinja-faq-name]: https://jinja.palletsprojects.com/en/stable/faq/#why-is-it-called-jinja
[flask]: https://flask.palletsprojects.com/en/stable/tutorial/templates/
[ansible]: https://docs.ansible.com/ansible/latest/user_guide/playbooks_templating.html
[salt]: https://docs.saltproject.io/en/latest/topics/jinja/index.html
[dbt]: https://docs.getdbt.com/docs/build/jinja-macros
[ccbysa4]: https://creativecommons.org/licenses/by-sa/4.0/deed.en
[icon-upstream]: https://commons.wikimedia.org/wiki/File:%E7%A5%A0svg.svg
[shrine-wikipedia]: https://en.wikipedia.org/wiki/Shinto_shrine
[hokora-wikipedia]: https://en.wikipedia.org/wiki/Hokora
[jammy-pip]: https://packages.ubuntu.com/jammy/python3-pip
[uv]: https://docs.astral.sh/uv/getting-started/installation/
[pipx]: https://pipx.pypa.io/latest/installation/
[pip]: https://pypi.org/project/pip/
[old-pip-unknown]: https://stackoverflow.com/q/78034052
[semver]: https://semver.org/
