Merge ~facelessuser/beautifulsoup:feature/enhanced-soupsieve into beautifulsoup:master

[Isaac Muse]

Enhanced support for soupsieve

Add `sieve` method to allow access to all CSS query methods.
Add `css_escape` as a global method.

Add access to soupsieve API for queries via `sieve`. An alternative could be to use the name `css` if desired.

Add `css_escape` as a global method to escape CSS identifiers.

Unmerged commits

36cd05d... by Isaac Muse on 2023-01-29

Enhanced support for soupsieve

Add `sieve` method to allow access to all CSS query methods.
Add `css_escape` as a global method.

diff --git a/bs4/__init__.py b/bs4/__init__.py
index db71cc7..226e7dd 100644
--- a/bs4/__init__.py
+++ b/bs4/__init__.py
@@ -56,8 +56,23 @@ from .element import (
     SoupStrainer,
     Tag,
     TemplateString,
+    soupsieve
     )
 
+
+def css_escape(identifier):
+    """Escape a CSS identifier.
+
+    :param identifier: A string to be treated as a CSS identifier.
+    Any characters unsupported characters will be escaped.
+
+    :return: An escaped CSS identifier string.
+    :rtype: str
+    """
+
+    return soupsieve.escape(identifier)
+
+
 # Define some custom warnings.
 class GuessedAtParserWarning(UserWarning):
     """The warning issued when BeautifulSoup has to guess what parser to
diff --git a/bs4/element.py b/bs4/element.py
index 583d0e8..7ae054e 100644
--- a/bs4/element.py
+++ b/bs4/element.py
@@ -8,6 +8,7 @@ except ImportError as e:
 import re
 import sys
 import warnings
+import functools
 try:
     import soupsieve
 except ImportError as e:
@@ -69,7 +70,52 @@ PYTHON_SPECIFIC_ENCODINGS = set([
     "string-escape",
     "string_escape",
 ])
-    
+
+
+class Sieve:
+    """An object scoped to a given document/element that provides CSS selecting/matching.
+
+    A wrapper around the SoupSieve object which scopes it to the given tag and namespaces.
+    """
+
+    def __init__(self, tag, sieve):
+        """Initialized the object with the scoped element.
+
+        :param tag: The element tag that queries will be scoped to.
+        :param sieve: The compiled SoupSieve object.
+        """
+
+        self._tag = tag
+        self._pattern = sieve
+
+    @property
+    def pattern(self):
+        """Return the pattern (SoupSieve object)."""
+
+        return self._pattern
+
+    def __getattr__(self, __name):
+        """Get attribute of the SoupSieve object and properly return it.
+
+        :param __name: The name of the attribute to be retrieved. If the
+        attribute is present on the SoupSieve object, it will be returned
+        from there; otherwise, it will be retrieved from the Sieve object.
+
+        :return: The desired atribute: function, property, etc.
+        """
+
+        try:
+            # Attempt to retrieve a Sieve attribute.
+            super().__getattribute__(__name)
+        except AttributeError:
+            pass
+
+        # We can assume the attribute must be in the SoupSieve object as it isn't present in Sieve.
+        attr = getattr(self.pattern, __name)
+        if callable(attr):
+            return lambda *args, __tag=self._tag, __attr=attr, **kwargs: attr(__tag, *args, **kwargs)
+        return attr
+
 
 class NamespacedAttribute(str):
     """A namespaced string (e.g. 'xml:lang') that remembers the namespace
@@ -1995,6 +2041,27 @@ class Tag(PageElement):
         # ResultSet.__getattr__ has a helpful error message.
         return ResultSet(None, results)
 
+    def sieve(self, pattern, namespaces=None, flags=0, *, custom=None, **kwargs):
+        """Access related Soup Sieve methods.
+
+        :param pattern: A string or compiled SoupSieve object that describes the
+        desired element to select or match.
+        :param namespaces: An optional mapping containing namespaces. If not provided,
+        BeautifulSoup will default them to what it discovered.
+        :param flags: Integer input specifying any and all flags to enable.
+        :param custom: Dictionary describing custom selectors.
+        :param **kwargs: Additional keyword arguments to be passed into SoupSieve's methods.
+
+        :return: A Sieve object which acts as a scoped SoupSieve object.
+        :rtype: bs4.element.Sieve
+        """
+
+        # Set the namespace if we have an uncompiled object.
+        if namespaces is None and not isinstance(pattern, soupsieve.css_match.SoupSieve):
+            namespaces = self._namespaces
+
+        return Sieve(self, soupsieve.compile(pattern, namespaces, flags=flags, custom=custom, **kwargs))
+
     # Old names for backwards compatibility
     def childGenerator(self):
         """Deprecated generator."""
diff --git a/bs4/tests/test_pageelement.py b/bs4/tests/test_pageelement.py
index 75bab04..ca9abd1 100644
--- a/bs4/tests/test_pageelement.py
+++ b/bs4/tests/test_pageelement.py
@@ -4,11 +4,15 @@ import pickle
 import pytest
 
 from soupsieve import SelectorSyntaxError
+from soupsieve.css_match import SoupSieve
 
-from bs4 import BeautifulSoup
+from bs4 import (
+    BeautifulSoup,
+    css_escape
+)
 from bs4.element import (
     Comment,
-    SoupStrainer,
+    SoupStrainer
 )
 from . import SoupTest
 
@@ -306,7 +310,6 @@ class TestCSSSelectors(SoupTest):
         match = self.soup.select_one('nonexistenttag')
         assert None == match
 
-
     def test_tag_in_tag_one(self):
         els = self.soup.select('div div')
         self.assert_selects('div div', ['inner', 'data1'])
@@ -315,7 +318,6 @@ class TestCSSSelectors(SoupTest):
         for selector in ('html div', 'html body div', 'body div'):
             self.assert_selects(selector, ['data1', 'main', 'inner', 'footer'])
 
-
     def test_limit(self):
         self.assert_selects('html div', ['main'], limit=1)
         self.assert_selects('html body div', ['inner', 'main'], limit=2)
@@ -634,6 +636,77 @@ class TestCSSSelectors(SoupTest):
         for element in soup.find_all(class_=['c1', 'c2']):
             assert element in selected
 
+    def test_sieve(self):
+        """Test sieve property."""
+
+        assert isinstance(self.soup.sieve('div').pattern, SoupSieve)
+
+    def test_sieve_select(self):
+        """Test `select`."""
+
+        els = self.soup.sieve('div#inner p').select()
+        assert len(els) == 3
+
+    def test_sieve_select_args(self):
+        """Test `select` with arguments."""
+
+        els = self.soup.sieve('div#inner p').select(1)
+        assert len(els) == 1
+
+    def test_sieve_select_one(self):
+        """Test `select_one`."""
+
+        el = self.soup.sieve('div#inner p').select_one()
+        assert el.name == 'p'
+
+    def test_sieve_iselect(self):
+        """Test `iselect`."""
+
+        els = self.soup.sieve('div#inner p').iselect()
+        # Should be a generator
+        assert not isinstance(els, list)
+        els = list(els)
+        assert len(els) == 3
+
+    def test_sieve_match(self):
+        """Test `match`."""
+
+        els = self.soup.sieve('div#inner p').select(1)
+        assert els[0].sieve('div#inner p').match()
+
+    def test_sieve_closest(self):
+        """Test `closest`."""
+
+        els = self.soup.sieve('div#inner p').select(1)
+        el = els[0].sieve('div').closest()
+        assert el.sieve('div#inner').match()
+
+    def test_sieve_filter(self):
+        """Test `filter`."""
+
+        # Implicit wildcard match of en, en-gb, and en-us of the direct parent div#main
+        els = self.soup.sieve('div#main > :lang("en")').select()
+        parent = els[0].parent
+        # Filter the direct descendants that match the given pattern.
+        els2 = parent.sieve(':lang("en")').filter()
+        assert len(els) == len(els2) == 3
+
+    def test_reuse_precompiled_pattern(self):
+        """Test that we can reuse a precompiled pattern."""
+
+        pattern = self.soup.sieve('div#main > :lang("en")').pattern
+        els = self.soup.sieve(pattern).select()
+        assert len(els) == 3
+        assert all([e.sieve(pattern).match() for e in els])
+
+    def test_css_escape(self):
+        """Test CSS escape."""
+
+        # Identifiers in CSS cannot start with numbers without escaping
+        html = """<div class="1test">test</div>"""
+        soup = BeautifulSoup(html, 'html.parser')
+        assert soup.sieve('.' + css_escape('1test')).select_one()['class'][0] == '1test'
+
 
 class TestPersistence(SoupTest):
     "Testing features like pickle and deepcopy."
@@ -749,4 +822,3 @@ class TestPersistence(SoupTest):
         assert None == div_copy.previous_element
         assert None == div_copy.find(string='Bar').next_element
         assert None != div.find(string='Bar').next_element
-