Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGES
Original file line number Diff line number Diff line change
@@ -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
-------------

Expand Down
2 changes: 2 additions & 0 deletions cssselect/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@

from cssselect.parser import (
FunctionalPseudoElement,
QualifiedPseudoElement,
Selector,
SelectorError,
SelectorSyntaxError,
Expand All @@ -24,6 +25,7 @@
"FunctionalPseudoElement",
"GenericTranslator",
"HTMLTranslator",
"QualifiedPseudoElement",
"Selector",
"SelectorError",
"SelectorSyntaxError",
Expand Down
109 changes: 97 additions & 12 deletions cssselect/parser.py
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,9 @@ class SelectorSyntaxError(SelectorError, SyntaxError):
"SpecificityAdjustment",
"CombinedSelector",
]
PseudoElement: TypeAlias = Union["FunctionalPseudoElement", str]
PseudoElement: TypeAlias = Union[
"FunctionalPseudoElement", "QualifiedPseudoElement", str
]


class Selector:
Expand All @@ -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``.
#:
Expand All @@ -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}"
Expand All @@ -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)}"
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand All @@ -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
Expand Down Expand Up @@ -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", "."):
Expand All @@ -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", "("):
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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()
Expand All @@ -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))
Expand Down Expand Up @@ -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(
Expand Down
45 changes: 45 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,9 @@ is a group of two selectors.
.. autoclass:: Selector()
:members:

.. autoclass:: QualifiedPseudoElement(pseudo_element, state)
:members:

.. autoclass:: FunctionalPseudoElement

.. autoclass:: GenericTranslator
Expand Down Expand Up @@ -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
<https://www.w3.org/TR/selectors-4/#pseudo-element-states>`_.


Customizing the translation
===========================

Expand Down
6 changes: 4 additions & 2 deletions tests/test_cssselect.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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("-", "_")
)
Expand All @@ -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:
Expand Down
Loading