pyquery – PyQuery complete API

class pyquery.pyquery.PyQuery(*args, **kwargs)

The main class

class Fn

Hook for defining custom function (like the jQuery.fn):

>>> fn = lambda: this.map(lambda i, el: PyQuery(this).outerHtml())
>>> PyQuery.fn.listOuterHtml = fn
>>> S = PyQuery(
...   '<ol>   <li>Coffee</li>   <li>Tea</li>   <li>Milk</li>   </ol>')
>>> S('li').listOuterHtml()
['<li>Coffee</li>', '<li>Tea</li>', '<li>Milk</li>']

addClass(value)

Alias for add_class()

add_class(value)

Add a css class to elements:

>>> d = PyQuery('<div></div>')
>>> d.add_class('myclass')
[<div.myclass>]
>>> d.addClass('myclass')
[<div.myclass>]

after(value)

add value after nodes

append(value)

append value to each nodes

appendTo(value)

Alias for append_to()

append_to(value)

append nodes to value

base_url

Return the url of current html document or None if not available.

before(value)

insert value before nodes

children(selector=None)

Filter elements that are direct children of self using optional selector:

>>> d = PyQuery('<span><p class="hello">Hi</p><p>Bye</p></span>')
>>> d
[<span>]
>>> d.children()
[<p.hello>, <p>]
>>> d.children('.hello')
[<p.hello>]

clone()

return a copy of nodes

closest(selector=None)

>>> d = PyQuery(
...  '<div class="hello"><p>This is a '
...  '<strong class="hello">test</strong></p></div>')
>>> d('strong').closest('div')
[<div.hello>]
>>> d('strong').closest('.hello')
[<strong.hello>]
>>> d('strong').closest('form')
[]

contents()

Return contents (with text nodes):

>>> d = PyQuery('hello <b>bold</b>')
>>> d.contents()  # doctest: +ELLIPSIS
['hello ', <Element b at ...>]

each(func)

apply func on each nodes

empty()

remove nodes content

encoding

return the xml encoding of the root element

end()

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>]

eq(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>]
>>> d('p').eq(2)
[]

extend(other)

Extend with another PyQuery object

filter(selector)

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>]
>>> d('p').filter(lambda i, this: PyQuery(this).text() == 'Hi')
[<p.hello>]

find(selector)

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>]

hasClass(name)

Alias for has_class()

has_class(name)

Return True if element has class:

>>> d = PyQuery('<div class="myclass"></div>')
>>> d.has_class('myclass')
True
>>> d.hasClass('myclass')
True

height(value=<NoDefault>)

set/get height of element

hide()

Add display:none to elements style:

>>> print(PyQuery('<div style="display:none;"/>').hide())
<div style="display: none"/>

html(value=<NoDefault>, **kwargs)

Get or set the html representation of sub nodes.

Get the text value:

>>> d = PyQuery('<div><span>toto</span></div>')
>>> print(d.html())
<span>toto</span>

Extra args are passed to lxml.etree.tostring:

>>> d = PyQuery('<div><span></span></div>')
>>> print(d.html())
<span/>
>>> print(d.html(method='html'))
<span></span>

Set the text value:

>>> d.html('<span>Youhou !</span>')
[<div>]
>>> print(d)
<div><span>Youhou !</span></div>

insertAfter(value)

Alias for insert_after()

insertBefore(value)

Alias for insert_before()

insert_after(value)

insert nodes after value

insert_before(value)

insert nodes before value

is_(selector)

Returns True if selector matches at least one current element, else False:

>>> d = PyQuery('<p class="hello"><span>Hi</span></p><p>Bye</p>')
>>> d('p').eq(0).is_('.hello')
True

>>> d('p').eq(0).is_('span')
False

>>> d('p').eq(1).is_('.hello')
False

items(selector=None)

Iter over elements. Return PyQuery objects:

>>> d = PyQuery('<div><span>foo</span><span>bar</span></div>')
>>> [i.text() for i in d.items('span')]
['foo', 'bar']
>>> [i.text() for i in d('span').items()]
['foo', 'bar']
>>> list(d.items('a')) == list(d('a').items())
True

make_links_absolute(base_url=None)

Make all links absolute.

map(func)

Returns a new PyQuery after transforming current items with 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']

nextAll(selector=None)

Alias for next_all()

nextUntil(selector, filter_=None)

Alias for next_until()

next_all(selector=None)

>>> h = '<span><p class="hello">Hi</p><p>Bye</p><img scr=""/></span>'
>>> d = PyQuery(h)
>>> d('p:last').next_all()
[<img>]
>>> d('p:last').nextAll()
[<img>]

next_until(selector, filter_=None)

>>> h = '''
... <h2>Greeting 1</h2>
... <p>Hello!</p><p>World!</p>
... <h2>Greeting 2</h2><p>Bye!</p>
... '''
>>> d = PyQuery(h)
>>> d('h2:first').nextUntil('h2')
[<p>, <p>]

not_(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>]

outerHtml(method='html')

Alias for outer_html()

outer_html(method='html')

Get the html representation of the first selected element:

>>> d = PyQuery('<div><span class="red">toto</span> rocks</div>')
>>> print(d('span'))
<span class="red">toto</span> rocks
>>> print(d('span').outer_html())
<span class="red">toto</span>
>>> print(d('span').outerHtml())
<span class="red">toto</span>

>>> S = PyQuery('<p>Only <b>me</b> & myself</p>')
>>> print(S('b').outer_html())
<b>me</b>

parents(selector=None)

>>> d = PyQuery('<span><p class="hello">Hi</p><p>Bye</p></span>')
>>> d('p').parents()
[<span>]
>>> d('.hello').parents('span')
[<span>]
>>> d('.hello').parents('p')
[]

prepend(value)

prepend value to nodes

prependTo(value)

Alias for prepend_to()

prepend_to(value)

prepend nodes to value

prevAll(selector=None)

Alias for prev_all()

prev_all(selector=None)

>>> h = '<span><p class="hello">Hi</p><p>Bye</p><img scr=""/></span>'
>>> d = PyQuery(h)
>>> d('p:last').prev_all()
[<p.hello>]
>>> d('p:last').prevAll()
[<p.hello>]

remove(expr=<NoDefault>)

Remove nodes:

>>> h = (
... '<div>Maybe <em>she</em> does <strong>NOT</strong> know</div>'
... )
>>> d = PyQuery(h)
>>> d('strong').remove()
[<strong>]
>>> print(d)
<div>Maybe <em>she</em> does  know</div>

removeAttr(name)

Alias for remove_attr()

removeClass(value)

Alias for remove_class()

remove_attr(name)

Remove an attribute:

>>> d = PyQuery('<div id="myid"></div>')
>>> d.remove_attr('id')
[<div>]
>>> d.removeAttr('id')
[<div>]

remove_class(value)

Remove a css class to elements:

>>> d = PyQuery('<div class="myclass"></div>')
>>> d.remove_class('myclass')
[<div>]
>>> d.removeClass('myclass')
[<div>]

remove_namespaces()

Remove all namespaces:

>>> doc = PyQuery('<foo xmlns="http://example.com/foo"></foo>')
>>> doc
[<{http://example.com/foo}foo>]
>>> doc.remove_namespaces()
[<foo>]

replaceAll(expr)

Alias for replace_all()

replaceWith(value)

Alias for replace_with()

replace_all(expr)

replace nodes by expr

replace_with(value)

replace nodes by value:

>>> doc = PyQuery("<html><div /></html>")
>>> node = PyQuery("<span />")
>>> child = doc.find('div')
>>> child.replace_with(node)
[<div>]
>>> print(doc)
<html><span/></html>

root

return the xml root element

serialize()

Serialize form elements as a URL-encoded string.

>>> h = (
... '<form><input name="order" value="spam">'
... '<input name="order2" value="baked beans"></form>'
... )
>>> d = PyQuery(h)
>>> d.serialize()
'order=spam&order2=baked%20beans'

serializeArray()

Alias for serialize_array()

serializeDict()

Alias for serialize_dict()

serializePairs()

Alias for serialize_pairs()

serialize_array()

Serialize form elements as an array of dictionaries, whose structure mirrors that produced by the jQuery API. Notably, it does not handle the deprecated keygen form element.

>>> d = PyQuery('<form><input name="order" value="spam"></form>')
>>> d.serialize_array() == [{'name': 'order', 'value': 'spam'}]
True
>>> d.serializeArray() == [{'name': 'order', 'value': 'spam'}]
True

serialize_dict()

Serialize form elements as an ordered dictionary. Multiple values corresponding to the same input name are concatenated into one list.

>>> d = PyQuery('''<form>
...             <input name="order" value="spam">
...             <input name="order" value="eggs">
...             <input name="order2" value="ham">
...             </form>''')
>>> d.serialize_dict()
OrderedDict([('order', ['spam', 'eggs']), ('order2', 'ham')])
>>> d.serializeDict()
OrderedDict([('order', ['spam', 'eggs']), ('order2', 'ham')])

serialize_pairs()

Serialize form elements as an array of 2-tuples conventional for typical URL-parsing operations in Python.

>>> d = PyQuery('<form><input name="order" value="spam"></form>')
>>> d.serialize_pairs()
[('order', 'spam')]
>>> d.serializePairs()
[('order', 'spam')]

show()

Add display:block to elements style:

>>> print(PyQuery('<div />').show())
<div style="display: block"/>

siblings(selector=None)

>>> h = '<span><p class="hello">Hi</p><p>Bye</p><img scr=""/></span>'
>>> d = PyQuery(h)
>>> d('.hello').siblings()
[<p>, <img>]
>>> d('.hello').siblings('img')
[<img>]

text(value=<NoDefault>, **kwargs)

Get or set the text representation of sub nodes.

Get the text value:

>>> doc = PyQuery('<div><span>toto</span><span>tata</span></div>')
>>> print(doc.text())
tototata
>>> doc = PyQuery('''<div><span>toto</span>
...               <span>tata</span></div>''')
>>> print(doc.text())
toto tata

Get the text value, without squashing newlines:

>>> doc = PyQuery('''<div><span>toto</span>
...               <span>tata</span></div>''')
>>> print(doc.text(squash_space=False))
toto
tata

Set the text value:

>>> doc.text('Youhou !')
[<div>]
>>> print(doc)
<div>Youhou !</div>

toggleClass(value)

Alias for toggle_class()

toggle_class(value)

Toggle a css class to elements

>>> d = PyQuery('<div></div>')
>>> d.toggle_class('myclass')
[<div.myclass>]
>>> d.toggleClass('myclass')
[<div>]

val(value=<NoDefault>)

Set the attribute value:

>>> d = PyQuery('<input />')
>>> d.val('Youhou')
[<input>]

Get the attribute value:

>>> d.val()
'Youhou'

Set the selected values for a select element with the multiple attribute:

>>> d = PyQuery('''
...             <select multiple>
...                 <option value="you"><option value="hou">
...             </select>
...             ''')
>>> d.val(['you', 'hou'])
[<select>]

Get the selected values for a select element with the multiple attribute:

>>> d.val()
['you', 'hou']

width(value=<NoDefault>)

set/get width of element

wrap(value)

A string of HTML that will be created on the fly and wrapped around each target:

>>> d = PyQuery('<span>youhou</span>')
>>> d.wrap('<div></div>')
[<div>]
>>> print(d)
<div><span>youhou</span></div>

wrapAll(value)

Alias for wrap_all()

wrap_all(value)

Wrap all the elements in the matched set into a single wrapper element:

>>> d = PyQuery('<div><span>Hey</span><span>you !</span></div>')
>>> print(d('span').wrap_all('<div id="wrapper"></div>'))
<div id="wrapper"><span>Hey</span><span>you !</span></div>

>>> d = PyQuery('<div><span>Hey</span><span>you !</span></div>')
>>> print(d('span').wrapAll('<div id="wrapper"></div>'))
<div id="wrapper"><span>Hey</span><span>you !</span></div>

xhtml_to_html()

Remove xhtml namespace:

>>> doc = PyQuery(
...         '<html xmlns="http://www.w3.org/1999/xhtml"></html>')
>>> doc
[<{http://www.w3.org/1999/xhtml}html>]
>>> doc.xhtml_to_html()
[<html>]