# HG changeset patch # User cmlenz # Date 1180700570 0 # Node ID 5b42b341185a447c39db26da05dcac53a0d46c6f # Parent 1e1e0564dc52590d408e4989e02ac6b38f08b423 A couple of minor doc refinements. diff --git a/doc/style/epydoc.css b/doc/style/epydoc.css --- a/doc/style/epydoc.css +++ b/doc/style/epydoc.css @@ -54,7 +54,9 @@ table.summary th th, table.summary td td { border: none; } table.summary td.summary table td { color: #666; font-size: 90%; } table.summary td.summary table br { display: none; } -table.summary td.summary span.summary-type { font-size: 90%; } +table.summary td.summary span.summary-type { font-family: monospace; + font-size: 90%; +} table.summary td.summary span.summary-type code { font-size: 110%; } p.indent-wrapped-lines { color: #999; font-size: 85%; margin: 0; padding: 0 0 0 7em; text-indent: -7em; diff --git a/genshi/builder.py b/genshi/builder.py --- a/genshi/builder.py +++ b/genshi/builder.py @@ -139,7 +139,10 @@ yield TEXT, child, (None, -1, -1) def generate(self): - """Return a markup event stream for the fragment.""" + """Return a markup event stream for the fragment. + + :rtype: `Stream` + """ return Stream(self._generate()) @@ -243,6 +246,8 @@ """Append any positional arguments as child nodes, and keyword arguments as attributes. + :return: the element itself so that calls can be chained + :rtype: `Element` :see: `Fragment.append` """ self.attrib |= Attrs(_kwargs_to_attrs(kwargs)) @@ -259,7 +264,10 @@ yield END, self.tag, (None, -1, -1) def generate(self): - """Return a markup event stream for the fragment.""" + """Return a markup event stream for the fragment. + + :rtype: `Stream` + """ return Stream(self._generate()) @@ -313,6 +321,7 @@ nodes. :return: the created `Fragment` + :rtype: `Fragment` """ return Fragment()(*args) @@ -322,6 +331,7 @@ :param namespace: the namespace URI or `Namespace` object :return: an `ElementFactory` that produces elements bound to the given namespace + :rtype: `ElementFactory` """ return ElementFactory(namespace) @@ -330,9 +340,13 @@ :param name: the tag name of the element to create :return: an `Element` with the specified name + :rtype: `Element` """ return Element(self.namespace and self.namespace[name] or name) tag = ElementFactory() -"""Global `ElementFactory` bound to the default namespace.""" +"""Global `ElementFactory` bound to the default namespace. + +:type: `ElementFactory` +""" diff --git a/genshi/core.py b/genshi/core.py --- a/genshi/core.py +++ b/genshi/core.py @@ -70,7 +70,7 @@ :param events: a sequence or iterable providing the events """ - self.events = events + self.events = events #: The underlying iterable producing the events def __iter__(self): return iter(self.events) @@ -114,6 +114,10 @@ Commonly, serializers should be used at the end of the "pipeline"; using them somewhere in the middle may produce unexpected results. + + :param function: the callable object that should be applied as a filter + :return: the filtered stream + :rtype: `Stream` """ return Stream(_ensure(function(self))) @@ -131,23 +135,28 @@ is equivalent to:: stream | filter1 | filter2 + + :param filters: one or more callable objects that should be applied as + filters + :return: the filtered stream + :rtype: `Stream` """ return reduce(operator.or_, (self,) + filters) def render(self, method='xml', encoding='utf-8', **kwargs): """Return a string representation of the stream. + Any additional keyword arguments are passed to the serializer, and thus + depend on the `method` parameter value. + :param method: determines how the stream is serialized; can be either "xml", "xhtml", "html", "text", or a custom serializer class :param encoding: how the output string should be encoded; if set to `None`, this method returns a `unicode` object - - Any additional keyword arguments are passed to the serializer, and thus - depend on the `method` parameter value. - - :see: XMLSerializer.__init__, XHTMLSerializer.__init__, - HTMLSerializer.__init__, TextSerializer.__init__ + :return: a `str` or `unicode` object + :rtype: `basestring` + :see: XMLSerializer, XHTMLSerializer, HTMLSerializer, TextSerializer """ from genshi.output import encode generator = self.serialize(method=method, **kwargs) @@ -161,6 +170,7 @@ :param namespaces: mapping of namespace prefixes used in the path :param variables: mapping of variable names to values :return: the selected substream + :rtype: `Stream` :raises PathSyntaxError: if the given path expression is invalid or not supported """ @@ -175,15 +185,16 @@ the serialized output incrementally, as opposed to returning a single string. + Any additional keyword arguments are passed to the serializer, and thus + depend on the `method` parameter value. + :param method: determines how the stream is serialized; can be either "xml", "xhtml", "html", "text", or a custom serializer class - - Any additional keyword arguments are passed to the serializer, and thus - depend on the `method` parameter value. - - :see: XMLSerializer.__init__, XHTMLSerializer.__init__, - HTMLSerializer.__init__, TextSerializer.__init__ + :return: an iterator over the serialization results (`Markup` or + `unicode` objects, depending on the serialization method) + :rtype: ``iterator`` + :see: XMLSerializer, XHTMLSerializer, HTMLSerializer, TextSerializer """ from genshi.output import get_serializer return get_serializer(method, **kwargs)(_ensure(self)) @@ -275,6 +286,9 @@ def __contains__(self, name): """Return whether the list includes an attribute with the specified name. + + :return: `True` if the list includes the attribute + :rtype: `bool` """ for attr, _ in self: if attr == name: @@ -286,6 +300,9 @@ def __or__(self, attrs): """Return a new instance that contains the attributes in `attrs` in addition to any already existing attributes. + + :return: a new instance with the merged attributes + :rtype: `Attrs` """ repl = dict([(an, av) for an, av in attrs if an in self]) return Attrs([(sn, repl.get(sn, sv)) for sn, sv in self] + @@ -299,6 +316,10 @@ def __sub__(self, names): """Return a new instance with all attributes with a name in `names` are removed. + + :param names: the names of the attributes to remove + :return: a new instance with the attribute removed + :rtype: `Attrs` """ if isinstance(names, basestring): names = (names,) @@ -312,6 +333,7 @@ :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 + :rtype: `object` """ for attr, value in self: if attr == name: @@ -326,6 +348,9 @@ >>> Attrs([('href', '#'), ('title', 'Foo')]).totuple() ('TEXT', u'#Foo', (None, -1, -1)) + + :return: a `TEXT` event + :rtype: `tuple` """ return TEXT, u''.join([x[1] for x in self]), (None, -1, -1) @@ -373,6 +398,7 @@ :param escape_quotes: whether double quote characters in the elements should be escaped :return: the joined `Markup` object + :rtype: `Markup` :see: `escape` """ return Markup(unicode(self).join([escape(item, quotes=escape_quotes) @@ -396,7 +422,7 @@ :param quotes: if ``True``, double quote characters are escaped in addition to the other special characters :return: the escaped `Markup` string - :see: `genshi.core.escape` + :rtype: `Markup` """ if not text: return cls() @@ -416,6 +442,8 @@ >>> Markup('1 < 2').unescape() u'1 < 2' + :return: the unescaped string + :rtype: `unicode` :see: `genshi.core.unescape` """ if not self: @@ -433,6 +461,8 @@ the core XML entities (``&``, ``'``, ``>``, ``<`` and ``"``) are not stripped. + :return: a `Markup` instance with entities removed + :rtype: `Markup` :see: `genshi.util.stripentities` """ return Markup(stripentities(self, keepxmlentities=keepxmlentities)) @@ -440,6 +470,8 @@ def striptags(self): """Return a copy of the text with all XML/HTML tags removed. + :return: a `Markup` instance with all tags removed + :rtype: `Markup` :see: `genshi.util.striptags` """ return Markup(striptags(self)) @@ -453,13 +485,15 @@ >>> unescape(Markup('1 < 2')) u'1 < 2' - If the provided `text` object is not a `Markup` instance, the text is - returned as-is. + If the provided `text` object is not a `Markup` instance, it is returned + unchanged. >>> unescape('1 < 2') '1 < 2' :param text: the text to unescape + :return: the unescsaped string + :rtype: `unicode` """ if not isinstance(text, Markup): return text diff --git a/genshi/path.py b/genshi/path.py --- a/genshi/path.py +++ b/genshi/path.py @@ -77,6 +77,9 @@ """Create the path object from a string. :param text: the path expression + :param filename: the name of the file in which the path expression was + found (used in error messages) + :param lineno: the line on which the expression was found """ self.source = text self.paths = PathParser(text, filename, lineno).parse() @@ -110,6 +113,7 @@ :param namespaces: (optional) a mapping of namespace prefixes to URIs :param variables: (optional) a mapping of variable names to values :return: the substream matching the path, or an empty stream + :rtype: `Stream` """ if namespaces is None: namespaces = {} @@ -159,6 +163,13 @@ ... if test(event, {}, {}): ... print event[0], repr(event[1]) START (QName(u'child'), Attrs([(QName(u'id'), u'2')])) + + :param ignore_context: if `True`, the path is interpreted like a pattern + in XSLT, meaning for example that it will match + at any depth + :return: a function that can be used to test individual events in a + stream against the path + :rtype: ``function`` """ paths = [(p, len(p), [0], [], [0] * len(p)) for p in [ (ignore_context and [_DOTSLASHSLASH] or []) + p for p in self.paths