diff --git a/README.md b/README.md index 4eabffd..ec93bf4 100644 --- a/README.md +++ b/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 diff --git a/changelog.md b/changelog.md index d0b6115..a1f3d65 100644 --- a/changelog.md +++ b/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. diff --git a/materialx/__meta__.py b/materialx/__meta__.py index 1b16c04..7320b13 100644 --- a/materialx/__meta__.py +++ b/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() diff --git a/materialx/emoji.py b/materialx/emoji.py index 71ce566..b0da6fc 100644 --- a/materialx/emoji.py +++ b/materialx/emoji.py @@ -13,6 +13,16 @@ 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 + +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)) @@ -30,6 +40,30 @@ def _patch_index(options): return _patch_index_for_locations(tuple(icon_locations)) +def deprecated(message, stacklevel=2): # 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__}' is deprecated. {message}", + category=DeprecationWarning, + stacklevel=stacklevel + ) + return func(*args, **kwargs) + return _deprecated_func + return _wrapper + + @functools.lru_cache(maxsize=None) def _patch_index_for_locations(icon_locations): import pymdownx.twemoji_db as twemoji_db @@ -53,18 +87,21 @@ def _patch_index_for_locations(icon_locations): if OPTION_SUPPORT: # pragma: no cover + @deprecated(DEPRECATED.format('material.extensions.emoji.twemoji')) def twemoji(options, md): """Provide a copied Twemoji index with additional codes for Material included icons.""" return _patch_index(options) else: # pragma: no cover + @deprecated(DEPRECATED.format('material.extensions.emoji.twemoji')) def twemoji(): """Provide a copied Twemoji index with additional codes for Material included icons.""" return _patch_index({}) +@deprecated(DEPRECATED.format('material.extensions.emoji.to_svg')) def to_svg(index, shortname, alias, uc, alt, title, category, options, md): """Return SVG element."""