Mercurial > genshi > genshi-test
comparison genshi/builder.py @ 430:e7a4d43c438a
Moved the `builder` document into the API docs.
| author | cmlenz |
|---|---|
| date | Thu, 22 Mar 2007 17:14:09 +0000 |
| parents | 5b248708bbed |
| children | 747baa1cd597 |
comparison
equal
deleted
inserted
replaced
| 429:6911f3c5a7e8 | 430:e7a4d43c438a |
|---|---|
| 9 # | 9 # |
| 10 # This software consists of voluntary contributions made by many | 10 # This software consists of voluntary contributions made by many |
| 11 # individuals. For the exact contribution history, see the revision | 11 # individuals. For the exact contribution history, see the revision |
| 12 # history and logs, available at http://genshi.edgewall.org/log/. | 12 # history and logs, available at http://genshi.edgewall.org/log/. |
| 13 | 13 |
| 14 """Support for programmatically generating markup streams.""" | 14 """Support for programmatically generating markup streams from Python code using |
| 15 a very simple syntax. The main entry point to this module is the `tag` object | |
| 16 (which is actually an instance of the ``ElementFactory`` class). You should | |
| 17 rarely (if ever) need to directly import and use any of the other classes in | |
| 18 this module. | |
| 19 | |
| 20 Elements can be created using the `tag` object using attribute access. For | |
| 21 example: | |
| 22 | |
| 23 >>> doc = tag.p('Some text and ', tag.a('a link', href='http://example.org/'), '.') | |
| 24 >>> doc | |
| 25 <Element "p"> | |
| 26 | |
| 27 This produces an `Element` instance which can be further modified to add child | |
| 28 nodes and attributes. This is done by "calling" the element: positional | |
| 29 arguments are added as child nodes (alternatively, the `Element.append` method | |
| 30 can be used for that purpose), whereas keywords arguments are added as | |
| 31 attributes: | |
| 32 | |
| 33 >>> doc(tag.br) | |
| 34 <Element "p"> | |
| 35 >>> print doc | |
| 36 <p>Some text and <a href="http://example.org/">a link</a>.<br/></p> | |
| 37 | |
| 38 If an attribute name collides with a Python keyword, simply append an underscore | |
| 39 to the name: | |
| 40 | |
| 41 >>> doc(class_='intro') | |
| 42 <Element "p"> | |
| 43 >>> print doc | |
| 44 <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p> | |
| 45 | |
| 46 As shown above, an `Element` can easily be directly rendered to XML text by | |
| 47 printing it or using the Python ``str()`` function. This is basically a | |
| 48 shortcut for converting the `Element` to a stream and serializing that | |
| 49 stream: | |
| 50 | |
| 51 >>> stream = doc.generate() | |
| 52 >>> stream | |
| 53 <genshi.core.Stream object at ...> | |
| 54 >>> print stream | |
| 55 <p class="intro">Some text and <a href="http://example.org/">a link</a>.<br/></p> | |
| 56 | |
| 57 | |
| 58 The `tag` object also allows creating "fragments", which are basically lists | |
| 59 of nodes (elements or text) that don't have a parent element. This can be useful | |
| 60 for creating snippets of markup that are attached to a parent element later (for | |
| 61 example in a template). Fragments are created by calling the `tag` object, which | |
| 62 returns an object of type `Fragment`: | |
| 63 | |
| 64 >>> fragment = tag('Hello, ', tag.em('world'), '!') | |
| 65 >>> fragment | |
| 66 <Fragment> | |
| 67 >>> print fragment | |
| 68 Hello, <em>world</em>! | |
| 69 """ | |
| 15 | 70 |
| 16 from genshi.core import Attrs, Namespace, QName, Stream, START, END, TEXT | 71 from genshi.core import Attrs, Namespace, QName, Stream, START, END, TEXT |
| 17 | 72 |
| 18 __all__ = ['Fragment', 'Element', 'tag'] | 73 __all__ = ['Fragment', 'Element', 'tag'] |
| 19 __docformat__ = 'restructuredtext en' | 74 __docformat__ = 'restructuredtext en' |