Skip to main content

Python typings of all payloads that Discord sends as TypedDicts

Project description

discord-typings

Python typings of all payloads that Discord sends as TypedDicts.

Quickstart

The library requires no setup except for installation. The easiest way to install it is through PyPI where it is similarly named discord-typings:

pip install discord-typings

Now, start importing the relevant typings directly from the library:

from discord_typings import UserData


def print_author(user: UserData) -> None:
    print(f"Created by {user['username']}#{user['discriminator']}")


print_author({
    'id': '344404945359077377',
    'username': 'Bluenix',
    'discriminator': '7543',
    'avatar': None
})

It is also possible to import the library inside of a TYPE_CHECKING-clause:

from typing import Any, TYPE_CHECKING

if TYPE_CHECKING:
    from discord_typings import Snowflake


class Data:
    id: 'Snowflake'
    value: Any

Note It is not recommended to import the library this way, as it does not allow you to introspect the annotations in other code. It is merely pointed out for completeness.

Naming and Usage

There is no documentation or API reference as this provides no value on top of the Discord developer documentation the types are based on. Typings are named after the object they represent, and there are little to no exceptions to this rule.

Typings use suffixes to differentiate between potential wrapping objects in user code - such as importing UserData to parse into a custom User class. These are Data, Event, and Command. Event refers to a gateway event received over the gateway while Command refers to a gateway command sent over the gateway. Data is used for any general objects like UserData.

Exceptions

To differentiate between the data for complete application commands, and the data Discord expects to receive to create an application command, there is a special-cased ApplicationCommandPayload.

Codestyle and Contributing

Discord-typings is a relatively simple library with little code, but unfortunately needs to be constantly maintained with Discord's API. The purpose of this library is for this to be a community effort; any help with maintenance is greatly appreciated.

Structure

The library follows the API docs both in terms of naming, structure, and order inside of individual files. This should hopefully make it easier to find the code to change when you have the documentation entry at hand.

All internal imports should be done by importing the entire module, then accessing the typing as an attribute. If from ... import ..., or specific things are imported, that is likely to create complicated circular imports. Inside of annotations, wrap the attribute access (discord_typings.X) in quotes to make it a string and defer its evaluation.

All typings which directly represent a Discord payload (excluding typings created for the purpose of a Union) should be added to the file's __all__, then be added to the module's __init__ and its __all__.

Version Guarantees

Once discord-typings releases its v1.0 release, it will follow strict semantic versioning guarantees. Keep in mind that this only applies to the Python interface - such as TypeDicts, top-level unions, and other aliases.

Due to Discord's frequent API updates, it is not guaranteed that code which type-checks in one minor version will do so in another one. This is because code which does not type-check will not have an effect on runtime for users.

As a reminder of semantic versioning, and a summary of the above:

Release Type Upgrade Downgrade Comment
Major Only type of release with breaking Python changes
Minor X May add new features, can break type-checking
Patch X X Only intended for bugs

Warn Patch versions will be used to rectify any accidental breaking changes or unintended bugs / behaviour, therefore you should always use the latest patch version.

Note Because patch versions may change previous behaviour, they could be considered breaking, however the intention is always to fix unintended behaviour or previous breaking changes which should not have been. In those cases, the previous version will be pulled from PyPI.

Links and Feedback

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

discord_typings-0.9.0.tar.gz (27.7 kB view details)

Uploaded Source

Built Distribution

discord_typings-0.9.0-py3-none-any.whl (34.6 kB view details)

Uploaded Python 3

File details

Details for the file discord_typings-0.9.0.tar.gz.

File metadata

  • Download URL: discord_typings-0.9.0.tar.gz
  • Upload date:
  • Size: 27.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.31.0

File hashes

Hashes for discord_typings-0.9.0.tar.gz
Algorithm Hash digest
SHA256 fc39321dd04b3299e2b680da34454be8f29540acff4303752d514444daeb4e6d
MD5 4d526b9bf517aebe3962e9dd4afed49a
BLAKE2b-256 4aa0862d1e1457fe891a61d83da327f8a8b27334fbc0c4fe1b0edc3b4a47fb8a

See more details on using hashes here.

File details

Details for the file discord_typings-0.9.0-py3-none-any.whl.

File metadata

File hashes

Hashes for discord_typings-0.9.0-py3-none-any.whl
Algorithm Hash digest
SHA256 3d8776e16aa1f908fae947225d9cfd99701bcf0c7e28ca56bc10d892d1cfcffa
MD5 89fd08c983f55bb080a017c75e430a00
BLAKE2b-256 135fd3298bbd3fbb30fd137ac130013244930744633169c0d07e42fc8a5501f9

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page