Problem Description

The library currently targets Python 3.10 and 3.11, but misses opportunities to leverage new features from newer versions (3.12 to 3.14). As Python evolves, many areas of this codebase can be improved.

Proposed Solution

Refactor, migrate and modernize the code incrementally to take advantage of features introduced in Python 3.11–3.14:

Python 3.11

• Replace asyncio.gather() with manual error handling using asyncio.TaskGroup (PEP 654) and handle failures using ExceptionGroup. Target: http_client.py:418–422
• Replace asyncio.wait_for() with asyncio.timeout(). Target: client.py:1638, client.py:2042
• Replace string-based enums with StrEnum. Target: enums.py:703–747, application_commands.py:137–150
• Replace tomli with built-in tomllib. Target: setup.py:7–8, pyproject.toml:1–4, 13
• Refactor type hints using Self, NotRequired, Required in TypedDict, parameterized generics. Target: user.py:2, application_commands.py:168

Python 3.12

• Use PEP 695 syntax for declaring type parameters and aliases. Target: context.py:420–421, user.pyi:37–39
• Use Unpack to type **kwargs. Target: message.py:1017–1040
• Add @typing.override decorators to overridden methods. Target: context.py:841–845
• Use asyncio.eager_task_factory(), asyncio.create_eager_task_factory(), and asyncio.current_task() in latency-critical sections. Target: http_client.py:414–415, client.py:1944–1950
• Use itertools.batched() for layout grouping and pagination logic. Target: components.py:822–840, paginators.py:348–364

Python 3.13

• Evaluate impact of free-threading (PEP 703) and JIT compilation (PEP 744) on WebSocket/API, especially in: client.py:1840–1847, GatewayClient, context resolution.
• Use copy.replace() for immutable model transformation. Target: __init__.py:121–178
• Use asyncio.Queue.shutdown(), asyncio.as_completed() and PythonFinalizationError. Target: gateway.py:117-127, 110–135
• Use TypeIs in polymorphic typing contexts. Target: client.py:1841–1855
• Adopt PEP 696 type parameter defaults. Target: context.py:420–422
• Add support for warnings.deprecated() and typing.ReadOnly in API response models
• Use ssl.create_default_context(). Target: http_client.py:12–14 (depending on aiohttp’s handling)
• Future-proof functools.partial usage by wrapping in staticmethod as its behavior changes in future versions. Target: client.py:3

Python 3.14

• Use InterpreterPoolExecutor to offload CPU-intensive tasks in extensions, replacing thread pools or uvloop where applicable. Target: client.py:1001–1016
• Refactor forward references using PEP 649 & 749 to allow runtime evaluation of annotations. Target: client.py:371–381
• Unify Union types (Union[A, B] and A | B )
• Adopt PEP 750 t-strings. Target: client.py:325–337

Alternatives Considered

No response

Additional Information

These enhancements can be rolled out incrementally.

As the Discord API evolves and bots handle more concurrency and CPU-bound work, leveraging these language improvements will be increasingly beneficial.

Code of Conduct

• I agree to follow the contribution requirements.