feat: Setup a fully featured test setup and add initial tests on utils

.github/workflows/lib-checks.yml

@@ -48,6 +48,7 @@ jobs:
           uv run codespell --ignore-words-list="groupt,nd,ot,ro,falsy,BU" \
           --exclude-file=".github/workflows/codespell.yml"
   ruff:
+    if: ${{ github.event_name != 'schedule' }}
     runs-on: ubuntu-latest
     steps:
       - name: "Checkout Repository"
@@ -93,3 +94,29 @@ jobs:
         run: mkdir -p -v .mypy_cache
       - name: "Run mypy"
         run: uv run mypy --non-interactive discord/
+  tests:
+    if: ${{ github.event_name != 'schedule' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.13', '3.12', '3.11', '3.10']
+    steps:
+      - name: "Checkout Repository"
+        uses: actions/checkout@v4
+
+      - name: "Setup Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: "Install uv"
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --no-python-downloads --group dev
+
+      - name: "Run tests"
+        run: uv run tox

.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
       - id: end-of-file-fixer
         exclude: \.(po|pot|yml|yaml)$
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.9
+    rev: v0.12.0
     hooks:
       - id: ruff
         args: [ --fix ]

CHANGELOG-V3.md

@@ -12,3 +12,17 @@ release.
 ### Deprecated
 
 ### Removed
+
+- `utils.filter_params`
+- `utils.sleep_until` use `asyncio.sleep` combined with `datetime.datetime` instead
+- `utils.compute_timedelta` use the `datetime` module instead
+- `utils.resolve_invite`
+- `utils.resolve_template`
+- `utils.parse_time` use `datetime.datetime.fromisoformat` instead
+- `utils.time_snowflake` use `utils.generate_snowflake` instead
+- `utils.warn_deprecated`
+- `utils.deprecated`
+- `utils.get` use `utils.find` with `lambda i: i.attr == val` instead
+- `AsyncIterator.get` use `AsyncIterator.find` with `lambda i: i.attr == val` instead
+- `utils.as_chunks` use `itertools.batched` on Python 3.12+ or your own implementation
+  instead

discord/__version.py

@@ -35,7 +35,7 @@
 
 from typing import Literal, NamedTuple
 
-from .utils import deprecated
+from .utils.private import deprecated
 from ._version import __version__, __version_tuple__
 
 

discord/abc.py

@@ -41,6 +41,7 @@
     runtime_checkable,
 )
 
+from .utils.private import warn_deprecated
 from . import utils
 from .context_managers import Typing
 from .enums import ChannelType
@@ -724,7 +725,7 @@ def permissions_for(self, obj: Member | Role, /) -> Permissions:
             if obj.is_default():
                 return base
 
-            overwrite = utils.get(self._overwrites, type=_Overwrites.ROLE, id=obj.id)
+            overwrite = utils.find(lambda o: o.type == _Overwrites.ROLE and o.id == obj.id, self._overwrites)
             if overwrite is not None:
                 base.handle_overwrite(overwrite.allow, overwrite.deny)
 
@@ -1529,7 +1530,7 @@ async def send(
                 from .message import MessageReference  # noqa: PLC0415
 
                 if not isinstance(reference, MessageReference):
-                    utils.warn_deprecated(
+                    warn_deprecated(
                         f"Passing {type(reference).__name__} to reference",
                         "MessageReference",
                         "2.7",

discord/activity.py

@@ -32,7 +32,7 @@
 from .colour import Colour
 from .enums import ActivityType, try_enum
 from .partial_emoji import PartialEmoji
-from .utils import _get_as_snowflake
+from .utils.private import get_as_snowflake
 
 __all__ = (
     "BaseActivity",
@@ -226,7 +226,7 @@ def __init__(self, **kwargs):
         self.timestamps: ActivityTimestamps = kwargs.pop("timestamps", {})
         self.assets: ActivityAssets = kwargs.pop("assets", {})
         self.party: ActivityParty = kwargs.pop("party", {})
-        self.application_id: int | None = _get_as_snowflake(kwargs, "application_id")
+        self.application_id: int | None = get_as_snowflake(kwargs, "application_id")
         self.url: str | None = kwargs.pop("url", None)
         self.flags: int = kwargs.pop("flags", 0)
         self.sync_id: str | None = kwargs.pop("sync_id", None)

discord/appinfo.py

@@ -27,6 +27,8 @@
 
 from typing import TYPE_CHECKING
 
+from .utils.private import warn_deprecated
+from .utils.private import get_as_snowflake
 from . import utils
 from .asset import Asset
 from .permissions import Permissions
@@ -200,9 +202,9 @@ def __init__(self, state: ConnectionState, data: AppInfoPayload):
         self._summary: str = data["summary"]
         self.verify_key: str = data["verify_key"]
 
-        self.guild_id: int | None = utils._get_as_snowflake(data, "guild_id")
+        self.guild_id: int | None = get_as_snowflake(data, "guild_id")
 
-        self.primary_sku_id: int | None = utils._get_as_snowflake(data, "primary_sku_id")
+        self.primary_sku_id: int | None = get_as_snowflake(data, "primary_sku_id")
         self.slug: str | None = data.get("slug")
         self._cover_image: str | None = data.get("cover_image")
         self.terms_of_service_url: str | None = data.get("terms_of_service_url")
@@ -261,7 +263,7 @@ def summary(self) -> str | None:
         .. versionadded:: 1.3
         .. deprecated:: 2.7
         """
-        utils.warn_deprecated(
+        warn_deprecated(
             "summary",
             "description",
             reference="https://discord.com/developers/docs/resources/application#application-object-application-structure",

discord/asset.py

@@ -47,6 +47,11 @@
 MISSING = utils.MISSING
 
 
+def _valid_icon_size(size: int) -> bool:
+    """Icons must be power of 2 within [16, 4096]."""
+    return not size & (size - 1) and 4096 >= size >= 16
+
+
 class AssetMixin:
     url: str
     _state: Any | None
@@ -371,7 +376,7 @@ def replace(
             url = url.with_path(f"{path}.{static_format}")
 
         if size is not MISSING:
-            if not utils.valid_icon_size(size):
+            if not _valid_icon_size(size):
                 raise InvalidArgument("size must be a power of 2 between 16 and 4096")
             url = url.with_query(size=size)
         else:
@@ -398,7 +403,7 @@ def with_size(self, size: int, /) -> Asset:
         InvalidArgument
             The asset had an invalid size.
         """
-        if not utils.valid_icon_size(size):
+        if not _valid_icon_size(size):
             raise InvalidArgument("size must be a power of 2 between 16 and 4096")
 
         url = str(yarl.URL(self._url).with_query(size=size))

discord/audit_logs.py

@@ -26,7 +26,9 @@
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Callable, ClassVar, Generator, TypeVar
+from functools import cached_property
 
+from .utils.private import get_as_snowflake
 from . import enums, utils
 from .asset import Asset
 from .automod import AutoModAction, AutoModTriggerMetadata
@@ -559,21 +561,21 @@ def _from_data(self, data: AuditLogEntryPayload) -> None:
         # into meaningful data when requested
         self._changes = data.get("changes", [])
 
-        self.user = self._get_member(utils._get_as_snowflake(data, "user_id"))  # type: ignore
-        self._target_id = utils._get_as_snowflake(data, "target_id")
+        self.user = self._get_member(get_as_snowflake(data, "user_id"))  # type: ignore
+        self._target_id = get_as_snowflake(data, "target_id")
 
     def _get_member(self, user_id: int) -> Member | User | None:
         return self.guild.get_member(user_id) or self._users.get(user_id)
 
     def __repr__(self) -> str:
         return f"<AuditLogEntry id={self.id} action={self.action} user={self.user!r}>"
 
-    @utils.cached_property
+    @cached_property
     def created_at(self) -> datetime.datetime:
         """Returns the entry's creation time in UTC."""
         return utils.snowflake_time(self.id)
 
-    @utils.cached_property
+    @cached_property
     def target(
         self,
     ) -> (
@@ -597,24 +599,24 @@ def target(
         else:
             return converter(self._target_id)
 
-    @utils.cached_property
+    @property
     def category(self) -> enums.AuditLogActionCategory:
         """The category of the action, if applicable."""
         return self.action.category
 
-    @utils.cached_property
+    @cached_property
     def changes(self) -> AuditLogChanges:
         """The list of changes this entry has."""
         obj = AuditLogChanges(self, self._changes, state=self._state)
         del self._changes
         return obj
 
-    @utils.cached_property
+    @property
     def before(self) -> AuditLogDiff:
         """The target's prior state."""
         return self.changes.before
 
-    @utils.cached_property
+    @property
     def after(self) -> AuditLogDiff:
         """The target's subsequent state."""
         return self.changes.after

discord/bot.py

@@ -63,7 +63,8 @@
 from .shard import AutoShardedClient
 from .types import interactions
 from .user import User
-from .utils import MISSING, async_all, find, get
+from .utils import MISSING, find
+from .utils.private import async_all
 
 if TYPE_CHECKING:
     from .member import Member
@@ -216,13 +217,13 @@ def get_application_command(
                 return command
             elif (names := name.split())[0] == command.name and isinstance(command, SlashCommandGroup):
                 while len(names) > 1:
-                    command = get(commands, name=names.pop(0))
+                    command = find(lambda c: c.name == names.pop(0), commands)
                     if not isinstance(command, SlashCommandGroup) or (
                         guild_ids is not None and command.guild_ids != guild_ids
                     ):
                         return
                     commands = command.subcommands
-                command = get(commands, name=names.pop())
+                command = find(lambda c: c.name == names.pop(), commands)
                 if not isinstance(command, type) or (guild_ids is not None and command.guild_ids != guild_ids):
                     return
                 return command
@@ -357,7 +358,7 @@ def _check_command(cmd: ApplicationCommand, match: Mapping[str, Any]) -> bool:
 
         # Now let's see if there are any commands on discord that we need to delete
         for cmd, value_ in registered_commands_dict.items():
-            match = get(pending, name=value_["name"])
+            match = find(lambda c: c.name == value_["name"], pending)
             if match is None:
                 # We have this command registered but not in our list
                 return_value.append(
@@ -515,8 +516,9 @@ def register(
                         }
                     )
                     continue
-                # We can assume the command item is a command, since it's only a string if action is delete
-                match = get(pending, name=cmd["command"].name, type=cmd["command"].type)
+                # We can assume the command item is a com
+                # mand, since it's only a string if action is delete
+                match = find(lambda c: c.name == cmd["command"].name and c.type == cmd["command"].type, pending)
                 if match is None:
                     continue
                 if cmd["action"] == "edit":
@@ -605,10 +607,9 @@ def register(
             registered = await register("bulk", data, guild_id=guild_id)
 
         for i in registered:
-            cmd = get(
+            cmd = find(
+                lambda c: c.name == i["name"] and c.type == i.get("type"),
                 self.pending_application_commands,
-                name=i["name"],
-                type=i.get("type"),
             )
             if not cmd:
                 raise ValueError(f"Registered command {i['name']}, type {i.get('type')} not found in pending commands")
@@ -712,11 +713,9 @@ async def on_connect():
                 registered_guild_commands[guild_id] = app_cmds
 
         for i in registered_commands:
-            cmd = get(
+            cmd = find(
+                lambda c: c.name == i["name"] and c.guild_ids is None and c.type == i.get("type"),
                 self.pending_application_commands,
-                name=i["name"],
-                guild_ids=None,
-                type=i.get("type"),
             )
             if cmd:
                 cmd.id = i["id"]