# HG changeset patch # User cmlenz # Date 1151487718 0 # Node ID 35956040ba6e853cae8df6a00af58a2a3e29784c # Parent b4f78c05e5c9260a777d50df96699f223b1e9854 More docstrings for the builder module. diff --git a/markup/builder.py b/markup/builder.py --- a/markup/builder.py +++ b/markup/builder.py @@ -17,6 +17,9 @@ class Fragment(object): + """Represents a markup fragment, which is basically just a list of element + or text nodes. + """ __slots__ = ['children'] def __init__(self): @@ -48,7 +51,7 @@ return self def generate(self): - """Generator that yield tags and text nodes as strings.""" + """Return a markup event stream for the fragment.""" def _generate(): for child in self.children: if isinstance(child, Fragment): @@ -160,7 +163,7 @@ return Fragment.__call__(self, *args) def generate(self): - """Generator that yield tags and text nodes as strings.""" + """Return a markup event stream for the fragment.""" def _generate(): yield Stream.START, (self.tag, self.attrib), (-1, -1) for kind, data, pos in Fragment.generate(self): @@ -170,16 +173,50 @@ class ElementFactory(object): + """Factory for `Element` objects. + + A new element is created simply by accessing a correspondingly named + attribute of the factory object: + + >>> factory = ElementFactory() + >>> print factory.foo + + >>> print factory.foo(id=2) + + + A factory can also be bound to a specific namespace: + + >>> factory = ElementFactory('http://www.w3.org/1999/xhtml') + >>> print factory.html(lang="en") + + + The namespace for a specific element can be altered on an existing factory + by specifying the new namespace using item access: + + >>> factory = ElementFactory() + >>> print factory.html(factory['http://www.w3.org/2000/svg'].g(id=3)) + + + Usually, the `ElementFactory` class is not be used directly. Rather, the + `tag` instance should be used to create elements. + """ def __init__(self, namespace=None): + """Create the factory, optionally bound to the given namespace. + + @param namespace: the namespace URI for any created elements, or `None` + for no namespace + """ if namespace and not isinstance(namespace, Namespace): namespace = Namespace(namespace) self.namespace = namespace def __getitem__(self, namespace): + """Return a new factory that is bound to the specified namespace.""" return ElementFactory(namespace) def __getattr__(self, name): + """Create an `Element` with the given name.""" return Element(self.namespace and self.namespace[name] or name)