Repository: facelessuser/soupsieve

Issue:
Deprecate comments and icomments
Soup Sieve is a CSS selector library, and comment extraction is actually out of scope. It isn't hard to extract comments manually either. I think moving forward it is better to cut out unrelated bloat and focus on our main priority, CSS selectors.

Discussion:

Patch:
diff --git a/docs/src/markdown/about/changelog.md b/docs/src/markdown/about/changelog.md
index 8314f45..0c1b135 100644
--- a/docs/src/markdown/about/changelog.md
+++ b/docs/src/markdown/about/changelog.md
@@ -4,6 +4,8 @@
 
 - **NEW**: Allow `:contans()` to accept a list of text to search for. (#115)
 - **NEW**: Add new `escape` function for escaping CSS identifiers. (#125)
+- **NEW**: Deprecate `comments` and `icomments` in the API to ensure Soup Sieve focuses only on CSS selectors.
+`comments` and `icomments` will most likely be removed in 2.0. (#130)
 - **FIX**: Don't install test files when installing the `soupsieve` package. (#111)
 - **FIX**: Improve efficiency of `:contains()` comparison.
 - **FIX**: Null characters should translate to the Unicode REPLACEMENT CHARACTER (`U+FFFD`) according to the
diff --git a/docs/src/markdown/api.md b/docs/src/markdown/api.md
index 83e3bbf..d400b08 100644
--- a/docs/src/markdown/api.md
+++ b/docs/src/markdown/api.md
@@ -151,6 +151,9 @@ from the given tag down through all of its children.  You can limit how many com
 
 `comments` accepts a `Tag`/`BeautifulSoup` object, a `limit`, and flags.
 
+!!! warning "Deprecated in 1.9.0"
+    `comments` is deprecated so Soup Sieve can focus on only CSS selectors. `comments` will be removed in version 2.0.
+
 ## `soupsieve.icomments()`
 
 ```py3
@@ -160,6 +163,9 @@ def icomments(node, limit=0, flags=0, **kwargs):
 
 `icomments` is exactly like `comments` except that it returns a generator instead of a list.
 
+!!! warning "Deprecated in 1.9.0"
+    `icomments` is deprecated so Soup Sieve can focus on only CSS selectors. `comments` will be removed in version 2.0.
+
 ## `soupsieve.escape()`
 
 ```py3
@@ -182,6 +188,9 @@ would normally cause an identifier to be invalid.
 '�'
 ```
 
+!!! new "New in 1.9.0"
+    `escape` is a new API function added in 1.9.0.
+
 ## `soupsieve.compile()`
 
 ```py3
diff --git a/soupsieve/__init__.py b/soupsieve/__init__.py
index 16c501b..49c478f 100644
--- a/soupsieve/__init__.py
+++ b/soupsieve/__init__.py
@@ -30,7 +30,7 @@ from .__meta__ import __version__, __version_info__  # noqa: F401
 from . import css_parser as cp
 from . import css_match as cm
 from . import css_types as ct
-from .util import DEBUG, _QUIRKS, SelectorSyntaxError  # noqa: F401
+from .util import DEBUG, _QUIRKS, deprecated, SelectorSyntaxError  # noqa: F401
 
 __all__ = (
     'DEBUG', "_QUIRKS", 'SelectorSyntaxError', 'SoupSieve',
@@ -87,12 +87,14 @@ def filter(select, iterable, namespaces=None, flags=0, **kwargs):  # noqa: A001
     return compile(select, namespaces, flags, **kwargs).filter(iterable)
 
 
+@deprecated("'comments' is not related to CSS selectors and will be removed in the future.")
 def comments(tag, limit=0, flags=0, **kwargs):
     """Get comments only."""
 
-    return list(icomments(tag, limit, flags))
+    return [comment for comment in cm.CommentsMatch(tag).get_comments(limit)]
 
 
+@deprecated("'icomments' is not related to CSS selectors and will be removed in the future.")
 def icomments(tag, limit=0, flags=0, **kwargs):
     """Iterate comments only."""
 
diff --git a/soupsieve/css_match.py b/soupsieve/css_match.py
index 923eb84..fb936ae 100644
--- a/soupsieve/css_match.py
+++ b/soupsieve/css_match.py
@@ -1297,11 +1297,13 @@ class SoupSieve(ct.Immutable):
         else:
             return [node for node in iterable if not CSSMatch.is_navigable_string(node) and self.match(node)]
 
+    @util.deprecated("'comments' is not related to CSS selectors and will be removed in the future.")
     def comments(self, tag, limit=0):
         """Get comments only."""
 
-        return list(self.icomments(tag, limit))
+        return [comment for comment in CommentsMatch(tag).get_comments(limit)]
 
+    @util.deprecated("'icomments' is not related to CSS selectors and will be removed in the future.")
     def icomments(self, tag, limit=0):
         """Iterate comments only."""
 


Test patch:
diff --git a/tests/test_api.py b/tests/test_api.py
index baf2d83..c37543b 100644
--- a/tests/test_api.py
+++ b/tests/test_api.py
@@ -708,6 +708,68 @@ class TestInvalidQuirks(TestInvalid):
             self.assertTrue(issubclass(w[-1].category, sv_util.QuirksWarning))
 
 
+class TestDeprecated(util.TestCase):
+    """Test deprecated."""
+
+    def test_comment(self):
+        """Test comment."""
+
+        html = '<div><!-- comments -->text</div>'
+        soup = self.soup(html, 'html.parser')
+
+        with warnings.catch_warnings(record=True) as w:
+            # Cause all warnings to always be triggered.
+            warnings.simplefilter("always")
+
+            sv.comments(soup)
+            self.assertTrue(len(w) == 1)
+            self.assertTrue(issubclass(w[-1].category, DeprecationWarning))
+
+    def test_comment_compilied(self):
+        """Test compiled comment."""
+
+        html = '<div><!-- comments -->text</div>'
+        soup = self.soup(html, 'html.parser')
+
+        with warnings.catch_warnings(record=True) as w:
+            # Cause all warnings to always be triggered.
+            warnings.simplefilter("always")
+
+            pattern = sv.compile('div')
+            pattern.comments(soup)
+            self.assertTrue(len(w) == 1)
+            self.assertTrue(issubclass(w[-1].category, DeprecationWarning))
+
+    def test_icomment(self):
+        """Test `icomment`."""
+
+        html = '<div><!-- comments -->text</div>'
+        soup = self.soup(html, 'html.parser')
+
+        with warnings.catch_warnings(record=True) as w:
+            # Cause all warnings to always be triggered.
+            warnings.simplefilter("always")
+
+            sv.icomments(soup)
+            self.assertTrue(len(w) == 1)
+            self.assertTrue(issubclass(w[-1].category, DeprecationWarning))
+
+    def test_icomment_compilied(self):
+        """Test compiled `icomment`."""
+
+        html = '<div><!-- comments -->text</div>'
+        soup = self.soup(html, 'html.parser')
+
+        with warnings.catch_warnings(record=True) as w:
+            # Cause all warnings to always be triggered.
+            warnings.simplefilter("always")
+
+            pattern = sv.compile('div')
+            pattern.icomments(soup)
+            self.assertTrue(len(w) == 1)
+            self.assertTrue(issubclass(w[-1].category, DeprecationWarning))
+
+
 class TestSyntaxErrorReporting(util.TestCase):
     """Test reporting of syntax errors."""