ya-tagscript 1.0.0a4__py3-none-any.whl

ya_tagscript/__init__.py

@@ -0,0 +1,6 @@
+from .interpreter import Response, TagScriptInterpreter
+
+__all__ = (
+    "Response",
+    "TagScriptInterpreter",
+)

ya_tagscript/adapters/__init__.py

@@ -0,0 +1,21 @@
+from .discord_adapters import (
+    AttributeAdapter,
+    ChannelAdapter,
+    GuildAdapter,
+    MemberAdapter,
+)
+from .function_adapter import FunctionAdapter
+from .int_adapter import IntAdapter
+from .object_adapter import ObjectAdapter
+from .string_adapter import StringAdapter
+
+__all__ = (
+    "AttributeAdapter",
+    "ChannelAdapter",
+    "FunctionAdapter",
+    "GuildAdapter",
+    "IntAdapter",
+    "MemberAdapter",
+    "ObjectAdapter",
+    "StringAdapter",
+)

ya_tagscript/adapters/discord_adapters/__init__.py

@@ -0,0 +1,11 @@
+from .attribute_adapter import AttributeAdapter
+from .channel_adapter import ChannelAdapter
+from .guild_adapter import GuildAdapter
+from .member_adapter import MemberAdapter
+
+__all__ = (
+    "AttributeAdapter",
+    "ChannelAdapter",
+    "GuildAdapter",
+    "MemberAdapter",
+)

ya_tagscript/adapters/discord_adapters/attribute_adapter.py

@@ -0,0 +1,62 @@
+from collections.abc import Callable
+from typing import Any
+
+from ...interfaces import AdapterABC
+from ...interpreter import Context
+from ...util import escape_content
+
+
+class AttributeAdapter(AdapterABC):
+    """A basic Discord object adapter
+
+    **Attributes**:
+
+    - ``id``: :class:`int` — The object's ID
+    - ``created_at``: :class:`~datetime.datetime` — Represents the object's creation
+      time
+    - ``timestamp``: :class:`int` — The seconds-based timestamp of the object's
+      ``created_at`` attribute
+    - ``name``: :class:`str` — The object's name or the stringified version of the
+      object if no name exists
+    """
+
+    __slots__ = ("object", "_attributes", "_methods")
+
+    def __init__(
+        self,
+        base: Any,  # should be typed by each subclass, not feasible here
+    ):
+        self.object = base
+        self._attributes = {
+            "id": self.object.id,
+            "created_at": self.object.created_at,
+            "timestamp": int(self.object.created_at.timestamp()),
+            "name": getattr(self.object, "name", str(self.object)),
+        }
+        self._methods: dict[str, Callable[[], Any]] = {}
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__qualname__} object={self.object!r}>"
+
+    def get_value(self, ctx: Context) -> str | None:
+        should_escape = False
+
+        if ((param := ctx.node.parameter) is None) or (
+            (parsed_param := ctx.interpret_segment(param)).strip() == ""
+        ):
+            return_value = str(self.object)
+        else:
+            try:
+                value = self._attributes[parsed_param]
+            except KeyError:
+                if method := self._methods.get(parsed_param):
+                    value = method()
+                else:
+                    return None
+
+            if isinstance(value, tuple):
+                value, should_escape = value
+
+            return_value = str(value) if value is not None else None
+
+        return escape_content(return_value) if should_escape else return_value

ya_tagscript/adapters/discord_adapters/channel_adapter.py

@@ -0,0 +1,54 @@
+from typing import Any
+
+import discord
+
+from .attribute_adapter import AttributeAdapter
+
+
+class ChannelAdapter(AttributeAdapter):
+    """A :class:`discord.TextChannel` adapter
+
+    Note:
+        Only :class:`discord.TextChannel` instances are fully supported. The
+        constructor accepts ``Any`` to avoid type checking issues when creating this
+        adapter with the :attr:`discord.ext.commands.Context.channel` attribute, which
+        could be any kind of channel. This loose typing allows the construction with
+        that attribute but doesn't set any of the :class:`discord.TextChannel`-specific
+        attributes.
+
+    **Attributes**:
+
+    (from base :class:`AttributeAdapter`)
+
+    - ``id``: :class:`int` — The channel's ID
+    - ``created_at``: :class:`~datetime.datetime` — Represents the channel's creation
+      time
+    - ``timestamp``: :class:`int` — The seconds-based timestamp of the channel's
+      ``created_at`` attribute
+    - ``name``: :class:`str` — The channel's name
+
+    (:class:`discord.TextChannel`-specific)
+
+    - ``nsfw``: :class:`bool` — Whether this :class:`discord.TextChannel` is marked as
+      NSFW and is therefore age-gated
+    - ``mention``: :class:`str` — The mention string for this channel
+    - ``topic``: :class:`str` | :data:`None` — The channel's topic, if it exists and
+      :data:`None` otherwise
+    - ``slowmode``: :class:`int` — The slowmode delay of the channel in seconds
+      (0 represents a disabled slowmode)
+    - ``position``: :class:`int` — The position of the channel in the channel list
+    """
+
+    def __init__(self, channel: Any):
+        # hard to type usefully since ctx.channel might not be TextChannel
+        super().__init__(base=channel)
+        if not isinstance(channel, discord.TextChannel):
+            return
+        additional_attributes = {
+            "nsfw": channel.nsfw,
+            "mention": channel.mention,
+            "topic": channel.topic,
+            "slowmode": channel.slowmode_delay,
+            "position": channel.position,
+        }
+        self._attributes.update(additional_attributes)

ya_tagscript/adapters/discord_adapters/guild_adapter.py

@@ -0,0 +1,63 @@
+import random
+from collections.abc import Sequence
+
+import discord
+
+from .attribute_adapter import AttributeAdapter
+
+
+class GuildAdapter(AttributeAdapter):
+    """A :class:`discord.Guild` adapter
+
+    **Attributes**:
+
+    (from base :class:`AttributeAdapter`)
+
+    - ``id``: :class:`int` — The guild's ID
+    - ``created_at``: :class:`~datetime.datetime` — Represents the guild's creation
+      time
+    - ``timestamp``: :class:`int` — The seconds-based timestamp of the guild's
+      ``created_at`` attribute
+    - ``name``: :class:`str` — The guild's name
+
+    (:class:`discord.Guild`-specific)
+
+    - ``icon``: :class:`tuple[str, Literal[False]]` — The guild's icon. The first tuple
+      element contains the icon's URL or is empty. The :data:`False` instructs the
+      adapter to not escape the contents of this attribute.
+    - ``member_count``: :class:`int` | :data:`None` — The number of members in this
+      guild (alias: ``members``) (Can be :data:`None` under some circumstances)
+    - ``members``: :class:`int` | :data:`None` — The number of members in this guild
+      (alias: ``member_count``) (Can be :class:`None` under some circumstances)
+    - ``bots``: :class:`int` — The number of bots in this guild
+    - ``humans``: :class:`int` — The number of human users in this guild
+    - ``description``: :class:`str` — The guild's description
+
+    - ``random``: :class:`discord.Member` — Returns a randomly chosen member of the
+      guild
+    """
+
+    def __init__(self, guild: discord.Guild):
+        super().__init__(base=guild)
+        bots = 0
+        humans = 0
+        for m in guild.members:
+            if m.bot:
+                bots += 1
+            else:
+                humans += 1
+        additional_attributes = {
+            "icon": (getattr(guild.icon, "url", ""), False),
+            "member_count": guild.member_count,
+            "members": guild.member_count,
+            "bots": bots,
+            "humans": humans,
+            "description": guild.description or "No description.",
+        }
+        self._attributes.update(additional_attributes)
+        additional_methods = {"random": self.random_member}
+        self._methods.update(additional_methods)
+
+    def random_member(self) -> discord.Member:
+        members: Sequence[discord.Member] = self.object.members
+        return random.choice(members)

ya_tagscript/adapters/discord_adapters/member_adapter.py

@@ -0,0 +1,60 @@
+import discord
+
+from .attribute_adapter import AttributeAdapter
+
+
+class MemberAdapter(AttributeAdapter):
+    """A :class:`discord.Member` adapter
+
+    **Attributes**:
+
+    (from base :class:`AttributeAdapter`)
+
+    - ``id``: :class:`int` — The user's ID
+    - ``created_at``: :class:`~datetime.datetime` — Represents the user's creation time
+    - ``timestamp``: :class:`int` — The seconds-based timestamp of the user's
+      ``created_at`` attribute
+    - ``name``: :class:`str` — The user's name
+
+    (:class:`discord.Member`-specific)
+
+    - ``color`` :class:`discord.Colour` — The colour the user's name is shown in
+      (depends on their top role) (alias: ``colour``)
+    - ``colour`` :class:`discord.Colour` — The colour the user's name is shown in
+      (depends on their top role) (alias: ``color``)
+    - ``global_name``: :class:`str` | :data:`None` — The user's global nickname
+    - ``nick``: :class:`str` | :data:`None` — The user's guild-specific nickname
+    - ``avatar`` :class:`tuple[str, Literal[False]]` — The user's avatar. The first
+      tuple element contains the avatar's URL. The False instructs the adapter to not
+      escape the contents of this attribute.
+    - ``discriminator``: :class:`str` — The user's discriminator
+    - ``joined_at``: :class:`~datetime.datetime` — The user's time of joining this
+      guild. If the user has left the guild, this falls back to the user's creation
+      time.
+    - ``joinstamp``: :class:`int` — The seconds-based timestamp of the user's
+      joined_at attribute
+    - ``mention``: :class:`str` — The mention string for this user
+    - ``bot``: :class:`bool` — Whether this user is a bot account
+    - ``top_role``: :class:`discord.Role` — The user's topmost role
+    - ``roleids``: :class:`str` — A space-separated list of the IDs of each role of
+      this user.
+    """
+
+    def __init__(self, member: discord.Member):
+        super().__init__(base=member)
+        joined_at = member.joined_at or member.created_at
+        additional_attributes = {
+            "color": member.color,
+            "colour": member.colour,
+            "global_name": member.global_name,
+            "nick": member.nick,
+            "avatar": (member.display_avatar.url, False),
+            "discriminator": member.discriminator,
+            "joined_at": joined_at,
+            "joinstamp": int(joined_at.timestamp()),
+            "mention": member.mention,
+            "bot": member.bot,
+            "top_role": member.top_role,
+            "roleids": " ".join(str(rid.id) for rid in member.roles),
+        }
+        self._attributes.update(additional_attributes)

ya_tagscript/adapters/function_adapter.py

@@ -0,0 +1,24 @@
+from collections.abc import Callable
+from typing import Any
+
+from ..interfaces import AdapterABC
+from ..interpreter import Context
+
+
+class FunctionAdapter(AdapterABC):
+    """An adapter for a simple, no-arg function
+
+    Caution:
+        The provided function CANNOT take ANY arguments.
+    """
+
+    __slots__ = ("fn",)
+
+    def __init__(self, function: Callable[[], Any]):
+        self.fn: Callable[[], Any] = function
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__qualname__} fn={self.fn!r}>"
+
+    def get_value(self, ctx: Context) -> str | None:
+        return str(self.fn())

ya_tagscript/adapters/int_adapter.py

@@ -0,0 +1,17 @@
+from ..interfaces import AdapterABC
+from ..interpreter import Context
+
+
+class IntAdapter(AdapterABC):
+    """An adapter for integers"""
+
+    __slots__ = ("integer",)
+
+    def __init__(self, integer: int):
+        self.integer: int = int(integer)
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__qualname__} integer={self.integer!r}>"
+
+    def get_value(self, ctx: Context) -> str | None:
+        return str(self.integer)

ya_tagscript/adapters/object_adapter.py

@@ -0,0 +1,49 @@
+from inspect import ismethod
+
+from ..interfaces import AdapterABC
+from ..interpreter import Context
+
+
+class ObjectAdapter(AdapterABC):
+    """An adapter for any sort of Python object
+
+    Caution:
+        The following things are unsupported and will be rejected
+
+        - Methods
+        - Private attributes (names starting with ``_``)
+        - Nested attributes (``obj.a.b``)
+
+            - ``obj.a`` is accepted
+            - ``obj.a.b`` is not accepted
+
+        - Float attributes will be truncated into integer values (``12.97 -> 12``)
+    """
+
+    __slots__ = ("obj",)
+
+    def __init__(self, base: object):
+        self.obj = base
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__qualname__} object={self.obj!r}>"
+
+    def get_value(self, ctx: Context) -> str | None:
+        if ctx.node.parameter is None:
+            return str(self.obj)
+
+        parsed_param = ctx.interpret_segment(ctx.node.parameter)
+
+        if parsed_param.startswith("_") or "." in parsed_param:
+            return None
+
+        try:
+            attribute = getattr(self.obj, parsed_param)
+        except AttributeError:
+            return None
+        if ismethod(attribute):
+            return None
+        elif isinstance(attribute, float):
+            attribute = int(attribute)
+
+        return str(attribute)

ya_tagscript/adapters/string_adapter.py

@@ -0,0 +1,93 @@
+from ..interfaces import AdapterABC
+from ..interpreter import Context
+from ..util import escape_content
+
+
+class StringAdapter(AdapterABC):
+    """An adapter for strings
+
+    .. _partial-substring-retrieval:
+
+    Retrieving partial substrings with parameters
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    You can optionally use parameters to limit what parts of the string should be
+    retrieved.
+
+    If you provide a single number n as the parameter, the n-th word of the string is
+    returned (split by spaces). The first word is at index 1, and so on (1-indexed).
+
+    **Examples**::
+
+        # Assume my_string_variable holds "Hello there. General Kenobi."
+        {my_string_variable(2)}
+        # there.
+
+        {my_string_variable(3)}
+        # General
+
+    If you provide a single number followed (or preceded) by a plus, all words after
+    (or before) are returned (split by spaces).
+
+    **Examples**::
+
+        # Assume my_string_variable holds "Hello there. General Kenobi."
+        {my_string_variable(3+)}
+        # General Kenobi.
+
+        {my_string_variable(+2)}
+        # Hello there.
+
+    You can define the characters to split the string on by passing a payload. The
+    string will then be split at occurrences of those characters.
+
+    **Examples**::
+
+        # Assume my_string_variable holds "Hello there. General Kenobi."
+        {my_string_variable(2):.}
+        # General Kenobi
+
+        {my_string_variable(3):en}
+        # obi.
+    """
+
+    def __init__(self, string: str, *, should_escape: bool = False):
+        self.string: str = str(string)
+        self.should_escape: bool = should_escape
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__qualname__} string={self.string!r}>"
+
+    def get_value(self, ctx: Context) -> str | None:
+        return self._return_value(self._handle_ctx(ctx))
+
+    def _handle_ctx(self, ctx: Context) -> str:
+        if (param := ctx.node.parameter) is None:
+            return self.string
+
+        parsed_param = ctx.interpret_segment(param)
+        parsed_payload = (
+            ctx.interpret_segment(ctx.node.payload)
+            if ctx.node.payload is not None
+            else None
+        )
+
+        try:
+            if "+" not in parsed_param:
+                index = int(parsed_param) - 1
+                splitter = " " if parsed_payload is None else parsed_payload
+                return self.string.split(splitter)[index]
+            else:
+                index = int(parsed_param.replace("+", "")) - 1
+                splitter = " " if parsed_payload is None else parsed_payload
+                if parsed_param.startswith("+"):
+                    return splitter.join(self.string.split(splitter)[: index + 1])
+                elif parsed_param.endswith("+"):
+                    return splitter.join(self.string.split(splitter)[index:])
+                else:
+                    return self.string.split(splitter)[index]
+        except (ValueError, IndexError):
+            return self.string
+
+    def _return_value(self, string: str) -> str | None:
+        return escape_content(string) if self.should_escape else string

ya_tagscript/blocks/__init__.py

@@ -0,0 +1,70 @@
+from .actions import (
+    CommandBlock,
+    DeleteBlock,
+    OverrideBlock,
+    ReactBlock,
+    RedirectBlock,
+    SilenceBlock,
+)
+from .conditional import AllBlock, AnyBlock, IfBlock, PythonBlock
+from .discord import CooldownBlock, EmbedBlock
+from .flow import BreakBlock, ShortcutRedirectBlock, StopBlock
+from .limiters import BlacklistBlock, RequireBlock
+from .lists import CycleBlock, ListBlock
+from .math import MathBlock, OrdinalBlock
+from .meta import CommentBlock, DebugBlock
+from .rng import FiftyFiftyBlock, RandomBlock, RangeBlock
+from .strings import (
+    CaseBlock,
+    JoinBlock,
+    ReplaceBlock,
+    SubstringBlock,
+    URLDecodeBlock,
+    URLEncodeBlock,
+)
+from .time import StrfBlock, TimedeltaBlock
+from .variables import (
+    AssignmentBlock,
+    LooseVariableGetterBlock,
+    StrictVariableGetterBlock,
+)
+
+__all__ = (
+    "AllBlock",
+    "AnyBlock",
+    "AssignmentBlock",
+    "BlacklistBlock",
+    "BreakBlock",
+    "CaseBlock",
+    "CommandBlock",
+    "CommentBlock",
+    "CooldownBlock",
+    "CycleBlock",
+    "DebugBlock",
+    "DeleteBlock",
+    "EmbedBlock",
+    "FiftyFiftyBlock",
+    "IfBlock",
+    "JoinBlock",
+    "ListBlock",
+    "LooseVariableGetterBlock",
+    "MathBlock",
+    "OrdinalBlock",
+    "OverrideBlock",
+    "PythonBlock",
+    "RandomBlock",
+    "RangeBlock",
+    "ReactBlock",
+    "RedirectBlock",
+    "ReplaceBlock",
+    "RequireBlock",
+    "ShortcutRedirectBlock",
+    "SilenceBlock",
+    "StopBlock",
+    "StrfBlock",
+    "StrictVariableGetterBlock",
+    "SubstringBlock",
+    "TimedeltaBlock",
+    "URLDecodeBlock",
+    "URLEncodeBlock",
+)

ya_tagscript/blocks/actions/__init__.py

@@ -0,0 +1,15 @@
+from .command_block import CommandBlock
+from .delete_block import DeleteBlock
+from .override_block import OverrideBlock
+from .react_block import ReactBlock
+from .redirect_block import RedirectBlock
+from .silence_block import SilenceBlock
+
+__all__ = (
+    "CommandBlock",
+    "DeleteBlock",
+    "OverrideBlock",
+    "ReactBlock",
+    "RedirectBlock",
+    "SilenceBlock",
+)

ya_tagscript/blocks/actions/command_block.py

@@ -0,0 +1,66 @@
+from ...interfaces import BlockABC
+from ...interpreter import Context
+
+
+class CommandBlock(BlockABC):
+    """
+    Run a command as if the tag invoker had run it.
+
+    By default, only 3 command blocks can be used in a tag.
+
+    **Usage**: ``{command:<command text>}``
+
+    **Aliases**: ``c``, ``com``, ``cmd``, ``command``
+
+    **Parameter**: ``None``
+
+    **Payload**: ``command text`` (required)
+
+    **Examples**::
+
+        {c:ping}
+        # adds "ping" to the "commands" list of the Response's actions attribute
+
+        {c:ban {target(id)} flooding/spam}
+        # (Assuming target is a user with ID 123)
+        # adds "ban 123 flooding/spam"
+
+    **Response Attribute**:
+
+    This block sets the following attribute on the
+    :class:`~ya_tagscript.interpreter.Response` object:
+
+    - :attr:`~ya_tagscript.interpreter.Response.actions`
+        - ``actions["commands"]``: :class:`list[str]` | :data:`None` — A list of
+          command strings or :data:`None`
+
+    Note:
+        This block will only add the processed command strings to the ``commands``
+        :attr:`~ya_tagscript.interpreter.Response.actions` key as shown above. It is
+        *up to the client* to implement actual command execution behaviour as desired.
+    """
+
+    requires_nonempty_payload = True
+
+    def __init__(self, limit: int = 3):
+        self.limit = limit
+
+    @property
+    def _accepted_names(self) -> set[str]:
+        return {"c", "com", "cmd", "command"}
+
+    def process(self, ctx: Context) -> str | None:
+        if (payload := ctx.node.payload) is None or payload.strip() == "":
+            return None
+
+        command = ctx.interpret_segment(payload)
+
+        commands: list[str] | None = ctx.response.actions.get("commands")
+        if commands is not None:
+            if len(commands) >= self.limit:
+                return f"`COMMAND LIMIT REACHED ({self.limit})`"
+            ctx.response.actions["commands"].append(command)
+        else:
+            ctx.response.actions["commands"] = [command]
+
+        return ""