TagScriptEngine v3.2 update for discord.py 2.4.0

MANIFEST.in

@@ -0,0 +1,2 @@
+include LICENSE
+include README.md

README.md

@@ -1,9 +1,16 @@
 ## Information
-<a href='https://tagscriptengine.readthedocs.io/en/latest/?badge=latest'>
-    <img src='https://readthedocs.org/projects/tagscriptengine/badge/?version=latest' alt='Documentation Status' />
+<a href="https://pypi.python.org/pypi/AdvancedTagscriptEngine/">
+    <img src="https://img.shields.io/pypi/pyversions/AdvancedTagscriptEngine" alt="AdvancedTagScriptEngine" />
 </a>
-<a href='https://pypi.python.org/pypi/AdvancedTagscriptEngine/'>
-    <img src='https://img.shields.io/pypi/v/AdvancedTagscriptEngine' alt=' yPI' />
+<a href="https://pypi.python.org/pypi/AdvancedTagscriptEngine/">
+    <img src="https://img.shields.io/pypi/v/AdvancedTagScriptEngine" alt="PyPI - Version">
+</a>
+<a href="https://tagscriptengine.readthedocs.io/en/latest/?badge=latest">
+    <img src="https://readthedocs.org/projects/tagscriptengine/badge/?version=latest" alt="Documentation Status" />
+</a>
+<a href="https://pypi.python.org/pypi/AdvancedTagscriptEngine/">
+    <img src="https://img.shields.io/pypi/dm/AdvancedTagScriptEngine" alt="PyPI - Downloads" />
+
 </a>
 
 This repository is a fork of JonSnowbd's [TagScript](https://github.com/JonSnowbd/TagScript), a string templating language.
@@ -12,7 +19,7 @@ well as multiple utility blocks. Additionally, several tweaks have been made to
 behavior.
 
 This TagScriptEngine is used on [MELON, a Discord bot](https://melonbot.io/invite).
-An example implementation can be found its [Tags cog](https://github.com/japandotorg/Seina-Cogs/tree/main/tags).
+An example implementation can be found in the [Tags cog](https://github.com/japandotorg/Seina-Cogs/tree/main/tags).
 
 Additional documentation on the TagScriptEngine library can be [found here](https://tagscriptengine.readthedocs.io/en/latest/).
 
@@ -21,7 +28,7 @@ Additional documentation on the TagScriptEngine library can be [found here](http
 Download the latest version through pip:
 
 ```
-pip(3) install AdvancedTagscriptEngine
+pip(3) install AdvancedTagScriptEngine
 ```
 
 Download from a commit:
@@ -34,12 +41,12 @@ Install for editing/development:
 
 ```
 git clone https://github.com/japandotorg/TagScriptEngine.git
-pip(3) install -e ./TagScript
+pip(3) install -e ./TagScriptEngine
 ```
 
 ## What?
 
-TagScript is a drop in easy to use string interpreter that lets you provide users with ways of
+AdvancedTagScriptEngine is a drop in easy to use string interpreter that lets you provide users with ways of
 customizing their profiles or chat rooms with interactive text.
 
 For example TagScript comes out of the box with a random block that would let users provide
@@ -50,6 +57,8 @@ use.
 
 `Python 3.8+`
 
+`pyparsing`
+
 `discord.py`
 
-`pyparsing`
+`Red-DiscordBot` [optional]

TagScriptEngine/__init__.py

@@ -1,17 +1,185 @@
-from collections import namedtuple
+from __future__ import annotations
 
-from .adapter import *
-from .block import *
-from .exceptions import *
-from .interface import *
-from .interpreter import *
-from .utils import *
-from .verb import Verb as Verb
+from typing import Final, NamedTuple, Tuple
 
-__version__ = "3.1.4"
+from .adapter import (
+    SafeObjectAdapter as SafeObjectAdapter,
+    StringAdapter as StringAdapter,
+    IntAdapter as IntAdapter,
+    FunctionAdapter as FunctionAdapter,
+    DiscordAttributeAdapter as DiscordAttributeAdapter,
+    UserAdapter as UserAdapter,
+    MemberAdapter as MemberAdapter,
+    DMChannelAdapter as DMChannelAdapter,
+    ChannelAdapter as ChannelAdapter,
+    GuildAdapter as GuildAdapter,
+    RoleAdapter as RoleAdapter,
+    AttributeAdapter as AttributeAdapter,
+    DiscordObjectAdapter as DiscordObjectAdapter,
+    RedCommandAdapter as RedCommandAdapter,
+    RedBotAdapter as RedBotAdapter,
+)
+from .block import (
+    implicit_bool as implicit_bool,
+    helper_parse_if as helper_parse_if,
+    helper_parse_list_if as helper_parse_list_if,
+    helper_split as helper_split,
+    AllowedMentionsBlock as AllowedMentionsBlock,
+    AllBlock as AllBlock,
+    AnyBlock as AnyBlock,
+    AssignmentBlock as AssignmentBlock,
+    BlacklistBlock as BlacklistBlock,
+    BreakBlock as BreakBlock,
+    SequentialGather as SequentialGather,
+    CommandBlock as CommandBlock,
+    EmbedBlock as EmbedBlock,
+    FiftyFiftyBlock as FiftyFiftyBlock,
+    IfBlock as IfBlock,
+    LooseVariableGetterBlock as LooseVariableGetterBlock,
+    MathBlock as MathBlock,
+    OverrideBlock as OverrideBlock,
+    PythonBlock as PythonBlock,
+    RandomBlock as RandomBlock,
+    RangeBlock as RangeBlock,
+    RedirectBlock as RedirectBlock,
+    ReplaceBlock as ReplaceBlock,
+    RequireBlock as RequireBlock,
+    ShortCutRedirectBlock as ShortCutRedirectBlock,
+    StopBlock as StopBlock,
+    StrfBlock as StrfBlock,
+    StrictVariableGetterBlock as StrictVariableGetterBlock,
+    SubstringBlock as SubstringBlock,
+    URLEncodeBlock as URLEncodeBlock,
+    UpperBlock as UpperBlock,
+    LowerBlock as LowerBlock,
+    CountBlock as CountBlock,
+    LengthBlock as LengthBlock,
+    CooldownBlock as CooldownBlock,
+)
+from .interface import (
+    Adapter as Adapter,
+    SimpleAdapter as SimpleAdapter,
+    Block as Block,
+    verb_required_block as verb_required_block,
+)
+from ._warnings import (
+    TagScriptEngineDeprecationWarning as TagScriptEngineDeprecationWarning,
+)
+from .exceptions import (
+    TagScriptError as TagScriptError,
+    WorkloadExceededError as WorkloadExceededError,
+    ProcessError as ProcessError,
+    EmbedParseError as EmbedParseError,
+    BadColourArgument as BadColourArgument,
+    StopError as StopError,
+    CooldownExceeded as CooldownExceeded,
+)
+from .interpreter import (
+    Interpreter as Interpreter,
+    AsyncInterpreter as AsyncInterpreter,
+    Context as Context,
+    Response as Response,
+    Node as Node,
+    build_node_tree as build_node_tree,
+)
+from .utils import (
+    truncate as truncate,
+    escape_content as escape_content,
+    maybe_await as maybe_await,
+)
+from .verb import (
+    Verb as Verb,
+)
 
 
-class VersionInfo(namedtuple("VersionInfo", "major minor micro")):
+__all__: Tuple[str, ...] = (
+    "implicit_bool",
+    "helper_parse_if",
+    "helper_parse_list_if",
+    "helper_split",
+    "AllBlock",
+    "AnyBlock",
+    "AssignmentBlock",
+    "BlacklistBlock",
+    "BreakBlock",
+    "SequentialGather",
+    "CommandBlock",
+    "CooldownBlock",
+    "EmbedBlock",
+    "FiftyFiftyBlock",
+    "IfBlock",
+    "LooseVariableGetterBlock",
+    "MathBlock",
+    "OverrideBlock",
+    "PythonBlock",
+    "RandomBlock",
+    "RangeBlock",
+    "RedirectBlock",
+    "ReplaceBlock",
+    "RequireBlock",
+    "ShortCutRedirectBlock",
+    "StopBlock",
+    "StrfBlock",
+    "StrictVariableGetterBlock",
+    "SubstringBlock",
+    "URLEncodeBlock",
+    "UpperBlock",
+    "LowerBlock",
+    "CountBlock",
+    "LengthBlock",
+    "SafeObjectAdapter",
+    "StringAdapter",
+    "IntAdapter",
+    "FunctionAdapter",
+    "RedCommandAdapter",
+    "RedBotAdapter",
+    "AttributeAdapter",
+    "DiscordAttributeAdapter",
+    "UserAdapter",
+    "MemberAdapter",
+    "DMChannelAdapter",
+    "ChannelAdapter",
+    "GuildAdapter",
+    "RoleAdapter",
+    "DiscordObjectAdapter",
+    "Adapter",
+    "SimpleAdapter",
+    "Block",
+    "verb_required_block",
+    "TagScriptEngineDeprecationWarning",
+    "TagScriptError",
+    "WorkloadExceededError",
+    "ProcessError",
+    "EmbedParseError",
+    "BadColourArgument",
+    "StopError",
+    "CooldownExceeded",
+    "Interpreter",
+    "AsyncInterpreter",
+    "Context",
+    "Response",
+    "Node",
+    "build_node_tree",
+    "truncate",
+    "escape_content",
+    "maybe_await",
+    "Verb",
+    "__version__",
+    "VersionInfo",
+    "version_info",
+)
+
+
+__version__: Final[str] = "3.2.2"
+
+
+class VersionNamedTuple(NamedTuple):
+    major: int
+    minor: int
+    micro: int
+
+
+class VersionInfo(VersionNamedTuple):
     """
     Version information.
 
@@ -25,9 +193,9 @@ class VersionInfo(namedtuple("VersionInfo", "major minor micro")):
         Micro version number.
     """
 
-    __slots__ = ()
+    __slots__: Tuple[str, ...] = ()
 
-    def __str__(self):
+    def __str__(self) -> str:
         """
         Returns a string representation of the version information.
 
@@ -39,7 +207,7 @@ def __str__(self):
         return "{major}.{minor}.{micro}".format(**self._asdict())
 
     @classmethod
-    def from_str(cls, version):
+    def from_str(cls, version: str) -> "VersionInfo":
         """
         Returns a VersionInfo instance from a string.
 
@@ -56,4 +224,4 @@ def from_str(cls, version):
         return cls(*map(int, version.split(".")))
 
 
-version_info = VersionInfo.from_str(__version__)
+version_info: VersionInfo = VersionInfo.from_str(__version__)

TagScriptEngine/_warnings.py

@@ -0,0 +1,88 @@
+import warnings
+import functools
+from typing import Callable, Optional, Tuple, TypeVar
+from typing_extensions import ParamSpec
+
+
+_P = ParamSpec("_P")
+_T = TypeVar("_T")
+
+
+__all__: Tuple[str, ...] = (
+    "TagScriptEngineDeprecationWarning",
+    "TagScriptEngineAttributeRemovalWarning",
+)
+
+
+class TagScriptEngineAttributeRemovalWarning(Warning):
+    """A class for issuing removal warning for TagScriptEngine class attributes."""
+
+
+class TagScriptEngineDeprecationWarning(DeprecationWarning):
+    """A class for issuing deprecation warnings for TagScriptEngine modules."""
+
+
+def remove(
+    name: str, *, reason: Optional[str] = None, version: Optional[str] = None, level: int = 2
+) -> None:
+    warnings.warn(
+        "Removal: {name}.{reason}{version}".format(
+            name=name,
+            reason=" ({})".format(reason) if reason else "",
+            version=" -- Removal scheduled since version v{}".format(version) if version else "",
+        ),
+        category=TagScriptEngineAttributeRemovalWarning,
+        stacklevel=level,
+    )
+
+
+def removal(
+    *,
+    name: Optional[str] = None,
+    reason: Optional[str] = None,
+    version: Optional[str] = None,
+    level: int = 3,
+) -> Callable[[Callable[_P, _T]], Callable[_P, _T]]:
+    def decorator(func: Callable[_P, _T]) -> Callable[_P, _T]:
+        functools.wraps(func)
+
+        def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _T:
+            remove(name or func.__name__, reason=reason, version=version, level=level)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+def depricate(
+    name: str, *, reason: Optional[str] = None, version: Optional[str] = None, level: int = 2
+) -> None:
+    warnings.warn(
+        "Deprecated: {name}.{reason}{version}".format(
+            name=name,
+            reason=" ({})".format(reason) if reason else "",
+            version=" -- Deprecated since version v{}.".format(version) if version else "",
+        ),
+        category=TagScriptEngineDeprecationWarning,
+        stacklevel=level,
+    )
+
+
+def deprecated(
+    *,
+    name: Optional[str] = None,
+    reason: Optional[str] = None,
+    version: Optional[str] = None,
+    level: int = 3,
+) -> Callable[[Callable[_P, _T]], Callable[_P, _T]]:
+    def decorator(func: Callable[_P, _T]) -> Callable[_P, _T]:
+        functools.wraps(func)
+
+        def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _T:
+            depricate(name or func.__name__, reason=reason, version=version, level=level)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator