Skip to content
Snippets Groups Projects
Commit d0f60720 authored by Mike Bayer's avatar Mike Bayer
Browse files

docstrings

parent 5d4575af
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/build/usage.rst
+ 3
− 0
View file @ d0f60720
......@@ -418,6 +418,9 @@ API Documentation
.. autoclass:: mako.template.Template
:members:
.. autoclass:: mako.lookup.TemplateCollection
:members:
.. autoclass:: mako.lookup.TemplateLookup
:members:
......
mako/lookup.py
+ 105
− 1
View file @ d0f60720
......@@ -15,7 +15,28 @@ except:
import dummy_threading as threading
class TemplateCollection(object):
"""Represent a collection of :class:`.Template` objects,
identifiable via uri.
A :class:`.TemplateCollection` is linked to the usage of
all template tags that address other templates, such
as ``<%include>``, ``<%namespace>``, and ``<%inherit>``.
The ``file`` attribute of each of those tags refers
to a string URI that is passed to that :class:`.Template`
object's :class:`.TemplateCollection` for resolution.
:class:`.TemplateCollection` is an abstract class,
with the usual default implementation being :class:`.TemplateLookup`.
"""
def has_template(self, uri):
"""Return ``True`` if this :class:`.TemplateLookup` is capable of
returning a :class:`.Template` object for the given URL.
:param uri: String uri of the template to be resolved.
"""
try:
self.get_template(uri)
return True
......@@ -23,6 +44,18 @@ class TemplateCollection(object):
return False
def get_template(self, uri, relativeto=None):
"""Return a :class:`.Template` object corresponding to the given
URL.
The default implementation raises :class:`.NotImplementedError`.
Implementations should raise :class:`.TemplateLookupException` if
the given uri cannot be resolved.
:param uri: String uri of the template to be resolved.
:param relativeto: if present, the given URI is assumed to be relative
to this uri.
"""
raise NotImplementedError()
def filename_to_uri(self, uri, filename):
......@@ -44,6 +77,59 @@ class TemplateCollection(object):
return uri
class TemplateLookup(TemplateCollection):
"""Represent a collection of templates that locates template source files
from the local filesystem.
The primary argument is the ``directories`` argument, the list of
directories to search::
lookup = TemplateLookup(["/path/to/templates"])
some_template = lookup.get_template("/index.html")
The :class:`.TemplateLookup` can also be given :class:`.Template` objects
programattically using :meth:`put_string` or :meth:`put_template`::
lookup = TemplateLookup()
lookup.put_string("base.html", '''
<html><body>${self.next()}</body></html>
''')
lookup.put_string("hello.html", '''
<%include file='base.html'/>
Hello, world !
''')
:param directories: A list of directory names which will be searched for
a particular template URI. The URI is appended to each directory and
the filesystem checked.
:param collection_size: Approximate size of the collection used to
store templates. If left at its default of -1, the size is unbounded,
and a plain Python dictionary is used to relate URI strings to :class:`.Template`
instances. Otherwise, a least-recently-used cache object is used which
will maintain the size of the collection approximately to the number given.
:param filesystem_checks: When at its default value of ``True``, each
call to :meth:`get_template()` will compare the filesystem last modified
time to the time in which an existing :class:`.Template` object was created.
This allows the :class:`.TemplateLookup` to regenerate a new :class:`.Template`
whenever the original source has been updated. Set this to ``False`` for a
very minor performance increase.
:param modulename_callable: A callable which, when present, is passed the
path of the source file as well as the requested URI, and then returns the
full path of the generated Python module file. This is used to inject
alternate schemes for Pyhton module location. If left at its default
of ``None``, the built in system of generation based on ``module_directory``
plus ``uri`` is used.
All other keyword parameters available for :class:`.Template` are mirrored here.
When new :class:`.Template` objects are created, the keywords established with
this :class:`.TemplateLookup` are passed on to each new :class:`.Template`.
"""
def __init__(self,
directories=None,
module_directory=None,
......@@ -100,6 +186,13 @@ class TemplateLookup(TemplateCollection):
self._mutex = threading.Lock()
def get_template(self, uri):
"""Return a :class:`.Template` object corresponding to the given
URL.
Note the "relativeto" argument is not supported here at the moment.
"""
try:
if self.filesystem_checks:
return self._check(uri, self._collection[uri])
......@@ -116,7 +209,7 @@ class TemplateLookup(TemplateCollection):
"Cant locate template for uri %r" % uri)
def adjust_uri(self, uri, relativeto):
"""adjust the given uri based on the calling filename."""
"""adjust the given uri based on the given relative uri."""
if uri[0] != '/':
if relativeto is not None:
......@@ -128,6 +221,9 @@ class TemplateLookup(TemplateCollection):
def filename_to_uri(self, filename):
"""Convert the given filename to a uri relative to
this TemplateCollection."""
try:
return self._uri_cache[filename]
except KeyError:
......@@ -193,6 +289,10 @@ class TemplateLookup(TemplateCollection):
return template
def put_string(self, uri, text):
"""Place a new :class:`.Template` object into this :class:`.TemplateLookup`,
based on the given string of text.
"""
self._collection[uri] = Template(
text,
lookup=self,
......@@ -200,5 +300,9 @@ class TemplateLookup(TemplateCollection):
**self.template_args)
def put_template(self, uri, template):
"""Place a new :class:`.Template` object into this :class:`.TemplateLookup`,
based on the given :class:`.Template` object.
"""
self._collection[uri] = template
mako/template.py
+ 2
− 1
View file @ d0f60720
......@@ -76,7 +76,8 @@ class Template(object):
:param uri: string uri or other identifier for this template. If not provided,
the uri is generated from the filesystem path, or from the
in-memory identity of a non-file-based template. The primary usage of the
uri is to generate the file path of the generated Python module file,
uri is to provide a key within :class:`.TemplateLookup`, as well as to
generate the file path of the generated Python module file,
if ``module_directory`` is specified.
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment