AdvancedTagscript 3.2.3__py3-none-any.whl

TagScriptEngine/block/comment.py

@@ -0,0 +1,29 @@
+from typing import Optional, Tuple
+from ..interface import Block
+from ..interpreter import Context
+
+
+class CommentBlock(Block):
+    """
+    The comment block is just for comments, it will not be parsed,
+    however it will be removed from your tag's output.
+
+    **Usage:** ``{comment([other]):[text]}``
+
+    **Aliases:** /, Comment, comment, //, #
+
+    **Payload:** ``text``
+
+    **Parameter:** ``other``
+
+    .. tagscript::
+
+        {#:Comment!}
+
+        {Comment(Something):Comment!}
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("/", "Comment", "comment", "//", "#")
+
+    def process(self, ctx: Context) -> Optional[str]:
+        return ""

TagScriptEngine/block/control.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from typing import Optional, Tuple, cast
+
+from ..interface import verb_required_block, Block
+from ..interpreter import Context
+from . import helper_parse_if, helper_parse_list_if, helper_split
+
+
+__all__: Tuple[str, ...] = ("AnyBlock", "AllBlock", "IfBlock")
+
+
+def parse_into_output(payload: str, result: Optional[bool]) -> Optional[str]:
+    if result is None:
+        return
+    try:
+        output = helper_split(payload, False)
+        if output is not None and len(output) == 2:
+            if result:
+                return output[0]
+            else:
+                return output[1]
+        elif result:
+            return payload
+        else:
+            return ""
+    except:  # noqa: E722
+        return
+
+
+ImplicitPPRBlock: Block = verb_required_block(True, payload=True, parameter=True)
+
+
+class AnyBlock(ImplicitPPRBlock):  # type: ignore
+    """
+    The any block checks that any of the passed expressions are true.
+    Multiple expressions can be passed to the parameter by splitting them with ``|``.
+
+    The payload is a required message that must be split by ``|``.
+    If the expression evaluates true, then the message before the ``|`` is returned, else the message after is returned.
+
+    **Usage:** ``{any(<expression|expression|...>):<message>}``
+
+    **Aliases:** ``or``
+
+    **Payload:** message
+
+    **Parameter:** expression
+
+    **Examples:** ::
+
+        {any({args}==hi|{args}==hello|{args}==heyy):Hello {user}!|How rude.}
+        # if {args} is hi
+        Hello sravan#0001!
+
+        # if {args} is what's up!
+        How rude.
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("any", "or")
+
+    def process(self, ctx: Context) -> Optional[str]:
+        result = any(helper_parse_list_if(ctx.verb.parameter) or [])
+        return parse_into_output(cast(str, ctx.verb.payload), result)
+
+
+class AllBlock(ImplicitPPRBlock):  # type: ignore
+    """
+    The all block checks that all of the passed expressions are true.
+    Multiple expressions can be passed to the parameter by splitting them with ``|``.
+
+    The payload is a required message that must be split by ``|``.
+    If the expression evaluates true, then the message before the ``|`` is returned, else the message after is returned.
+
+    **Usage:** ``{all(<expression|expression|...>):<message>}``
+
+    **Aliases:** ``and``
+
+    **Payload:** message
+
+    **Parameter:** expression
+
+    **Examples:** ::
+
+        {all({args}>=100|{args}<=1000):You picked {args}.|You must provide a number between 100 and 1000.}
+        # if {args} is 52
+        You must provide a number between 100 and 1000.
+
+        # if {args} is 282
+        You picked 282.
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("all", "and")
+
+    def process(self, ctx: Context) -> Optional[str]:
+        result = all(helper_parse_list_if(ctx.verb.parameter) or [])
+        return parse_into_output(cast(str, ctx.verb.payload), result)
+
+
+class IfBlock(ImplicitPPRBlock):  # type: ignore
+    """
+    The if block returns a message based on the passed expression to the parameter.
+    An expression is represented by two values compared with an operator.
+
+    The payload is a required message that must be split by ``|``.
+    If the expression evaluates true, then the message before the ``|`` is returned, else the message after is returned.
+
+    **Expression Operators:**
+
+    +----------+--------------------------+---------+---------------------------------------------+
+    | Operator | Check                    | Example | Description                                 |
+    +==========+==========================+=========+=============================================+
+    | ``==``   | equality                 | a==a    | value 1 is equal to value 2                 |
+    +----------+--------------------------+---------+---------------------------------------------+
+    | ``!=``   | inequality               | a!=b    | value 1 is not equal to value 2             |
+    +----------+--------------------------+---------+---------------------------------------------+
+    | ``>``    | greater than             | 5>3     | value 1 is greater than value 2             |
+    +----------+--------------------------+---------+---------------------------------------------+
+    | ``<``    | less than                | 4<8     | value 1 is less than value 2                |
+    +----------+--------------------------+---------+---------------------------------------------+
+    | ``>=``   | greater than or equality | 10>=10  | value 1 is greater than or equal to value 2 |
+    +----------+--------------------------+---------+---------------------------------------------+
+    | ``<=``   | less than or equality    | 5<=6    | value 1 is less than or equal to value 2    |
+    +----------+--------------------------+---------+---------------------------------------------+
+
+    **Usage:** ``{if(<expression>):<message>]}``
+
+    **Payload:** message
+
+    **Parameter:** expression
+
+    **Examples:** ::
+
+        {if({args}==63):You guessed it! The number I was thinking of was 63!|Too {if({args}<63):low|high}, try again.}
+        # if args is 63
+        # You guessed it! The number I was thinking of was 63!
+
+        # if args is 73
+        # Too low, try again.
+
+        # if args is 14
+        # Too high, try again.
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("if",)
+
+    def process(self, ctx: Context) -> Optional[str]:
+        result = helper_parse_if(cast(str, ctx.verb.parameter))
+        return parse_into_output(cast(str, ctx.verb.payload), result)

TagScriptEngine/block/cooldown.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional, Tuple, cast
+
+from discord.ext.commands import Cooldown, CooldownMapping
+
+from ..exceptions import CooldownExceeded
+from ..interface import verb_required_block
+from ..interpreter import Context
+from .helpers import helper_split
+
+__all__: Tuple[str, ...] = ("CooldownBlock",)
+
+
+class CooldownBlock(verb_required_block(True, payload=True, parameter=True)):  # type: ignore
+    """
+    The cooldown block implements cooldowns when running a tag.
+    The parameter requires 2 values to be passed: ``rate`` and ``per`` integers.
+    The ``rate`` is the number of times the tag can be used every ``per`` seconds.
+
+    The payload requires a ``key`` value, which is the key used to store the cooldown.
+    A key should be any string that is unique. If a channel's ID is passed as a key,
+    the tag's cooldown will be enforced on that channel. Running the tag in a separate channel
+    would have a different cooldown with the same ``rate`` and ``per`` values.
+
+    The payload also has an optional ``message`` value, which is the message to be sent when the
+    cooldown is exceeded. If no message is passed, the default message will be sent instead.
+    The cooldown message supports 2 blocks: ``key`` and ``retry_after``.
+
+    **Usage:** ``{cooldown(<rate>|<per>):<key>|[message]}``
+
+    **Payload:** key, message
+
+    **Parameter:** rate, per
+
+    **Examples:** ::
+
+        {cooldown(1|10):{author(id)}}
+        # the tag author used the tag more than once in 10 seconds
+        # The bucket for 741074175875088424 has reached its cooldown. Retry in 3.25 seconds."
+
+        {cooldown(3|3):{channel(id)}|Slow down! This tag can only be used 3 times per 3 seconds per channel. Try again in **{retry_after}** seconds."}
+        # the tag was used more than 3 times in 3 seconds in a channel
+        # Slow down! This tag can only be used 3 times per 3 seconds per channel. Try again in **0.74** seconds.
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("cooldown",)
+    COOLDOWNS: Dict[Any, CooldownMapping] = {}
+
+    @classmethod
+    def create_cooldown(cls, key: Any, rate: float, per: int) -> CooldownMapping:
+        cooldown = CooldownMapping.from_cooldown(rate, per, lambda x: x)
+        cls.COOLDOWNS[key] = cooldown
+        return cooldown
+
+    def process(self, ctx: Context) -> Optional[str]:
+        verb = ctx.verb
+        try:
+            rate, per = cast(List[str], helper_split(cast(str, verb.parameter), maxsplit=1))
+            per = int(per)
+            rate = float(rate)
+        except (ValueError, TypeError):
+            return
+
+        if split := helper_split(cast(str, verb.payload), False, maxsplit=1):
+            key, message = split
+        else:
+            key = verb.payload
+            message = None
+
+        cooldown_key = ctx.response.extra_kwargs.get("cooldown_key")
+        if cooldown_key is None:
+            cooldown_key = ctx.original_message
+        try:
+            cooldown = self.COOLDOWNS[cooldown_key]
+            base = cast(Cooldown, cooldown._cooldown)
+            if (rate, per) != (base.rate, base.per):
+                cooldown = self.create_cooldown(cooldown_key, rate, per)
+        except KeyError:
+            cooldown = self.create_cooldown(cooldown_key, rate, per)
+
+        current = time.time()
+        bucket = cast(Cooldown, cooldown.get_bucket(key, current))
+        retry_after = bucket.update_rate_limit(current)
+        if retry_after:
+            retry_after = round(retry_after, 2)
+            if message:
+                message = message.replace("{key}", str(key)).replace(
+                    "{retry_after}", str(retry_after)
+                )
+            else:
+                message = f"The bucket for {key} has reached its cooldown. Retry in {retry_after} seconds."
+            raise CooldownExceeded(message, bucket, cast(str, key), retry_after)
+        return ""

TagScriptEngine/block/count.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from typing import Optional, Tuple, cast
+
+from ..interface import verb_required_block
+from ..interpreter import Context
+
+
+__all__: Tuple[str, ...] = ("CountBlock", "LengthBlock")
+
+
+class CountBlock(verb_required_block(True, payload=True)):  # type: ignore
+    """
+    The count block will count how much of text is in message.
+    This is case sensitive and will include substrings, if you
+    don't provide a parameter, it will count the spaces in the
+    message.
+
+    **Usage:** ``{count([text]):<message>}``
+
+    **Aliases:** ``None``
+
+    **Payload:** ``message``
+
+    **Parameter:** text
+
+    .. tagscript::
+        {count(Tag):TagScriptEngine}
+        # 1
+
+        {count(Tag): Tag Script Engine TagScriptEngine}
+        # 2
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("count",)
+
+    def process(self, ctx: Context) -> Optional[str]:
+        if ctx.verb.parameter:
+            payload: str = cast(str, ctx.verb.payload)
+            return str(payload.count(ctx.verb.parameter))
+        return str(len(cast(str, ctx.verb.payload)) + 1)
+
+
+class LengthBlock(verb_required_block(True, payload=True)):  # type: ignore
+    """
+    The length block will check the length of the given String.
+    If a parameter is passed in, the block will check the length
+    based on what you passed in, w for word, s for spaces.
+    If you provide an invalid parameter, the block will return -1.
+
+    **Usage:** ``{length(<text>)}``
+
+    **Aliases:** ``len``
+
+    **Payload:** None
+
+    **Parameter:** ``text``
+
+    .. tagscript::
+
+        {len("TagScriptEngine")}
+        15
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("length", "len")
+
+    def process(self, ctx: Context) -> Optional[str]:
+        return str(len(ctx.verb.parameter)) if ctx.verb.parameter else "-1"

TagScriptEngine/block/embedblock.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+import json
+from inspect import ismethod
+from typing import Any, Dict, List, Optional, Tuple, Union, cast
+
+from discord import Colour, Embed
+
+from ..interface import Block
+from ..interpreter import Context
+from .helpers import helper_split, easier_helper_split, implicit_bool
+from ..utils import truncate
+from ..exceptions import BadColourArgument, EmbedParseError
+from .._warnings import removal
+
+try:
+    import orjson  # noqa: F401
+except ModuleNotFoundError:
+    _has_orjson: bool = False
+else:
+    _has_orjson: bool = True
+
+
+__all__: Tuple[str, ...] = ("EmbedBlock",)
+
+
+if _has_orjson:
+    _from_json = orjson.loads  # type: ignore
+else:
+    _from_json = json.loads
+
+
+def string_to_color(argument: str) -> Colour:
+    arg = argument.replace("0x", "").lower()
+
+    if arg[0] == "#":
+        arg = arg[1:]
+    try:
+        value = int(arg, base=16)
+        if not (0 <= value <= 0xFFFFFF):
+            raise BadColourArgument(arg)
+        return Colour(value=value)
+    except ValueError:
+        arg = arg.replace(" ", "_")
+        method = getattr(Colour, arg, None)
+        if arg.startswith("from_") or method is None or not ismethod(method):
+            raise BadColourArgument(arg)
+        return method()
+
+
+def set_color(embed: Embed, attribute: str, value: str) -> None:
+    value = string_to_color(value)  # type: ignore
+    setattr(embed, attribute, value)
+
+
+def set_dynamic_url(embed: Embed, attribute: str, value: str) -> None:
+    method = getattr(embed, f"set_{attribute}")
+    method(url=value)
+
+
+def add_field(embed: Embed, _: str, payload: str) -> None:
+    if (data := easier_helper_split(payload, maxsplit=3)) is None:  # type: ignore
+        raise EmbedParseError("`add_field` payload was not split by |")
+    try:
+        name, value, _inline = data
+        inline = implicit_bool(_inline)
+        if inline is None:
+            raise EmbedParseError(
+                "`inline` argument for `add_field` is not a boolean value (_inline)"
+            )
+    except ValueError:
+        name, value = cast(List[str], helper_split(payload, 2))  # type: ignore
+        inline = False
+    name = truncate(name, max=FIELD_LIMITS["field.name"])
+    value = truncate(value, max=FIELD_LIMITS["field.value"])
+    embed.add_field(name=name, value=value, inline=inline)
+
+
+def set_footer(embed: Embed, _: str, payload: str) -> None:
+    data = easier_helper_split(payload, maxsplit=2)  # type: ignore
+    if data is None:
+        embed.set_footer(text=truncate(payload, max=FIELD_LIMITS["footer.text"]))
+    else:
+        text, icon_url = data
+        embed.set_footer(text=truncate(text, max=FIELD_LIMITS["footer.text"]), icon_url=icon_url)
+
+
+# Discord embed field character limits
+# https://docs.discord.com/developers/resources/message#embed-object-embed-limits
+FIELD_LIMITS: Dict[str, int] = {
+    "title": 256,
+    "description": 4096,
+    "footer.text": 2048,
+    "author.name": 256,
+    "field.name": 256,
+    "field.value": 1024,
+}
+
+
+class EmbedBlock(Block):
+    """
+    An embed block will send an embed in the tag response.
+    There are two ways to use the embed block, either by using properly
+    formatted embed JSON from an embed generator or manually inputting
+    the accepted embed attributes.
+
+    **JSON**
+
+    Using JSON to create an embed offers complete embed customization.
+    Multiple embed generators are available online to visualize and generate
+    embed JSON.
+
+    **Usage:** ``{embed(<json>)}``
+
+    **Payload:** None
+
+    **Parameter:** json
+
+    **Examples:** ::
+
+        {embed({"title":"Hello!", "description":"This is a test embed."})}
+        {embed({
+            "title":"Here's a random duck!",
+            "image":{"url":"https://random-d.uk/api/randomimg"},
+            "color":15194415
+        })}
+
+    **Manual**
+
+    The following embed attributes can be set manually:
+
+    *   ``title``
+    *   ``description``
+    *   ``color``
+    *   ``url``
+    *   ``thumbnail``
+    *   ``image``
+    *   ``footer``
+    *   ``field`` - (See below)
+
+    Adding a field to an embed requires the payload to be split by ``|``,
+    ``;`` or ``,`` into either 2 or 3 parts. The first part is the name
+    of the field, the  second is the text of the field, and the third
+    optionally specifies  whether the field should be inline.
+
+    **Usage:** ``{embed(<attribute>):<value>}``
+
+    **Payload:** value
+
+    **Parameter:** attribute
+
+    **Examples:** ::
+
+        {embed(color):#37b2cb}
+        {embed(title):Rules}
+        {embed(description):Follow these rules to ensure a good experience in our server!}
+        {embed(field):Rule 1|Respect everyone you speak to.|false}
+        {embed(footer):Thanks for reading!|{guild(icon)}}
+
+    Both methods can be combined to create an embed in a tag.
+    The following tagscript uses JSON to create an embed with fields and later
+    set the embed title.
+
+    ::
+
+        {embed(title):my embed title}
+        {embed({{
+            "fields": [
+                {
+                    "name": "Field 1",
+                    "value": "field description",
+                    "inline": false
+                }
+            ]
+        })}
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("embed",)
+
+    ATTRIBUTE_HANDLERS: Dict[str, Any] = {
+        "description": setattr,
+        "title": setattr,
+        "color": set_color,
+        "colour": set_color,
+        "url": setattr,
+        "thumbnail": set_dynamic_url,
+        "image": set_dynamic_url,
+        "field": add_field,
+        "footer": set_footer,
+    }
+
+    @removal(
+        name="EmbedBlock",
+        reason=(
+            "One of EmbedBlock's trait is scheduled to be removed in the next minor release, "
+            "A minor exception handling which would restrict the embed from getting sent and "
+            "would raise TagScriptEngine.exceptions.EmbedParseError incase it had more than "
+            "6000 characters, to know more about the limitations of discord embeds refer to the "
+            "[Official Discord API Docs](https://discord.com/developers/docs/resources/channel#embed-object-embed-limits)."
+        ),
+        version="3.2.0",
+    )
+    def __init__(self) -> None:
+        super().__init__()
+
+    @staticmethod
+    def get_embed(ctx: Context) -> Embed:
+        return ctx.response.actions.get("embed", Embed())
+
+    @staticmethod
+    def value_to_color(value: Optional[Union[int, str]]) -> Colour:
+        if value is None or isinstance(value, Colour):
+            return value  # type: ignore
+        if isinstance(value, int):
+            return Colour(value)
+        elif isinstance(value, str):
+            return string_to_color(value)
+        else:
+            raise EmbedParseError("Received invalid type for color key (expected string or int)")
+
+    def text_to_embed(self, text: str) -> Embed:
+        try:
+            data = _from_json(text)
+        except (json.decoder.JSONDecodeError, ValueError) as error:
+            raise EmbedParseError(error) from error
+
+        if data.get("embed"):
+            data = data["embed"]
+        if data.get("timestamp"):
+            data["timestamp"] = data["timestamp"].strip("Z")
+
+        color = data.pop("color", data.pop("colour", None))
+
+        try:
+            embed = Embed.from_dict(data)
+        except Exception as error:
+            raise EmbedParseError(error) from error
+        else:
+            if color := self.value_to_color(color):
+                embed.color = color
+            self._truncate_embed_fields(embed)
+            return embed
+
+    @classmethod
+    def update_embed(cls, embed: Embed, attribute: str, value: str) -> Embed:
+        # Truncate value to Discord's per-field limit before setting
+        if attribute in FIELD_LIMITS:
+            value = truncate(value, max=FIELD_LIMITS[attribute])
+        handler = cls.ATTRIBUTE_HANDLERS[attribute]
+        try:
+            handler(embed, attribute, value)
+        except Exception as error:
+            raise EmbedParseError(error) from error
+        return embed
+
+    @staticmethod
+    def _truncate_embed_fields(embed: Embed) -> None:
+        """Truncate embed fields to Discord's per-field character limits."""
+        if embed.title and len(embed.title) > FIELD_LIMITS["title"]:
+            embed.title = truncate(embed.title, max=FIELD_LIMITS["title"])
+        if embed.description and len(embed.description) > FIELD_LIMITS["description"]:
+            embed.description = truncate(embed.description, max=FIELD_LIMITS["description"])
+        if embed.footer and embed.footer.text and len(embed.footer.text) > FIELD_LIMITS["footer.text"]:
+            embed.set_footer(text=truncate(embed.footer.text, max=FIELD_LIMITS["footer.text"]), icon_url=embed.footer.icon_url)
+        if embed.author and embed.author.name and len(embed.author.name) > FIELD_LIMITS["author.name"]:
+            embed.set_author(name=truncate(embed.author.name, max=FIELD_LIMITS["author.name"]), url=embed.author.url, icon_url=embed.author.icon_url)
+        for field in embed.fields:
+            if field.name and len(field.name) > FIELD_LIMITS["field.name"]:
+                idx = embed.fields.index(field)
+                embed.set_field_at(idx, name=truncate(field.name, max=FIELD_LIMITS["field.name"]), value=field.value, inline=field.inline)
+            if field.value and len(field.value) > FIELD_LIMITS["field.value"]:
+                idx = embed.fields.index(field)
+                embed.set_field_at(idx, name=field.name, value=truncate(field.value, max=FIELD_LIMITS["field.value"]), inline=field.inline)
+
+    @staticmethod
+    def return_error(error: Exception) -> str:
+        return f"Embed Parse Error: {error}"
+
+    @staticmethod
+    def return_embed(ctx: Context, embed: Embed) -> str:
+        try:
+            length = len(embed)
+        except Exception as error:
+            return str(error)
+        if length > 6000:
+            return f"`MAX EMBED LENGTH REACHED ({length}/6000)`"
+        ctx.response.actions["embed"] = embed
+        return ""
+
+    def process(self, ctx: Context) -> Optional[str]:
+        if not ctx.verb.parameter:
+            return self.return_embed(ctx, self.get_embed(ctx))
+
+        lowered = ctx.verb.parameter.lower()
+        try:
+            if ctx.verb.parameter.startswith("{") and ctx.verb.parameter.endswith("}"):
+                embed = self.text_to_embed(ctx.verb.parameter)
+            elif lowered in self.ATTRIBUTE_HANDLERS and ctx.verb.payload:
+                embed = self.get_embed(ctx)
+                embed = self.update_embed(embed, lowered, ctx.verb.payload)
+            else:
+                return
+        except EmbedParseError as error:
+            return self.return_error(error)
+
+        return self.return_embed(ctx, embed)

TagScriptEngine/block/fiftyfifty.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import random
+from typing import Optional, Tuple
+
+from ..interface import verb_required_block
+from ..interpreter import Context
+
+
+__all__: Tuple[str, ...] = ("FiftyFiftyBlock",)
+
+
+class FiftyFiftyBlock(verb_required_block(True, payload=True)):  # type: ignore
+    """
+    The fifty-fifty block has a 50% change of returning the payload, and 50% chance of returning null.
+
+    **Usage:**  ``{50:<message>}``
+
+    **Aliases:**  ``5050, ?``
+
+    **Payload:**  message
+
+    **Parameter:**  None
+
+    **Examples:**  ::
+
+        I pick {if({5050:.}!=):heads|tails}
+        # I pick heads
+    """
+
+    ACCEPTED_NAMES: Tuple[str, ...] = ("5050", "50", "?")
+
+    def process(self, ctx: Context) -> Optional[str]:
+        return random.choice(["", ctx.verb.payload])