Deprecate commentsiter and selectiter (#4)

* Deprecate commentsiter and selectiter
Use iselect and icomments instead as they are shorter and easier to read

* Add codecov config

Author: facelessuser

.codecov.yml

@@ -0,0 +1,5 @@
+comment: false
+
+coverage:
+  status:
+    patch: false

docs/src/dictionary/en-custom.txt

@@ -19,6 +19,7 @@ WIP
 XHTML
 accessor
 builtin
+deprecations
 html
 iterable
 linter

docs/src/markdown/about/changelog.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.5.0
+
+- **NEW**: Deprecate `commentsiter` and `selectiter` in favor of `icomments` and `iselect`. Expect removal in version 1.0.
+
 ## 0.4.0
 
 - **NEW**: Initial prerelease.

docs/src/markdown/api.md

@@ -37,14 +37,14 @@ def select(select, node, namespaces=None, limit=0, mode=HTML5):
 [<p class="a">Cat</p>, <p class="b">Dog</p>, <p class="c">Mouse</p>]
 ```
 
-### `soupsieve.selectiter()`
+### `soupsieve.iselect()`
 
 ```py3
-def selectiter(select, node, namespaces=None, limit=0, mode=HTML5):
+def iselect(select, node, namespaces=None, limit=0, mode=HTML5):
     """Select the specified tags."""
 ```
 
-`selectiter` is exactly like `select` except that it returns a generator instead of a list.
+`iselect` is exactly like `select` except that it returns a generator instead of a list.
 
 ### `soupsieve.match()`
 
@@ -92,14 +92,14 @@ def comments(node, limit=0, mode=HTML5):
 
 `comments` accepts a `node` or element, a `limit`, and a document mode.
 
-### `soupsieve.commentsiter()`
+### `soupsieve.icomments()`
 
 ```
-def comments(node, limit=0, mode=HTML5):
+def icomments(node, limit=0, mode=HTML5):
     """Get comments only."""
 ```
 
-`commentsiter` is exactly like `comments` except that it returns a generator instead of a list.
+`icomments` is exactly like `comments` except that it returns a generator instead of a list.
 
 ### `soupsieve.compile()`
 

soupsieve/__init__.py

@@ -27,11 +27,12 @@
 """
 from .__meta__ import __version__, __version_info__  # noqa: F401
 from . import css_parser as cp
-from .util import HTML, HTML5, XHTML, XML
+from .util import HTML, HTML5, XHTML, XML, deprecated
 
 __all__ = (
     'HTML', 'HTML5', 'XHTML', 'XML',
-    'SoupSieve', 'compile', 'purge', 'comments', 'select', 'match', 'filter'
+    'SoupSieve', 'compile', 'purge',
+    'comments', 'icomments', 'select', 'iselect', 'match', 'filter'
 )
 
 SoupSieve = cp.SoupSieve
@@ -79,10 +80,10 @@ def comments(node, limit=0, mode=HTML5):
     return compile("", None, mode).comments(node, limit)
 
 
-def commentsiter(node, limit=0, mode=HTML5):
+def icomments(node, limit=0, mode=HTML5):
     """Iterate comments only."""
 
-    yield from compile("", None, mode).commentsiter(node, limit)
+    yield from compile("", None, mode).icomments(node, limit)
 
 
 def select(select, node, namespaces=None, limit=0, mode=HTML5):
@@ -91,7 +92,22 @@ def select(select, node, namespaces=None, limit=0, mode=HTML5):
     return compile(select, namespaces, mode).select(node, limit)
 
 
+def iselect(select, node, namespaces=None, limit=0, mode=HTML5):
+    """Iterate the specified tags."""
+
+    yield from compile(select, namespaces, mode).iselect(node, limit)
+
+
+# ====== Deprecated ======
+@deprecated("Use 'icomments' instead.")
+def commentsiter(node, limit=0, mode=HTML5):
+    """Iterate comments only."""
+
+    yield from icomments(node, limit, mode)
+
+
+@deprecated("Use 'iselect' instead.")
 def selectiter(select, node, namespaces=None, limit=0, mode=HTML5):
     """Iterate the specified tags."""
 
-    yield from compile(select, namespaces, mode).selectiter(node, limit)
+    yield from iselect(select, node, namespaces, limit, mode)

soupsieve/__meta__.py

@@ -186,5 +186,5 @@ def parse_version(ver, pre=False):
     return Version(major, minor, micro, release, pre, post, dev)
 
 
-__version_info__ = Version(0, 4, 0, "final")
+__version_info__ = Version(0, 5, 0, "final")
 __version__ = __version_info__._get_canonical()

soupsieve/css_parser.py

@@ -5,6 +5,7 @@
 from functools import lru_cache
 from . import util
 from . import css_match as cm
+from .util import deprecated
 
 
 # Selector patterns
@@ -590,25 +591,25 @@ def filter(self, nodes):  # noqa A001
         else:
             return [node for node in nodes if self.match(node)]
 
-    def commentsiter(self, node, limit=0):
-        """Iterate comments only."""
-
-        yield from self._sieve(node, capture=False, comments=True, limit=limit)
-
     def comments(self, node, limit=0):
         """Get comments only."""
 
-        return list(self.commentsiter(node, limit))
+        return list(self.icomments(node, limit))
 
-    def selectiter(self, node, limit=0):
-        """Iterate the specified tags."""
+    def icomments(self, node, limit=0):
+        """Iterate comments only."""
 
-        yield from self._sieve(node, limit=limit)
+        yield from self._sieve(node, capture=False, comments=True, limit=limit)
 
     def select(self, node, limit=0):
         """Select the specified tags."""
 
-        return list(self.selectiter(node, limit))
+        return list(self.iselect(node, limit))
+
+    def iselect(self, node, limit=0):
+        """Iterate the specified tags."""
+
+        yield from self._sieve(node, limit=limit)
 
     def __repr__(self):
         """Representation."""
@@ -617,6 +618,19 @@ def __repr__(self):
 
     __str__ = __repr__
 
+    # ====== Deprecated ======
+    @deprecated("Use 'SoupSieve.icomments' instead.")
+    def commentsiter(self, node, limit=0):
+        """Iterate comments only."""
+
+        yield from self.icomments(node, limit)
+
+    @deprecated("Use 'SoupSieve.iselect' instead.")
+    def selectiter(self, node, limit=0):
+        """Iterate the specified tags."""
+
+        yield from self.iselect(node, limit)
+
 
 def _pickle(p):
     return SoupSieve, (p.pattern, p.namespaces, p.mode)

soupsieve/util.py

@@ -2,6 +2,8 @@
 from collections import Mapping
 from collections.abc import Hashable
 import bs4
+from functools import wraps
+import warnings
 
 HTML5 = 0x1
 HTML = 0x2
@@ -126,3 +128,23 @@ def __repr__(self):
         return "%r" % self._d
 
     __str__ = __repr__
+
+
+def deprecated(message, stacklevel=2):
+    """
+    Raise a `DeprecationWarning` when wrapped function/method is called.
+
+    Borrowed from https://stackoverflow.com/a/48632082/866026
+    """
+
+    def _decorator(func):
+        @wraps(func)
+        def _func(*args, **kwargs):
+            warnings.warn(
+                "'{}' is deprecated. {}".format(func.__name__, message),
+                category=DeprecationWarning,
+                stacklevel=stacklevel
+            )
+            return func(*args, **kwargs)
+        return _func
+    return _decorator

tests/test_level1.py

@@ -119,3 +119,23 @@ def test_class(self):
             ["2"],
             mode=sv.HTML5
         )
+
+    def test_classes(self):
+        """Test classes."""
+
+        markup = """
+        <div>
+        <p>Some text <span id="1" class="foo"> in a paragraph</span>.
+        <a id="2" class="bar" href="http://google.com">Link</a>
+        <a id="3" class="foo" href="http://google.com">Link</a>
+        <a id="4" class="foo bar" href="http://google.com">Link</a>
+        </p>
+        </div>
+        """
+
+        self.assert_selector(
+            markup,
+            "a.foo.bar",
+            ["4"],
+            mode=sv.HTML5
+        )

tests/test_level2.py

@@ -32,45 +32,75 @@ class TestLevel2(util.TestCase):
     def test_direct_child(self):
         """Test direct child."""
 
+        markup = """
+        <div>
+        <p id="0">Some text <span id="1"> in a paragraph</span>.</p>
+        <a id="2" href="http://google.com">Link</a>
+        <span id="3">Direct child</span>
+        <pre>
+        <span id="4">Child 1</span>
+        <span id="5">Child 2</span>
+        <span id="6">Child 3</span>
+        </pre>
+        </div>
+        """
+
+        # Spaces
         self.assert_selector(
-            """
-            <div>
-            <p id="0">Some text <span id="1"> in a paragraph</span>.</p>
-            <a id="2" href="http://google.com">Link</a>
-            <span id="3">Direct child</span>
-            <pre>
-            <span id="4">Child 1</span>
-            <span id="5">Child 2</span>
-            <span id="6">Child 3</span>
-            </pre>
-            </div>
-            """,
+            markup,
             "div > span",
             ["3"],
             mode=sv.HTML5
         )
 
+        # No spaces
+        self.assert_selector(
+            markup,
+            "div>span",
+            ["3"],
+            mode=sv.HTML5
+        )
+
     def test_direct_sibling(self):
         """Test direct sibling."""
 
+        markup = """
+        <div>
+        <p id="0">Some text <span id="1"> in a paragraph</span>.</p>
+        <a id="2" href="http://google.com">Link</a>
+        <span id="3">Direct child</span>
+        <pre>
+        <span id="4">Child 1</span>
+        <span id="5">Child 2</span>
+        <span id="6">Child 3</span>
+        </pre>
+        </div>
+        """
+
+        # Spaces
         self.assert_selector(
-            """
-            <div>
-            <p id="0">Some text <span id="1"> in a paragraph</span>.</p>
-            <a id="2" href="http://google.com">Link</a>
-            <span id="3">Direct child</span>
-            <pre>
-            <span id="4">Child 1</span>
-            <span id="5">Child 2</span>
-            <span id="6">Child 3</span>
-            </pre>
-            </div>
-            """,
+            markup,
             "span + span",
             ["5", "6"],
             mode=sv.HTML5
         )
 
+        # No spaces
+        self.assert_selector(
+            markup,
+            "span+span",
+            ["5", "6"],
+            mode=sv.HTML5
+        )
+
+        # Complex
+        self.assert_selector(
+            markup,
+            "span#4 + span#5",
+            ["5"],
+            mode=sv.HTML5
+        )
+
     def test_wild_tag(self):
         """Test wild tag."""
 
@@ -113,6 +143,28 @@ def test_attribute(self):
             mode=sv.HTML5
         )
 
+    def test_multi_attribute(self):
+        """Test multiple attribute."""
+
+        self.assert_selector(
+            """
+            <div id="div">
+            <p id="0">Some text <span id="1"> in a paragraph</span>.</p>
+            <a id="2" href="http://google.com">Link</a>
+            <span id="3">Direct child</span>
+            <pre id="pre">
+            <span id="4" class="test">Child 1</span>
+            <span id="5" class="test" data-test="test">Child 2</span>
+            <span id="6">Child 3</span>
+            <span id="6">Child 3</span>
+            </pre>
+            </div>
+            """,
+            "span[id].test[data-test=test]",
+            ["5"],
+            mode=sv.HTML5
+        )
+
     def test_attribute_equal(self):
         """Test attribute with value that equals specified value."""