Changeset 2806:e136e67ef19c in livinglogic.python.xist

Show
Ignore:
Timestamp:
07/24/07 19:23:19 (12 years ago)
Author:
Walter Doerwald <walter@…>
Branch:
default
Message:

More docstrings for xfind selectors.

Files:
1 modified

Legend:

Unmodified
Added
Removed
  • src/ll/xist/xfind.py

    r2805 r2806  
    133133    <prompt>>>> </prompt><input>from ll.xist.ns import html</input> 
    134134    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
    135     <prompt>>>> </prompt><input>for node in doc.walknode(html.a):</input> 
     135    <prompt>>>> </prompt><input>for node in doc.walknode(<em>html.a</em>):</input> 
    136136    <prompt>... </prompt><input>\tprint node.bytes()</input> 
    137137    <prompt>... </prompt><input></input> 
     
    182182    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
    183183    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
    184     <prompt>>>> </prompt><input>for node in doc.walknode(xfind.hasname("img")):</input> 
     184    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.hasname("img")</em>):</input> 
    185185    <prompt>... </prompt><input>\tprint node.bytes()</input> 
    186186    <prompt>... </prompt><input></input> 
     
    211211class hasname_xml(Selector): 
    212212    """ 
    213     <class>hasname_xml</class> work similar to <pyref class="hasname"><class>hasname</class></pyref> 
     213    <class>hasname_xml</class> works similar to <pyref class="hasname"><class>hasname</class></pyref> 
    214214    except that the specified name is treated as the &xml; name, not the Python name. 
    215215    """ 
     
    244244    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
    245245    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
    246     <prompt>>>> </prompt><input>for node in doc.walknode(doc[0]/xsc.Element):</input> 
     246    <prompt>>>> </prompt><input>for node in doc.walknode(<em>doc[0]/xsc.Element</em>):</input> 
    247247    <prompt>... </prompt><input>\tprint repr(node)</input> 
    248248    <prompt>... </prompt><input></input> 
     
    281281    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
    282282    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
    283     <prompt>>>> </prompt><input>for node in doc.walknode(xfind.empty):</input> 
     283    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.empty</em>):</input> 
    284284    <prompt>... </prompt><input>\tprint node.bytes()</input> 
    285285    <prompt>... </prompt><input></input> 
     
    317317    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
    318318    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
    319     <prompt>>>> </prompt><input>for node in doc.walknode(xfind.onlychild & html.a):</input> 
     319    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.onlychild &amp; html.a</em>):</input> 
    320320    <prompt>... </prompt><input>\tprint node.bytes()</input> 
    321321    <prompt>... </prompt><input></input> 
     
    352352    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
    353353    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
    354     <prompt>>>> </prompt><input>for node in doc.walknode(xfind.onlyoftype & xsc.Element):</input> 
     354    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.onlyoftype &amp; xsc.Element</em>):</input> 
    355355    <prompt>... </prompt><input>\tprint repr(node)</input> 
    356356    <prompt>... </prompt><input></input> 
     
    363363    </example> 
    364364    """ 
     365 
    365366    def match(self, path): 
    366367        if len(path) >= 2: 
     
    391392    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
    392393    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
    393     <prompt>>>> </prompt><input>for node in doc.walknode(xfind.onlyoftype & xsc.Element):</input> 
     394    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.onlyoftype &amp; xsc.Element</em>):</input> 
    394395    <prompt>... </prompt><input>\tprint repr(node)</input> 
    395396    <prompt>... </prompt><input></input> 
     
    402403    </example> 
    403404    """ 
     405 
    404406    def __init__(self, *attrnames): 
    405407        self.attrnames = attrnames 
     
    420422class hasattr_xml(Selector): 
    421423    """ 
    422     <class>hasattr_xml</class> work similar to <pyref class="hasattr"><class>hasattr</class></pyref> 
     424    <class>hasattr_xml</class> works similar to <pyref class="hasattr"><class>hasattr</class></pyref> 
    423425    except that the specified names are treated as &xml; names instead of Python names. 
    424426    """ 
     427 
    425428    def __init__(self, *attrnames): 
    426429        self.attrnames = attrnames 
     
    440443 
    441444class attrhasvalue(Selector): 
     445    """ 
     446    <par>Selector that selects all element nodes where an attribute with the 
     447    specified Python name has the specified value. Note that 
     448    <pyref module="ll.xist.xsc" class="Attr" method="isfancy">fancy</pyref> attributes 
     449    will not be considered.</par> 
     450 
     451    <example> 
     452    <tty> 
     453    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     454    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     455    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.attrhasvalue("rel", "stylesheet")</em>):</input> 
     456    <prompt>... </prompt><input>\tprint repr(node)</input> 
     457    <prompt>... </prompt><input></input> 
     458    <![CDATA[<link media="screen" type="text/css" href="http://www.python.org/styles/screen-switcher-default.css" rel="stylesheet" id="screen-switcher-stylesheet" /> 
     459    <link media="scReen" type="text/css" rel="stylesheet" href="http://www.python.org/styles/netscape4.css" /> 
     460    <link media="print" type="text/css" rel="stylesheet" href="http://www.python.org/styles/print.css" />]]> 
     461    </tty> 
     462    </example> 
     463    """ 
     464 
    442465    def __init__(self, attrname, attrvalue): 
    443466        self.attrname = attrname 
     
    458481 
    459482class attrhasvalue_xml(Selector): 
     483    """ 
     484    <class>attrhasvalue_xml</class> works similar to <pyref class="attrhasvalue"><class>attrhasvalue</class></pyref> 
     485    except that the specified name is treated as an &xml; name instead of a Python name. 
     486    """ 
     487 
    460488    def __init__(self, attrname, attrvalue): 
    461489        self.attrname = attrname 
     
    479507 
    480508class attrcontains(Selector): 
     509    """ 
     510    <par>Selector that selects all element nodes where an attribute with the 
     511    specified Python name contains the specified subtring in its value. Note that 
     512    <pyref module="ll.xist.xsc" class="Attr" method="isfancy">fancy</pyref> attributes 
     513    will not be considered.</par> 
     514 
     515    <example> 
     516    <tty> 
     517    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     518    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     519    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.attrcontains("rel", "stylesheet")</em>):</input> 
     520    <prompt>... </prompt><input>\tprint repr(node)</input> 
     521    <prompt>... </prompt><input></input> 
     522    <![CDATA[<link type="text/css" id="screen-switcher-stylesheet" media="screen" rel="stylesheet" href="http://www.python.org/styles/screen-switcher-default.css" /> 
     523    <link type="text/css" media="scReen" rel="stylesheet" href="http://www.python.org/styles/netscape4.css" /> 
     524    <link type="text/css" media="print" rel="stylesheet" href="http://www.python.org/styles/print.css" /> 
     525    <link type="text/css" title="large text" media="screen" rel="alternate stylesheet" href="http://www.python.org/styles/largestyles.css" /> 
     526    <link type="text/css" title="default fonts" media="screen" rel="alternate stylesheet" href="http://www.python.org/styles/defaultfonts.css" />]]> 
     527    </tty> 
     528    </example> 
     529    """ 
     530 
    481531    def __init__(self, attrname, attrvalue): 
    482532        self.attrname = attrname 
     
    497547 
    498548class attrcontains_xml(Selector): 
     549    """ 
     550    <class>attrcontains_xml</class> works similar to <pyref class="attrcontains"><class>attrcontains</class></pyref> 
     551    except that the specified name is treated as an &xml; name instead of a Python name. 
     552    """ 
     553 
    499554    def __init__(self, attrname, attrvalue): 
    500555        self.attrname = attrname 
     
    518573 
    519574class attrstartswith(Selector): 
     575    """ 
     576    <par>Selector that selects all element nodes where an attribute with the 
     577    specified Python name starts with the specified string. Note that 
     578    <pyref module="ll.xist.xsc" class="Attr" method="isfancy">fancy</pyref> attributes 
     579    will not be considered.</par> 
     580 
     581    <example> 
     582    <tty> 
     583    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     584    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     585    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.attrstartswith("class_", "input-")</em>):</input> 
     586    <prompt>... </prompt><input>\tprint repr(node)</input> 
     587    <prompt>... </prompt><input></input> 
     588    <![CDATA[<input class="input-text" id="q" type="text" name="q" /> 
     589    <input value="search" class="input-button" id="submit" type="submit" name="submit" />]]> 
     590    </tty> 
     591    </example> 
     592    """ 
     593 
    520594    def __init__(self, attrname, attrvalue): 
    521595        self.attrname = attrname 
     
    536610 
    537611class attrstartswith_xml(Selector): 
     612    """ 
     613    <class>attrstartswith_xml</class> works similar to <pyref class="attrstartswith"><class>attrstartswith</class></pyref> 
     614    except that the specified name is treated as an &xml; name instead of a Python name. 
     615    """ 
     616 
    538617    def __init__(self, attrname, attrvalue): 
    539618        self.attrname = attrname 
     
    557636 
    558637class attrendswith(Selector): 
     638    """ 
     639    <par>Selector that selects all element nodes where an attribute with the 
     640    specified Python name ends with the specified string. Note that 
     641    <pyref module="ll.xist.xsc" class="Attr" method="isfancy">fancy</pyref> attributes 
     642    will not be considered.</par> 
     643 
     644    <example> 
     645    <tty> 
     646    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     647    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     648    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.attrendswith("href", ".css")</em>):</input> 
     649    <prompt>... </prompt><input>\tprint repr(node)</input> 
     650    <prompt>... </prompt><input></input> 
     651    <![CDATA[<link href="http://www.python.org/styles/screen-switcher-default.css" type="text/css" rel="stylesheet" id="screen-switcher-stylesheet" media="screen" /> 
     652    <link type="text/css" rel="stylesheet" href="http://www.python.org/styles/netscape4.css" media="scReen" /> 
     653    <link type="text/css" rel="stylesheet" href="http://www.python.org/styles/print.css" media="print" /> 
     654    <link title="large text" type="text/css" rel="alternate stylesheet" href="http://www.python.org/styles/largestyles.css" media="screen" /> 
     655    <link title="default fonts" type="text/css" rel="alternate stylesheet" href="http://www.python.org/styles/defaultfonts.css" media="screen" />]]> 
     656    </tty> 
     657    </example> 
     658    """ 
     659 
    559660    def __init__(self, attrname, attrvalue): 
    560661        self.attrname = attrname 
     
    575676 
    576677class attrendswith_xml(Selector): 
     678    """ 
     679    <class>attrendswith_xml</class> works similar to <pyref class="attrendswith"><class>attrendswith</class></pyref> 
     680    except that the specified name is treated as an &xml; name instead of a Python name. 
     681    """ 
     682 
    577683    def __init__(self, attrname, attrvalue): 
    578684        self.attrname = attrname 
     
    603709    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
    604710    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
    605     <prompt>>>> </prompt><input>for node in doc.walknode(xfind.hasid("logo")):</input> 
     711    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.hasid("logo")</em>):</input> 
    606712    <prompt>... </prompt><input>\tprint node.bytes()</input> 
    607713    <prompt>... </prompt><input></input> 
     
    638744    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
    639745    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
    640     <prompt>>>> </prompt><input>for node in doc.walknode(xfind.hasclass("reference")):</input> 
     746    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.hasclass("reference")</em>):</input> 
    641747    <prompt>... </prompt><input>\tprint node.bytes()</input> 
    642748    <prompt>... </prompt><input></input> 
     
    671777class inattr(Selector): 
    672778    """ 
    673     <par>Selector that is true only if the node is an attribute or is inside an 
    674     attribute.</par> 
     779    <par>Selector that selects all attribute nodes and nodes inside of attributes.</par> 
    675780    <example> 
    676781    <tty> 
    677782    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
    678783    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
    679     <prompt>>>> </prompt><input>for node in doc.walknode(xfind.inattr & xsc.Text):</input> 
     784    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.inattr &amp; xsc.Text</em>):</input> 
    680785    <prompt>... </prompt><input>\tprint node.bytes()</input> 
    681786    <prompt>... </prompt><input></input> 
     
    698803 
    699804class Combinator(Selector): 
    700     pass 
     805    """ 
     806    <par>A <class>Combinator</class> is a selector that combines two or more other 
     807    selectors in a certain way.</par> 
     808    """ 
    701809 
    702810 
    703811class BinaryCombinator(Combinator): 
     812    """ 
     813    <par>A <class>BinaryCombinator</class> is a combinator that combines two selector: 
     814    the left hand selector and the right hand selector.</par> 
     815    """ 
    704816    reprsymbol = None 
    705817 
     
    719831 
    720832class ChildCombinator(BinaryCombinator): 
     833    """ 
     834    <par>A <class>ChildCombinator</class> is a <class>BinaryCombinator</class>. 
     835    To match the <class>ChildCombinator</class> the node must match the 
     836    right hand selector and it's immediate parent must match the left hand 
     837    selector (i.e. it works similar to the <lit>&gt;</lit> combinator in &css; 
     838    or the <lit>/</lit> combinator in XPath.</par> 
     839 
     840    <par><class>ChildCombinator</class>s can be created via the division operator:</par> 
     841 
     842    <example> 
     843    <tty> 
     844    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     845    <prompt>>>> </prompt><input>from ll.xist.ns import html</input> 
     846    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     847    <prompt>>>> </prompt><input>for node in doc.walknode(<em>html.a/html.img</em>):</input> 
     848    <prompt>... </prompt><input>\tprint node.bytes()</input> 
     849    <prompt>... </prompt><input></input> 
     850    <![CDATA[<img src="http://www.python.org/images/python-logo.gif" alt="homepage" id="logo" border="0" /> 
     851    <img id="skiptonav" alt="skip to navigation" src="http://www.python.org/images/trans.gif" border="0" /> 
     852    <img id="skiptocontent" alt="skip to content" src="http://www.python.org/images/trans.gif" border="0" /> 
     853    <img alt="success story photo" class="success" src="http://www.python.org/images/success/nasa.jpg" />]]> 
     854    </tty> 
     855    </example> 
     856    """ 
    721857    def match(self, path): 
    722858        if path and self.right.match(path): 
     
    731867 
    732868class DescendantCombinator(BinaryCombinator): 
     869    """ 
     870    <par>A <class>DescendantCombinator</class> is a <class>BinaryCombinator</class>. 
     871    To match the <class>DescendantCombinator</class> the node must match the 
     872    right hand selector and any of it's ancestor nodes must match the left hand 
     873    selector (i.e. it works similar to the descendant combinator in &css; 
     874    or the <lit>//</lit> combinator in XPath.</par> 
     875 
     876    <par><class>DescendantCombinator</class>s can be created via the floor division 
     877    operator <lit>//</lit>:</par> 
     878 
     879    <example> 
     880    <tty> 
     881    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     882    <prompt>>>> </prompt><input>from ll.xist.ns import html</input> 
     883    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     884    <prompt>>>> </prompt><input>for node in doc.walknode(<em>html.div//html.img</em>):</input> 
     885    <prompt>... </prompt><input>\tprint node.bytes()</input> 
     886    <prompt>... </prompt><input></input> 
     887    <![CDATA[<img id="skiptonav" alt="skip to navigation" src="http://www.python.org/images/trans.gif" border="0" /> 
     888    <img id="skiptocontent" alt="skip to content" src="http://www.python.org/images/trans.gif" border="0" /> 
     889    <img alt="success story photo" class="success" src="http://www.python.org/images/success/nasa.jpg" />]]> 
     890    </tty> 
     891    </example> 
     892    """ 
    733893    def match(self, path): 
    734894        if path and self.right.match(path):