A plugin for Poetry which lets you substitute text on build. This plugin was created to allow you to keep a single source of truth for package wide properties such as version and author.
The easiest way to install the plugin is via the self add command of Poetry.
poetry self add poetry-templating
If you used pipx to install Poetry you can add the plugin via the pipx inject command.
pipx inject poetry poetry-templating
Otherwise, if you used pip to install Poetry you can add the plugin packages via the pip install command.
pip install poetry-templating
Poetry Templating uses 'template slots' as placeholders and definitions for what they should be replaced with. Consider the following file:
__version__ = "${pyproject.tool.poetry.version}"When evaluated, the slot will be replaced with the tool.poetry.version property from pyproject.toml, for example:
__version__ = "1.2.3"Slots can also be used in conjunction with comments to add entire lines only present in the built package. This can be used with # templating: delete to significantly change functionality in the built package, for example:
production = false # templating: delete
# ${"production = true"}
becomes
production = truePoetry Templating will automatically evaluate template slots when building the package distributables with the poetry build command. You can also evaluate the project in-place by running the poetry templating evaluate command.
Poetry Templating features a number of constructs which can be used in template slots.
Denoted by quotes or double quotes, literal constructs simply replace the slot with the text within.
${"Hello World"}
becomes
Hello World
Template slots within literal constructs are also evaluated, allowing for basic string concatenation, for example:
# ${"__version__ = ${pyproject.tool.poetry.version}"}
becomes
__version__ = "1.2.3"Allows you to refernce values from the package's pyproject.toml file.
${pyproject.tool.poetry.version}
${pyproject.tool.poetry.authors.0}
becomes
1.2.3
John Doe <john.doe@example.com
Allows you to reference the buildtime environment variables.
${env.HOME}
becomes
/home/example/
Denoted with a forward slash, or ./ for relative files, the file construct gets the entire content of an arbitrary file.
${/LICENCE}
becomes
MIT License
Permission is hereby granted ...
Poetry Templating can be configured in your pyproject.toml file under the tool.poetry-templating table.
| key | default | description |
|---|---|---|
| encoding | "utf-8" | The text encoding to use when processing files. |
| include | ["*.py"] | A list of glob patterns for files to process. |
| exclude | [] | A list of glob patterns for files not to process, has priority over include. |
Poetry Templating can also be enabled and disabled within a single file:
# templating: off
example = "${'will NOT get evaluated'}"
# templating: on
evaluated = "${'WILL get evaluated'}"
becomes
example = "${'will NOT get evaluated'}"
evaluated = "WILL get evaluated"