# discord-typings
Python typings of all payloads that Discord sends as `TypedDict`s.
## 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`:
```bash
pip install discord-typings
```
Now, start importing the relevant typings directly from the library:
```python
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:
```python
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](#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 `TypeDict`s, 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
* [PyPI Package](https://pypi.org/project/discord-typings)
* [Discord API Docs](https://discord.com/developers/docs/intro)
* [Wumpy Project Discord Server](https://discord.gg/ZWpjYdKKTF)
Raw data
{
"_id": null,
"home_page": null,
"name": "discord-typings",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "discord, discord-api, discord-api-wrapper, python-3, typing",
"author": null,
"author_email": "Bluenix <bluenixdev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/91/57/d6ebfbe97005821bdc18758fb5368c650225e368811471af2f8b1067cd2d/discord_typings-0.8.0.tar.gz",
"platform": null,
"description": "# discord-typings\n\nPython typings of all payloads that Discord sends as `TypedDict`s.\n\n## Quickstart\n\nThe library requires no setup except for installation. The easiest way to\ninstall it is through PyPI where it is similarly named `discord-typings`:\n\n```bash\npip install discord-typings\n```\n\nNow, start importing the relevant typings directly from the library:\n\n```python\nfrom discord_typings import UserData\n\n\ndef print_author(user: UserData) -> None:\n print(f\"Created by {user['username']}#{user['discriminator']}\")\n\n\nprint_author({\n 'id': '344404945359077377',\n 'username': 'Bluenix',\n 'discriminator': '7543',\n 'avatar': None\n})\n```\n\nIt is also possible to import the library inside of a `TYPE_CHECKING`-clause:\n\n```python\nfrom typing import Any, TYPE_CHECKING\n\nif TYPE_CHECKING:\n from discord_typings import Snowflake\n\n\nclass Data:\n id: 'Snowflake'\n value: Any\n```\n\n> **Note**\n> It is not recommended to import the library this way, as it does not allow\n> you to introspect the annotations in other code. It is merely pointed out\n> for completeness.\n\n## Naming and Usage\n\nThere is no documentation or API reference as this provides no value on top of\nthe Discord developer documentation the types are based on. Typings are named\nafter the object they represent, and there are little to no\n[exceptions](#exceptions) to this rule.\n\nTypings use suffixes to differentiate between potential wrapping objects in\nuser code - such as importing `UserData` to parse into a custom `User` class.\nThese are `Data`, `Event`, and `Command`. `Event` refers to a gateway event\n*received* over the gateway while `Command` refers to a gateway command *sent*\nover the gateway. `Data` is used for any general objects like `UserData`.\n\n### Exceptions\n\nTo differentiate between the data for complete application commands, and the\ndata Discord expects to receive to create an application command, there is\na special-cased `ApplicationCommandPayload`.\n\n## Codestyle and Contributing\n\nDiscord-typings is a relatively simple library with little code, but\nunfortunately needs to be constantly maintained with Discord's API.\nThe purpose of this library is for this to be a community effort;\nany help with maintenance is greatly appreciated.\n\n### Structure\n\nThe library follows the API docs both in terms of naming, structure, and order\ninside of individual files. This should hopefully make it easier to find the\ncode to change when you have the documentation entry at hand.\n\nAll internal imports should be done by importing the entire module, then\naccessing the typing as an attribute. If `from ... import ...`, or specific\nthings are imported, that is likely to create complicated circular imports.\nInside of annotations, wrap the attribute access (`discord_typings.X`) in\nquotes to make it a string and defer its evaluation.\n\nAll typings which directly represent a Discord payload (excluding typings\ncreated for the purpose of a `Union`) should be added to the file's `__all__`,\nthen be added to the module's `__init__` and its `__all__`.\n\n## Version Guarantees\n\nOnce discord-typings releases its `v1.0` release, it will follow strict\nsemantic versioning guarantees. Keep in mind that this *only applies*\nto the Python interface - such as `TypeDict`s, top-level unions, and\nother aliases.\n\nDue to Discord's frequent API updates, it is not guaranteed that code\nwhich type-checks in one minor version will do so in another one. This\nis because code which does not type-check will not have an effect on\nruntime for users.\n\nAs a reminder of semantic versioning, and a summary of the above:\n\n| Release Type | Upgrade | Downgrade | Comment |\n| ------------ | ------- | --------- | ------------------------------------------------- |\n| **Major** | | | Only type of release with breaking Python changes |\n| **Minor** | X | | May add new features, can break type-checking |\n| **Patch** | X | X | Only intended for bugs |\n\n> **Warn**\n> Patch versions will be used to rectify any accidental breaking changes\n> or unintended bugs / behaviour, therefore you should **always** use\n> the latest patch version.\n\n> **Note**\n> Because patch versions may change previous behaviour, they *could* be\n> considered breaking, however the intention is always to fix unintended\n> behaviour or previous breaking changes which should not have been.\n> In those cases, the previous version will be pulled from PyPI.\n\n## Links and Feedback\n\n* [PyPI Package](https://pypi.org/project/discord-typings)\n* [Discord API Docs](https://discord.com/developers/docs/intro)\n* [Wumpy Project Discord Server](https://discord.gg/ZWpjYdKKTF)\n",
"bugtrack_url": null,
"license": null,
"summary": "Python typings of all payloads that Discord sends as TypedDicts",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/Bluenix2/discord-typings/",
"Repository": "https://github.com/Bluenix2/discord-typings/"
},
"split_keywords": [
"discord",
" discord-api",
" discord-api-wrapper",
" python-3",
" typing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0a75341c1d0b84771dbabe207fe4be896d65213d2ec75ba907219b939245a2e0",
"md5": "70fc7be3ed9f4eb98a5ad6a46560f0a2",
"sha256": "6b51f9d1b6e5fb70c72c87dbcc608feaa5ff5c88bb77ea6b3dc53d80b8732792"
},
"downloads": -1,
"filename": "discord_typings-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "70fc7be3ed9f4eb98a5ad6a46560f0a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 32983,
"upload_time": "2024-03-24T16:08:53",
"upload_time_iso_8601": "2024-03-24T16:08:53.922895Z",
"url": "https://files.pythonhosted.org/packages/0a/75/341c1d0b84771dbabe207fe4be896d65213d2ec75ba907219b939245a2e0/discord_typings-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9157d6ebfbe97005821bdc18758fb5368c650225e368811471af2f8b1067cd2d",
"md5": "399cb8b1cdbc2f63dde5d46ddb48c2a0",
"sha256": "5cb849f9205085a81bf05dca90367a270af86148c4e91c355fc212354a4d55fd"
},
"downloads": -1,
"filename": "discord_typings-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "399cb8b1cdbc2f63dde5d46ddb48c2a0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 26977,
"upload_time": "2024-03-24T16:08:56",
"upload_time_iso_8601": "2024-03-24T16:08:56.127185Z",
"url": "https://files.pythonhosted.org/packages/91/57/d6ebfbe97005821bdc18758fb5368c650225e368811471af2f8b1067cd2d/discord_typings-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-24 16:08:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Bluenix2",
"github_project": "discord-typings",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "discord-typings"
}
JSON
