Skip to main content

Prompt Template

A lightweight, zero-dependency Python library for managing LLM prompt templates. Built on the design principles of string.Template but with enhanced features specifically designed for LLM prompt engineering.

Support This Project

If you find prompt-template helpful, please consider sponsoring the development:

Sponsor on GitHub

Your support helps maintain and improve this library for the community! 🚀

Features

  • Strong template validation with detailed error messages
  • Support for nested braces and complex JSON structures
  • Automatic value serialization for common Python types
  • Default value support with deep copying for mutable types
  • Incremental template population with value inheritance
  • Type hints for enhanced IDE support
  • Zero dependencies - just pure Python
  • 100% test coverage

Installation

pip install prompt-template

Usage

The library is intentionally very simple to use. The idea is to keep it simple, have validation and serialization builtin, and make debugging simple.

Simple Templates

from prompt_template import PromptTemplate

# Create a template
template = PromptTemplate("Hello ${name}! Welcome to ${location}.")

# Render with values
result = template.to_string(name="Alice", location="Wonderland")
print(result)  # Hello Alice! Welcome to Wonderland.

Default Values

# Set default values that can be overridden later
template = PromptTemplate("Hello ${name}! Your settings are: ${settings}")

# Set default values - they're safely deep copied
template.set_default(
    name="Guest",
    settings={"theme": "light", "language": "en"}
)

# Use with defaults
print(template.to_string())
# Hello Guest! Your settings are: {"theme": "light", "language": "en"}

# Override specific values
print(template.to_string(name="Alice"))
# Hello Alice! Your settings are: {"theme": "light", "language": "en"}

# Override everything
print(template.to_string(
    name="Bob",
    settings={"theme": "dark", "language": "fr"}
))
# Hello Bob! Your settings are: {"theme": "dark", "language": "fr"}

Named Templates

Adding a name to your template enhances error messages with context. Templates with the same name and content are considered equal:

# Create named templates
template1 = PromptTemplate(
    name="user_greeting",
    template="Hello ${name}! Welcome to ${location}."
)

# Templates can be compared and used as dictionary keys
template2 = PromptTemplate(
    name="user_greeting",
    template="Hello ${name}! Welcome to ${location}."
)
assert template1 == template2

# Templates have a readable string representation
print(template1)  # PromptTemplate [user_greeting]:\n\nHello ${name}! Welcome to ${location}.

Complex JSON Templates

The library handles nested structures elegantly:

template = PromptTemplate("""
{
    "user": {
        "name": "${username}",
        "role": "${role}"
    },
    "settings": {
        "theme": "${theme}",
        "notifications": ${notifications},
        "preferences": ${preferences}
    }
}
""")

# Values are automatically serialized
result = template.to_string(
    username="john_doe",
    role="admin",
    theme="dark",
    notifications={"email": True, "push": False},
    preferences=["daily_digest", "weekly_report"]
)

Template Methods

The library provides two main methods for populating templates:

# to_string(): Validates inputs, uses defaults, and serializes values
template = PromptTemplate("Hello ${name}!")
template.set_default(name="Guest")
result = template.to_string()  # Uses default
result = template.to_string(name="Alice")  # Overrides default

# substitute(): Lower-level method for partial population
base = PromptTemplate("${greeting} ${name}!")
partial = base.substitute(greeting="Hello")  # Returns a new PromptTemplate
final = partial.to_string(name="Alice")

Nested Templates

Templates can be nested within other templates:

# Create nested templates
inner = PromptTemplate("My name is ${name}")
inner.set_default(name="Alice")

outer = PromptTemplate("""
User message:
${message}
""")

# Combine templates
result = outer.to_string(message=inner.to_string())
print(result)
# User message:
# My name is Alice

Type Handling and Automatic Serialization

The library automatically handles various Python types:

from uuid import UUID
from decimal import Decimal
from datetime import datetime

template = PromptTemplate("""
{
    "id": "${id}",
    "amount": "${amount}",
    "metadata": ${metadata}
}
""")

result = template.to_string(
    id=UUID("550e8400-e29b-41d4-a716-446655440000"),
    amount=Decimal("45.67"),
    metadata={
        "timestamp": datetime.now(),
        "values": [1, 2, 3]
    }
)

Custom Serialization

You can override or extend serialization by subclassing PromptTemplate and implementing the serializer method:

from typing import Any
from datetime import datetime
from decimal import Decimal
from prompt_template import PromptTemplate as BasePromptTemplate
import orjson


class PromptTemplate(BasePromptTemplate):
    @staticmethod
    def serializer(value: Any) -> str:
        """Custom serializer with orjson for better performance.
        """
        try:
            return orjson.dumps(value).decode('utf-8')
        except Exception:
            return super().serializer(value)

Error Handling

The library provides specific errors classes for error handling:

Missing Values

from prompt_template import MissingTemplateValuesError

template = PromptTemplate("Hello ${name}!")
try:
    template.to_string()  # No values provided
except MissingTemplateValuesError as e:
    print(f"Missing values: {e.missing_values}")  # {'name'}

Invalid Keys

from prompt_template import InvalidTemplateKeysError

template = PromptTemplate("Hello ${name}!")
try:
    template.to_string(name="World", invalid_key="value")
except InvalidTemplateKeysError as e:
    print(f"Invalid keys: {e.invalid_keys}")  # ['invalid_key']
    print(f"Valid keys: {e.valid_keys}")  # {'name'}

Serialization Errors

from prompt_template import TemplateSerializationError

template = PromptTemplate("Value: ${value}")
try:
    template.to_string(value=object())  # Non-serializable object
except TemplateSerializationError as e:
    print(f"Failed to serialize key '{e.key}': {e.original_error}")

License

MIT License

Metadata

Release files for prompt-template 1.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for prompt-template 1.2.1
File Size Uploaded Provenance Actions
prompt_template-1.2.1.tar.gz 66.3 kB With provenance Details for prompt_template-1.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for prompt-template 1.2.1
File Interpreter ABI Platform Actions
prompt_template-1.2.1-py3-none-any.whl Python 3 none any Details for prompt_template-1.2.1-py3-none-any.whl

Total release size: 75.1 kB

Release files / prompt_template-1.2.1.tar.gz

Download URL prompt_template-1.2.1.tar.gz
Size 66.3 kB
Tags Source
SHA-256 checksum
How to use checksums
c642f3c2d4f0c71e60c994c81a43b1abc256f276f062ebc89814837eecc4d191
BLAKE2b-256 checksum
How to use checksums
790372553d9062a28ca473dd193e8ee11a4cf1c702cfaa6be847d2b15c91dac4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / prompt_template-1.2.1-py3-none-any.whl

Download URL prompt_template-1.2.1-py3-none-any.whl
Size 8.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e69c55520899c3ec332753aabda46ee70b52618fe5ab202df32f1087926170cb
BLAKE2b-256 checksum
How to use checksums
0da5fe323912188fc02f002ffd41402e87b0210ccd0afef077cf4f044f1fe38a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for prompt-template 1.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for prompt_template-1.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page