cssselect

cssselect is a small, focused Python library that parses CSS3 selector syntax and compiles it into equivalent XPath 1.0 expressions. Those expressions can then be handed to lxml or any other XPath-capable engine to find matching elements in an XML or HTML document, letting developers query documents with familiar CSS syntax instead of hand-writing XPath.

Originally extracted from lxml’s cssselect module and now maintained under the Scrapy organization, the library underpins CSS-selector support in tools like Scrapy and Parsel. It has no runtime dependencies of its own and ships a fully typed API (py.typed), making it easy to embed inside larger scraping or document-processing pipelines.

What You Get

• A CSS3 selector parser producing an inspectable AST via parse()
• A translator (GenericTranslator, HTMLTranslator) converting parsed selectors into XPath 1.0 expressions
• HTML-specific extensions (case-insensitive attribute matching, :hover/:visited handling) via HTMLTranslator
• A dependency-free, fully typed (py.typed) implementation with no lxml requirement at import time
• A large regression test suite (1,500+ lines) covering pseudo-classes, combinators, and edge-case selectors

Common Use Cases

• Powering CSS-selector support inside web scraping frameworks (it is the selector engine behind Scrapy/Parsel)
• Letting XML/HTML processing scripts select nodes with div.class > a[href]-style CSS instead of writing raw XPath
• Building custom document-querying tools that need a CSS-to-XPath bridge without depending on a full browser engine
• Validating or debugging CSS selectors by inspecting the XPath they compile to

Under The Hood

Architecture - the library is a two-stage compiler: parser.py (1,046 lines) tokenizes and parses CSS3 selector strings into a small AST of selector/combinator objects, and xpath.py (929 lines) walks that AST to emit XPath 1.0 strings via GenericTranslator/HTMLTranslator classes exposed through the 36-line __init__.py façade (parse, GenericTranslator().css_to_xpath()). Tech Stack - pure Python with zero runtime dependencies, a pyproject.toml-based build declaring BSD-3-Clause licensing, and no lxml requirement at import time even though lxml is the library’s primary downstream consumer. Code Quality - tests/test_cssselect.py is a 1,540-line pytest suite (larger than the combined 2,011 lines of source), exercising pseudo-classes, attribute selectors, combinators, and HTML-specific quirks in detail, indicating high confidence in correctness for a small, algorithmically dense codebase. API Design - the public surface is intentionally minimal (parse() plus two translator classes), so consumers get CSS-to-XPath translation with almost no boilerplate, and the shipped py.typed marker gives static type checkers full visibility into the API.