Gradual Migration from TypedDict to Pydantic Models

[Paillat-dev]

Please give your opinion on this. I opened it as a feature request as it is something I would very well like to see in pycord. Below are my thoughts and ideas, which I am pretty sure have some issues themselves. I would be happy to contribute on working on this. I think it may be a good step towards v3 or whatever it is called.

Summary

Migrate internal models from TypedDict to Pydantic to improve type safety, runtime validation, and developer experience.

What is the feature request for?

The core library

The Problem

Currently, the internal models/types primarily use TypedDict for type annotations. While TypedDict provides static typing benefits, it has several limitations:

1. No runtime validation capabilities - impossible to validate actual payloads against their type definitions
2. No runtime type checking - isinstance() checks aren't possible on typed dicts as they are just dicts at runtime.
3. Type definitions can easily become outdated as they aren't enforced at runtime
4. No automatic type casting or data transformation (custom validators and serializers)
5. Limited developer experience (e.g., no runtime field validation)

The Ideal Solution

Gradually migrate our internal model definitions to Pydantic, starting with API requests/responses and gateway models. This would provide:

1. Improved type safety throughout the library
2. Validation of API/Gateway requests/responses
3. Betterer developer experience with proper IDE support
4. More maintainable codebase
5. Clearer separation between API models and internal representations
6. It's rust :p

Here is a rough idea of how I would do it and some ideas, to be discussed if this fr is moved forward in the first place:

1. Create a new models submodule with the following structure:

   • models/base/: Core model definitions matching Discord's API objects
   • models/api/: Request/response models for API
   • models/gateway/: Gateway-related models

2. Add an optional Model parameter to HTTPClient.request and other places where applicable to automagically cast to a pydantic model:

   def request[T: BaseModel](self, ..., model: type[T] | None = None) -> T:

   This allows slow and gradual adoption, you can start by just implementing the new ones then migrate the old ones.

3. Migrate existing TypedDict definitions to Pydantic models, add new features to support this change where applicable. Enforce all new model implementations to use Pydantic models.

Additional Context

https://discord.com/channels/881207955029110855/881224361015672863/1302431199670833223
https://discord.com/channels/881207955029110855/881735314987708456/1299306561432326165

[Paillat-dev]

What are thoughts on this ? This is a proposition, if the idea would be accepted I would love to work on it.