Pyramid Jinja2

Warnings

• breaking Python 2.x and older Python 3.x versions are no longer supported. Version 2.7 dropped Python 2.6 and 3.2, Version 2.8 dropped Python 3.3, and Version 2.9 dropped Python 3.6. The current version requires Python >=3.7.0.
  Fix: Upgrade your Python environment to 3.7 or newer before upgrading `pyramid_jinja2`.
• breaking As of `pyramid_jinja2` 2.3, using `pyramid_jinja2.renderer_factory` now explicitly requires `pyramid_jinja2` to be included in the Configurator (via `config.include('pyramid_jinja2')` or `pyramid.includes` setting). Previously, it could be used without explicit inclusion.
  Fix: Ensure `config.include('pyramid_jinja2')` is present in your application's `__init__.py` or that `pyramid_jinja2` is listed in `pyramid.includes` in your .ini file.
• gotcha The default behavior of `jinja2.bytecode_caching` changed in version 1.10 from `true` to `false`. Additionally, the automatic `atexit` callback for clearing bytecode cache files was removed.
  Fix: If you relied on bytecode caching for performance, explicitly set `jinja2.bytecode_caching = true` in your Pyramid settings. You must also implement a manual cleanup strategy (e.g., a cron job) for stale cache files if using filesystem caching.
• deprecated The `model_url` filter was deprecated in version 2.7 in favor of `resource_url` to align with Pyramid's vocabulary changes.
  Fix: Update your Jinja2 templates to use `resource_url` instead of `model_url` for generating URLs related to resources.
• gotcha For custom Jinja2 filters, Jinja2 >= 3.0 deprecated `@jinja2.contextfilter` in favor of `@jinja2.pass_context`. `pyramid_jinja2` version 2.9.2 and later supports both, but newer Jinja2 versions will warn or break with `contextfilter` usage.
  Fix: If you define custom Jinja2 filters, use `@jinja2.pass_context` instead of `@jinja2.contextfilter` for compatibility with Jinja2 3.0 and newer.

Install

• pip install pyramid-jinja2 Install stable version

Imports

• Configurator.include('pyramid_jinja2')

  from pyramid.config import Configurator
  config = Configurator()
  config.include('pyramid_jinja2')

  Activates the Jinja2 renderer and associated configurator directives.
• add_jinja2_renderer

  config.add_jinja2_renderer('.html', settings_prefix='jinja2.')

  Used to register custom renderers with different file extensions or settings. Available after `config.include('pyramid_jinja2')`.
• add_jinja2_search_path

  config.add_jinja2_search_path('myapp:templates')

  Adds a directory or asset specification to the Jinja2 environment's search path for templates.
• get_jinja2_environment

  env = config.get_jinja2_environment()

  Retrieves the configured Jinja2 Environment object for direct manipulation (e.g., adding globals/filters dynamically). Requires `config.commit()` or deferred action for full configuration to apply.

Quickstart

This quickstart demonstrates a basic Pyramid application using `pyramid_jinja2` to render templates. It sets up two routes with corresponding views, each rendering a different Jinja2 template. The `config.include('pyramid_jinja2')` line is crucial for activating the Jinja2 renderer, and `jinja2.directories` is configured to locate templates.

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

# Assuming a 'templates' directory exists with 'home.jinja2' in the same package
# e.g., myapp/templates/home.jinja2

@view_config(route_name='home', renderer='home.jinja2')
def home_view(request):
    return {'project': 'pyramid_jinja2 example', 'name': request.matchdict.get('name', 'World')}

@view_config(route_name='hello', renderer='templates/hello.jinja2')
def hello_view(request):
    return {'name': request.matchdict.get('name', 'Guest')}

if __name__ == '__main__':
    with Configurator() as config:
        config.include('pyramid_jinja2')
        config.add_settings({'jinja2.directories': 'myapp:templates'}) # Or pass to Configurator(settings=...)
        config.add_route('home', '/')
        config.add_route('hello', '/hello/{name}')
        config.scan('.') # Scans for @view_config decorators
        app = config.make_wsgi_app()

    server = make_server('0.0.0.0', 6543, app)
    print('Serving Pyramid Jinja2 app on http://0.0.0.0:6543')
    print("Try: http://localhost:6543/ and http://localhost:6543/hello/Alice")
    server.serve_forever()

# Example template (myapp/templates/home.jinja2):
# <h1>Welcome to {{ project }}!</h1>
# <p>Hello, {{ name }}!</p>

# Example template (myapp/templates/hello.jinja2):
# <h1>Greetings!</h1>
# <p>Hello, {{ name }} from a different template!</p>