Commits

Christian Wyglendowski committed 84b61de

Moved many of the traversal doctests from README.txt into method docstrings.

Comments (0)

Files changed (2)

pyquery/README.txt

 Traversing
 ----------
 
-Some jQuery traversal methods are supported.  For instance, you can filter the selection list
-using a string selector::
+Some jQuery traversal methods are supported.  Here are a few examples.
+
+You can filter the selection list using a string selector::
 
     >>> d('p').filter('.hello')
     [<p#hello.hello>]
 
-Filtering can also be done using a function::
-
-    >>> d('p').filter(lambda i: i == 1)
-    [<p#test>]
-
-Filtering functions can refer to the current element as 'this', like in jQuery::
-
-    >>> d('p').filter(lambda i: pq(this).text() == 'you know Python rocks')
-    [<p#hello.hello>]
-
-The opposite of filter is `not_` - it returns the items that don't match the selector::
-
-    >>> d('p').not_('.hello')
-    [<p#test>]
-
-You can map a callable onto a PyQuery and get a mutated result. The result can
-contain any items, not just elements::
-
-    >>> d('p').map(lambda i, e: pq(e).text())
-    ['you know Python rocks', 'hello python !']
-
-Like the filter method, map callbacks can reference the current item as this::
-
-    >>> d('p').map(lambda i, e: len(pq(this).text()))
-    [21, 14]
-
-The map callback can also return a list, which will extend the resulting
-PyQuery::
-
-    >>> d('p').map(lambda i, e: pq(this).text().split())
-    ['you', 'know', 'Python', 'rocks', 'hello', 'python', '!']
-
 It is possible to select a single element with eq::
 
     >>> d('p').eq(0)
     [<p#hello.hello>]
 
-The `is_` method lets you query if any current elements match the selector::
-
-    >>> d('p').eq(0).is_('.hello')
-    True
-    >>> d('p').eq(1).is_('.hello')
-    False
-
-hasClass allows for checking for the presence of a class by name::
-
-    >>> d('p').eq(0).hasClass('hello')
-    True
-    >>> d('p').eq(1).hasClass('hello')
-    False
-
 You can find nested elements::
 
     >>> d('p').find('a')

pyquery/pyquery.py

     ##############
 
     def filter(self, selector):
-        """Filter elements in self using selector (string or function)."""
+        """Filter elements in self using selector (string or function).
+
+            >>> d = PyQuery('<p class="hello">Hi</p><p>Bye</p>')
+            >>> d('p')
+            [<p.hello>, <p>]
+            >>> d('p').filter('.hello')
+            [<p.hello>]
+            >>> d('p').filter(lambda i: i == 1)
+            [<p>]
+            >>> d('p').filter(lambda i: PyQuery(this).text() == 'Hi')
+            [<p.hello>]
+        """
         if not callable(selector):
             return self.__class__(selector, self, **dict(parent=self))
         else:
             return self.__class__(elements, **dict(parent=self))
 
     def not_(self, selector):
-        """Return elements that don't match the given selector."""
+        """Return elements that don't match the given selector.
+
+            >>> d = PyQuery('<p class="hello">Hi</p><p>Bye</p><div></div>')
+            >>> d('p').not_('.hello')
+            [<p>]
+        """
         exclude = set(self.__class__(selector, self))
         return self.__class__([e for e in self if e not in exclude], **dict(parent=self))
 
     def is_(self, selector):
-        """Returns True if selector matches at least one current element, else False."""
+        """Returns True if selector matches at least one current element, else False.
+            >>> d = PyQuery('<p class="hello">Hi</p><p>Bye</p><div></div>')
+            >>> d('p').eq(0).is_('.hello')
+            True
+            >>> d('p').eq(1).is_('.hello')
+            False
+        """
         return bool(self.__class__(selector, self))
 
     def find(self, selector):
-        """Find elements using selector traversing down from self."""
+        """Find elements using selector traversing down from self.
+
+            >>> m = '<p><span><em>Whoah!</em></span></p><p><em> there</em></p>'
+            >>> d = PyQuery(m)
+            >>> d('p').find('em')
+            [<em>, <em>]
+            >>> d('p').eq(1).find('em')
+            [<em>]
+        """
         xpath = selector_to_xpath(selector)
         results = [child.xpath(xpath) for tag in self for child in tag.getchildren()]
         # Flatten the results
         return self.__class__(elements, **dict(parent=self))
 
     def eq(self, index):
-        """Return PyQuery of only the element with the provided index."""
+        """Return PyQuery of only the element with the provided index.
+
+            >>> d = PyQuery('<p class="hello">Hi</p><p>Bye</p><div></div>')
+            >>> d('p').eq(0)
+            [<p.hello>]
+            >>> d('p').eq(1)
+            [<p>]
+        """
         return self.__class__([self[index]], **dict(parent=self))
 
     def each(self, func):
 
         func should take two arguments - 'index' and 'element'.  Elements can
         also be referred to as 'this' inside of func.
+
+            >>> d = PyQuery('<p class="hello">Hi there</p><p>Bye</p><br />')
+            >>> d('p').map(lambda i, e: PyQuery(e).text())
+            ['Hi there', 'Bye']
+
+            >>> d('p').map(lambda i, e: len(PyQuery(this).text()))
+            [8, 3]
+
+            >>> d('p').map(lambda i, e: PyQuery(this).text().split())
+            ['Hi', 'there', 'Bye']
         """
         items = []
         try:
         return len(self)
 
     def end(self):
+        """Break out of a level of traversal and return to the parent level.
+
+            >>> m = '<p><span><em>Whoah!</em></span></p><p><em> there</em></p>'
+            >>> d = PyQuery(m)
+            >>> d('p').eq(1).find('em').end().end()
+            [<p>, <p>]
+        """
         return self._parent
 
     ##############
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.