Migrer vers la version 2.0¶

La version 2.0 a introduit de nouvelles fonctionnalités Discord et a marqué certaines anciennes fonctionnalités comme obsolètes.

Une partie de la refonte implique la création de commandes d’application et de composants. Ces changements incluent une nouvelle classe Bot, ui.View, et une nouvelle classe ApplicationContext. Si vous êtes intéressé par leur création, veuillez consulter notre guide.

Changement de version de Python¶

Afin de faciliter le développement et de permettre à nos dépendances de se mettre à jour pour supporter Python 3.8 ou une version supérieure, la bibliothèque a dû retirer le support des versions de Python inférieures à 3.7, ce qui signifie essentiellement que le support pour Python 3.7 et les versions antérieures a été abandonné.

Changements majeurs des modèles¶

Ci-dessous sont les changements majeurs qui se sont produits dans la v2.0 :

Suppression du support des comptes utilisateurs¶

Avant la version 2.0, les comptes utilisateurs étaient pris en charge. Cela allait à l’encontre de l’esprit de la bibliothèque et des conditions d’utilisation de Discord, et a été supprimé. Ainsi, les fonctionnalités qui leur étaient exclusivement réservées ont été supprimées :

L’argument bot de Client.start() et Client.run()
L’argument afk de Client.change_presence()
Classes Profile, Relationship, Call Message, Group Call
RelationshipType, HypeSquadHouse, PremiumType, UserContentFilter, FriendFlags, Theme
GroupChannel.add_recipients, remove_recipients, edit (NOTE : GroupChannel lui-même reste toujours)
Guild.ack
Client.self_bot
Client.fetch_user_profile
Message.call et ack
ClientUser.email, premium, premium_type, get_relationship, relationships, friends, blocked, create_group, edit_settings
Arguments de ClientUser.edit : password, new_password, email, house
User.relationship, mutual_friends, is_friend, is_blocked, block, Unblock, remove_friend, send_friend_request, profile
Événements : on_relationship_add et on_relationship_update

Temps conscient du fuseau horaire¶

utcnow devient now(datetime.timezone.utc). Si vous construisez vous-même un objet datetime.datetime, passez tzinfo=datetime.timezone.utc.

embed = discord.Embed(
    title = "Pi Day 2021 in UTC",
    timestamp = datetime(2021, 3, 14, 15, 9, 2, tzinfo=timezone.utc)
)

Note that newly-added utils.utcnow() can be used as an alias of datetime.datetime.now(datetime.timezone.utc).

Asset Changes¶

Les attributs liés aux actifs qui renvoyaient auparavant des chaînes de hachage (par exemple User.avatar) renvoient maintenant Asset. Asset.key renvoie le hachage à partir de maintenant.

Les méthodes Asset.replace() ou Asset.with_x() peuvent être utilisées pour obtenir des tailles ou des types d’actifs spécifiques.
Emoji.url et PartialEmoji.url sont maintenant str. Emoji.save() et Emoji.read() sont ajoutés pour sauvegarder ou lire les emojis.
Emoji.url_as et PartialEmoji.url_as ont été supprimés.
Certains attributs AuditLogDiff renvoient maintenant Asset au lieu de str, : AuditLogDiff.splash, AuditLogDiff.icon, AuditLogDiff.avatar
User.avatar renvoie None` si l’avatar n’est pas défini et est à la place l’avatar par défaut ; utilisez User.display_avatar pour un comportement similaire à celui précédant la version 2.0.

Avant	Après
`str(user.avatar_url)`	`user.display_avatar.url`
`str(user.avatar_url_as(size=128))`	`user.display_avatar.with_size(128).url`
`str(user.avatar_url_as(size=128, static_format="png"))`	`user.display_avatar.replace(size=128, static_format="png").url`
`str(user.avatar_url_as(size=128, static_format="png"))`	`user.display_avatar.with_size(128).with_static_format("png").url`
`await user.avatar_url.read()`	`await user.display_avatar.read()`
`str(emoji.url)`	`emoji.url`
`str(emoji.url_as(size=32))`	`emoji.with_size(32).url`
`str(url_as(size=128, static_format="png"))`	`emoji.replace(size=128, static_format="png").url`
`str(sticker.image_url)`	`sticker.url`
`str(partialemoji.url)`	`partialemoji.url`

Webhook Changes¶

class:Webhook et WebhookMessage sont maintenant toujours asynchrones. Pour une utilisation synchrone (requests), utilisez SyncWebhook et SyncWebhookMessage.
WebhookAdapter, AsyncWebhookAdapter, et RequestsWebhookAdapter sont supprimés, car ils sont inutiles.
adapter arguments of Webhook.partial() and Webhook.from_url() are removed. Sessions are now passed directly to partial / from_url.

webhook = discord.SyncWebhook.from_url(
    f"https://discord.com/api/webhooks/{id}/{token}"
)
webhook.send("Hello from Pycord 2.0")

async with aiohttp.ClientSession() as session:
    webhook = discord.Webhook.partial(
        id,
        token,
        session=session
    )
    await webhook.send("Hello from Pycord 2.0")

Intents Changes¶

Intents.message_content is now a privileged intent. Disabling it causes Message.content, Message.embeds, Message.components, and Message.attachments to be empty (an empty string or an empty array), directly causing ext.commands.Command s to not run. See here for more information.

Threads Introduced¶

The following methods and attributes can return Thread objects:

Message.channel
Client.fetch_channel()
Guild.fetch_channel()
ext.commands.ChannelNotReadable.argument
ext.commands.NSFWChannelRequired’s channel argument
Client.get_channel()

Permission Changes¶

permissions_in has been removed in favor of checking the permissions of the channel for said user.

Avant	Après
`User.permissions_in`	`abc.GuildChannel.permissions_for`
`Member.permissions_in`	`abc.GuildChannel.permissions_for`

Edit Method Behavior Change¶

edit methods of most classes no longer update the cache in-place, and instead returns the modified object.

Positional-Keyword Argument Split¶

The following are now positional only:

The following are now keyword only:

Event Changes¶

on_presence_update() replaces on_member_update for updates to Member.status and Member.activities.
on_private_channel_create/delete will no longer be dispatched due to Discord changes.
on_socket_raw_receive() is no longer dispatched for incomplete data, and the value passed is always decompressed and decoded to str. Previously, when received a multi-part zlib-compressed binary message, on_socket_raw_receive() was dispatched on all messages with the compressed, encoded bytes.

Message.type For Replies¶

Message.type now returns MessageType.reply for replies, instead of MessageType.default.

Sticker Changes¶

Sticker.preview_image was removed as Discord no longer provides the data.
StickerType, an enum of sticker formats, is renamed to StickerFormatType. Old name is used for a new enum with different purpose (checking if the sticker is guild sticker or Nitro sticker).
Message.stickers is now List[StickerItem] instead of List[Sticker]. While StickerItem supports some operations of previous Sticker, description and pack_id attributes do not exist. Sticker can be fetched via StickerItem.fetch() method.
Sticker.image is removed. Sticker can still be fetched via Sticker.read() or Sticker.save() and its URL can be accessed via Sticker.url, just like new Emoji.
Due to the introduction of GuildSticker, Sticker.tags is removed from the parent class Sticker and moved to StandardSticker.tags.

Type Changes¶

Many method arguments now reject None or return None.

DMChannel.recipient is now optional, and will return None in many cases.
User.avatar returns None if the avatar is not set and is instead the default avatar.
Guild.create_text_channel’s topic argument no longer accepts None.
Guild.vanity_invite can now return None.
Template.edit’s name argument no longer accepts None.
Member.edit’s roles argument no longer accepts None.
Bot.add_listener and Bot.remove_listener’s name arguments no longer accept None.
The following ext.commands.Context attributes can now be None: prefix, command, invoked_with, invoked_subcommand.
ext.commands.Command.help can now be None.

Miscellaneous Changes¶

The following were removed:

Client.request_offline_members
Client.logout
ExtensionNotFound.original
MemberCacheFlags.online
guild_subscriptions argument of Client
fetch_offline_members argument of Client
HelpCommand.clean_prefix moved to ext.commands.Context.clean_prefix
VerificationLevel.table_flip (alias of high) was removed. extreme, very_high, and double_table_flip attributes were removed and replaced with VerificationLevel.highest.

The following were renamed:

Colour.blurple is renamed to Colour.og_blurple, and Colour.blurple now returns the newer color.
missing_perms arguments and attributes of ext.commands.MissingPermissions and ext.commands.BotMissingPermissions are renamed to missing_permissions.

The following were changed in behavior:

Embed that has a value is always considered truthy. Previously it only considered text fields.
Bot.add_cog() now raises an error when a cog with the same name is already registered. override argument can be used to bring back the 1.x behavior.
StageChannel.edit() can no longer edit topic. Use StageInstance.edit() instead.
StageChannel.clone() no longer clones its topic.

The following were changed in types:

ext.commands.Command.clean_params is now a dict, not OrderedDict.
Reaction.custom_emoji is now Reaction.is_custom_emoji for consistency.
IntegrationAccount.id is now str, instead of int, due to Discord changes.
AuditLogDiff.type is now Union[ChannelType, StickerType], instead of ChannelType.

Parting Words¶

The v2.0 of the library implemented a lot of new features. To implement newer features, such as slash commands, they can be seen on our guide.