diff --git a/CHANGES b/CHANGES index 0883f0a..1d464ec 100644 --- a/CHANGES +++ b/CHANGES @@ -1,6 +1,16 @@ Changelog ========= +Next release +------------ + +Unreleased. + +* Parse user-action pseudo-classes and their logical combinations after a + pseudo-element, preserving their order and specificity. Such selectors + expose a ``QualifiedPseudoElement`` through ``Selector.pseudo_element``; + existing pseudo-element representations and XPath behavior are unchanged. + Version 1.6.0 ------------- diff --git a/cssselect/__init__.py b/cssselect/__init__.py index 2f9ba23..1ec029f 100644 --- a/cssselect/__init__.py +++ b/cssselect/__init__.py @@ -12,6 +12,7 @@ from cssselect.parser import ( FunctionalPseudoElement, + QualifiedPseudoElement, Selector, SelectorError, SelectorSyntaxError, @@ -24,6 +25,7 @@ "FunctionalPseudoElement", "GenericTranslator", "HTMLTranslator", + "QualifiedPseudoElement", "Selector", "SelectorError", "SelectorSyntaxError", diff --git a/cssselect/parser.py b/cssselect/parser.py index 4c5349a..eceaca4 100644 --- a/cssselect/parser.py +++ b/cssselect/parser.py @@ -64,7 +64,9 @@ class SelectorSyntaxError(SelectorError, SyntaxError): "SpecificityAdjustment", "CombinedSelector", ] -PseudoElement: TypeAlias = Union["FunctionalPseudoElement", str] +PseudoElement: TypeAlias = Union[ + "FunctionalPseudoElement", "QualifiedPseudoElement", str +] class Selector: @@ -80,11 +82,9 @@ class Selector: def __init__(self, tree: Tree, pseudo_element: PseudoElement | None = None) -> None: self.parsed_tree = tree - if pseudo_element is not None and not isinstance( - pseudo_element, FunctionalPseudoElement - ): + if isinstance(pseudo_element, str): pseudo_element = ascii_lower(pseudo_element) - #: A :class:`FunctionalPseudoElement`, + #: A :class:`FunctionalPseudoElement` or :class:`QualifiedPseudoElement`, #: or the identifier for the pseudo-element as a string, # or ``None``. #: @@ -107,7 +107,9 @@ def __init__(self, tree: Tree, pseudo_element: PseudoElement | None = None) -> N self.pseudo_element = pseudo_element def __repr__(self) -> str: - if isinstance(self.pseudo_element, FunctionalPseudoElement): + if isinstance( + self.pseudo_element, (FunctionalPseudoElement, QualifiedPseudoElement) + ): pseudo_element = repr(self.pseudo_element) elif self.pseudo_element: pseudo_element = f"::{self.pseudo_element}" @@ -117,7 +119,9 @@ def __repr__(self) -> str: def canonical(self) -> str: """Return a CSS representation for this selector (a string)""" - if isinstance(self.pseudo_element, FunctionalPseudoElement): + if isinstance( + self.pseudo_element, (FunctionalPseudoElement, QualifiedPseudoElement) + ): pseudo_element = f"::{self.pseudo_element.canonical()}" elif self.pseudo_element: pseudo_element = f"::{_serialize_ident(self.pseudo_element)}" @@ -137,6 +141,9 @@ def specificity(self) -> tuple[int, int, int]: """ a, b, c = self.parsed_tree.specificity() + if isinstance(self.pseudo_element, QualifiedPseudoElement): + a2, b2, c2 = self.pseudo_element.specificity() + return a + a2, b + b2, c + c2 if self.pseudo_element: c += 1 return a, b, c @@ -197,6 +204,43 @@ def canonical(self) -> str: return f"{_serialize_ident(self.name)}({args})" +class QualifiedPseudoElement: + """A pseudo-element followed by user-action pseudo-classes. + + ``pseudo_element`` is its name or a :class:`FunctionalPseudoElement`. + ``state`` is the parsed tree of the following pseudo-classes, rooted at + an implicit universal selector. It applies to the pseudo-element itself, + not to the originating element in ``Selector.parsed_tree``. + """ + + def __init__( + self, pseudo_element: str | FunctionalPseudoElement, state: Tree + ) -> None: + self.pseudo_element = ( + ascii_lower(pseudo_element) + if isinstance(pseudo_element, str) + else pseudo_element + ) + self.state = state + + def __repr__(self) -> str: + return f"{self.__class__.__name__}[::{self.canonical()}]" + + def canonical(self) -> str: + """Return the pseudo-element and its state without the leading ``::``.""" + pseudo_element = ( + _serialize_ident(self.pseudo_element) + if isinstance(self.pseudo_element, str) + else self.pseudo_element.canonical() + ) + return pseudo_element + self.state.canonical()[1:] + + def specificity(self) -> tuple[int, int, int]: + """Include the pseudo-element and the following pseudo-classes.""" + a, b, c = self.state.specificity() + return a, b, c + 1 + + class Function: """ Represents selector:name(expr) @@ -629,6 +673,7 @@ def parse_simple_selector( inside_negation: bool = False, inside_selector_list: bool = False, inside_relative_selector: bool = False, + inside_pseudo_element: bool = False, ) -> tuple[Tree, PseudoElement | None]: stream.skip_whitespace() selector_start = len(stream.used) @@ -639,6 +684,8 @@ def parse_simple_selector( preceding -= 1 at_selector_start = preceding < 0 or stream.used[preceding].is_delim(",") peek = stream.peek() + if inside_pseudo_element and peek != ("DELIM", ":"): + raise SelectorSyntaxError(f"Expected a pseudo-class, got {peek}") if peek.type == "IDENT" or peek == ("DELIM", "*"): if peek.type == "IDENT": namespace = stream.next().value @@ -666,9 +713,21 @@ def parse_simple_selector( if peek.type in ("S", "EOF") or peek.is_delim(",", "+", ">", "~", ")"): break if pseudo_element: + if peek == ("DELIM", ":"): + state, _ = parse_simple_selector( + stream, + inside_negation=inside_negation, + inside_selector_list=inside_selector_list, + inside_relative_selector=inside_relative_selector, + inside_pseudo_element=True, + ) + assert not isinstance(pseudo_element, QualifiedPseudoElement) + return result, QualifiedPseudoElement(pseudo_element, state) raise SelectorSyntaxError( f"Got pseudo-element ::{pseudo_element} not at the end of a selector" ) + if inside_pseudo_element and peek != ("DELIM", ":"): + raise SelectorSyntaxError(f"Expected a pseudo-class, got {peek}") if peek.type == "HASH": result = Hash(result, cast("str", stream.next().value)) elif peek == ("DELIM", "."): @@ -689,6 +748,10 @@ def parse_simple_selector( elif peek == ("DELIM", ":"): stream.next() if stream.peek() == ("DELIM", ":"): + if inside_pseudo_element: + raise SelectorSyntaxError( + "Multiple pseudo-elements are not supported" + ) stream.next() pseudo_element = stream.next_ident() if stream.peek() == ("DELIM", "("): @@ -698,6 +761,16 @@ def parse_simple_selector( ) continue ident = stream.next_ident() + if inside_pseudo_element: + allowed = ( + {"is", "where", "not"} + if stream.peek() == ("DELIM", "(") + else {"hover", "active", "focus", "focus-visible", "focus-within"} + ) + if ascii_lower(ident) not in allowed: + raise SelectorSyntaxError( + f"Pseudo-class :{ident} is not supported after a pseudo-element" + ) if ident.lower() in ("first-line", "first-letter", "before", "after"): # Special case: CSS 2.1 pseudo-elements can have a single ':' # Any new pseudo-element must have two. @@ -730,7 +803,9 @@ def parse_simple_selector( if inside_negation: raise SelectorSyntaxError("Got nested :not()") argument, argument_pseudo_element = parse_simple_selector( - stream, inside_negation=True + stream, + inside_negation=True, + inside_pseudo_element=inside_pseudo_element, ) while 1: # Whitespace before the closing parenthesis is not a @@ -744,6 +819,8 @@ def parse_simple_selector( if peek == ("DELIM", ")"): stream.next() break + if inside_pseudo_element: + raise SelectorSyntaxError(f"Expected ')', got {peek}") if peek.is_delim("+", ">", "~"): argument_combinator = cast("str", stream.next().value) stream.skip_whitespace() @@ -762,10 +839,14 @@ def parse_simple_selector( elif ident.lower() == "has": result = Relation(result, parse_relative_selector(stream)) elif ident.lower() in ("matches", "is"): - selectors = parse_simple_selector_arguments(stream) + selectors = parse_simple_selector_arguments( + stream, inside_pseudo_element=inside_pseudo_element + ) result = Matching(result, selectors) elif ident.lower() == "where": - selectors = parse_simple_selector_arguments(stream) + selectors = parse_simple_selector_arguments( + stream, inside_pseudo_element=inside_pseudo_element + ) result = SpecificityAdjustment(result, selectors) else: result = Function(result, ident, parse_arguments(stream)) @@ -834,11 +915,15 @@ def parse_relative_selector(stream: TokenStream) -> list[tuple[Token, Selector]] return arguments -def parse_simple_selector_arguments(stream: TokenStream) -> list[Tree]: +def parse_simple_selector_arguments( + stream: TokenStream, inside_pseudo_element: bool = False +) -> list[Tree]: arguments = [] while 1: result, pseudo_element = parse_simple_selector( - stream, inside_selector_list=True + stream, + inside_selector_list=True, + inside_pseudo_element=inside_pseudo_element, ) if pseudo_element: raise SelectorSyntaxError( diff --git a/docs/index.rst b/docs/index.rst index 1d5b49c..bcf14d0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,6 +54,9 @@ is a group of two selectors. .. autoclass:: Selector() :members: +.. autoclass:: QualifiedPseudoElement(pseudo_element, state) + :members: + .. autoclass:: FunctionalPseudoElement .. autoclass:: GenericTranslator @@ -152,6 +155,48 @@ These are non-standard extensions: It should not be a problem anymore. +Pseudo-classes after a pseudo-element +------------------------------------- + +The parser accepts the user-action pseudo-classes ``:hover``, ``:active``, +``:focus``, ``:focus-visible`` and ``:focus-within`` after a pseudo-element. +They can also be combined with ``:is()``, ``:where()`` and ``:not()``, subject +to the existing limitations of those functions. Their arguments must contain +only these pseudo-classes; type, class, ID and attribute selectors are not +allowed in this position. Pseudo-element-specific states, chained +pseudo-elements and combinators after a pseudo-element remain unsupported. + +For example, ``.item::before:hover`` constrains the pseudo-element's state, +while ``.item:hover::before`` constrains the originating element's state. +The parser preserves this distinction:: + + >>> from cssselect import parse + >>> selector = parse(".item::before:hover")[0] + >>> selector.canonical() + '.item::before:hover' + >>> selector.specificity() + (0, 2, 1) + >>> selector.pseudo_element.pseudo_element + 'before' + >>> selector.pseudo_element.state.canonical() + '*:hover' + +For the new syntax, :attr:`Selector.pseudo_element` is a +:class:`QualifiedPseudoElement`. Unqualified pseudo-elements keep their +existing string or :class:`FunctionalPseudoElement` representation. +The originating element remains in ``Selector.parsed_tree``. + +XPath translation still rejects pseudo-elements by default. Calling +:meth:`GenericTranslator.selector_to_xpath` without +``translate_pseudo_elements=True`` ignores the whole qualified pseudo-element, +including its state. A custom ``GenericTranslator.xpath_pseudo_element`` +implementation receives the :class:`QualifiedPseudoElement` object and must +handle its state explicitly, or reject it. + +This follows `Selectors Level 4, Pseudo-classing Pseudo-elements +`_. + + Customizing the translation =========================== diff --git a/tests/test_cssselect.py b/tests/test_cssselect.py index 266bbca..fc2cbe5 100644 --- a/tests/test_cssselect.py +++ b/tests/test_cssselect.py @@ -593,7 +593,7 @@ def get_error(css: str) -> str | None: # Mis-placed pseudo-elements assert get_error("a:before:empty") == ( - "Got pseudo-element ::before not at the end of a selector" + "Pseudo-class :empty is not supported after a pseudo-element" ) assert get_error("li:before a") == ( "Got pseudo-element ::before not at the end of a selector" @@ -1224,7 +1224,7 @@ def xpath_pseudo_element( f"The functional pseudo-element ::{pseudo_element.name}() is unknown" ) xpath = method(xpath, pseudo_element.arguments) - else: + elif isinstance(pseudo_element, str): method_name = "xpath_{}_simple_pseudo_element".format( pseudo_element.replace("-", "_") ) @@ -1234,6 +1234,8 @@ def xpath_pseudo_element( f"The pseudo-element ::{pseudo_element} is unknown" ) xpath = method(xpath) + else: + raise ExpressionError("Pseudo-element states are not supported") return xpath # functional pseudo-class: diff --git a/tests/test_pseudo_element_states.py b/tests/test_pseudo_element_states.py new file mode 100644 index 0000000..1a9a3ea --- /dev/null +++ b/tests/test_pseudo_element_states.py @@ -0,0 +1,147 @@ +"""Parsing states of pseudo-elements without applying them to their origin.""" + +from __future__ import annotations + +import pytest +from lxml import html + +import cssselect +from cssselect import ExpressionError, GenericTranslator, SelectorSyntaxError, parse +from cssselect.parser import FunctionalPseudoElement + + +@pytest.mark.parametrize( + ("source", "canonical", "specificity"), + [ + (".something::before:hover", ".something::before:hover", (0, 2, 1)), + ("a:before:active", "a::before:active", (0, 1, 2)), + ("A::BEFORE:HOVER:FOCUS", "A::before:hover:focus", (0, 2, 2)), + ("::first-line:focus-visible", "::first-line:focus-visible", (0, 1, 1)), + ("::after:focus-within", "::after:focus-within", (0, 1, 1)), + ("a::part(tab):hover", "a::part(tab):hover", (0, 1, 2)), + ("#id::before:not(:hover)", "#id::before:not(:hover)", (1, 1, 1)), + ( + "p::before:is(:hover,:focus:active)", + "p::before:is(:hover, :focus:active)", + (0, 2, 2), + ), + ("p::after:hover:where(:focus)", "p::after:hover:where(:focus)", (0, 1, 2)), + ("p::after:where(:hover):active", "p::after:where(:hover):active", (0, 1, 2)), + ( + "p::before:not(:is(:hover,:active))", + "p::before:not(:is(:hover, :active))", + (0, 1, 2), + ), + ("div > a.x::before:hover", "div > a.x::before:hover", (0, 2, 3)), + (r".x::b\65 fore:h\6f ver", ".x::before:hover", (0, 2, 1)), + ], +) +def test_pseudo_element_state_round_trip( + source: str, canonical: str, specificity: tuple[int, int, int] +) -> None: + selector = parse(source)[0] + assert selector.canonical() == canonical + assert selector.specificity() == specificity + reparsed = parse(canonical)[0] + assert reparsed.canonical() == canonical + assert reparsed.specificity() == specificity + assert repr(reparsed) == repr(selector) + + +@pytest.mark.parametrize( + "state", ["hover", "active", "focus", "focus-visible", "focus-within"] +) +def test_pseudo_element_state_belongs_to_the_pseudo_element(state: str) -> None: + selector = parse(f".something::before:{state}")[0] + pseudo = selector.pseudo_element + assert isinstance(pseudo, cssselect.QualifiedPseudoElement) + assert pseudo.pseudo_element == "before" + assert pseudo.state.canonical() == f"*:{state}" + assert selector.parsed_tree.canonical() == "*.something" + document = html.fromstring('

') + xpath = GenericTranslator().selector_to_xpath(selector) + assert [node.get("id") for node in document.xpath(xpath)] == ["yes"] + with pytest.raises(ExpressionError, match="Pseudo-elements are not supported"): + GenericTranslator().selector_to_xpath(selector, translate_pseudo_elements=True) + with pytest.raises(ExpressionError, match="Pseudo-elements are not supported"): + GenericTranslator().css_to_xpath(selector.canonical()) + + +def test_pseudo_element_state_keeps_function_arguments() -> None: + pseudo = parse("a::part(tab):hover")[0].pseudo_element + assert isinstance(pseudo, cssselect.QualifiedPseudoElement) + assert isinstance(pseudo.pseudo_element, FunctionalPseudoElement) + assert pseudo.pseudo_element.name == "part" + assert [token.value for token in pseudo.pseudo_element.arguments] == ["tab"] + + +def test_pseudo_element_state_selector_groups() -> None: + selectors = parse("a::before:hover, b:focus::after, c::part(tab):active") + assert [selector.canonical() for selector in selectors] == [ + "a::before:hover", + "b:focus::after", + "c::part(tab):active", + ] + assert [selector.specificity() for selector in selectors] == [ + (0, 1, 2), + (0, 1, 2), + (0, 1, 2), + ] + assert selectors[1].pseudo_element == "after" + + +@pytest.mark.parametrize( + "source", + [ + "a::before.foo", + "a::before#id", + "a::before[title]", + "a::before:hover.foo", + "a::before:hover#id", + "a::before:hover[title]", + "a::before:hover > b", + "a::before:hover + b", + "a::before:hover ~ b", + "a::before:hover b", + "a::before:hover :active", + "a::before::after", + "a::before:hover::after", + "a::before:before", + "a::before:nth-child(1)", + "a::before:enabled", + "a::before:unknown", + "a::before:has(:hover)", + "a::before:is(.foo)", + "a::before:is(#id)", + "a::before:is([title])", + "a::before:is(*)", + "a::before:is(*:hover)", + "a::before:is(a:hover)", + "a::before:is(:hover, .foo)", + "a::before:where(:hover, :nth-child(1))", + "a::before:not(*)", + "a::before:not(.foo)", + "a::before:not(:hover > :active)", + "a::before:not(:hover :active)", + "a::before:not(:hover, :active)", + "a::before:is(::after:hover)", + "a::before:where(:hover,)", + "a::before:hover(", + "a::before:", + "a::before:is()", + "a::before:not()", + "a:not(::before:hover)", + "a:is(::before:hover)", + "a:has(::before:hover)", + ], +) +def test_pseudo_element_states_reject_other_selector_kinds(source: str) -> None: + with pytest.raises(SelectorSyntaxError): + parse(source) + + +def test_existing_pseudo_element_representation_is_unchanged() -> None: + assert parse("a:before")[0].pseudo_element == "before" + assert parse("a::BEFORE")[0].pseudo_element == "before" + assert isinstance(parse("a::part(tab)")[0].pseudo_element, FunctionalPseudoElement) + assert parse("a:hover::before")[0].parsed_tree.canonical() == "a:hover"