AdvancedTagScript 3.3.0__py3-none-any.whl → 3.3.2__py3-none-any.whl

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):

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")

TagScriptEngine/adapter/redbotadapters.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 import datetime
-from typing import Any, Dict, Optional, Tuple, cast
+from typing import Any, Optional, Tuple, cast
 
 import discord
 
@@ -23,20 +25,59 @@ __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")
+    """
+    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:
-        super().__init__(base=base)
+        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": getattr(command, "description", 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,
@@ -78,13 +119,17 @@ class RedBotAdapter(SimpleAdapter["Red"]):
     discriminator
         The bot's discriminator.
     nick
-        The bot's nickname, if they have one, else their username.
+        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 (*)
@@ -100,18 +145,28 @@ class RedBotAdapter(SimpleAdapter["Red"]):
     unique_users (*)
         The bot's unique user count.
     percentage_chunked (*)
-        Percentage of chunked guilds the bot has.
+        Percentage of the bot's members that are cached/chunked (rounded to two
+        decimals); ``0`` when no member counts are available.
 
-    .. warning::
-        Attributes denoting ``(*)`` can only be used by the bot owner.
+    Attributes marked ``(*)`` are owner-only and return nothing for other users.
     """
-
-    if not _has_redbot:
-        raise ImportError("A Red-DiscordBot instance is required to use this.")
+ 
+    # 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:
-        super().__init__(base=base)
+        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)
@@ -124,35 +179,51 @@ class RedBotAdapter(SimpleAdapter["Red"]):
                 "name": self.user.name,
                 "discriminator": self.user.discriminator,
                 "nick": self.user.display_name,
-                "mention": self.user.display_avatar.url,
+                "mention": self.user.mention,
+                "avatar": (self.user.display_avatar.url, False),
                 "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 _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[ctx.parameter]
+                value: Any = self._attributes[parameter]
             except KeyError:
                 return  # type: ignore
             if isinstance(value, tuple):

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**
 

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.dist-info → advancedtagscript-3.3.2.dist-info}/METADATA

@@ -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.dist-info → advancedtagscript-3.3.2.dist-info}/RECORD

@@ -1,20 +1,20 @@
-TagScriptEngine/__init__.py,sha256=v1jE2WhSkANRnPWLj4UieHunkkCnO6aNEaACln7u2dI,6143
+TagScriptEngine/__init__.py,sha256=QfGmahJ3D2bD2JqBcpgWcwpLTojka6t7jRH_yvJh0Xc,6144
 TagScriptEngine/_warnings.py,sha256=pfMXaEVGpIue0eqgzZ6HkLXEka1UGl61-yuH9uEnVe4,2662
 TagScriptEngine/exceptions.py,sha256=lhvskKi2AySE5pul_iAA251jdMv-92QkjodR4X-G27Y,2833
 TagScriptEngine/interpreter.py,sha256=5kF0kEqaZf5Hyu8tkmDDLEy7y-qvd6xiUJ3GwpDDh44,16638
 TagScriptEngine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-TagScriptEngine/utils.py,sha256=Kq7_w6nuJizPYZDJIzXZ51b1ea92_7Vm_YDKbQci7F4,1697
+TagScriptEngine/utils.py,sha256=b5PnxFLmz7ubb_PFd4xK79iUQwWrg2KUx-gJlep2gOM,1666
 TagScriptEngine/verb.py,sha256=nk5IenRRGuwzIY7cMyGQn7aVYvmGcNTszztAQTSHP54,5047
 TagScriptEngine/adapter/__init__.py,sha256=9ohds_8-zbVKZobQCE7xb96XrF6Be8lCSjJCJHHSuDM,1266
-TagScriptEngine/adapter/discordadapters.py,sha256=l_6HijmmGDRX7lhahskH6mTteJFpS7IcMEvnKPqIQhY,19005
+TagScriptEngine/adapter/discordadapters.py,sha256=vOILu1tWNSpYM1s1kUcjQzM3T2fkBSSGo4xrkgOdJgA,19470
 TagScriptEngine/adapter/functionadapter.py,sha256=lQlWm0dO-41bTQ2etFpWRaGnG22V1HMy9aiB8FnFZOU,591
 TagScriptEngine/adapter/intadapter.py,sha256=jENx5ah8k0U1PjJccV0NiYFsWFU9ZXTFgz3f-qx30SA,548
 TagScriptEngine/adapter/objectadapter.py,sha256=7bW-Qd6gujq2ALdK3p0ONoCSPWCTv6srkkDNjzkvDEU,1017
-TagScriptEngine/adapter/redbotadapters.py,sha256=9a0EDSmelI-RJF6Mgpti1fogsNIAvNoC3F40aTKGKgk,5936
+TagScriptEngine/adapter/redbotadapters.py,sha256=0TjQ6t0ONuPDEyl1rLvjj4uL0goQxB5Ts8AcRfxBA_w,8740
 TagScriptEngine/adapter/stringadapter.py,sha256=VaJzkm1b8b7w1T90DjR3gOH0DIsZlWtcFe1YG7DOqBQ,1710
 TagScriptEngine/block/__init__.py,sha256=zfoPTCTBDIuOkcjKnNL8gYIRKOi4c4gkYNwNJPvYctQ,3223
 TagScriptEngine/block/allowedmentions.py,sha256=WMGWi1Fe0U_vUBsc4uyiX1XfQjGkhpdlyvq3HhCCLd4,2219
-TagScriptEngine/block/assign.py,sha256=lgJY_hUIjrKPm4N9vWr_rxhrKejGrMRbBG3oasb0hAI,8657
+TagScriptEngine/block/assign.py,sha256=JtYvbyB_nXm0Hf3FKawCdRCWP1V5Een1hAXwnLGOyHc,8723
 TagScriptEngine/block/breakblock.py,sha256=nt3T7fDhTxH0jpO8lu0_3oC4XwVuKKg9cmkdLsZwzL8,1288
 TagScriptEngine/block/case.py,sha256=SF4uaAWyC9AiBzoI5SPDCaRx6wrY-_0IQDI1T_mZFvk,1503
 TagScriptEngine/block/command.py,sha256=3xKo5H3K8F7BpxeHJp9I80n0QWvk_GHQCQpKnvQ7ZxQ,4309
@@ -44,8 +44,8 @@ TagScriptEngine/block/urlencodeblock.py,sha256=sWqdSBk-uTZZjebKhAFmlROvnQvLcjvyI
 TagScriptEngine/interface/__init__.py,sha256=37lAOMONKmWDLiC5Ox9Y3TNQUQbzW54oUugbQe0e9gc,341
 TagScriptEngine/interface/adapter.py,sha256=4jBBz7hc-8fsRSZ5DWOrUxrhXqS0SvJCdW57TZl8sQo,1967
 TagScriptEngine/interface/block.py,sha256=S0hWRH6uqBz_cYRIh3LGMyo63UK6gNidtf6EiLUKL0c,3653
-advancedtagscript-3.3.0.dist-info/licenses/LICENSE,sha256=NvdimESU3jrNgd_8E4i-eTecQ_jGegRrrWk1v2gOnHY,252
-advancedtagscript-3.3.0.dist-info/METADATA,sha256=Jk7KqEwJRIWH9XZrCbZCELDLF2vl121n3jMSaRc4-J0,3565
-advancedtagscript-3.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-advancedtagscript-3.3.0.dist-info/top_level.txt,sha256=6lY4lZDvWxraERrit1lvDsCCDdfo9e83kk_tBemAJCo,16
-advancedtagscript-3.3.0.dist-info/RECORD,,
+advancedtagscript-3.3.2.dist-info/licenses/LICENSE,sha256=NvdimESU3jrNgd_8E4i-eTecQ_jGegRrrWk1v2gOnHY,252
+advancedtagscript-3.3.2.dist-info/METADATA,sha256=GbVFcPOX0J9V-ir-xtSyjnMjU8ms-WKlOQgIRRx5VCI,3565
+advancedtagscript-3.3.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+advancedtagscript-3.3.2.dist-info/top_level.txt,sha256=6lY4lZDvWxraERrit1lvDsCCDdfo9e83kk_tBemAJCo,16
+advancedtagscript-3.3.2.dist-info/RECORD,,