Skip to content

fix: Align TypedDicts for API objects with the actual API spec - #3448

Draft
ToothyDev wants to merge 5 commits into
masterfrom
fix/types-and-api-objects
Draft

ToothyDev wants to merge 5 commits into
masterfrom
fix/types-and-api-objects

Conversation

@ToothyDev

@ToothyDev ToothyDev commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

I've noticed the TypedDicts for the .types and .raw_models folders were partly incomplete, partly wrong, and wholly a mess. So before work on correcting typing across the lib can start, this has to be corrected first, as without a correct base of what the API returns, it's all in vain.
The main goals are:

  1. Unify Python syntax (currently mixed between total=False (using only Required[...] for required keys) and total=True (aka not passing it) and marking non-required keys via NotRequired[...]. I've opted for the latter approach across the lib, as it's immediately obvious what is and isn't optional, and optional keys should stand out more.
  2. Add missing, correct wrong, and remove non-documented (by Discord) keys in existing dicts, taking the official Discord docs as sole source of truth
  3. (Optional) Simplify hierarchy and inheritance, as there currently seem to be random splits of big classes into smaller ones with no apparent rules to it

Out of scope: Fixing any type errors that result from these changes in any other files, because this is partly the base for all future typing work. These changes should by all means not have any runtime effects, although I will of course do some testing.

Information

  • This PR fixes an issue.
  • This PR adds something new (e.g. new method or parameters).
  • This PR is a breaking change (e.g. methods or parameters removed/renamed).
  • This PR is not a code change (e.g. documentation, README, typehinting,
    examples, ...).

Checklist

  • I have searched the open pull requests for duplicates.
  • If code changes were made then they have been tested.
    • I have updated the documentation to reflect the changes.
  • If type: ignore comments were used, a comment is also left explaining why.
  • I have updated the changelog to include these changes.
  • I have read the Contributing Guidelines.
  • AI Usage has been disclosed. -> None
    • If AI has been used, I understand fully what the code does

@ToothyDev ToothyDev added help wanted Extra attention is needed priority: low Low Priority API reflection Discord API isn't correctly reflected labels Nov 15, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Pycord Nov 15, 2026
@pycord-app

pycord-app Bot commented Nov 15, 2026

Copy link
Copy Markdown

Thanks for opening this pull request!
Please make sure you have read the Contributing Guidelines and Code of Conduct.

This pull request can be checked-out with:

git fetch origin pull/3448/head:pr-3448
git checkout pr-3448

This pull request can be installed with:

pip install git+https://github.com/Pycord-Development/pycord@refs/pull/3448/head

@ToothyDev

ToothyDev commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor Author

@Paillat-dev I've done 2 files so far and I want your opinion on it. The re-sorting of the keys was done according to the official API docs as that makes stuff faster to find, and when I'm already looking at all types, I figured I might as well do that tedious work too.

I also need some info on whether there's any rules on how the classes are split up (see both files I edited) or whether these should be unified into a single object if they are not explicitly separate on the API docs

@ToothyDev ToothyDev changed the title fix: TypedDicts for API objects fix: Align TypedDicts for API objects with the actual API spec Nov 15, 2026
Comment thread discord/types/appinfo.py Resolved

@Paillat-dev Paillat-dev left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wanted to look at this but then got caught into other work. However I think there are a couple confusion between all the possible places one of those types can come from and how they can differ (e.g. sending vs receiving vs gateway). Make sure it is clear what is for what use, including whether something is just a base (some bases are private with _ other public).

Maybe including pasting this into some LLM and telling it to compare it with the API and then check if you missed something in your changes/fixes.

Comment thread discord/types/appinfo.py
class ApplicationIntegrationTypeConfiguration(TypedDict, total=False):
oauth2_install_params: AppInstallParams
class ApplicationIntegrationTypeConfiguration(TypedDict):
oauth2_install_params: ApplicationInstallParams

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs lists the ouath2_install_params field as optional (and it was that when using total=False).
image

Comment thread discord/types/invite.py
target_user: NotRequired[PartialUser]
target_type: NotRequired[InviteTargetType]
target_application: NotRequired[PartialAppInfo]
target_application: NotRequired[PartialApplicationInfo]

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I get it correctly, the docs state that target_application is not limited to those three fields (see link 2).

Comment thread discord/types/invite.py
target_type: NotRequired[InviteTargetType]
target_user: NotRequired[PartialUser]
target_application: NotRequired[PartialAppInfo]
target_application: NotRequired[PartialApplicationInfo]

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here. It's clearly not only limited to id, flags and flags_new

Comment thread discord/types/activity.py
flags: int
emoji: ActivityEmoji | None
secrets: ActivitySecrets
session_id: str | None

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

discord.activity:L590 and discord.activity:L859 still tend to you the session_id, should be dropped.

@vmphase

vmphase commented Nov 17, 2026

Copy link
Copy Markdown
Member

Regarding my comments on target_application: in my opinion, you should split it into PartialApplicationInfo and ReadyApplicationInfo:

class PartialApplicationInfo(TypedDict):
    """Partial application object."""
    id: Snowflake
    name: NotRequired[str]
    icon: NotRequired[str | None]
    description: NotRequired[str]
    rpc_origins: NotRequired[list[str]]
    verify_key: NotRequired[str]
    ...

class ReadyApplicationInfo(TypedDict):
    """Received from the gateway during the READY event."""
    id: Snowflake
    flags: int
    flags_new: str

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

API reflection Discord API isn't correctly reflected help wanted Extra attention is needed priority: low Low Priority

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

3 participants