refactor: utils

[Paillat-dev]

The general goal of these changes is to lower the amount of code we have to maintain across te library.

Changes include:

Separated utils function in:

• utils.private for private utils that are to be used in the library code
• utils for user facing utils

Removed over specific utils

Removed overly specific public utils that wouldn't commonly be used by users and aren't hard to re implement in any project. See CHANGELOG-V3.md for a comprehensive list.

Removed unused (or lesser used) utils

Remove utils that were used less than once or twice in the library in favor of:

• Moving them to a specific file if they were specific to a part of the library and shouldn't have been in utils in the first place
• For utils that implemented a one-liner, replace the util's usage with said one liner
• For utils similar to other utils, use another util

Merged overlapping utils

Merge utils with common goals or with same goal with one another, e.g. see changes to utils.time_snowflake -> utils.generate_snowflake

[Copilot]

Pull Request Overview

This PR refactors the utils module by splitting it into public (utils.public) and private (utils.private) submodules, removing obsolete helpers, and updating all code, documentation, and tests to use the new utilities.

• Split discord/utils.py into utils/public.py (user-facing) and utils/private.py (internal), then removed the old monolith.
• Replaced _get_as_snowflake, maybe_coroutine, utils.get, and other deprecated helpers with get_as_snowflake, maybe_awaitable, find, etc.
• Updated imports across the codebase, adjusted docs and tests, and merged overlapping utilities (e.g. time_snowflake → generate_snowflake).

Reviewed Changes

Copilot reviewed 62 out of 62 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/test_utils.py	Updated imports to include generate_snowflake, but missing coverage for it
docs/locales/en/LC_MESSAGES/api/utils.po	Translation reference for generate_snowflake is malformed
discord/member.py	add_roles now uses a set comprehension, which loses original ordering
discord/ext/commands/converter.py	Erroneous extra name=argument passed to find, breaking its API
discord/ext/tasks/init.py	Duplicated compute_timedelta logic instead of reusing utils.private

Comments suppressed due to low confidence (5)

tests/test_utils.py:34

• Add tests for generate_snowflake, covering both mode='boundary' (with high=True and high=False) and mode='realistic' to ensure it produces correct snowflake values.

    generate_snowflake,

docs/locales/en/LC_MESSAGES/api/utils.po:616

• This reference is malformed; update it to refer to discord.utils.generate_snowflake instead of discord.utils.:1.

#: 3dbe398f94684d7d81111c3a9d78ddee discord.utils.:1 of

discord/ext/commands/converter.py:794

• The extra keyword argument name=argument is invalid for find, which only takes a predicate and a sequence; remove name=argument.

                result = discord.utils.find(lambda e: e.name == argument, guild.emojis)

discord/member.py:1051

• Using a set comprehension here drops the original order of roles; consider using dict.fromkeys(...) or utils._unique to dedupe while preserving order.

            new_roles = list({Object(id=r.id) for s in (self.roles[1:], roles) for r in s})

discord/ext/tasks/init.py:52

• [nitpick] This duplicates the same logic in utils.private.compute_timedelta; consider importing and reusing that function to avoid code duplication.

def compute_timedelta(dt: datetime.datetime):