Pyjo.DOM.CSS - CSS selector engine

from Pyjo.DOM.CSS import CSS

# Select elements from DOM tree
css = CSS(tree=tree)
elements = css.select('h1, h2, h3')

# Or import the module, as in Google Python Style Guide

import Pyjo.DOM.CSS

# Select elements from DOM tree
css = Pyjo.DOM.CSS.new(tree=tree)
elements = css.select('h1, h2, h3')

Pyjo.DOM.CSS is the CSS selector engine used by Pyjo.DOM, based on the HTML Living Standard and Selectors Level 3.

Selectors

All CSS selectors that make sense for a standalone parser are supported.

*

Any element.

all = css.select('*')

E

An element of type E.

title = css.select('title')

E[foo]

An E element with a foo attribute.

links = css.select('a[href]')

E[foo="bar"]

An E element whose foo attribute value is exactly equal to bar.

case_sensitive = css.select('input[type="hidden"]')
case_sensitive = css.select('input[type=hidden]')

E[foo="bar" i]

An E element whose foo attribute value is exactly equal to any (ASCII-range) case-permutation of bar. Note that this selector is EXPERIMENTAL and might change without warning!

case_insensitive = css.select('input[type="hidden" i]')
case_insensitive = css.select('input[type=hidden i]')
case_insensitive = css.select('input[class~="foo" i]')

This selector is part of Selectors Level 4, which is still a work in progress.

E[foo="bar" s]

An E element whose foo attribute value is exactly and case-sensitively equal to bar. Note that this selector is EXPERIMENTAL and might change without warning!

case_sensitive = css.select('input[type="hidden" s]')

This selector is part of Selectors Level 4, which is still a work in progress.

E[foo~="bar"]

An E element whose foo attribute value is a list of whitespace-separated values, one of which is exactly equal to bar.

foo = css.select('input[class~="foo"]')
foo = css.select('input[class~=foo]')

E[foo^="bar"]

An E element whose foo attribute value begins exactly with the string bar.

begins_with = css.select('input[name^="f"]')
begins_with = css.select('input[name^=f]')

E[foo$="bar"]

An E element whose foo attribute value ends exactly with the string bar.

ends_with = css.select('input[name$="o"]')
ends_with = css.select('input[name$=o]')

E[foo*="bar"]

An E element whose foo attribute value contains the substring bar.

contains = css.select('input[name*="fo"]')
contains = css.select('input[name*=fo]')

E[foo|="en"]

An E element whose foo attribute has a hyphen-separated list of values beginning (from the left) with en.

english = css.select('link[hreflang|=en]')

E:root

An E element, root of the document.

root = css.select(':root')

E:nth-child(n)

An E element, the n-th child of its parent.

third = css.select('div:nth-child(3)')
odd = css.select('div:nth-child(odd)')
even = css.select('div:nth-child(even)')
top3 = css.select('div:nth-child(-n+3)')

E:nth-last-child(n)

An E element, the n-th child of its parent, counting from the last one.

third = css.select('div:nth-last-child(3)')
odd = css.select('div:nth-last-child(odd)')
even = css.select('div:nth-last-child(even)')
bottom3 = css.select('div:nth-last-child(-n+3)')

E:nth-of-type(n)

An E element, the n-th sibling of its type.

third = css.select('div:nth-of-type(3)')
odd = css.select('div:nth-of-type(odd)')
even = css.select('div:nth-of-type(even)')
top3 = css.select('div:nth-of-type(-n+3)')

E:nth-last-of-type(n)

An E element, the n-th sibling of its type, counting from the last one.

third = css.select('div:nth-last-of-type(3)')
odd = css.select('div:nth-last-of-type(odd)')
even = css.select('div:nth-last-of-type(even)')
bottom3 = css.select('div:nth-last-of-type(-n+3)')

E:first-child

An E element, first child of its parent.

first = css.select('div p:first-child')

E:last-child

An E element, last child of its parent.

last = css.select('div p:last-child')

E:first-of-type

An E element, first sibling of its type.

first = css.select('div p:first-of-type')

E:last-of-type

An E element, last sibling of its type.

last = css.select('div p:last-of-type')

E:only-child

An E element, only child of its parent.

lonely = css.select('div p:only-child')

E:only-of-type

An E element, only sibling of its type.

lonely = css.select('div p:only-of-type')

E:empty

An E element that has no children (including text nodes).

empty = css.select(':empty')

E:visited

Alias for E:link.

E:scope

An E element being a designated reference element. Note that this selector is EXPERIMENTAL and might change without warning!

scoped = css.select('a:not(:scope > a)')
scoped = css.select('div :scope p')
scoped = css.select('~ p')

This selector is part of Selectors Level 4, which is still a work in progress.

E:checked

A user interface element E which is checked (for instance a radio-button or checkbox).

input = css.select(':checked')

E.warning

An E element whose class is “warning”.

warning = css.select('div.warning')

E#myid

An E element with ID equal to “myid”.

foo = css.select('div#foo')

E:not(s1, s2)

An E element that does not match either compound selector s1 or compound selector s2. Note that support for compound selectors is EXPERIMENTAL and might change without warning!

others = css.select('div p:not(:first-child, :last-child)')

Support for compound selectors was added as part of Selectors Level 4, which is still a work in progress.

E:is(s1, s2)

An E element that matches compound selector s1 and/or compound selector s2. Note that this selector is EXPERIMENTAL and might change without warning!

headers = css.select(':is(section, article, aside, nav) h1')

This selector is part of Selectors Level 4, which is still a work in progress.

E:has(rs1, rs2)

An E element, if either of the relative selectors rs1 or rs2, when evaluated with E as the :scope elements, match an element. Note that this selector is EXPERIMENTAL and might change without warning!

link = css.select('a:has(> img)')

This selector is part of Selectors Level 4, which is still a work in progress. Also be aware that this feature is currently marked at-risk, so there is a high chance that it will get removed completely.

E:text(string_or_regex)

An E element containing text content that substring matches string_or_regex case-insensitively or that regex matches string_or_regex. For regular expressions use the format :text(/.../). Note that this selector is EXPERIMENTAL and might change without warning!

# Substring match
login = css.select(':text(Log in)')

# Regex match
login = css.select(':text(/Log ?in/)')

# Regex match (case-insensitive)
login = css.select(':text(/(?i:Log ?in)/)')

This is a custom selector for Pyjo.DOM and not part of any spec.

A|E

An E element that belongs to the namespace alias A from CSS Namespaces Module Level 3. Keyword arguments passed to selector methods are used to declare namespace aliases.

elem = css.select('lq|elem', lq='http://example.com/q-markup')

Using an empty alias searches for an element that belongs to no namespace.

div = css.select('|div')

E F

An F element descendant of an E element.

headlines = css.select('div h1')

E > F

An F element child of an E element.

headlines = css.select('html > body > div > h1')

E + F

An F element immediately preceded by an E element.

second = css.select('h1 + h2')

E ~ F

An F element preceded by an E element.

second = css.select('h1 ~ h2')

E, F, G

Elements of type E, F and G.

headlines = css.select('h1, h2, h3')

E[foo=bar][bar=baz]

An E element whose attributes match all following attribute selectors.

links = css.select('a[foo^=b][foo$=ar]')

Debugging

You can set the PYJO_DOM_CSS_DEBUG environment variable to get some advanced diagnostics information printed to sys.stderr.

PYJO_DOM_CSS_DEBUG=1

See also

Pyjoyment, https://mojolicious.org.

Ported from Mojo::DOM::CSS of Mojolicious 9.53.

Classes

class Pyjo.DOM.CSS.Pyjo_DOM_CSS(tree: Tree | None = None)[source]

Pyjo.DOM.CSS inherits all methods from Pyjo.Base and implements the following new ones.

matches(css: Anything, **ns: str) → bool | None[source]
boolean = css.matches('head > title')
boolean = css.matches('svg|line', svg='http://www.w3.org/2000/svg')

Check if first node in tree matches the CSS selector. Trailing keyword arguments can be used to declare xml namespace aliases.

select(css: Anything, **ns: str) → list[Tree][source]
results = css.select('head > title')
results = css.select('svg|line', svg='http://www.w3.org/2000/svg')

Run CSS selector against tree. Trailing keyword arguments can be used to declare xml namespace aliases.

select_iter(css: Anything, **ns: str) → Iterator[Tree][source]
results = css.select_iter('head > title')
results = css.select_iter('svg|line', svg='http://www.w3.org/2000/svg')

Same as select(), but returns an iterator, which runs the CSS selector against tree as its results are taken, in the order of the document.

select_one(css: Anything, **ns: str) → Tree | None[source]
result = css.select_one('head > title')
result = css.select_one('svg|line', svg='http://www.w3.org/2000/svg')

Run CSS selector against tree and stop as soon as the first node matched. Trailing keyword arguments can be used to declare xml namespace aliases.

tree: Tree | None
tree = css.tree
css.tree = ['root']

Document Object Model. Note that this structure should only be used very carefully since it is very dynamic.