Add support for nesting ampersand

When used outside the context of nesting, ampersand is treated as the
scoping root.

Author: facelessuser

docs/src/markdown/about/changelog.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.6
+
+-   **NEW** Add support for `&` as scoping root per the CSS Nesting Module, Level 1. When `&` is used outside the
+    context of nesting, it is treated as the scoping root (equivalent to `:scope`).
+
 ## 2.5
 
 -   **NEW**: Update to support Python 3.12.

docs/src/markdown/selectors/pseudo-classes.md

@@ -1579,6 +1579,14 @@ https://developer.mozilla.org/en-US/docs/Web/CSS/:root
 
 ## `:scope`:material-flask:{: title="Experimental" data-md-color-primary="purple" .icon} {:#:scope}
 
+/// new | New 2.6
+`&`, which was introduced in [CSS Nesting Level 1](https://www.w3.org/TR/css-nesting-1/#nest-selector) can be used as
+an alternative to `:scope` and is essentially equivalent. Soup Sieve does not support nesting selectors, but `&`, when
+not used in the context of nesting is treated as the scoping root per the specification.
+
+`#!py3 sv.select('& > p', soup.div)` is equivalent to `#!py3 sv.select(':scope > p', soup.div)`.
+///
+
 `:scope` represents the the element a `match`, `select`, or `filter` is being called on. If we were, for instance,
 using `:scope` on a div (`#!py3 sv.select(':scope > p', soup.div)`) `:scope` would represent **that** div element, and
 no others. If called on the Beautiful Soup object which represents the entire document, it would simply select

pyproject.toml

@@ -69,7 +69,7 @@ show_error_codes = true
 [tool.ruff]
 line-length = 120
 
-select = [
+lint.select = [
     "A",    # flake8-builtins
     "B",    # flake8-bugbear
     "D",    # pydocstyle
@@ -85,7 +85,7 @@ select = [
     "PERF"  # Perflint
 ]
 
-ignore = [
+lint.ignore = [
     "E741",
     "D202",
     "D401",

soupsieve/__init__.py

@@ -31,7 +31,7 @@
 from . import css_match as cm
 from . import css_types as ct
 from .util import DEBUG, SelectorSyntaxError  # noqa: F401
-import bs4  # type: ignore[import]
+import bs4  # type: ignore[import-untyped]
 from typing import Any, Iterator, Iterable
 
 __all__ = (

soupsieve/__meta__.py

@@ -193,5 +193,5 @@ def parse_version(ver: str) -> Version:
     return Version(major, minor, micro, release, pre, post, dev)
 
 
-__version_info__ = Version(2, 5, 0, "final")
+__version_info__ = Version(2, 6, 0, "final")
 __version__ = __version_info__._get_canonical()

soupsieve/css_match.py

@@ -5,7 +5,7 @@
 import re
 from . import css_types as ct
 import unicodedata
-import bs4  # type: ignore[import]
+import bs4  # type: ignore[import-untyped]
 from typing import Iterator, Iterable, Any, Callable, Sequence, cast  # noqa: F401
 
 # Empty tag pattern (whitespace okay)

soupsieve/css_parser.py

@@ -127,6 +127,8 @@
 PAT_PSEUDO_CLASS_SPECIAL = fr'(?P<name>:{IDENTIFIER})(?P<open>\({WSC}*)'
 # Custom pseudo class (`:--custom-pseudo`)
 PAT_PSEUDO_CLASS_CUSTOM = fr'(?P<name>:(?=--){IDENTIFIER})'
+# Nesting ampersand selector. Matches `&`
+PAT_AMP = r'&'
 # Closing pseudo group (`)`)
 PAT_PSEUDO_CLOSE = fr'{WSC}*\)'
 # Pseudo element (`::pseudo-element`)
@@ -435,6 +437,7 @@ class CSSParser:
         SelectorPattern("pseudo_class_custom", PAT_PSEUDO_CLASS_CUSTOM),
         SelectorPattern("pseudo_class", PAT_PSEUDO_CLASS),
         SelectorPattern("pseudo_element", PAT_PSEUDO_ELEMENT),
+        SelectorPattern("amp", PAT_AMP),
         SelectorPattern("at_rule", PAT_AT_RULE),
         SelectorPattern("id", PAT_ID),
         SelectorPattern("class", PAT_CLASS),
@@ -967,6 +970,9 @@ def parse_selectors(
                 # Handle parts
                 if key == "at_rule":
                     raise NotImplementedError(f"At-rules found at position {m.start(0)}")
+                elif key == "amp":
+                    sel.flags |= ct.SEL_SCOPE
+                    has_selector = True
                 elif key == 'pseudo_class_custom':
                     has_selector = self.parse_pseudo_class_custom(sel, m, has_selector)
                 elif key == 'pseudo_class':

tests/test_nesting_1/__init__.py

@@ -0,0 +1 @@
+"""Test CSS introduced by Nesting level 1."""

tests/test_nesting_1/test_amp.py

@@ -0,0 +1,80 @@
+"""Test ampersand selectors."""
+from .. import util
+import soupsieve as sv
+
+
+class TestAmp(util.TestCase):
+    """Test scope selectors."""
+
+    MARKUP = """
+    <html id="root">
+    <head>
+    </head>
+    <body>
+    <div id="div">
+    <p id="0" class="somewordshere">Some text <span id="1"> in a paragraph</span>.</p>
+    <a id="2" href="http://google.com">Link</a>
+    <span id="3" class="herewords">Direct child</span>
+    <pre id="pre" class="wordshere">
+    <span id="4">Child 1</span>
+    <span id="5">Child 2</span>
+    <span id="6">Child 3</span>
+    </pre>
+    </div>
+    </body>
+    </html>
+    """
+
+    def test_amp_is_root(self):
+        """Test ampersand is the root when the a specific element is not the target of the select call."""
+
+        # Scope is root when applied to a document node
+        self.assert_selector(
+            self.MARKUP,
+            "&",
+            ["root"],
+            flags=util.HTML
+        )
+
+        self.assert_selector(
+            self.MARKUP,
+            "& > body > div",
+            ["div"],
+            flags=util.HTML
+        )
+
+    def test_amp_cannot_select_target(self):
+        """Test that ampersand, the element which scope is called on, cannot be selected."""
+
+        for parser in util.available_parsers(
+                'html.parser', 'lxml', 'html5lib', 'xml'):
+            soup = self.soup(self.MARKUP, parser)
+            el = soup.html
+
+            # Scope is the element we are applying the select to, and that element is never returned
+            self.assertTrue(len(sv.select('&', el, flags=sv.DEBUG)) == 0)
+
+    def test_amp_is_select_target(self):
+        """Test that ampersand is the element which scope is called on."""
+
+        for parser in util.available_parsers(
+                'html.parser', 'lxml', 'html5lib', 'xml'):
+            soup = self.soup(self.MARKUP, parser)
+            el = soup.html
+
+            # Scope here means the current element under select
+            ids = [el.attrs['id'] for el in sv.select('& div', el, flags=sv.DEBUG)]
+            self.assertEqual(sorted(ids), sorted(['div']))
+
+            el = soup.body
+            ids = [el.attrs['id'] for el in sv.select('& div', el, flags=sv.DEBUG)]
+            self.assertEqual(sorted(ids), sorted(['div']))
+
+            # `div` is the current element under select, and it has no `div` elements.
+            el = soup.div
+            ids = [el.attrs['id'] for el in sv.select('& div', el, flags=sv.DEBUG)]
+            self.assertEqual(sorted(ids), sorted([]))
+
+            # `div` does have an element with the class `.wordshere`
+            ids = [el.attrs['id'] for el in sv.select('& .wordshere', el, flags=sv.DEBUG)]
+            self.assertEqual(sorted(ids), sorted(['pre']))