{"id":3236,"library":"pyramid-mako","title":"Mako Template Bindings for Pyramid","description":"Pyramid_mako provides a set of bindings that integrate the Mako templating system with the Pyramid web framework. It enables Pyramid applications to render dynamic content using Mako templates, which compile into Python modules for optimal performance. The library is currently at version 1.1.0 and is actively maintained by the Pylons Project, receiving updates to ensure compatibility with newer Python versions and Pyramid releases.","status":"maintenance","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/Pylons/pyramid_mako","tags":["pyramid","mako","templating","web framework","pylons"],"install":[{"cmd":"pip install pyramid-mako","lang":"bash","label":"Install pyramid-mako"}],"dependencies":[{"reason":"Pyramid is the web framework for which these bindings are created.","package":"pyramid"},{"reason":"Mako is the templating engine being integrated; pyramid-mako 1.1.0 requires mako >= 1.1.0.","package":"Mako","optional":false}],"imports":[{"note":"Registers the Mako renderer with your Pyramid application's Configurator.","symbol":"includeme","correct":"config.include('pyramid_mako')"},{"note":"Used for direct rendering of a template within a view callable.","symbol":"render","correct":"from pyramid.renderers import render"},{"note":"Configurator directive to register additional Mako renderers for different file extensions or with specific settings.","symbol":"add_mako_renderer","correct":"config.add_mako_renderer('.html', settings_prefix='mako.')"}],"quickstart":{"code":"import os\nfrom wsgiref.simple_server import make_server\nfrom pyramid.config import Configurator\nfrom pyramid.response import Response\nfrom pyramid.view import view_config\n\n# --- myapp/__init__.py ---\n@view_config(route_name='home', renderer='templates/home.mako')\ndef home_view(request):\n    name = request.matchdict.get('name', 'World')\n    return {'project': 'Pyramid Mako App', 'user_name': name}\n\ndef main(global_config, **settings):\n    with Configurator(settings=settings) as config:\n        config.include('pyramid_mako')\n\n        # Configure mako.directories for template lookup if using relative paths\n        # For this example, 'templates' is relative to the current package.\n        # If using asset specs like 'mypackage:templates', no mako.directories needed for that specific template.\n        config.add_settings({'mako.directories': 'myapp:templates'})\n\n        config.add_route('home', '/howdy/{name}')\n        config.add_route('root', '/')\n        config.scan('.') # Scan current package for @view_config decorators\n    return config.make_wsgi_app()\n\n# To run: Save this as myapp/__init__.py\n# Create myapp/templates/home.mako:\n# <h1>Hello, ${user_name} from ${project}!</h1>\n# From your project root (one level above 'myapp'), run:\n# pserve development.ini (assuming development.ini is configured to point to myapp.main)\n# Or create a minimal development.ini:\n# [app:main]\n# use = egg:myapp#main\n# \n# [server:main]\n# use = egg:waitress#main\n# host = 0.0.0.0\n# port = 6543\n# \n# [loggers]\n# keys = root, myapp\n# \n# [handlers]\n# keys = console\n# \n# [formatters]\n# keys = generic\n# \n# [logger_root]\n# level = INFO\n# handlers = console\n# \n# [logger_myapp]\n# level = DEBUG\n# handlers = console\n# qualname = myapp\n# \n# [handler_console]\n# class = StreamHandler\n# args = (sys.stderr,)\n# level = NOTSET\n# formatter = generic\n# \n# [formatter_generic]\n# format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s\n\n\nif __name__ == '__main__':\n    # This block is typically replaced by 'pserve development.ini'\n    # For a truly minimal runnable example without an .ini file or folder structure:\n    class RootView:\n        def __init__(self, request):\n            self.request = request\n\n        @view_config(route_name='hello', renderer='string:<h1>Hello, ${user_name}!</h1>')\n        def hello(self):\n            return {'user_name': 'Anonymous'}\n\n    with Configurator() as config:\n        config.include('pyramid_mako')\n        config.add_route('hello', '/')\n        config.add_view(RootView, attr='hello')\n        app = config.make_wsgi_app()\n\n    server = make_server('0.0.0.0', 6543, app)\n    print('Serving on http://0.0.0.0:6543')\n    server.serve_forever()","lang":"python","description":"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."},"warnings":[{"fix":"Install `pyramid_mako` via `pip install pyramid-mako` and add `config.include('pyramid_mako')` to your Pyramid application's `Configurator` setup.","message":"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`.","severity":"breaking","affected_versions":"Pyramid >= 1.5"},{"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.","message":"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.","severity":"deprecated","affected_versions":"pyramid-mako >= 1.0, Pyramid >= 1.5"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all Mako template file paths and directory names used in your Pyramid configuration and renderer specifications do not contain spaces.","message":"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.","severity":"gotcha","affected_versions":"Pyramid >= 1.4"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}