Selector Reference

Every pseudo-class and attribute operator registered in the selector engine. Generated from natural_pdf/selectors/registry.py, natural_pdf/selectors/_clauses.py, and the parser dispatch tables in natural_pdf/selectors/parser.py.

Pseudo-classes (element filters)

Applied with a colon, e.g. text:bold. These filter individual elements.

Name	Aliases	What it matches	Example
:bold		Text drawn with a bold font variant.	text:bold
:checked		Checkbox-like element whose is_checked is true.	checkbox:checked
:contains		Element text contains the given string. Case-sensitive by default; pass case=False to find/find_all for case-insensitive, regex=True to treat the argument as a regular expression.	text:contains("Invoice")
:empty		Element has no text, or only whitespace.	text:empty
:endswith	:ends-with	Element text ends with the given string.	text:endswith("%")
:first-child		Element is the first child of its parent.	text:first-child
:highlight	:highlighted	Text covered by a highlight annotation.	text:highlight
:horizontal		Element reports is_horizontal (mainly lines).	line:horizontal
:italic		Text drawn with an italic font variant.	text:italic
:last-child		Element is the last child of its parent.	text:last-child
:not-bold		Text that is not bold.	text:not-bold
:not-empty		Element has non-whitespace text.	text:not-empty
:not-italic		Text that is not italic.	text:not-italic
:regex		Element text matches the regular expression (via re.search). case=False adds re.IGNORECASE.	text:regex("\d{4}-\d{2}")
:startswith	:starts-with	Element text starts with the given string.	text:startswith("Total")
:strike	:strikethrough, :strikeout	Text with strikethrough decoration.	text:strike
:unchecked		Checkbox-like element whose is_checked is false.	checkbox:unchecked
:underline	:underlined	Text with underline decoration.	text:underline
:vertical		Element reports is_vertical (mainly lines).	line:vertical

Collection pseudo-classes

Applied after element filtering; they operate on the whole result list (in document order).

Name	Aliases	What it does	Example
:first		Keep only the first matched element.	text:bold:first
:last		Keep only the last matched element.	text:bold:last
:limit		Keep at most the first N matches.	text:limit(10)
:nth		Keep the element at the given 0-based index; negative indices count from the end.	text:nth(2)
:slice		Slice the matches with Python slice semantics: :slice(stop), :slice(start, stop), or :slice(start, stop, step).	text:slice(0, 5)

Relational pseudo-classes

Take a reference selector as an argument and keep elements positioned relative to its first match.

Name	Aliases	What it does	Example
:above		Keep elements entirely above the first element matched by the reference selector.	text:above(line:horizontal)
:below		Keep elements entirely below the first element matched by the reference selector.	text:below(text:contains("Header"))
:left-of		Keep elements entirely left of the first element matched by the reference selector.	text:left-of(rect)
:near		Keep elements whose center is within near_threshold points (default 50) of the reference element’s center.	text:near(text:contains("Total"))
:right-of		Keep elements entirely right of the first element matched by the reference selector.	text:right-of(rect)

Parser-level pseudo-classes

Handled by the selector parser/executor itself rather than the clause registry.

Name	Aliases	What it does	Example
:closest		Rank matches by text similarity to the argument; @threshold sets the minimum similarity (0-1). Applied during selector execution.	text:closest(Invoice Number@0.7)
:not		Invert an inner selector.	text:not(:bold)
:ocr		OCR-tolerant text match that forgives commonly-confused characters (handled during selector execution).	text:ocr("Invoice")

Attribute operators

Applied in brackets, e.g. text[size>12]. Attribute names use CSS-style hyphens or Python-style underscores interchangeably.

Operator	Aliases	Meaning	Example
(bare)		Attribute exists and is not None.	text[fontname]
!=		Not equal.	text[fontname!=Courier]
$=		String ends with the value.	text[fontname$=Bold]
*=		String contains the value (case-insensitive for fontname).	text[fontname*=narrow]
<		Numeric less-than.	text[width<100]
<=		Numeric less-than-or-equal.	text[size<=8]
=		Equal. Colors compare with a small perceptual tolerance; boolean attributes accept true/false/1/0/yes.	text[size=12]
>		Numeric greater-than.	text[size>12]
>=		Numeric greater-than-or-equal.	text[size>=14]
^=		String starts with the value.	text[fontname^=Arial]
~=		Approximately equal — colors match within a small perceptual distance ([color~=red] accepts near-reds). Numeric values are rejected at parse time as ambiguous; use an explicit range like [size>=11][size<=13].	text[color~=red]

Extending the vocabulary

Third-party packages can add clauses with natural_pdf.selectors.register_pseudo, register_attribute, register_post_pseudo, and register_relational_pseudo.