AdvancedTagScript 3.3.0__tar.gz → 3.3.2__tar.gz

{advancedtagscript-3.3.0 → advancedtagscript-3.3.2}/AdvancedTagScript.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AdvancedTagScript
-Version: 3.3.0
+Version: 3.3.2
 Summary: An easy drop in user-provided Templating system.
 Home-page: https://github.com/cool-aid-man/TagScriptEngine
 Author: cool-aid-man, inthedark.org, PhenoM4n4n

{advancedtagscript-3.3.0 → advancedtagscript-3.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AdvancedTagScript
-Version: 3.3.0
+Version: 3.3.2
 Summary: An easy drop in user-provided Templating system.
 Home-page: https://github.com/cool-aid-man/TagScriptEngine
 Author: cool-aid-man, inthedark.org, PhenoM4n4n

{advancedtagscript-3.3.0 → advancedtagscript-3.3.2}/TagScriptEngine/__init__.py

@@ -181,7 +181,7 @@ __all__: Tuple[str, ...] = (
 )
 
 
-__version__: Final[str] = "3.3.0"
+__version__: Final[str] = "3.3.2"
 
 
 class VersionNamedTuple(NamedTuple):

{advancedtagscript-3.3.0 → advancedtagscript-3.3.2}/TagScriptEngine/adapter/discordadapters.py

@@ -103,7 +103,6 @@ class DiscordAttributeAdapter(
     ]
 ):
     """
-    .. versionadded:: 3.2.0
     """
 
     def __init__(
@@ -191,7 +190,6 @@ class UserAdapter(DiscordAttributeAdapter):
     avatar_decoration
         A link to the user's avatar decoration.
 
-    .. versionadded:: 3.2.0
     """
 
     def update_attributes(self) -> None:
@@ -260,16 +258,26 @@ class MemberAdapter(DiscordAttributeAdapter):
         If the user has boosted, this will be the UTC timestamp of when they did,
         if not this will be empty.
     timed_out
-        If the user is timed out, this will be the UTC timestamp of when they'll be untimed-out,
-        if not timed out this will be empty.
+        If the user is currently timed out, the datetime of when the timeout ends;
+        otherwise ``False``.
     banner
-        The users banner url
+        The user's banner url, if available. A banner is not delivered over the
+        gateway, so the bare engine only sees it when the member was retrieved
+        via an explicit REST fetch - otherwise this is empty for cached members.
+        The Tags cog resolves it lazily (fetching only when a tag uses ``banner``,
+        with caching and a per-user cooldown), so there it is populated on demand.
     """
 
     def update_attributes(self) -> None:
         object: discord.Member = cast(discord.Member, self.object)
         avatar_url: str = object.display_avatar.url
         joined_at: datetime.datetime = getattr(object, "joined_at", self.object.created_at)
+        # So ``timed_out_until`` must be compared against the current time. 
+        # And Returns ``False`` when the member isn't currently timed out.
+        timed_out_until: Any = getattr(object, "timed_out_until", None)
+        is_timed_out: bool = bool(timed_out_until) and timed_out_until > discord.utils.utcnow()
+        # ``Member.banner``/``display_banner`` is now explicitly fetched.
+        banner: Any = getattr(object, "display_banner", None) or getattr(object, "banner", None)
         additional_attributes: Dict[str, Any] = {
             "color": object.color,
             "colour": object.color,
@@ -282,8 +290,8 @@ class MemberAdapter(DiscordAttributeAdapter):
             "bot": object.bot,
             "top_role": getattr(object, "top_role", ""),
             "boost": getattr(object, "premium_since", ""),
-            "timed_out": getattr(object, "timed_out_until", ""),
-            "banner": object.banner.url if object.banner else "",
+            "timed_out": timed_out_until if is_timed_out else False,
+            "banner": banner.url if banner else "",
         }
         if roleids := getattr(self.object, "_roles", None):
             additional_attributes["roleids"] = " ".join(str(r) for r in roleids)
@@ -315,7 +323,6 @@ class DMChannelAdapter(DiscordAttributeAdapter):
     jump_url
         A link to the channel.
 
-    .. versionadded:: 3.2.0
     """
 
     def update_attributes(self) -> None:
@@ -359,9 +366,6 @@ class ChannelAdapter(DiscordAttributeAdapter):
         If no category channel, this will return empty.
     jump_url
         A link to the channel.
-
-    .. versionchanged:: 3.2.0
-        Added ``jump_url`` as a parameter.
     """
 
     def update_attributes(self) -> None:
@@ -429,10 +433,6 @@ class GuildAdapter(DiscordAttributeAdapter):
         A link to the server's invite splash.
     banner
         A link to the server's banner.
-
-    .. versionchanged:: 3.2.0
-        Added ``mfa``, ``boosters``, ``boost_level``,
-        ``discovery_splash``, ``invite_splash`` & ``banner``.
     """
 
     def update_attributes(self) -> None:
@@ -509,7 +509,6 @@ class RoleAdapter(DiscordAttributeAdapter):
     position
         The role's position.
 
-    .. versionadded:: 3.2.0
     """
 
     def update_attributes(self) -> None:
@@ -546,7 +545,6 @@ class DiscordObjectAdapter(Adapter):
     timestamp
         The object's creation date as a UTC timestamp.
 
-    .. versionadded:: 3.2.0
     """
 
     __slots__: Tuple[str, ...] = ("object", "_attributes", "_methods")

advancedtagscript-3.3.2/TagScriptEngine/adapter/redbotadapters.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import datetime
+from typing import Any, Optional, Tuple, cast
+
+import discord
+
+from ..verb import Verb
+from ..interface import SimpleAdapter
+from ..utils import escape_content
+
+try:
+    import redbot  # noqa: F401
+except ModuleNotFoundError:
+    _has_redbot = False
+else:
+    _has_redbot = True
+
+    from redbot.core.bot import Red
+    from redbot.core.commands import Command
+    from redbot.core.utils.chat_formatting import humanize_number, humanize_list
+    
+
+__all__: Tuple[str, ...] = ("RedCommandAdapter", "RedBotAdapter")
+
+
+class RedCommandAdapter(SimpleAdapter["Command"]):
+    """
+    The ``{commandinfo}`` block reads a command's metadata and returns it as
+    text. Unlike the :ref:`Command Block`, it does **not** run the command.
+    See the attribute list below.
+
+    **Usage:** ``{commandinfo([attribute]):<command>}``
+
+    **Payload:** command (supplied by the block)
+
+    **Parameter:** attribute, None
+
+    Attributes
+    ----------
+    name
+        The command's name.
+    qualified_name
+        The command's full name, including any parent groups.
+    cog_name
+        The name of the cog the command belongs to.
+    description
+        The command's description. Most commands leave this unset, so it falls
+        back to the help text's first line (``short_doc``) when empty.
+    short_doc
+        The first line of the command's help text.
+    help
+        The command's full help text (its docstring).
+    aliases
+        The command's aliases, or ``None`` if it has none.
+    signature
+        The command's argument signature. Empty for commands that take no
+        arguments.
+    """
+
+    def __init__(self, base: Command, *, signature: Optional[str] = None) -> None:
+        if not _has_redbot:
+            raise ImportError(
+                "A Red-DiscordBot instance is required to use this.", name="redbot"
+            )
+        self.signature: Optional[str] = signature
+        super().__init__(base=base)
+
+    def update_attributes(self) -> None:
+        command: Command = self.object
+        # As no command sets ``description`` so the docstring goes to ``help`` (and ``short_doc`` is its first line).
+        short_doc: str = getattr(command, "short_doc", "") or ""
+        description: str = getattr(command, "description", "") or short_doc
+        self._attributes.update(
+            {
+                "name": command.name,
+                "cog_name": getattr(command, "cog_name", None),
+                "description": description,
+                "short_doc": short_doc,
+                "help": getattr(command, "help", None),
+                "aliases": humanize_list(list(getattr(command, "aliases", []))) or "None",
+                "qualified_name": command.qualified_name,
+                "signature": self.signature,
+            }
+        )
+
+    def get_value(self, ctx: Verb) -> str:
+        should_escape: bool = False
+        if ctx.parameter is None:
+            return_value: str = self.object.qualified_name
+        else:
+            try:
+                value: Any = self._attributes[ctx.parameter]
+            except KeyError:
+                return  # type: ignore
+            if isinstance(value, tuple):
+                value, should_escape = value
+            return_value: str = str(value) if value is not None else None  # type: ignore
+        return escape_content(return_value) if should_escape else return_value
+
+
+class RedBotAdapter(SimpleAdapter["Red"]):
+    """
+    The ``{bot}`` block with no parameters returns the bot's name & discriminator,
+    but passing the attributes listed below to the block payload will return that attribute instead.
+
+    **Usage:** ``{bot([attribute])}``
+
+    **Payload:** None
+
+    **Parameter:** attribute, None
+
+    Attributes
+    ----------
+    id
+        The bot's Discord ID.
+    name
+        The bot's username.
+    discriminator
+        The bot's discriminator.
+    nick
+        The bot's global display name. This is not a per-server nickname: the
+        bot user has no guild context here, so a server-specific nick is not
+        available through this block.
+    created_at
+        The bot's creation date.
+    timestamp
+        The bot's creation date as a UTC timestamp.
+    mention
+        A formatted text that pings the bot.
+    avatar
+        A link to the bot's avatar, which can be used in embeds.
+    verified
+        If the bot is verified or not.
+    shard_count (*)
+        The bot's total shard count.
+    servers (*)
+        Total server/guild count of the bot.
+    channels (*)
+        Total number of channels visible to the bot.
+    visible_users (*)
+        Total number of users visible to the bot.
+    total_users (*)
+        The bot's total user count.
+    unique_users (*)
+        The bot's unique user count.
+    percentage_chunked (*)
+        Percentage of the bot's members that are cached/chunked (rounded to two
+        decimals); ``0`` when no member counts are available.
+
+    Attributes marked ``(*)`` are owner-only and return nothing for other users.
+    """
+ 
+    # Bot-Owner Only attributes since these require iterating the whole guild/member cache.
+    OWNER_ATTRIBUTES: Tuple[str, ...] = (
+        "shard_count",
+        "servers",
+        "channels",
+        "visible_users",
+        "total_users",
+        "unique_users",
+        "percentage_chunked",
+    )
+
+    def __init__(self, base: Red, *, owner: bool = True) -> None:
+        if not _has_redbot:
+            raise ImportError("A Red-DiscordBot instance is required to use this.")
+        self.is_owner: bool = owner
+        super().__init__(base=base)
+
+    def update_attributes(self) -> None:
+        self.user: discord.ClientUser = cast(discord.ClientUser, self.object.user)
+        created_at: datetime.datetime = getattr(
+            self.user, "created_at", None
+        ) or discord.utils.snowflake_time(self.user.id)
+        self._attributes.update(
+            {
+                "id": self.user.id,
+                "name": self.user.name,
+                "discriminator": self.user.discriminator,
+                "nick": self.user.display_name,
+                "mention": self.user.mention,
+                "avatar": (self.user.display_avatar.url, False),
+                "created_at": created_at,
+                "timestamp": int(created_at.timestamp()),
+                "verified": self.user.verified,
+            }
+        )
+
+    def _compute_owner_attribute(self, name: str) -> Any:
+        bot: Red = self.object
+        if name == "shard_count":
+            # ``shard_count`` is None on an unsharded bot.
+            return humanize_number(bot.shard_count or 1)
+        if name == "servers":
+            return humanize_number(len(bot.guilds))
+        if name == "channels":
+            return humanize_number(sum(len(g.channels) for g in bot.guilds))
+        if name == "unique_users":
+            return humanize_number(len(bot.users))
+        visible_users: int = sum(len(g.members) for g in bot.guilds)
+        if name == "visible_users":
+            return humanize_number(visible_users)
+        total_users: int = sum(g.member_count or 0 for g in bot.guilds)
+        if name == "total_users":
+            return humanize_number(total_users)
+        if name == "percentage_chunked":
+            # Guard against a bot in no guilds / with no counted members.
+            return round(visible_users / total_users * 100, 2) if total_users else 0
+        return None
+
+    def get_value(self, ctx: Verb) -> str:
+        should_escape: bool = False
+        if ctx.parameter is None:
+            return_value: str = "{0.name}#{0.discriminator}".format(self.user)
+        else:
+            parameter: str = ctx.parameter
+            if parameter in self.OWNER_ATTRIBUTES:
+                # Owner-only: hidden from non-owners, computed on demand (and
+                # cached in ``_attributes``) the first time an owner asks for it.
+                if not self.is_owner:
+                    return  # type: ignore
+                if parameter not in self._attributes:
+                    self._attributes[parameter] = self._compute_owner_attribute(parameter)
+            try:
+                value: Any = self._attributes[parameter]
+            except KeyError:
+                return  # type: ignore
+            if isinstance(value, tuple):
+                value, should_escape = value
+            return_value: str = str(value) if value is not None else None  # type: ignore
+        return escape_content(return_value) if should_escape else return_value

{advancedtagscript-3.3.0 → advancedtagscript-3.3.2}/TagScriptEngine/block/assign.py

@@ -55,8 +55,10 @@ class AssignmentBlock(verb_required_block(False, parameter=True)):  # type: igno
         - You can name variables with **anything** ``except`` existing block names or aliases.
         - They will ``not`` reference the value in payload, if the name is same as an existing block name or alias.
     
-    ----
-    
+    .. raw:: html
+
+        <hr>
+
     .. important:: How Argument Parsing Works - In Detail
 
     - A variable is essentially a string that can be treated as a sequence of elements (words, numbers, etc.) when accessed.
@@ -66,8 +68,10 @@ class AssignmentBlock(verb_required_block(False, parameter=True)):  # type: igno
       to extract ``specific`` parts. Let's take a look at **how** it works.
     - Parsing out of bounds index will return the whole string.
     
-    ----
-    
+    .. raw:: html
+
+        <hr>
+
     .. rubric:: **Basic Argument Parsing**
     
     Example
@@ -148,7 +152,9 @@ class AssignmentBlock(verb_required_block(False, parameter=True)):  # type: igno
         - ``-n``   → nth element from end
         - ``-n+``  → nth element from end → then forward to end (index resolved first)
     
-    -----
+    .. raw:: html
+
+        <hr>
     
     .. rubric:: **Advanced Argument Parsing**
 

{advancedtagscript-3.3.0 → advancedtagscript-3.3.2}/TagScriptEngine/utils.py

@@ -33,8 +33,6 @@ def truncate(text: str, *, max: int = 2000, var: str = "...") -> str:
     -------
     str
         The truncated content.
-
-    .. versionadded:: 3.2.0
     """
     if len(text) <= max:
         return text

advancedtagscript-3.3.0/TagScriptEngine/adapter/redbotadapters.py

@@ -1,161 +0,0 @@
-import datetime
-from typing import Any, Dict, Optional, Tuple, cast
-
-import discord
-
-from ..verb import Verb
-from ..interface import SimpleAdapter
-from ..utils import escape_content
-
-try:
-    import redbot  # noqa: F401
-except ModuleNotFoundError:
-    _has_redbot = False
-else:
-    _has_redbot = True
-
-    from redbot.core.bot import Red
-    from redbot.core.commands import Command
-    from redbot.core.utils.chat_formatting import humanize_number, humanize_list
-    
-
-__all__: Tuple[str, ...] = ("RedCommandAdapter", "RedBotAdapter")
-
-
-class RedCommandAdapter(SimpleAdapter["Command"]):
-    if not _has_redbot:
-        raise ImportError("A Red-DiscordBot instance is required to use this.", name="redbot")
-
-    def __init__(self, base: Command, *, signature: Optional[str] = None) -> None:
-        super().__init__(base=base)
-        self.signature: Optional[str] = signature
-
-    def update_attributes(self) -> None:
-        command: Command = self.object
-        self._attributes.update(
-            {
-                "name": command.name,
-                "cog_name": getattr(command, "cog_name", None),
-                "description": getattr(command, "description", None),
-                "aliases": humanize_list(list(getattr(command, "aliases", []))) or "None",
-                "qualified_name": command.qualified_name,
-                "signature": self.signature,
-            }
-        )
-
-    def get_value(self, ctx: Verb) -> str:
-        should_escape: bool = False
-        if ctx.parameter is None:
-            return_value: str = self.object.qualified_name
-        else:
-            try:
-                value: Any = self._attributes[ctx.parameter]
-            except KeyError:
-                return  # type: ignore
-            if isinstance(value, tuple):
-                value, should_escape = value
-            return_value: str = str(value) if value is not None else None  # type: ignore
-        return escape_content(return_value) if should_escape else return_value
-
-
-class RedBotAdapter(SimpleAdapter["Red"]):
-    """
-    The ``{bot}`` block with no parameters returns the bot's name & discriminator,
-    but passing the attributes listed below to the block payload will return that attribute instead.
-
-    **Usage:** ``{bot([attribute])}``
-
-    **Payload:** None
-
-    **Parameter:** attribute, None
-
-    Attributes
-    ----------
-    id
-        The bot's Discord ID.
-    name
-        The bot's username.
-    discriminator
-        The bot's discriminator.
-    nick
-        The bot's nickname, if they have one, else their username.
-    created_at
-        The bot's creation date.
-    timestamp
-        The bot's creation date as a UTC timestamp.
-    mention
-        A formatted text that pings the bot.
-    verified
-        If the bot is verified or not.
-    shard_count (*)
-        The bot's total shard count.
-    servers (*)
-        Total server/guild count of the bot.
-    channels (*)
-        Total number of channels visible to the bot.
-    visible_users (*)
-        Total number of users visible to the bot.
-    total_users (*)
-        The bot's total user count.
-    unique_users (*)
-        The bot's unique user count.
-    percentage_chunked (*)
-        Percentage of chunked guilds the bot has.
-
-    .. warning::
-        Attributes denoting ``(*)`` can only be used by the bot owner.
-    """
-
-    if not _has_redbot:
-        raise ImportError("A Red-DiscordBot instance is required to use this.")
-
-    def __init__(self, base: Red, *, owner: bool = True) -> None:
-        super().__init__(base=base)
-        self.is_owner: bool = owner
-
-    def update_attributes(self) -> None:
-        self.user: discord.ClientUser = cast(discord.ClientUser, self.object.user)
-        created_at: datetime.datetime = getattr(
-            self.user, "created_at", None
-        ) or discord.utils.snowflake_time(self.user.id)
-        self._attributes.update(
-            {
-                "id": self.user.id,
-                "name": self.user.name,
-                "discriminator": self.user.discriminator,
-                "nick": self.user.display_name,
-                "mention": self.user.display_avatar.url,
-                "created_at": created_at,
-                "timestamp": int(created_at.timestamp()),
-                "verified": self.user.verified,
-            }
-        )
-        if self.is_owner:
-            visible_users: int = sum(len(g.members) for g in self.object.guilds)
-            total_users: int = sum(
-                g.member_count if g.member_count else 0 for g in self.object.guilds
-            )
-            owner_attributes: Dict[str, Any] = {
-                "shard_count": humanize_number(self.object.bot.shard_count),
-                "servers": humanize_number(len(self.object.guilds)),
-                "channels": humanize_number(sum(len(g.channels) for g in self.object.guilds)),
-                "visible_users": humanize_number(visible_users),
-                "total_users": humanize_number(total_users),
-                "unique_users": humanize_number(len(self.object.users)),
-                "percentage_chunked": visible_users / total_users * 100,
-            }
-            self._attributes.update(owner_attributes)
-
-    def get_value(self, ctx: Verb) -> str:
-        should_escape: bool = False
-        if ctx.parameter is None:
-            return_value: str = "{0.name}#{0.discriminator}".format(self.user)
-        else:
-            try:
-                value: Any = self._attributes[ctx.parameter]
-            except KeyError:
-                return  # type: ignore
-            if isinstance(value, tuple):
-                value, should_escape = value
-            return_value: str = str(value) if value is not None else None  # type: ignore
-        return escape_content(return_value) if should_escape else return_value