Merge pull request #28 from facelessuser/chore/deprecate

Deprecate the library

Author: facelessuser

README.md

@@ -6,6 +6,11 @@
 ![License][license-image-mit]
 # MkDocs Material Extensions
 
+> NOTE: This project is now deprecated as MkDocs for Material now implements this logic directly.
+> Users should migrate to using `mkdocs-material`'s `material.extensions.emoji.twemoji` and 
+> `material.extensions.emoji.to_svg` in place of the respective `materialx.emoji.twemoji` and `materialx.emoji.to_svg`
+> functions provided by this library.
+
 Markdown extension resources for [MkDocs for Material][mkdocs-material]
 
 ## Install

changelog.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.3
+
+- **NEW**: The final release. `mkdocs-material` (version 9.4) now has this library's logic built-in making this library
+  obsolete. Users should migrate to using `mkdocs-material`'s `material.extensions.emoji.twemoji` and
+  `material.extensions.emoji.to_svg` in place of the respective `materialx.emoji.twemoji` and `materialx.emoji.to_svg`
+  functions.
+
 ## 1.2
 
 - **NEW**: Add official support for Python 3.11 and 3.12.

materialx/__meta__.py

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

materialx/emoji.py

@@ -13,6 +13,19 @@
 import pymdownx
 from pymdownx.emoji import TWEMOJI_SVG_CDN, add_attriubtes
 import xml.etree.ElementTree as etree  # noqa: N813
+import warnings
+from functools import wraps
+import logging
+
+log = logging.getLogger('mkdocs')
+
+DEPRECATED = """\
+Material emoji logic has been officially moved into mkdocs-material
+version 9.4. Please use Material's '{}'
+as mkdocs_material_extensions is deprecated and will no longer be
+supported moving forward. This is the last release.
+"""
+
 
 OPTION_SUPPORT = pymdownx.__version_info__ >= (7, 1, 0)
 RESOURCES = os.path.dirname(inspect.getfile(material))
@@ -22,6 +35,40 @@
     RES_PATH = os.path.join(RESOURCES, '.icons')
 
 
+@functools.lru_cache(maxsize=None)
+def log_msg(message):
+    """Log message."""
+
+    log.warning(message)
+
+
+def deprecated(message, stacklevel=2, name=None):  # pragma: no cover
+    """
+    Raise a `DeprecationWarning` when wrapped function/method is called.
+
+    Usage:
+
+        @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__ if name is None else name}' is deprecated.\n{message}",
+                category=DeprecationWarning,
+                stacklevel=stacklevel
+            )
+
+            log_msg(message)
+            return func(*args, **kwargs)
+        return _deprecated_func
+    return _wrapper
+
+
+@deprecated(DEPRECATED.format('material.extensions.emoji.twemoji'), name='materialx.emoji.twemoji')
 def _patch_index(options):
     """Patch the given index."""
 
@@ -65,6 +112,7 @@ def twemoji():
         return _patch_index({})
 
 
+@deprecated(DEPRECATED.format('material.extensions.emoji.to_svg'), 1, name='materialx.emoji.to_svg')
 def to_svg(index, shortname, alias, uc, alt, title, category, options, md):
     """Return SVG element."""