AdvancedTagscript 3.2.3__py3-none-any.whl

TagScriptEngine/block/require_blacklist.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Optional, Tuple, cast
+
+from ..interface import verb_required_block
+from ..interpreter import Context
+
+
+__all__: Tuple[str, ...] = ("RequireBlock", "BlacklistBlock")
+
+
+class RequireBlock(verb_required_block(True, parameter=True)):  # type: ignore
+    """
+    The require block will attempt to convert the given parameter into a channel
+    or role, using name or ID. If the user running the tag is not in the targeted
+    channel or doesn't have the targeted role, the tag will stop processing and
+    it will send the response if one is given. Multiple role or channel
+    requirements can be given, and should be split by a ",".
+
+    **Usage:** ``{require(<role,channel>):[response]}``
+
+    **Aliases:** ``whitelist``
+
+    **Payload:** response, None
+
+    **Parameter:** role, channel
+
+    **Examples:** ::
+
+        {require(Moderator)}
+        {require(#general, #bot-cmds):This tag can only be run in #general and #bot-cmds.}
+        {require(757425366209134764, 668713062186090506, 737961895356792882):You aren't allowed to use this tag.}
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("require", "whitelist")
+
+    def process(self, ctx: Context) -> Optional[str]:
+        actions = ctx.response.actions.get("requires")
+        if actions:
+            return None
+        ctx.response.actions["requires"] = {
+            "items": [i.strip() for i in cast(str, ctx.verb.parameter).split(",")],
+            "response": ctx.verb.payload,
+        }
+        return ""
+
+
+class BlacklistBlock(verb_required_block(True, parameter=True)):  # type: ignore
+    """
+    The blacklist block will attempt to convert the given parameter into a channel
+    or role, using name or ID. If the user running the tag is in the targeted
+    channel or has the targeted role, the tag will stop processing and
+    it will send the response if one is given. Multiple role or channel
+    requirements can be given, and should be split by a ",".
+
+    **Usage:** ``{blacklist(<role,channel>):[response]}``
+
+    **Payload:** response, None
+
+    **Parameter:** role, channel
+
+    **Examples:** ::
+
+        {blacklist(Muted)}
+        {blacklist(#support):This tag is not allowed in #support.}
+        {blacklist(Tag Blacklist, 668713062186090506):You are blacklisted from using tags.}
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("blacklist",)
+
+    def process(self, ctx: Context) -> Optional[str]:
+        actions = ctx.response.actions.get("blacklist")
+        if actions:
+            return None
+        ctx.response.actions["blacklist"] = {
+            "items": [i.strip() for i in cast(str, ctx.verb.parameter).split(",")],
+            "response": ctx.verb.payload,
+        }
+        return ""

TagScriptEngine/block/shortcutredirect.py

@@ -0,0 +1,23 @@
+from typing import Optional, Tuple, cast
+
+from ..interface import Block
+from ..interpreter import Context
+from ..verb import Verb
+
+
+__all__: Tuple[str, ...] = ("ShortCutRedirectBlock",)
+
+
+class ShortCutRedirectBlock(Block):
+    def __init__(self, var_name: str) -> None:
+        self.redirect_name: str = var_name
+
+    def will_accept(self, ctx: Context) -> bool:  # type: ignore
+        return cast(str, ctx.verb.declaration).isdigit()
+
+    def process(self, ctx: Context) -> Optional[str]:
+        blank: Verb = Verb()
+        blank.declaration = self.redirect_name
+        blank.parameter = ctx.verb.declaration
+        ctx.verb = blank
+        return None

TagScriptEngine/block/stopblock.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Optional, Tuple, cast
+
+from ..exceptions import StopError
+from ..interface import verb_required_block
+from ..interpreter import Context
+from . import helper_parse_if
+
+
+__all__: Tuple[str, ...] = ("StopBlock",)
+
+
+class StopBlock(verb_required_block(True, parameter=True)):  # type: ignore
+    """
+    The stop block stops tag processing if the given parameter is true.
+    If a message is passed to the payload it will return that message.
+
+    **Usage:** ``{stop(<bool>):[string]}``
+
+    **Aliases:** ``halt, error``
+
+    **Payload:** string, None
+
+    **Parameter:** bool
+
+    **Example:** ::
+
+        {stop({args}==):You must provide arguments for this tag.}
+        # enforces providing arguments for a tag
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("stop", "halt", "error")
+
+    def process(self, ctx: Context) -> Optional[str]:
+        if helper_parse_if(cast(str, ctx.verb.parameter)):
+            raise StopError("" if ctx.verb.payload is None else ctx.verb.payload)
+        return ""

TagScriptEngine/block/strf.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional, Tuple, cast
+
+from ..interface import Block
+from ..interpreter import Context
+
+
+__all__: Tuple[str, ...] = ("StrfBlock",)
+
+
+class StrfBlock(Block):
+    """
+    The strf block converts and formats timestamps based on `strftime formatting spec <https://strftime.org/>`_.
+    Two types of timestamps are supported: ISO and epoch.
+    If a timestamp isn't passed, the current UTC time is used.
+
+    Invoking this block with `unix` will return the current Unix timestamp.
+
+    **Usage:** ``{strf([timestamp]):<format>}``
+
+    **Aliases:** ``unix``
+
+    **Payload:** format, None
+
+    **Parameter:** timestamp
+
+    **Example:** ::
+
+        {strf:%Y-%m-%d}
+        # 2021-07-11
+
+        {strf({user(timestamp)}):%c}
+        # Fri Jun 29 21:10:28 2018
+
+        {strf(1420070400):%A %d, %B %Y}
+        # Thursday 01, January 2015
+
+        {strf(2019-10-09T01:45:00.805000):%H:%M %d-%B-%Y}
+        # 01:45 09-October-2019
+
+        {unix}
+        # 1629182008
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("strf", "unix")
+
+    def process(self, ctx: Context) -> Optional[str]:
+        if cast(str, ctx.verb.declaration).lower() == "unix":
+            return str(int(datetime.now(timezone.utc).timestamp()))
+        if not ctx.verb.payload:
+            return None
+        if ctx.verb.parameter:
+            if ctx.verb.parameter.isdigit():
+                try:
+                    t = datetime.fromtimestamp(int(ctx.verb.parameter))
+                except Exception:
+                    return
+            else:
+                try:
+                    t = datetime.fromisoformat(ctx.verb.parameter)
+                    # converts datetime.__str__ to datetime
+                except ValueError:
+                    return
+        else:
+            t = datetime.now()
+        if not t.tzinfo:
+            t = t.replace(tzinfo=timezone.utc)
+        return t.strftime(ctx.verb.payload)

TagScriptEngine/block/strictvariablegetter.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Optional, Tuple, cast
+
+from ..interface import Block
+from ..interpreter import Context
+
+
+__all__: Tuple[str, ...] = ("StrictVariableGetterBlock",)
+
+
+class StrictVariableGetterBlock(Block):
+    """
+    The strict variable block represents the adapters for any seeded or defined variables.
+    This variable implementation is considered "strict" since it checks whether the variable is
+    valid during :meth:`will_accept` and is only processed if the declaration refers to a valid
+    variable.
+
+    **Usage:** ``{<variable_name>([parameter]):[payload]}``
+
+    **Aliases:** This block is valid for any variable name in `Response.variables`.
+
+    **Payload:** Depends on the variable's underlying adapter.
+
+    **Parameter:** Depends on the variable's underlying adapter.
+
+    **Examples:** ::
+
+        {=(var):This is my variable.}
+        {var}
+        # This is my variable.
+    """
+
+    def will_accept(self, ctx: Context) -> bool:  # type: ignore
+        return ctx.verb.declaration in ctx.response.variables
+
+    def process(self, ctx: Context) -> Optional[str]:
+        return ctx.response.variables[cast(str, ctx.verb.declaration)].get_value(ctx.verb)

TagScriptEngine/block/substr.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Optional, Tuple, cast
+
+from ..interface import verb_required_block
+from ..interpreter import Context
+
+
+__all__: Tuple[str, ...] = ("SubstringBlock",)
+
+
+class SubstringBlock(verb_required_block(True, parameter=True)):  # type: ignore
+    ACCEPTED_NAMES: Tuple[str, ...] = ("substr", "substring")
+
+    def process(self, ctx: Context) -> Optional[str]:
+        try:
+            if "-" not in cast(str, ctx.verb.parameter):
+                return cast(str, ctx.verb.payload)[int(float(cast(str, ctx.verb.parameter))) :]
+
+            spl = cast(str, ctx.verb.parameter).split("-")
+            start = int(float(spl[0]))
+            end = int(float(spl[1]))
+            return cast(str, ctx.verb.payload)[start:end]
+        except Exception:
+            return

TagScriptEngine/block/urlencodeblock.py

@@ -0,0 +1,41 @@
+from typing import Tuple, cast
+from urllib.parse import quote, quote_plus
+
+from ..interface import verb_required_block
+from ..interpreter import Context
+
+
+__all__: Tuple[str, ...] = ("URLEncodeBlock",)
+
+
+class URLEncodeBlock(verb_required_block(True, payload=True)):  # type: ignore
+    """
+    This block will encode a given string into a properly formatted url
+    with non-url compliant characters replaced. Using ``+`` as the parameter
+    will replace spaces with ``+`` rather than ``%20``.
+
+    **Usage:** ``{urlencode(["+"]):<string>}``
+
+    **Payload:** string
+
+    **Parameter:** "+", None
+
+    **Examples:** ::
+
+        {urlencode:covid-19 sucks}
+        # covid-19%20sucks
+
+        {urlencode(+):im stuck at home writing docs}
+        # im+stuck+at+home+writing+docs
+
+        # the following tagscript can be used to search up tag blocks
+        # assume {args} = "command block"
+        # <https://seina-cogs.readthedocs.io/en/latest/search.html?q={urlencode(+):{args}}&check_keywords=yes&area=default>
+        # <https://seina-cogs.readthedocs.io/en/latest/search.html?q=command+block&check_keywords=yes&area=default>
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("urlencode",)
+
+    def process(self, ctx: Context) -> str:
+        method = quote_plus if ctx.verb.parameter == "+" else quote
+        return method(cast(str, ctx.verb.payload))

TagScriptEngine/exceptions.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Tuple
+
+from discord.ext.commands import Cooldown
+
+if TYPE_CHECKING:
+    from .interpreter import Interpreter, Response
+
+
+__all__: Tuple[str, ...] = (
+    "TagScriptError",
+    "WorkloadExceededError",
+    "ProcessError",
+    "EmbedParseError",
+    "BadColourArgument",
+    "StopError",
+    "CooldownExceeded",
+)
+
+
+class TagScriptError(Exception):
+    """Base class for all module errors."""
+
+
+class WorkloadExceededError(TagScriptError):
+    """Raised when the interpreter goes over its passed character limit."""
+
+
+class ProcessError(TagScriptError):
+    """
+    Raised when an exception occurs during interpreter processing.
+
+    Attributes
+    ----------
+    original: Exception
+        The original exception that occurred during processing.
+    response: Response
+        The incomplete response that was being processed when the exception occurred.
+    interpreter: Interpreter
+        The interpreter used for processing.
+    """
+
+    def __init__(self, error: Exception, response: Response, interpreter: Interpreter) -> None:
+        self.original: Exception = error
+        self.response: Response = response
+        self.interpreter: Interpreter = interpreter
+        super().__init__(error)
+
+
+class EmbedParseError(TagScriptError):
+    """Raised if an exception occurs while attempting to parse an embed."""
+
+
+class BadColourArgument(EmbedParseError):
+    """
+    Raised when the passed input fails to convert to `discord.Colour`.
+
+    Attributes
+    ----------
+    argument: str
+        The invalid input.
+    """
+
+    def __init__(self, argument: str) -> None:
+        self.argument: str = argument
+        super().__init__(f'Colour "{argument}" is invalid.')
+
+
+class StopError(TagScriptError):
+    """
+    Raised by the StopBlock to stop processing.
+
+    Attributes
+    ----------
+    message: str
+        The stop error message.
+    """
+
+    def __init__(self, message: str) -> None:
+        self.message: str = message
+        super().__init__(message)
+
+
+class CooldownExceeded(StopError):
+    """
+    Raised by the cooldown block when a cooldown is exceeded.
+
+    Attributes
+    ----------
+    message: str
+        The cooldown error message.
+    cooldown: discord.ext.commands.Cooldown
+        The cooldown bucket with information on the cooldown.
+    key: str
+        The cooldown key that reached its cooldown.
+    retry_after: float
+        The seconds left til the cooldown ends.
+    """
+
+    def __init__(self, message: str, cooldown: Cooldown, key: str, retry_after: float) -> None:
+        self.cooldown: Cooldown = cooldown
+        self.key: str = key
+        self.retry_after: float = retry_after
+        super().__init__(message)

TagScriptEngine/interface/__init__.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Tuple
+
+from .adapter import (
+    Adapter as Adapter,
+    SimpleAdapter as SimpleAdapter,
+)
+from .block import (
+    Block as Block,
+    verb_required_block as verb_required_block,
+)
+
+__all__: Tuple[str, ...] = ("Adapter", "SimpleAdapter", "Block", "verb_required_block")

TagScriptEngine/interface/adapter.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Generic, Optional, Protocol, Tuple, TypeVar
+
+if TYPE_CHECKING:
+    from ..verb import Verb
+
+
+_T = TypeVar("_T", bound=object)
+
+
+__all__: Tuple[str, ...] = ("Adapter", "SimpleAdapter")
+
+
+class _Adapter(Protocol):
+    def __repr__(self) -> str: ...
+
+    def get_value(self, ctx: Verb) -> Optional[str]: ...
+
+
+class Adapter(_Adapter):
+    """
+    The base class for TagScript blocks.
+
+    Implementations must subclass this to create adapters.
+    """
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__qualname__} at {hex(id(self))}>"
+
+    def get_value(self, ctx: Verb) -> Optional[str]:
+        """
+        Processes the adapter's actions for a given :class:`~TagScriptEngine.interpreter.Context`.
+
+        Subclasses must implement this.
+
+        Parameters
+        ----------
+        ctx: Verb
+            The context object containing the TagScript :class:`~TagScriptEngine.verb.Verb`.
+
+        Returns
+        -------
+        Optional[str]
+            The adapters's processed value.
+
+        Raises
+        ------
+        NotImplementedError
+            The subclass did not implement this required method.
+        """
+        raise NotImplementedError
+
+
+class SimpleAdapter(Adapter, Generic[_T]):
+    __slots__: Tuple[str, ...] = ("object", "attributes", "_methods")
+
+    def __init__(self, *, base: _T) -> None:
+        self.object: _T = base
+        self._attributes: Dict[str, Any] = {}
+        self._methods: Dict[str, Any] = {}
+        self.update_attributes()
+        self.update_methods()
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__qualname__} object={self.object!r}>"
+
+    def update_attributes(self) -> None:
+        pass
+
+    def update_methods(self) -> None:
+        pass
+
+    def get_value(self, ctx: Verb) -> Optional[str]:
+        raise NotImplementedError

TagScriptEngine/interface/block.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any, Optional, Protocol, Tuple, Type, cast
+
+if TYPE_CHECKING:
+    from ..interpreter import Context
+
+
+__all__: Tuple[str, ...] = ("Block", "verb_required_block")
+
+
+class _Block(Protocol):
+    ACCEPTED_NAMES: Tuple[str, ...]
+
+    def __repr__(self) -> str: ...
+
+    @classmethod
+    def will_accept(cls, ctx: Context) -> bool: ...
+
+    def pre_process(self, ctx: Context) -> Any: ...
+
+    def process(self, ctx: Context) -> Optional[str]: ...
+
+    def post_process(self, ctx: "Context") -> Any: ...
+
+
+class Block(_Block):
+    """
+    The base class for TagScript blocks.
+
+    Implementations must subclass this to create new blocks.
+
+    Attributes
+    ----------
+    ACCEPTED_NAMES: Tuple[str, ...]
+        The accepted names for this block. This ideally should be set as a class attribute.
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ()
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__qualname__} at {hex(id(self))}>"
+
+    @classmethod
+    def will_accept(cls, ctx: Context) -> bool:
+        """
+        Describes whether the block is valid for the given :class:`~TagScriptEngine.interpreter.Context`.
+
+        Parameters
+        ----------
+        ctx: Context
+            The context object containing the TagScript :class:`~TagScriptEngine.verb.Verb`.
+
+        Returns
+        -------
+        bool
+            Whether the block should be processed for this :class:`~TagScriptEngine.interpreter.Context`.
+        """
+        dec: str = cast(str, ctx.verb.declaration).lower()
+        return dec in cls.ACCEPTED_NAMES
+
+    def pre_process(self, ctx: Context) -> Any:
+        return None
+
+    def process(self, ctx: Context) -> Optional[str]:
+        """
+        Processes the block's actions for a given :class:`~TagScriptEngine.interpreter.Context`.
+
+        Subclasses must implement this.
+
+        Parameters
+        ----------
+        ctx: Context
+            The context object containing the TagScript :class:`~TagScriptEngine.verb.Verb`.
+
+        Returns
+        -------
+        Optional[str]
+            The block's processed value.
+
+        Raises
+        ------
+        NotImplementedError
+            The subclass did not implement this required method.
+        """
+        raise NotImplementedError
+
+    def post_process(self, ctx: "Context") -> Any:
+        return None
+
+
+@lru_cache(maxsize=None)
+def verb_required_block(
+    implicit: bool,
+    *,
+    parameter: bool = False,
+    payload: bool = False,
+) -> Type[Block]:
+    """
+    Get a Block subclass that requires a verb to implicitly or explicitly have a parameter or payload passed.
+
+    Parameters
+    ----------
+    implicit: bool
+        Specifies whether the value is required to be passed implicitly or explicitly.
+        ``{block()}`` would be allowed if implicit is False.
+    parameter: bool
+        Passing True will cause the block to require a parameter to be passed.
+    payload: bool
+        Passing True will cause the block to require the payload to be passed.
+    """
+    check = (lambda x: x) if implicit else (lambda x: x is not None)
+    
+    class VerbRequiredBlock(Block):
+        @classmethod
+        def will_accept(cls, ctx: Context) -> bool:
+            verb = ctx.verb
+            if payload and not check(verb.payload):
+                return False
+            if parameter and not check(verb.parameter):
+                return False
+            return super().will_accept(ctx)
+    return VerbRequiredBlock