refactor: utils (#44)

* Move utils.py to utils/

* 🔥 Remove `filter_params`

* ♻️ Merge `time_snowflake` and `generate_snowflake`, move `basic_autocomplete` to `utils/public.py`

* ♻️ Merge `time_snowflake` and `generate_snowflake`, move `basic_autocomplete` to `utils/public.py`

* 🔥 Remove `utils.sleep_until`

* chore: Start migration to uv & ruff & hatch (#4)

* Start migration to uv

* Setup ruff and hatch

* Change pre-commit to use ruff

* Format with ruff

* Fix mistake

* Add dev deps

* Change workflows to use uv and ruff

* ➕ Add colorlog and remove requirements folder and fix build

* 💚 Fix sphinx build ?

* 🐛 Add __version.py for version management and update import in __init__.py

* ✏️ Update lib-checks.yml to run ruff on ubuntu-latest

* 🐛 Update lib-checks.yml to run mypy with uv

* 🔥 Delete MANIFEST.in

* ✨ Enhance lib-checks.yml to include ruff formatter check

* ♻️ Refactor pyproject.toml and uv.lock to use optional-dependencies for voice and speed

* Setup CHANGELOG.md (#6)

* chore: update docs workflows to use 'uv' for dependency management (#33)

* chore: Update localization workflows to use 'uv' for dependency management

* chore: refactor Read the Docs configuration to use uv

* 🔥 Move stuff to private

* :refactor: move parse_time function to private utils and update references

* 📝 update CHANGELOG to reflect utility function changes

* 🎨 Format

* ♻️ move deprecation utilities to private utils and update references

* ♻️ move snowflake_time function to public.py

* ♻️ move oauth_url and Undefined class to public.py; update imports

* 📝 remove deprecated utility functions from documentation

* 📝 remove (re)moved utility functions from documentation

* 📝 add utils.resolve_template to changelog and remove from documentation

* 🐛 fix import path for warn_deprecated utility function

* :refactor: reorganize utility function imports and move evaluate_annotation to private module

* ♻️ update import paths for utility functions to use relative imports

* ♻️ move delay_task function to private

* ♻️ removed `utils.get` in favor of `utils.find`

* ♻️ removed `utils._unique`

It was used twice, and once it wasn't even necessary

* ♻️ move `async_all` to private

* ♻️ move `maybe_coroutine` to private

* ♻️ rename `maybe_coroutine` to `maybe_awaitable`

* ♻️ move `sane_wait_for` to private

* ♻️ move `format_dt` to public

* ♻️ remove `as_chunks` function

* 📝 update `utils.sleep_until` and `utils.parse_time` changelog to suggest alternatives

* ♻️ move `compute_timedelta` function

* ♻️ move `valid_icon_size` to `asset.py`

* ♻️ refactor `utils.get` to `utils.find` across multiple files

* ♻️ refactor markdown and mention handling functions in `__init__.py` and `public.py`

* ♻️ move SnowflakeList to `private.py`

* ♻️ move `find` function from `__init__.py` to `public.py`

* ♻️ move `copy_doc` to private

* ♻️ refactor `get` to `find` in onboarding and sticker modules

* 🐛 fix `copy_doc` decorator usage in context.py

* ♻️ move SequenceProxy to private module

* ♻️ move cached_slot_property to private

* 🚨 add noqa comments to prevent linting errors

* ♻️ move get_slots function to private module

* ♻️ refactor JSON serialization functions to private module

* ♻️ replace custom cached_property implementation with functools.cached_property

* ✏️ fix typo in CHANGELOG-V3.md

* ➖ remove unused dependencies from pyproject.toml and uv.lock

* ⚰️ remove test.py

* ♻️ remove duplicate import of raw_mentions in __init__.py

* 🐛 fix raw_role_mentions import in utils/__init__.py

* 🔥 Duplicate `Iterable` import

* Apply suggestion from @Lumabots

Co-authored-by: Lumouille <[email protected]>
Signed-off-by: Paillat <[email protected]>

* 🔥 Simplify imports

* 🔥 Simplify imports number 2

* 🔥 Simplify imports number 3 omg this is amazing

* 🔥 Simplify imports number 4 omg this is amazing yee

* 🔥 Simplify imports number 5

* Update discord/ext/commands/converter.py

Co-authored-by: Ice Wolfy <[email protected]>
Signed-off-by: Paillat <[email protected]>

* Apply suggestions from code review

Co-authored-by: Ice Wolfy <[email protected]>
Co-authored-by: Lumouille <[email protected]>
Signed-off-by: Paillat <[email protected]>

* Update discord/state.py

Co-authored-by: Lumouille <[email protected]>
Signed-off-by: Paillat <[email protected]>

* Update discord/state.py

Co-authored-by: Lumouille <[email protected]>
Signed-off-by: Paillat <[email protected]>

* ♻️ Remove _ prefix in from and to json

* ♻️ Make import less weird

* Update utils.po

Signed-off-by: Paillat <[email protected]>

* empty commit

* Update discord/poll.py

Co-authored-by: Copilot <[email protected]>
Signed-off-by: Paillat <[email protected]>

* Update discord/utils/private.py

Co-authored-by: Copilot <[email protected]>
Signed-off-by: Paillat <[email protected]>

* 🐛 Fix broken import after merge

* 🐛 Fix emojis.json path

* 🐛 Fix broken imports

* 🎨 Format stuff

* 🐛 Fix import

---------

Signed-off-by: Paillat <[email protected]>
Signed-off-by: Paillat <[email protected]>
Co-authored-by: Lumouille <[email protected]>
Co-authored-by: Ice Wolfy <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 4 people

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,7 @@
 
 from typing import TYPE_CHECKING
 
+from .utils.private import warn_deprecated, get_as_snowflake
 from . import utils
 from .asset import Asset
 from .permissions import Permissions
@@ -200,9 +201,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 +262,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
@@ -373,7 +378,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:
@@ -400,7 +405,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}>"
 
-    @property
+    @cached_property
     def created_at(self) -> datetime.datetime:
         """Returns the entry's creation time in UTC."""
         return utils.snowflake_time(self.id)
 
-    @property
+    @cached_property
     def target(
         self,
     ) -> (
@@ -602,7 +604,7 @@ def category(self) -> enums.AuditLogActionCategory:
         """The category of the action, if applicable."""
         return self.action.category
 
-    @property
+    @cached_property
     def changes(self) -> AuditLogChanges:
         """The list of changes this entry has."""
         obj = AuditLogChanges(self, self._changes, state=self._state)

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(
@@ -516,7 +517,7 @@ 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)
+                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 +606,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 +712,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"]