diff options
| author | Mike Bayer <mike_mp@zzzcomputing.com> | 2010-11-12 13:31:55 -0500 |
|---|---|---|
| committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2010-11-12 13:31:55 -0500 |
| commit | d0f607201ebbbeecc60880455aacb690906563bd (patch) | |
| tree | 7972a0938bf52f4a8d59e910568656312e3c41d2 | |
| parent | 5d4575aff2310268bfd439b514b778a7eff0fbf0 (diff) | |
| download | external_python_mako-d0f607201ebbbeecc60880455aacb690906563bd.tar.gz external_python_mako-d0f607201ebbbeecc60880455aacb690906563bd.tar.bz2 external_python_mako-d0f607201ebbbeecc60880455aacb690906563bd.zip | |
docstrings
| -rw-r--r-- | doc/build/usage.rst | 3 | ||||
| -rw-r--r-- | mako/lookup.py | 106 | ||||
| -rw-r--r-- | mako/template.py | 3 |
3 files changed, 110 insertions, 2 deletions
diff --git a/doc/build/usage.rst b/doc/build/usage.rst index fb26f37..4e536b3 100644 --- a/doc/build/usage.rst +++ b/doc/build/usage.rst @@ -418,6 +418,9 @@ API Documentation .. autoclass:: mako.template.Template :members: +.. autoclass:: mako.lookup.TemplateCollection + :members: + .. autoclass:: mako.lookup.TemplateLookup :members: diff --git a/mako/lookup.py b/mako/lookup.py index 0852355..15793b7 100644 --- a/mako/lookup.py +++ b/mako/lookup.py @@ -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 diff --git a/mako/template.py b/mako/template.py index 0e99acf..e78afcd 100644 --- a/mako/template.py +++ b/mako/template.py @@ -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. |