fixup! Use set instead of list for block level elements

Author: pawamoy

markdown/util.py

@@ -38,15 +38,34 @@
 _T = TypeVar('_T')
 
 
-"""
-Constants you might want to modify
------------------------------------------------------------------------------
-"""
+def deprecated(message: str, stacklevel: int = 2):
+    """
+    Raise a [`DeprecationWarning`][] when wrapped function/method is called.
+
+    Usage:
+
+    ```python
+    @deprecated("This method will be removed in version X; use Y instead.")
+    def some_method():
+        pass
+    ```
+    """
+    def wrapper(func):
+        @wraps(func)
+        def deprecated_func(*args, **kwargs):
+            warnings.warn(
+                f"'{func.__name__}' is deprecated. {message}",
+                category=DeprecationWarning,
+                stacklevel=stacklevel
+            )
+            return func(*args, **kwargs)
+        return deprecated_func
+    return wrapper
 
 
 # TODO: Raise errors from list methods in the future.
 # Later, remove this class entirely and use a regular set.
-class _BlockLevelElements:
+class _BlockLevelElements(list):
     # This hybrid list/set container exists for backwards compatibility reasons,
     # to support using both the `BLOCK_LEVEL_ELEMENTS` global variable (soft-deprecated)
     # and the `Markdown.block_level_elements` instance attribute (preferred) as a list or a set.
@@ -57,11 +76,8 @@ def __init__(self, elements: list[str], /) -> None:
         self._list = elements.copy()
         self._set = set(self._list)
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def __add__(self, other: list[str], /) -> list[str]:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         # Using `+` means user expects a list back.
         return self._list + other
 
@@ -72,29 +88,20 @@ def __and__(self, other: set[str], /) -> set[str]:
     def __contains__(self, item: str, /) -> bool:
         return item in self._set
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def __delitem__(self, index: int, /) -> None:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         element = self._list[index]
         del self._list[index]
         # Only remove from set if absent from list.
         if element not in self._list:
             self._set.remove(element)
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def __getitem__(self, index: int, /) -> str:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         return self._list[index]
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def __iadd__(self, other: list[str], /) -> set[str]:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         # In-place addition should update both list and set.
         self._list += other
         self._set.update(set(other))
@@ -150,18 +157,12 @@ def __xor__(self, value: set[str], /) -> set[str]:
         # Using `^` means user expects a set back.
         return self._set ^ value
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def __reversed__(self) -> Iterator[str]:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         return reversed(self._list)
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def __setitem__(self, index: int, value: str, /) -> None:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         # In-place item-setting should update both list and set.
         old = self._list[index]
         self._list[index] = value
@@ -178,11 +179,8 @@ def add(self, element: str, /) -> None:
         self._set.add(element)
         self._list.append(element)
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def append(self, element: str, /) -> None:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         # In-place addition should update both list and set.
         self._list.append(element)
         self._set.add(element)
@@ -195,11 +193,8 @@ def copy(self) -> _BlockLevelElements:
         # We're not sure yet whether the user wants to use it as a set or list.
         return _BlockLevelElements(self._list)
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def count(self, value: str, /) -> int:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         # Count in list, for backwards compatibility.
         # If used as a set, both counts will be the same (1).
         return self._list.count(value)
@@ -222,27 +217,18 @@ def discard(self, element: str, /) -> None:
         except ValueError:
             pass
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def extend(self, elements: list[str], /) -> None:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         # In-place extension should update both list and set.
         self._list.extend(elements)
         self._set.update(elements)
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def index(self, value, start: int = 0, stop: int = sys.maxsize, /):
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         return self._list.index(value, start, stop)
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def insert(self, index: int, element: str, /) -> None:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         # In-place insertion should update both list and set.
         self._list.insert(index, element)
         self._set.add(element)
@@ -289,24 +275,14 @@ def remove(self, element: str, /) -> None:
                 self._list.remove(element)
             except ValueError:
                 break
-        # We raise `ValueError` for backwards compatibility.
-        try:
-            self._set.remove(element)
-        except KeyError:
-            raise ValueError(f"{element!r} not in list") from None
+        self._set.remove(element)
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def reverse(self) -> None:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         self._list.reverse()
 
+    @deprecated("Using block level elements as a list is deprecated, use it as a set instead.")
     def sort(self, /, *, key: Callable | None = None, reverse: bool = False) -> None:
-        warnings.warn(
-            "Using block level elements as a list is deprecated, use it as a set instead.",
-            DeprecationWarning,
-        )
         self._list.sort(key=key, reverse=reverse)
 
     def symmetric_difference(self, other: set[str], /) -> set[str]:
@@ -331,6 +307,9 @@ def update(self, *others: set[str]) -> None:
         self._list.extend(element for element in sorted(self._set - set(self._list)))
 
 
+# Constants you might want to modify
+# -----------------------------------------------------------------------------
+
 # Type it as `set[str]` to express our intent for it to be used as such.
 # We explicitly lie here, so that users running type checkers will get
 # warnings when they use the container as a list. This is a very effective
@@ -402,31 +381,6 @@ def get_installed_extensions():
     return metadata.entry_points(group='markdown.extensions')
 
 
-def deprecated(message: str, stacklevel: int = 2):
-    """
-    Raise a [`DeprecationWarning`][] when wrapped function/method is called.
-
-    Usage:
-
-    ```python
-    @deprecated("This method will be removed in version X; use Y instead.")
-    def some_method():
-        pass
-    ```
-    """
-    def wrapper(func):
-        @wraps(func)
-        def deprecated_func(*args, **kwargs):
-            warnings.warn(
-                f"'{func.__name__}' is deprecated. {message}",
-                category=DeprecationWarning,
-                stacklevel=stacklevel
-            )
-            return func(*args, **kwargs)
-        return deprecated_func
-    return wrapper
-
-
 def parseBoolValue(value: str | None, fail_on_errors: bool = True, preserve_none: bool = False) -> bool | None:
     """Parses a string representing a boolean value. If parsing was successful,
        returns `True` or `False`. If `preserve_none=True`, returns `True`, `False`,

tests/test_block_level_elements.py

@@ -326,8 +326,11 @@ def test_index(self):
         ble = _BlockLevelElements(["a", "b", "c"])
         with self.assertWarns(DeprecationWarning):
             self.assertEqual(ble.index("a"), 0)
+        with self.assertWarns(DeprecationWarning):
             self.assertEqual(ble.index("b"), 1)
+        with self.assertWarns(DeprecationWarning):
             self.assertEqual(ble.index("c"), 2)
+        with self.assertWarns(DeprecationWarning):
             self.assertRaises(ValueError, ble.index, "d")
 
     def test_index_duplicates(self):
@@ -387,17 +390,20 @@ def test_pop(self):
         self.assertEqual(ble.pop(), "c")
         self.assertEqual(ble._list, ["a", "b"])
         self.assertEqual(ble._set, {"a", "b"})
-        self.assertEqual(ble.pop(0), "a")
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(ble.pop(0), "a")
         self.assertEqual(ble._list, ["b"])
         self.assertEqual(ble._set, {"b"})
-        self.assertRaises(IndexError, ble.pop, 10)
+        with self.assertWarns(DeprecationWarning):
+            self.assertRaises(IndexError, ble.pop, 10)
 
     def test_pop_duplicates(self):
         ble = _BlockLevelElements(["a", "a", "b", "b"])
         self.assertEqual(ble.pop(), "b")
         self.assertEqual(ble._list, ["a", "a", "b"])
         self.assertEqual(ble._set, {"a", "b"})
-        self.assertEqual(ble.pop(0), "a")
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(ble.pop(0), "a")
         self.assertEqual(ble._list, ["a", "b"])
         self.assertEqual(ble._set, {"a", "b"})
         self.assertEqual(ble.pop(), "b")
@@ -409,7 +415,7 @@ def test_remove(self):
         ble.remove("b")
         self.assertEqual(ble._list, ["a", "c"])
         self.assertEqual(ble._set, {"a", "c"})
-        self.assertRaises(ValueError, ble.remove, "d")
+        self.assertRaises(KeyError, ble.remove, "d")
 
     def test_remove_duplicates(self):
         ble = _BlockLevelElements(["a", "a", "b"])
@@ -468,3 +474,10 @@ def test_update(self):
         ble.update({"b", "c"})
         self.assertEqual(ble._list, ["a", "b", "c"])
         self.assertEqual(ble._set, {"a", "b", "c"})
+
+    # Special tests
+    def test_isinstance(self):
+        ble = _BlockLevelElements([])
+        self.assertIsInstance(ble, _BlockLevelElements)
+        self.assertIsInstance(ble, list)
+        # self.assertIsInstance(ble, set)