# HG changeset patch # User cmlenz # Date 1174605835 0 # Node ID be39660919a5b57afc970ae7edf10d4cbad72b7e # Parent 5692bc32ba5fafed072bc000e280cb5085d55a53 More API doc enhancements. diff --git a/genshi/core.py b/genshi/core.py --- a/genshi/core.py +++ b/genshi/core.py @@ -159,6 +159,11 @@ XPath expression. :param path: a string containing the XPath expression + :param namespaces: mapping of namespace prefixes used in the path + :param variables: mapping of variable names to values + :return: the selected substream + :raises PathSyntaxError: if the given path expression is invalid or not + supported """ from genshi.path import Path return Path(path).select(self, namespaces, variables) @@ -305,6 +310,11 @@ def get(self, name, default=None): """Return the value of the attribute with the specified name, or the value of the `default` parameter if no such attribute is found. + + :param name: the name of the attribute + :param default: the value to return when the attribute does not exist + :return: the attribute value, or the `default` value if that attribute + does not exist """ for attr, value in self: if attr == name: diff --git a/genshi/template/base.py b/genshi/template/base.py --- a/genshi/template/base.py +++ b/genshi/template/base.py @@ -35,10 +35,19 @@ class TemplateRuntimeError(TemplateError): - """Exception raised when an the evualation of a Python expression in a - template causes an error.""" + """Exception raised when an the evaluation of a Python expression in a + template causes an error. + """ def __init__(self, message, filename='', lineno=-1, offset=-1): + """Create the exception + + :param message: the error message + :param filename: the filename of the template + :param lineno: the number of line in the template at which the error + occurred + :param offset: the column number at which the error occurred + """ self.msg = message if filename != '' or lineno >= 0: message = '%s (%s, line %d)' % (self.msg, filename, lineno) @@ -53,6 +62,14 @@ error.""" def __init__(self, message, filename='', lineno=-1, offset=-1): + """Create the exception + + :param message: the error message + :param filename: the filename of the template + :param lineno: the number of line in the template at which the error + occurred + :param offset: the column number at which the error occurred + """ if isinstance(message, SyntaxError) and message.lineno is not None: message = str(message).replace(' (line %d)' % message.lineno, '') self.msg = message @@ -72,6 +89,13 @@ """ def __init__(self, name, filename='', lineno=-1): + """Create the exception + + :param name: the name of the directive + :param filename: the filename of the template + :param lineno: the number of line in the template at which the error + occurred + """ message = 'bad directive "%s"' % name TemplateSyntaxError.__init__(self, message, filename, lineno) @@ -102,6 +126,9 @@ """ def __init__(self, **data): + """Initialize the template context with the given keyword arguments as + data. + """ self.frames = deque([data]) self.pop = self.frames.popleft self.push = self.frames.appendleft @@ -111,11 +138,17 @@ return repr(list(self.frames)) def __contains__(self, key): - """Return whether a variable exists in any of the scopes.""" + """Return whether a variable exists in any of the scopes. + + :param key: the name of the variable + """ return self._find(key)[1] is not None def __delitem__(self, key): - """Set a variable in the current scope.""" + """Remove a variable from all scopes. + + :param key: the name of the variable + """ for frame in self.frames: if key in frame: del frame[key] @@ -124,7 +157,9 @@ """Get a variables's value, starting at the current scope and going upward. - Raises `KeyError` if the requested variable wasn't found in any scope. + :param key: the name of the variable + :return: the variable value + :raises KeyError: if the requested variable wasn't found in any scope """ value, frame = self._find(key) if frame is None: @@ -132,17 +167,28 @@ return value def __len__(self): - """Return the number of distinctly named variables in the context.""" + """Return the number of distinctly named variables in the context. + + :return: the number of variables in the context + """ return len(self.items()) def __setitem__(self, key, value): - """Set a variable in the current scope.""" + """Set a variable in the current scope. + + :param key: the name of the variable + :param value: the variable value + """ self.frames[0][key] = value def _find(self, key, default=None): """Retrieve a given variable's value and the frame it was found in. - Intented for internal use by directives. + Intended primarily for internal use by directives. + + :param key: the name of the variable + :param default: the default value to return when the variable is not + found """ for frame in self.frames: if key in frame: @@ -152,6 +198,10 @@ def get(self, key, default=None): """Get a variable's value, starting at the current scope and going upward. + + :param key: the name of the variable + :param default: the default value to return when the variable is not + found """ for frame in self.frames: if key in frame: @@ -159,23 +209,41 @@ return default def keys(self): + """Return the name of all variables in the context. + + :return: a list of variable names + """ keys = [] for frame in self.frames: keys += [key for key in frame if key not in keys] return keys def items(self): + """Return a list of ``(name, value)`` tuples for all variables in the + context. + + :return: a list of variables + """ return [(key, self.get(key)) for key in self.keys()] def push(self, data): - """Push a new scope on the stack.""" + """Push a new scope on the stack. + + :param data: the data dictionary to push on the context stack. + """ def pop(self): """Pop the top-most scope from the stack.""" def _apply_directives(stream, ctxt, directives): - """Apply the given directives to the stream.""" + """Apply the given directives to the stream. + + :param stream: the stream the directives should be applied to + :param ctxt: the `Context` + :param directives: the list of directives to apply + :return: the stream with the given directives applied + """ if directives: stream = directives[0](iter(stream), ctxt, directives[1:]) return stream diff --git a/genshi/template/loader.py b/genshi/template/loader.py --- a/genshi/template/loader.py +++ b/genshi/template/loader.py @@ -30,6 +30,11 @@ """Exception raised when a specific template file could not be found.""" def __init__(self, name, search_path): + """Create the exception. + + :param name: the filename of the template + :param search_path: the search path used to lookup the template + """ TemplateError.__init__(self, 'Template "%s" not found' % name) self.search_path = search_path @@ -101,11 +106,11 @@ If the `filename` parameter is relative, this method searches the search path trying to locate a template matching the given name. If the file - name is an absolute path, the search path is not bypassed. + name is an absolute path, the search path is ignored. - If requested template is not found, a `TemplateNotFound` exception is - raised. Otherwise, a `Template` object is returned that represents the - parsed template. + If the requested template is not found, a `TemplateNotFound` exception + is raised. Otherwise, a `Template` object is returned that represents + the parsed template. Template instances are cached to avoid having to parse the same template file more than once. Thus, subsequent calls of this method @@ -118,11 +123,14 @@ :param filename: the relative path of the template file to load :param relative_to: the filename of the template from which the new - template is being loaded, or ``None`` if the template - is being loaded directly + template is being loaded, or ``None`` if the + template is being loaded directly :param cls: the class of the template object to instantiate :param encoding: the encoding of the template to load; defaults to the ``default_encoding`` of the loader instance + :return: the loaded `Template` instance + :raises TemplateNotFound: if a template with the given name could not be + found """ if cls is None: cls = self.default_class diff --git a/genshi/template/plugin.py b/genshi/template/plugin.py --- a/genshi/template/plugin.py +++ b/genshi/template/plugin.py @@ -25,8 +25,8 @@ from genshi.template.markup import MarkupTemplate from genshi.template.text import TextTemplate -__all__ = ['ConfigurationError', 'MarkupTemplateEnginePlugin', - 'TextTemplateEnginePlugin'] +__all__ = ['ConfigurationError', 'AbstractTemplateEnginePlugin', + 'MarkupTemplateEnginePlugin', 'TextTemplateEnginePlugin'] __docformat__ = 'restructuredtext en'