Changeset 2412:2983890c7e98 in livinglogic.python.xist

Show
Ignore:
Timestamp:
06/29/05 19:02:05 (15 years ago)
Author:
Walter Doerwald <walter@…>
Branch:
default
Message:

Add docstrings to the parsing functions and rename arguments a bit.

Files:
1 modified

Legend:

Unmodified
Added
Removed
  • _xist/parsers.py

    r2398 r2412  
    500500        """ 
    501501        return the newest node from the stack that is a real node. 
    502         (There might be a fake node on the stack, because we are inside 
     502        (There might be fake nodes on the stack, because we are inside 
    503503        of illegal elements). 
    504504        """ 
     
    616616 
    617617    def parse(self, stream, base=None, sysid=None): 
     618        """ 
     619        Parse &xml; from the stream <arg>stream</arg> into an &xist; tree. 
     620        <arg>base</arg> is the base &url; for the parsing process, <arg>sysid</arg> 
     621        is the &xml; system identifier (defaulting to <arg>base</arg> if it is <lit>None</lit>). 
     622        """ 
    618623        if sysid is None: 
    619624            sysid = base 
    620625        return self._parse(stream, base, sysid, self.encoding) 
    621626 
    622     def parseString(self, string, base=None, sysid=None): 
    623         if isinstance(string, unicode): 
     627    def parseString(self, text, base=None, sysid=None): 
     628        """ 
     629        Parse the string <arg>text</arg> (<class>str</class> or <class>unicode</class>) 
     630        into an &xist; tree. <arg>base</arg> is the base &url; for the parsing process, <arg>sysid</arg> 
     631        is the &xml; system identifier (defaulting to <arg>base</arg> if it is <lit>None</lit>). 
     632        """ 
     633        if isinstance(text, unicode): 
    624634            encoding = "utf-8" 
    625             string = string.encode(encoding) 
     635            text = text.encode(encoding) 
    626636        else: 
    627637            encoding = self.encoding 
    628         stream = cStringIO.StringIO(string) 
     638        stream = cStringIO.StringIO(text) 
    629639        if base is None: 
    630640            base = url.URL("STRING") 
     
    634644 
    635645    def parseURL(self, name, base=None, sysid=None, headers=None, data=None): 
     646        """ 
     647        Parse &xml; input from the &url; <arg>name</arg> which might be a string 
     648        or an <pyref module="ll.url" class="URL"><class>URL</class></pyref> object 
     649        into an &xist; tree. <arg>base</arg> is the base &url; for the parsing process 
     650        (defaulting to the final &url; of the response (i.e. including redirects)), 
     651        <arg>sysid</arg> is the &xml; system identifier (defaulting to <arg>base</arg> 
     652        if it is <lit>None</lit>). <arg>headers</arg> is a dictionary with additional 
     653        headers used in the &http; request. If <arg>data</arg> is not <lit>None</lit> 
     654        it must be a dictionary. In this case <arg>data</arg> will be used as the data 
     655        for a <lit>POST</lit> request. 
     656        """ 
    636657        name = url.URL(name) 
    637658        stream = name.openread(headers=headers, data=data) 
     
    645666        return self._parse(stream, base, sysid, encoding) 
    646667 
    647     def parseFile(self, name, base=None, sysid=None): 
    648         name = os.path.expanduser(name) 
    649         stream = open(name, "rb") 
     668    def parseFile(self, filename, base=None, sysid=None): 
     669        """ 
     670        Parse &xml; input from the file named <arg>filename</arg>. <arg>base</arg> is 
     671        the base &url; for the parsing process (defaulting to <arg>name</arg>), 
     672        <arg>sysid</arg> is the &xml; system identifier (defaulting to <arg>base</arg>). 
     673        """ 
     674        name = os.path.expanduser(filename) 
     675        stream = open(filename, "rb") 
    650676        if base is None: 
    651             base = url.File(name) 
     677            base = url.File(filename) 
    652678        if sysid is None: 
    653679            sysid = str(base) 
     
    807833 
    808834def parse(stream, base, sysid=None, **parserargs): 
     835    """ 
     836    Parse &xml; from the stream <arg>stream</arg> into an &xist; tree. 
     837    For the arguments <arg>base</arg> and <arg>sysid</arg> see the method 
     838    <pyref class="Parser" method="parse"><method>parse</method></pyref> 
     839    in the <class>Parser</class> class. You can pass any other argument that the 
     840    <pyref class="Parser" method="__init__"><class>Parser</class> constructor</pyref> 
     841    takes as keyword arguments via <arg>parserargs</arg>. 
     842    """ 
    809843    parser = Parser(**parserargs) 
    810844    return parser.parse(stream, base, sysid) 
     
    812846 
    813847def parseString(text, base=None, sysid=None, **parserargs): 
     848    """ 
     849    Parse the string <arg>text</arg> (<class>str</class> or <class>unicode</class>) into an 
     850    &xist; tree. For the arguments <arg>base</arg> and <arg>sysid</arg> see the method 
     851    <pyref class="Parser" method="parseString"><method>parseString</method></pyref> 
     852    in the <class>Parser</class> class. You can pass any other argument that the 
     853    <pyref class="Parser" method="__init__"><class>Parser</class> constructor</pyref> 
     854    takes as keyword arguments via <arg>parserargs</arg>. 
     855    """ 
    814856    parser = Parser(**parserargs) 
    815857    return parser.parseString(text, base, sysid) 
     
    817859 
    818860def parseURL(url, base=None, sysid=None, headers=None, data=None, **parserargs): 
     861    """ 
     862    Parse &xml; input from the &url; <arg>name</arg> which might be a string 
     863    or an <pyref module="ll.url" class="URL"><class>URL</class></pyref> object 
     864    into an &xist; tree. For the arguments <arg>base</arg>, <arg>sysid</arg>, 
     865    <arg>headers</arg> and <arg>data</arg> see the method 
     866    <pyref class="Parser" method="parseURL"><method>parseURL</method></pyref> 
     867    in the <class>Parser</class> class. You can pass any other argument that the 
     868    <pyref class="Parser" method="__init__"><class>Parser</class> constructor</pyref> 
     869    takes as keyword arguments via <arg>parserargs</arg>. 
     870    """ 
    819871    parser = Parser(**parserargs) 
    820872    return parser.parseURL(url, base, sysid, headers, data) 
     
    822874 
    823875def parseFile(filename, base=None, sysid=None, **parserargs): 
     876    """ 
     877    Parse &xml; input from the file named <arg>filename</arg>. For the arguments 
     878    <arg>base</arg> and <arg>sysid</arg> see the method 
     879    <pyref class="Parser" method="parseFile"><method>parseFile</method></pyref> 
     880    in the <class>Parser</class> class. You can pass any other argument that the 
     881    <pyref class="Parser" method="__init__"><class>Parser</class> constructor</pyref> 
     882    takes as keyword arguments via <arg>parserargs</arg>. 
     883    """ 
    824884    parser = Parser(**parserargs) 
    825885    return parser.parseFile(filename, base, sysid)