Alongside format() and f-Strings, the Python Template class offers a safe and readable approach for dynamic string substitution, making it ideal when working with external or user-provided data.
Overview: Python Template class
The Template class in Python offers a safe and readable way to substitute values into strings using dollar-sign placeholders. It is particularly helpful when working with external data, user input, or templates where safety and simplicity matter more than complex formatting.
For a complete overview of Python string formatting techniques, visit our anchor page.
Syntax, Examples and Use Cases: Python Template class
To understand how the Template class works in practice, let’s first look at its syntax, then explore real examples, and finally see where it is commonly used.
Syntax: Template class
Here’s the basic structure of how placeholders and substitution work using the Template class.
from string import Template
t = Template("Hello, $name!")
t.substitute(name="Alice") # or t.safe_substitute(name="Alice")
Explanation
$variable– Placeholder that will be replaced with a valuesubstitute()– Replaces all placeholders; raisesKeyErrorif a value is missingsafe_substitute()– Replaces placeholders if values are provided; leaves missing ones unchanged without error${variable}– Use braces to clarify variable boundaries when concatenated with text
Examples: Template Class
Now let’s look at some practical examples to see how different features of the Template class behave in real situations.
Example 1: Basic Substitution
from string import Template
t = Template("Welcome, $user!")
print(t.substitute(user="Bob"))
# Output: Welcome, Bob!
Explanation: The substitute() method replaces $user with the value “Bob”.
Why this matters: This is the simplest use of the Template class and helps you understand how placeholders are replaced with actual values.
Example 2: Dictionary-Based Substitution
from string import Template
data = {"item": "Laptop", "price": 1200}
t = Template("The $item costs $$${price}.")
print(t.substitute(data))
# Output: The Laptop costs $1200.
Explanation: Multiple placeholders are replaced from the dictionary. $$ prints a literal dollar sign, ${price} ensures correct substitution.
Why this matters: In most real projects, your data will come from dictionaries, APIs, or JSON files — so this pattern becomes very useful.
Example 3: Using safe_substitute() to Handle Missing Values
from string import Template
t = Template("Hello $name, welcome to $city")
print(t.safe_substitute(name="Sam"))
# Output: Hello Sam, welcome to $city
Explanation: Missing placeholders (here $city) remain unchanged instead of raising an error.
Why this matters: Without this, your program may crash when data is missing, which is very common when working with user input or external sources.
Example 4: Using Braces to Avoid Ambiguity
from string import Template
t = Template("Amount: $amount${unit}")
print(t.substitute(amount=75, unit="kg"))
# Output: Amount: 75kg
Explanation: Braces ${unit} clearly define variable boundaries when followed by text.
Why this matters: This avoids confusion in complex strings and ensures your placeholders are interpreted correctly, especially when variables are combined with text.
Example 5: Handling Errors with substitute() vs safe_substitute()
from string import Template
t = Template("Hello $name, your ID is $id.")
# t.substitute(name="Neha") # Raises KeyError!
print(t.safe_substitute(name="Neha"))
# Output: Hello Neha, your ID is $id.
Explanation: safe_substitute() avoids runtime errors when some placeholders are missing, making it suitable for partial or optional data.
Why this matters: Understanding the difference helps you choose between strict error handling and flexible substitution depending on your use case.
Use Cases: Template Class
Once you understand how substitution works, it becomes easier to see where the Template class fits best in real-world applications.
- Email and document templates: Generating dynamic content like notifications, invoices, or reports
- User input handling: Safely inserting external or user-provided data without breaking the program
- Configuration and JSON-based data: Creating dynamic messages or outputs from structured data sources
- Partial or optional data scenarios: Handling missing values gracefully using
safe_substitute() - Readable template-based systems: When you need simple, maintainable string templates instead of complex formatting logic
Learn more about Python string formatting using format() and f-strings.