Skip to main content

Python Templating

When building web applications, one of the most important architectural concepts is the separation of concerns. Python templating engines help you achieve this by separating your presentation logic (how things look) from your business logic (how things work). In this guide, we'll explore Python templating, why it's important, and how to use popular templating engines.

What is Python Templating?​

Python templating is a technique that allows you to generate dynamic HTML content by combining static HTML templates with data from your Python application. A templating engine takes a template file containing special syntax and replaces the variables and expressions with actual values at runtime.

Think of templates as "fill-in-the-blank" documents where your Python code provides the answers.

Benefits of Using Templates​

  • Separation of concerns: Keeps presentation logic separate from business logic
  • Improved maintainability: Designers can work on HTML templates while developers focus on Python code
  • Reusability: Create once, use many times with different data
  • Security: Most templating engines automatically escape content to prevent XSS attacks

Jinja2​

Jinja2 is one of the most widely used templating engines in the Python ecosystem. It's the default templating engine for Flask and can also be used with Django.

Basic Jinja2 Example​

Let's create a simple Jinja2 template and render it:

python
from jinja2 import Template

# Create a template
template_string = """
<html>
<head>
    <title>{{ title }}</title>
</head>
<body>
    <h1>Hello, {{ name }}!</h1>
    
    <h2>Your Skills:</h2>
    <ul>
    {% for skill in skills %}
        <li>{{ skill }}</li>
    {% endfor %}
    </ul>
</body>
</html>
"""

# Create a Template object
template = Template(template_string)

# Render the template with data
rendered_html = template.render(
    title="My Profile",
    name="Alice",
    skills=["Python", "HTML", "CSS"]
)

print(rendered_html)

Output:

html
<html>
<head>
    <title>My Profile</title>
</head>
<body>
    <h1>Hello, Alice!</h1>
    
    <h2>Your Skills:</h2>
    <ul>
    
        <li>Python</li>
    
        <li>HTML</li>
    
        <li>CSS</li>
    
    </ul>
</body>
</html>

Jinja2 Key Features​

  1. Variable Substitution: Using {{ variable_name }}
  2. Control Structures: Like {% if condition %}, {% for item in items %}, etc.
  3. Template Inheritance: Using {% extends "base.html" %} and {% block content %}
  4. Filters: Modify variables using {{ name|capitalize }}
  5. Macros: Reusable template snippets similar to functions

Template Inheritance with Jinja2​

Template inheritance is a powerful feature that helps you avoid code duplication. Let's see it in action:

python
from jinja2 import Environment, FileSystemLoader

# Setup the environment
env = Environment(loader=FileSystemLoader('templates'))

# Create the base template (save as templates/base.html)
"""
<!DOCTYPE html>
<html>
<head>
    <title>{% block title %}Default Title{% endblock %}</title>
    <link rel="stylesheet" href="style.css" />
</head>
<body>
    <header>
        <h1>My Website</h1>
        <nav>
            <a href="/">Home</a>
            <a href="/about">About</a>
        </nav>
    </header>
    
    <main>
        {% block content %}
        {% endblock %}
    </main>
    
    <footer>
        &copy; 2023 My Website
    </footer>
</body>
</html>
"""

# Create a child template (save as templates/home.html)
"""
{% extends "base.html" %}

{% block title %}Home Page{% endblock %}

{% block content %}
    <h2>Welcome to our site!</h2>
    <p>This is the home page content.</p>
    
    <h3>Featured Products:</h3>
    <ul>
    {% for product in products %}
        <li>{{ product.name }} - ${{ product.price }}</li>
    {% endfor %}
    </ul>
{% endblock %}
"""

# Render the template
template = env.get_template('home.html')
rendered_html = template.render(
    products=[
        {"name": "Python Book", "price": 29.99},
        {"name": "Programming Course", "price": 59.99},
        {"name": "Laptop Sticker", "price": 4.99}
    ]
)

print(rendered_html)

The resulting HTML combines the base template with the specific content from the home template.

Mako Templates​

Mako is another popular templating engine known for its speed and flexibility. It's more Python-like than Jinja2.

python
from mako.template import Template

template_string = """
<html>
<head>
    <title>${title}</title>
</head>
<body>
    <h1>Hello, ${name}!</h1>
    
    <h2>Your Skills:</h2>
    <ul>
    % for skill in skills:
        <li>${skill}</li>
    % endfor
    </ul>
    
    ## This is a comment that won't appear in the output
    
    <%
        total_skills = len(skills)
    %>
    
    <p>You have ${total_skills} skills in total.</p>
</body>
</html>
"""

template = Template(template_string)
rendered_html = template.render(
    title="My Profile",
    name="Bob",
    skills=["Python", "JavaScript", "SQL", "Git"]
)

print(rendered_html)

Using Templates in Web Frameworks​

Flask with Jinja2​

Flask comes with Jinja2 integration out of the box:

python
from flask import Flask, render_template

app = Flask(__name__)

@app.route('/')
def home():
    user = {
        "name": "Developer",
        "role": "Python Programmer",
        "years_experience": 3
    }
    
    projects = [
        {"name": "Portfolio Website", "tech": "HTML/CSS/JS"},
        {"name": "Task Manager", "tech": "Python/Flask"},
        {"name": "Data Analysis Tool", "tech": "Python/Pandas"}
    ]
    
    return render_template('profile.html', user=user, projects=projects)

if __name__ == '__main__':
    app.run(debug=True)

The templates/profile.html file might look like:

html
<!DOCTYPE html>
<html>
<head>
    <title>{{ user.name }}'s Profile</title>
</head>
<body>
    <h1>{{ user.name }}</h1>
    <p>Role: {{ user.role }}</p>
    <p>Experience: {{ user.years_experience }} years</p>
    
    <h2>Projects:</h2>
    <ul>
    {% for project in projects %}
        <li>
            <strong>{{ project.name }}</strong> - 
            <em>{{ project.tech }}</em>
        </li>
    {% endfor %}
    </ul>
</body>
</html>

Django Templates​

Django has its own templating engine, which is similar to Jinja2 but with some differences:

python
# views.py
from django.shortcuts import render

def dashboard(request):
    context = {
        'username': 'sarah_dev',
        'tasks': [
            {'id': 1, 'title': 'Finish project', 'priority': 'High'},
            {'id': 2, 'title': 'Write tests', 'priority': 'Medium'},
            {'id': 3, 'title': 'Update documentation', 'priority': 'Low'}
        ]
    }
    return render(request, 'dashboard.html', context)

And templates/dashboard.html:

html
{% extends "base.html" %}

{% block title %}Dashboard{% endblock %}

{% block content %}
    <h1>Welcome back, {{ username }}!</h1>
    
    <h2>Your Tasks:</h2>
    <table>
        <tr>
            <th>ID</th>
            <th>Title</th>
            <th>Priority</th>
            <th>Actions</th>
        </tr>
        {% for task in tasks %}
        <tr>
            <td>{{ task.id }}</td>
            <td>{{ task.title }}</td>
            <td class="priority-{{ task.priority|lower }}">{{ task.priority }}</td>
            <td>
                <a href="{% url 'edit_task' task.id %}">Edit</a>
                <a href="{% url 'delete_task' task.id %}">Delete</a>
            </td>
        </tr>
        {% empty %}
        <tr>
            <td colspan="4">No tasks available.</td>
        </tr>
        {% endfor %}
    </table>
{% endblock %}

Best Practices for Python Templating​

  1. Keep logic in Python, not in templates: Templates should focus on presentation
  2. Use template inheritance: Create a base template with common elements
  3. Cache templates when possible: Rendering can be CPU-intensive
  4. Use context processors for common data: For data needed across many templates
  5. Organize templates in directories: Especially for large applications
  6. Use proper escaping: Be mindful of XSS vulnerabilities

Real-World Example: Email Template System​

Let's create a simple email template system that generates personalized emails:

python
from jinja2 import Environment, FileSystemLoader
import os
import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart

# Setup template environment
template_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "email_templates")
env = Environment(loader=FileSystemLoader(template_dir))

def send_welcome_email(user):
    # Load the template
    template = env.get_template("welcome.html")
    
    # Render the template with user data
    html_content = template.render(
        first_name=user["first_name"],
        username=user["username"],
        subscription_level=user["subscription_level"],
        features=SUBSCRIPTION_FEATURES[user["subscription_level"]]
    )
    
    # Create email message
    msg = MIMEMultipart()
    msg["From"] = "[email protected]"
    msg["To"] = user["email"]
    msg["Subject"] = f"Welcome to Our Platform, {user['first_name']}!"
    
    # Attach HTML content
    msg.attach(MIMEText(html_content, "html"))
    
    # In a real application, you'd send the email here
    # with smtplib.SMTP("smtp.example.com") as server:
    #     server.send_message(msg)
    
    # For demonstration, we'll just print the email content
    print("=" * 50)
    print(f"Email to: {user['email']}")
    print("=" * 50)
    print(html_content)
    print("=" * 50)

# Example data
SUBSCRIPTION_FEATURES = {
    "basic": ["Project access", "Community forums", "Documentation"],
    "premium": ["Project access", "Community forums", "Documentation", "Email support", "API access"],
    "enterprise": ["Project access", "Community forums", "Documentation", "Priority support", "API access", "Custom integration"]
}

# Example users
users = [
    {
        "first_name": "John", 
        "username": "john_doe",
        "email": "[email protected]",
        "subscription_level": "basic"
    },
    {
        "first_name": "Jane",
        "username": "jane_smith",
        "email": "[email protected]",
        "subscription_level": "premium"
    }
]

# Send welcome email to each user
for user in users:
    send_welcome_email(user)

And here's what the email_templates/welcome.html file might contain:

html
<!DOCTYPE html>
<html>
<head>
    <style>
        body { font-family: Arial, sans-serif; line-height: 1.6; }
        .header { background-color: #4285f4; color: white; padding: 20px; }
        .content { padding: 20px; }
        .footer { background-color: #f5f5f5; padding: 10px; font-size: 12px; }
        .features { margin: 20px 0; }
        .feature-item { padding: 5px 0; }
    </style>
</head>
<body>
    <div class="header">
        <h1>Welcome to Our Platform!</h1>
    </div>
    <div class="content">
        <p>Hello {{ first_name }},</p>
        
        <p>Thank you for joining our platform. Your account has been created successfully with the username <strong>{{ username }}</strong>.</p>
        
        <p>You've signed up for our <strong>{{ subscription_level|capitalize }}</strong> plan, which includes:</p>
        
        <div class="features">
            <ul>
            {% for feature in features %}
                <li class="feature-item">{{ feature }}</li>
            {% endfor %}
            </ul>
        </div>
        
        <p>If you have any questions, please don't hesitate to contact our support team.</p>
        
        <p>Best regards,<br>The Team</p>
    </div>
    <div class="footer">
        <p>This email was sent to you as part of your registration process. Please do not reply to this email.</p>
    </div>
</body>
</html>

Summary​

Python templating is a powerful concept that separates presentation from business logic in web applications. We've explored:

  • The fundamentals of templating and why it's important
  • How to use popular templating engines like Jinja2 and Mako
  • Template inheritance and reuse
  • Integration with web frameworks like Flask and Django
  • Best practices for using templates effectively
  • A real-world example of an email template system

By mastering Python templating, you can build more maintainable and scalable web applications, with cleaner code and better separation of concerns.

Additional Resources​

Exercises​

  1. Create a basic portfolio template that displays personal information and a list of projects
  2. Implement template inheritance with a base layout, navigation, and content blocks
  3. Build a product catalog template that shows items with images, descriptions, and prices
  4. Create an email template system with multiple templates (welcome, reset password, newsletter)
  5. Extend the Flask example to include a full blog with list and detail pages using templates

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)