Mako Template Bindings for Pyramid

Warnings

• breaking As of Pyramid 1.5, Mako templating support was removed from the Pyramid core. Projects upgrading to Pyramid 1.5 or newer must explicitly install `pyramid_mako` and activate it via `config.include('pyramid_mako')` in their application's `__init__.py` (or similar configuration entry point). Failure to do so will result in `ValueError: No such renderer factory .mako`.
  Fix: Install `pyramid_mako` via `pip install pyramid-mako` and add `config.include('pyramid_mako')` to your Pyramid application's `Configurator` setup.
• deprecated Returning a `('defname', dict)` tuple from a view using a Mako renderer is deprecated and will raise a `ValueError` in `pyramid_mako` 1.0+. This behavior was removed to standardize renderer usage.
  Fix: Instead of returning a tuple, specify the Mako `def` name directly in the renderer argument of your view configuration (e.g., `renderer='mypackage:templates/foo.mak#defname'`) and return only a dictionary from your view callable.
• gotcha Setting `mako.strict_undefined = true` in your Pyramid application settings can cause issues with the `pyramid_debugtoolbar` if its internal Mako templates contain unguarded placeholders that might be undefined in certain contexts.
  Fix: If `pyramid_debugtoolbar` breaks, avoid using `mako.strict_undefined = true` or use it with caution, ensuring all variables in your templates (and any templates you inherit from) are explicitly defined or guarded with `if` statements.
• gotcha As of Pyramid 1.4, spaces are no longer allowed in Mako template paths when rendering. Template paths containing spaces will lead to lookup failures.
  Fix: Ensure all Mako template file paths and directory names used in your Pyramid configuration and renderer specifications do not contain spaces.

Install

• pip install pyramid-mako Install pyramid-mako

Imports

• includeme

  config.include('pyramid_mako')

  Registers the Mako renderer with your Pyramid application's Configurator.
• render

  from pyramid.renderers import render

  Used for direct rendering of a template within a view callable.
• add_mako_renderer

  config.add_mako_renderer('.html', settings_prefix='mako.')

  Configurator directive to register additional Mako renderers for different file extensions or with specific settings.

Quickstart

This quickstart demonstrates how to set up a basic Pyramid application using `pyramid_mako`. It shows how to include `pyramid_mako` in your configuration, define a template directory using `mako.directories`, and render a Mako template from a Pyramid view. Views that use a renderer should return a dictionary, whose keys become top-level variables in the template. The example provides a small, self-contained Pyramid application. Note that for real-world applications, you'd typically use a `development.ini` file and a proper project structure created by a Pyramid cookiecutter.

import os
from wsgiref.simple_server import make_server
from pyramid.config import Configurator
from pyramid.response import Response
from pyramid.view import view_config

# --- myapp/__init__.py ---
@view_config(route_name='home', renderer='templates/home.mako')
def home_view(request):
    name = request.matchdict.get('name', 'World')
    return {'project': 'Pyramid Mako App', 'user_name': name}

def main(global_config, **settings):
    with Configurator(settings=settings) as config:
        config.include('pyramid_mako')

        # Configure mako.directories for template lookup if using relative paths
        # For this example, 'templates' is relative to the current package.
        # If using asset specs like 'mypackage:templates', no mako.directories needed for that specific template.
        config.add_settings({'mako.directories': 'myapp:templates'})

        config.add_route('home', '/howdy/{name}')
        config.add_route('root', '/')
        config.scan('.') # Scan current package for @view_config decorators
    return config.make_wsgi_app()

# To run: Save this as myapp/__init__.py
# Create myapp/templates/home.mako:
# <h1>Hello, ${user_name} from ${project}!</h1>
# From your project root (one level above 'myapp'), run:
# pserve development.ini (assuming development.ini is configured to point to myapp.main)
# Or create a minimal development.ini:
# [app:main]
# use = egg:myapp#main
# 
# [server:main]
# use = egg:waitress#main
# host = 0.0.0.0
# port = 6543
# 
# [loggers]
# keys = root, myapp
# 
# [handlers]
# keys = console
# 
# [formatters]
# keys = generic
# 
# [logger_root]
# level = INFO
# handlers = console
# 
# [logger_myapp]
# level = DEBUG
# handlers = console
# qualname = myapp
# 
# [handler_console]
# class = StreamHandler
# args = (sys.stderr,)
# level = NOTSET
# formatter = generic
# 
# [formatter_generic]
# format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s


if __name__ == '__main__':
    # This block is typically replaced by 'pserve development.ini'
    # For a truly minimal runnable example without an .ini file or folder structure:
    class RootView:
        def __init__(self, request):
            self.request = request

        @view_config(route_name='hello', renderer='string:<h1>Hello, ${user_name}!</h1>')
        def hello(self):
            return {'user_name': 'Anonymous'}

    with Configurator() as config:
        config.include('pyramid_mako')
        config.add_route('hello', '/')
        config.add_view(RootView, attr='hello')
        app = config.make_wsgi_app()

    server = make_server('0.0.0.0', 6543, app)
    print('Serving on http://0.0.0.0:6543')
    server.serve_forever()