Edgewall Software

Changeset 525 for trunk/genshi/input.py


Ignore:
Timestamp:
Mar 22, 2007, 10:12:03 PM (17 years ago)
Author:
cmlenz
Message:

More API docs.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/genshi/input.py

    r517 r525  
    3535
    3636def ET(element):
    37     """Convert a given ElementTree element to a markup stream."""
     37    """Convert a given ElementTree element to a markup stream.
     38   
     39    :param element: an ElementTree element
     40    :return: a markup stream
     41    """
    3842    tag_name = QName(element.tag.lstrip('{'))
    3943    attrs = Attrs([(QName(attr), value) for attr, value in element.items()])
    … …  
    5256class ParseError(Exception):
    5357    """Exception raised when fatal syntax errors are found in the input being
    54     parsed."""
     58    parsed.
     59    """
    5560
    5661    def __init__(self, message, filename=None, lineno=-1, offset=-1):
     62        """Exception initializer.
     63       
     64        :param message: the error message from the parser
     65        :param filename: the path to the file that was parsed
     66        :param lineno: the number of the line on which the error was encountered
     67        :param offset: the column number where the error was encountered
     68        """
    5769        self.msg = message
    5870        if filename:
    … …  
    129141
    130142    def parse(self):
     143        """Generator that parses the XML source, yielding markup events.
     144       
     145        :return: a markup event stream
     146        :raises ParseError: if the XML text is not well formed
     147        """
    131148        def _generate():
    132149            try:
    … …  
    238255
    239256def XML(text):
     257    """Parse the given XML source and return a markup stream.
     258   
     259    Unlike with `XMLParser`, the returned stream is reusable, meaning it can be
     260    iterated over multiple times:
     261   
     262    >>> xml = XML('<doc><elem>Foo</elem><elem>Bar</elem></doc>')
     263    >>> print xml
     264    <doc><elem>Foo</elem><elem>Bar</elem></doc>
     265    >>> print xml.select('elem')
     266    <elem>Foo</elem><elem>Bar</elem>
     267    >>> print xml.select('elem/text()')
     268    FooBar
     269   
     270    :param text: the XML source
     271    :return: the parsed XML event stream
     272    :raises ParseError: if the XML text is not well-formed
     273    """
    240274    return Stream(list(XMLParser(StringIO(text))))
    241275
    … …  
    278312
    279313    def parse(self):
     314        """Generator that parses the HTML source, yielding markup events.
     315       
     316        :return: a markup event stream
     317        :raises ParseError: if the HTML text is not well formed
     318        """
    280319        def _generate():
    281320            try:
    … …  
    369408
    370409def HTML(text, encoding='utf-8'):
     410    """Parse the given HTML source and return a markup stream.
     411   
     412    Unlike with `HTMLParser`, the returned stream is reusable, meaning it can be
     413    iterated over multiple times:
     414   
     415    >>> html = HTML('<body><h1>Foo</h1></body>')
     416    >>> print html
     417    <body><h1>Foo</h1></body>
     418    >>> print html.select('h1')
     419    <h1>Foo</h1>
     420    >>> print html.select('h1/text()')
     421    Foo
     422   
     423    :param text: the HTML source
     424    :return: the parsed XML event stream
     425    :raises ParseError: if the HTML text is not well-formed, and error recovery
     426                        fails
     427    """
    371428    return Stream(list(HTMLParser(StringIO(text), encoding=encoding)))
    372429
Note: See TracChangeset for help on using the changeset viewer.