cssselect is a BSD-licensed Python library that parses CSS3 Selectors and translates them into XPath 1.0 expressions. These XPath expressions can then be used with an XPath engine like lxml to find matching elements in XML or HTML documents. The library is currently at version 1.4.0 and maintains an active development cycle with releases published on PyPI.
Install & Compatibility
Where this runs
tested against v1.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.032s · 17.9MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.5s · import 0.028s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
from cssselect import GenericTranslator
from cssselect import HTMLTranslator
from cssselect import SelectorError
The `css_to_xpath` function is directly available from the top-level `cssselect` package.
from cssselect import css_to_xpath
from cssselect import SelectorSyntaxError
This quickstart demonstrates how to use `cssselect` to translate a CSS selector into an XPath 1.0 expression and then apply it to an HTML document using `lxml` to find matching elements. It highlights the use of `HTMLTranslator` for HTML-specific translations.
from lxml.etree import fromstring
from cssselect import HTMLTranslator, SelectorError
html_doc = '''
<div id="outer">
<p class="content">
<span>Text 1</span>
</p>
<div id="inner" class="content body">
Text 2
<span>Text 3</span>
</div>
</div>
'''
try:
# Use HTMLTranslator for HTML documents for better pseudo-class handling
translator = HTMLTranslator()
xpath_expression = translator.css_to_xpath('div.content > span')
print(f"Generated XPath: {xpath_expression}")
document = fromstring(html_doc)
# Find all elements matching the XPath expression
matches = document.xpath(xpath_expression)
for element in matches:
print(f"Matched element tag: {element.tag}, text: {element.text.strip() if element.text else ''}")
except SelectorError as e:
print(f"Invalid CSS selector: {e}")
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.