Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

- Add ``get_jinja2_environment`` directive.

- Add all configurator directives to documentation.
  • Loading branch information...
commit d0cd14b3088ec230b00b0e943b0068c2239d6586 1 parent f371c94
Chris McDonough mcdonc authored
7 CHANGES.txt
View
@@ -1,3 +1,10 @@
+Next release
+============
+
+- Add ``get_jinja2_environment`` directive.
+
+- Add all configurator directives to documentation.
+
1.0 (2011-05-12)
================
6 docs/api.rst
View
@@ -7,5 +7,11 @@
.. autofunction:: includeme
+.. autofunction:: add_jinja2_search_path
+
+.. autofunction:: add_jinja2_extension
+
+.. autofunction:: get_jinja2_environment
+
.. autoclass:: Jinja2TemplateRenderer
.. autoclass:: SmartAssetSpecLoader
2  docs/conf.py
View
@@ -125,7 +125,7 @@
# here, relative to this directory. They are copied after the builtin
# static files, so a file named "default.css" will overwrite the builtin
# "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
15 docs/glossary.rst
View
@@ -18,10 +18,17 @@ Glossary
<http://docs.pylonsproject.org/projects/pyramid/1.0/api/config.html#pyramid.config.Configurator>`_
pyramid_jinja2
- A set of bindings that make templates written for the
- :term:`Jinja2` templating system work under the :term:`Pyramid` web framework.
+ A set of bindings that make templates written for the :term:`Jinja2`
+ templating system work under the :term:`Pyramid` web framework.
Template Inheritance
- Allows you to build a base “skeleton” template that contains all the common
- elements of your site and defines blocks that child templates can override.
+ Allows you to build a base “skeleton” template that contains all the
+ common elements of your site and defines blocks that child templates
+ can override.
http://jinja.pocoo.org/docs/templates/#template-inheritance
+
+ Asset spec
+ A string representing the path to a directory or file present in a
+ Python module. See `Understanding Asset Specifications
+ <http://docs.pylonsproject.org/projects/pyramid/current/narr/assets.html#understanding-asset-specifications>`_
+ in the Pyramid documentation for more information.
12 docs/index.rst
View
@@ -35,8 +35,14 @@ Once activated either of these says, the following happens:
#) Files with the ``.jinja2`` extension are considered to be
:term:`Jinja2` templates.
-#) The ``add_jinja2_search_path`` method/directive is added to
- the :term:`configurator` instance.
+#) The :func:`pyramid_jinja2.add_jinja2_search_path` directive is added to
+ the :term:`configurator` instance.
+
+#) The :func:`pyramid_jinja2.add_jinja2_extension` directive is added to the
+ :term:`configurator` instance.
+
+#) The :func:`pyramid_jinja2.get_jinja2_environment` directive is added to the
+ :term:`configurator` instance.
Usage
=====
@@ -204,7 +210,7 @@ command to create a Jinja2-based Pyramid project::
This is a good way to see a working Pyramid application that uses Jinja2, even
if you wind up not using the result.
-.. code-block:: shell
+.. code-block:: text
:linenos:
# make sure Babel is installed
70 pyramid_jinja2/__init__.py
View
@@ -277,7 +277,20 @@ def __call__(self, value, system):
return self.template.render(system)
-def _add_jinja2_search_path(config, searchpath):
+def add_jinja2_search_path(config, searchpath):
+ """
+ This function is added as a method of a :term:`Configurator`, and
+ should not be called directly. Instead it should be called like so after
+ ``pyramid_jinja2`` has been passed to ``config.include``:
+
+ .. code-block:: python
+
+ config.add_jinja2_search_path('anotherpackage:templates/')
+
+ It will add the directory or :term:`asset spec` passed as ``searchpath``
+ to the current search path of the ``jinja2.environment.Environment`` used
+ by :mod:`pyramid_jinja2`.
+ """
registry = config.registry
env = _get_or_build_default_environment(registry)
if isinstance(searchpath, basestring):
@@ -286,7 +299,19 @@ def _add_jinja2_search_path(config, searchpath):
env.loader.searchpath.append(abspath_from_resource_spec(d))
-def _add_jinja2_extension(config, ext):
+def add_jinja2_extension(config, ext):
+ """
+ This function is added as a method of a :term:`Configurator`, and
+ should not be called directly. Instead it should be called like so after
+ ``pyramid_jinja2`` has been passed to ``config.include``:
+
+ .. code-block:: python
+
+ config.add_jinja2_extension(myext)
+
+ It will add the Jinja2 extension passed as ``ext`` to the current
+ ``jinja2.environment.Environment`` used by :mod:`pyramid_jinja2`.
+ """
registry = config.registry
lst = _get_extensions(config)
@@ -309,10 +334,45 @@ def _get_extensions(config_or_registry):
exts.append('jinja2.ext.i18n')
return exts
+def get_jinja2_environment(config):
+ """
+ This function is added as a method of a :term:`Configurator`, and
+ should not be called directly. Instead it should be called like so after
+ ``pyramid_jinja2`` has been passed to ``config.include``:
+
+ .. code-block:: python
+
+ config.get_jinja2_environment()
+
+ It will return the current ``jinja2.environment.Environment`` used by
+ :mod:`pyramid_jinja2` or ``None`` if no environment has yet been set up.
+ """
+ return config.registry.queryUtility(IJinja2Environment)
def includeme(config):
- '''Setup standard configurator registrations.'''
+ """Set up standard configurator registrations. Use via:
+
+ .. code-block:: python
+
+ config = Configurator()
+ config.include('pyramid_jinja2')
+
+ Once this function has been invoked, the ``.jinja2`` renderer is
+ available for use in Pyramid and these new directives are available as
+ methods of the configurator:
+
+ - ``add_jinja2_search_path``: Add a search path location to the search
+ path.
+
+ - ``add_jinja2_extension``: Add a list of extensions to the Jinja2
+ environment.
+
+ - get_jinja2_environment``: Return the Jinja2 ``environment.Environment``
+ used by ``pyramid_jinja2``.
+
+ """
config.add_renderer('.jinja2', renderer_factory)
- config.add_directive('add_jinja2_search_path', _add_jinja2_search_path)
- config.add_directive('add_jinja2_extension', _add_jinja2_extension)
+ config.add_directive('add_jinja2_search_path', add_jinja2_search_path)
+ config.add_directive('add_jinja2_extension', add_jinja2_extension)
+ config.add_directive('get_jinja2_environment', get_jinja2_environment)
_get_or_build_default_environment(config.registry)
7 pyramid_jinja2/demo/__init__.py
View
@@ -21,10 +21,9 @@ def root_view(request):
def app(global_settings, **settings):
config = Configurator(settings=settings)
config.include('pyramid_jinja2')
- config.add_route(name='root',
- pattern='/',
- view=root_view,
- renderer='helloworld.jinja2')
+ config.add_route(name='root', pattern='/')
+ config.add_view(root_view,
+ renderer='helloworld.jinja2')
config.add_translation_dirs('pyramid_jinja2.demo:locale/')
return config.make_wsgi_app()
14 pyramid_jinja2/tests/test_it.py
View
@@ -243,6 +243,15 @@ def test_it(self):
for x in utility.loader.searchpath],
['foobar', 'grrr'])
+class Test_get_jinja2_environment(unittest.TestCase):
+ def test_it(self):
+ from jinja2.environment import Environment
+ from pyramid_jinja2 import includeme
+ config = testing.setUp()
+ includeme(config)
+ self.assertEqual(config.get_jinja2_environment().__class__,
+ Environment)
+
class TestSmartAssetSpecLoader(unittest.TestCase):
@@ -396,7 +405,8 @@ def stack(self):
class MiscTests(Base, unittest.TestCase):
def test_add_jinja2_extension(self):
- from pyramid_jinja2 import _add_jinja2_extension, _get_or_build_default_environment
+ from pyramid_jinja2 import (add_jinja2_extension,
+ _get_or_build_default_environment)
self.config.include('pyramid_jinja2')
class MockExt(object):
@@ -405,7 +415,7 @@ class MockExt(object):
def __init__(self, x):
self.x = x
- _add_jinja2_extension(self.config, MockExt)
+ add_jinja2_extension(self.config, MockExt)
u = _get_or_build_default_environment(self.config.registry)
self.assertTrue('foobar' in u.extensions)
Please sign in to comment.
Something went wrong with that request. Please try again.