Changeset 2807:39af4db99b36 in livinglogic.python.xist

Show
Ignore:
Timestamp:
07/25/07 13:25:39 (12 years ago)
Author:
Walter Doerwald <walter@…>
Branch:
default
Message:

Add docstrings for all Combinator subclasses.

Files:
1 modified

Legend:

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

    r2806 r2807  
    804804class Combinator(Selector): 
    805805    """ 
    806     <par>A <class>Combinator</class> is a selector that combines two or more other 
    807     selectors in a certain way.</par> 
     806    <par>A <class>Combinator</class> is a selector that transforms one or combines 
     807    two or more other selectors in a certain way.</par> 
    808808    """ 
    809809 
     
    906906 
    907907class AdjacentSiblingCombinator(BinaryCombinator): 
     908    """ 
     909    <par>A <class>AdjacentSiblingCombinator</class> is a <class>BinaryCombinator</class>. 
     910    To match the <class>AdjacentSiblingCombinator</class> the node must match the 
     911    right hand selector and the immediately preceding sibling must match the left 
     912    hand selector.</par> 
     913 
     914    <par><class>AdjacentSiblingCombinator</class>s can be created via the 
     915    multiplication operator <lit>*</lit>. The following example outputs all links 
     916    inside those <class>p</class> elements that immediately follow a 
     917    <class>h2</class> element:</par> 
     918 
     919    <example> 
     920    <tty> 
     921    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     922    <prompt>>>> </prompt><input>from ll.xist.ns import html</input> 
     923    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     924    <prompt>>>> </prompt><input>for node in doc.walknode(<em>html.h2*html.p/html.a</em>):</input> 
     925    <prompt>... </prompt><input>\tprint node.bytes()</input> 
     926    <prompt>... </prompt><input></input> 
     927    <![CDATA[<a href="http://www.scipy.org/SciPy2007" class="reference">SciPy Conference</a> 
     928    <a href="https://www.enthought.com/scipy07/" class="reference">early registration</a> 
     929    <a href="http://www.europython.org/sections/registration_issues/how-to-register" class="reference">Online registration</a> 
     930    <a href="http://europython.org/" class="reference">EuroPython 2007</a> 
     931    <a href="http://www.osdc.com.au/papers/cfp.html" class="reference">Call For Papers</a> 
     932    <a href="http://www.swa.hpi.uni-potsdam.de/dls07/" class="reference">DLS 2007</a> 
     933    <a href="http://pythonpapers.cgpublisher.com/" class="reference">The Python Papers</a> 
     934    <a href="http://www.pyconuk.org/" class="reference">PyCon UK</a> 
     935    <a href="http://www.pyconuk.org/submit.html" class="reference">proposals for talks</a> 
     936    <a href="http://www.pycon.it/registration/" class="reference">registration online</a>]]> 
     937    </tty> 
     938    </example> 
     939    """ 
     940 
    908941    def match(self, path): 
    909942        if len(path) >= 2 and self.right.match(path): 
     
    926959 
    927960class GeneralSiblingCombinator(BinaryCombinator): 
     961    """ 
     962    <par>A <class>GeneralSiblingCombinator</class> is a <class>BinaryCombinator</class>. 
     963    To match the <class>GeneralSiblingCombinator</class> the node must match the 
     964    right hand selector and any of the preceding siblings must match the left 
     965    hand selector.</par> 
     966 
     967    <par><class>AdjacentSiblingCombinator</class>s can be created via the 
     968    exponentiation operator <lit>**</lit>. The following example outputs all links 
     969    that are not the first links inside their parent (i.e. they have another link 
     970    among their preceding siblings):</par> 
     971 
     972    <example> 
     973    <tty> 
     974    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     975    <prompt>>>> </prompt><input>from ll.xist.ns import html</input> 
     976    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     977    <prompt>>>> </prompt><input>for node in doc.walknode(<em>html.a**html.a</em>):</input> 
     978    <prompt>... </prompt><input>\tprint node.bytes()</input> 
     979    <prompt>... </prompt><input></input> 
     980    <![CDATA[<a href="http://www.python.org/about/success/ilm" class="reference">Industrial Light and Magic</a> 
     981    <a href="http://www.python.org/about/success/astra" class="reference">AstraZeneca</a> 
     982    <a href="http://www.python.org/about/success/honeywell" class="reference">Honeywell</a> 
     983    <a href="http://www.python.org/about/success" class="reference">and many others</a> 
     984    <a href="http://www.zope.org/">Zope</a>]]> 
     985    <rep>...</rep> 
     986    </tty> 
     987    </example> 
     988    """ 
     989 
    928990    def match(self, path): 
    929991        if len(path) >= 2 and self.right.match(path): 
     
    9431005 
    9441006class ChainedCombinator(Combinator): 
     1007    """ 
     1008    <par>A <class>ChainedCombinator</class> combines any number of other 
     1009    selectors.</par> 
     1010    """ 
     1011 
    9451012    reprsymbol = None 
    9461013 
     
    9591026 
    9601027class OrCombinator(ChainedCombinator): 
     1028    """ 
     1029    <par>An <class>OrCombinator</class> is a <class>ChainedCombinator</class> where 
     1030    the node must match at least one of the selectors to match the <class>OrCombinator</class>. 
     1031    An <class>OrCombinator</class> can be created with the binary or operator (<lit>|</lit>).</par> 
     1032 
     1033    <example> 
     1034    <tty> 
     1035    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     1036    <prompt>>>> </prompt><input>from ll.xist.ns import html</input> 
     1037    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     1038    <prompt>>>> </prompt><input>for node in doc.walknode(<em>xfind.hasattr("href") | xfind.hasattr("src")</em>):</input> 
     1039    <prompt>... </prompt><input>\tprint node.bytes()</input> 
     1040    <prompt>... </prompt><input></input> 
     1041    <![CDATA[<link type="application/rss+xml" title="RSS" rel="alternate" href="http://www.python.org/channews.rdf" /> 
     1042    <link media="screen" type="text/css" id="screen-switcher-stylesheet" rel="stylesheet" href="http://www.python.org/styles/screen-switcher-default.css" /> 
     1043    <link media="scReen" type="text/css" rel="stylesheet" href="http://www.python.org/styles/netscape4.css" /> 
     1044    <link media="print" type="text/css" rel="stylesheet" href="http://www.python.org/styles/print.css" /> 
     1045    <link media="screen" type="text/css" title="large text" rel="alternate stylesheet" href="http://www.python.org/styles/largestyles.css" /> 
     1046    <link media="screen" type="text/css" title="default fonts" rel="alternate stylesheet" href="http://www.python.org/styles/defaultfonts.css" /> 
     1047    <script src="http://www.python.org/js/iotbs2-key-directors-load.js" type="text/javascript"></script> 
     1048    <script src="http://www.python.org/js/iotbs2-directors.js" type="text/javascript"></script> 
     1049    <script src="http://www.python.org/js/iotbs2-core.js" type="text/javascript"></script> 
     1050    <a accesskey="1" id="logolink" href="http://www.python.org/"><img alt="homepage" src="http://www.python.org/images/python-logo.gif" id="logo" border="0" /></a>]]> 
     1051    <rep>...</rep> 
     1052    </tty> 
     1053    </example> 
     1054    """ 
     1055 
    9611056    def match(self, path): 
    9621057        return any(selector.match(path) for selector in self.selectors) 
     
    9691064 
    9701065class AndCombinator(ChainedCombinator): 
     1066    """ 
     1067    <par>An <class>AndCombinator</class> is a <class>ChainedCombinator</class> where 
     1068    the node must match all of the combined selectors to match the <class>AndCombinator</class>. 
     1069    An <class>AndCombinator</class> can be created with the binary and operator (<lit>&amp;</lit>).</par> 
     1070 
     1071    <example> 
     1072    <tty> 
     1073    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     1074    <prompt>>>> </prompt><input>from ll.xist.ns import html</input> 
     1075    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     1076    <prompt>>>> </prompt><input>for node in doc.walknode(<em>html.input & xfind.hasattr("id")</em>):</input> 
     1077    <prompt>... </prompt><input>\tprint node.bytes()</input> 
     1078    <prompt>... </prompt><input></input> 
     1079    <![CDATA[<input id="domains" name="domains" value="www.python.org" type="hidden" /> 
     1080    <input id="sitesearch" name="sitesearch" value="www.python.org" type="hidden" /> 
     1081    <input id="sourceid" name="sourceid" value="google-search" type="hidden" /> 
     1082    <input id="q" class="input-text" name="q" type="text" /> 
     1083    <input id="submit" value="search" name="submit" type="submit" class="input-button" />]]> 
     1084    </tty> 
     1085    </example> 
     1086    """ 
     1087 
    9711088    def match(self, path): 
    9721089        return all(selector.match(path) for selector in self.selectors) 
     
    9791096 
    9801097class NotCombinator(Combinator): 
     1098    """ 
     1099    <par>A <class>NotCombinator</class> inverts the selection logic of the 
     1100    underlying selector, i.e. a node matches only if it does not match the underlying 
     1101    selector. A <class>NotCombinator</class> can be created with the unary inversion operator (<lit>~</lit>).</par> 
     1102 
     1103    <par>The following example outputs all images that don't have a <lit>border</lit> attribute:</par> 
     1104 
     1105    <example> 
     1106    <tty> 
     1107    <prompt>>>> </prompt><input>from ll.xist import parsers, xfind</input> 
     1108    <prompt>>>> </prompt><input>from ll.xist.ns import html</input> 
     1109    <prompt>>>> </prompt><input>doc = parsers.parseURL("http://www.python.org", tidy=True)</input> 
     1110    <prompt>>>> </prompt><input>for node in doc.walknode(<em>html.img &amp; ~xfind.hasattr("border")</em>):</input> 
     1111    <prompt>... </prompt><input>\tprint node.bytes()</input> 
     1112    <prompt>... </prompt><input></input> 
     1113    <![CDATA[<img alt="success story photo" class="success" src="http://www.python.org/images/success/nasa.jpg" />]]> 
     1114    </tty> 
     1115    </example> 
     1116    """ 
     1117 
    9811118    def __init__(self, selector): 
    9821119        self.selector = selector