Migrating to v2.x

v2.0 is the latest major and breaking release of this library. This version not only brings the long-awaited new API features like interactions, threads etc. but also brings many breaking changes that can affect all the bots updating to v2 from v1.x.

This migration guide covers the prominent additions, bug fixes and most importantly breaking changes to help you easily migrate to v2. We highly suggest you reading this guide to avoid running into unexpected issues.

Python requirement

Prior v2, In v1.x, The minimum Python version required was 3.5, This is not the case in v2. To make development easier and allow our dependencies to adapt new versions, Support for Python version lower then 3.8 has been dropped.

You now need Python 3.8 or higher to use this library.

Removal of Non-bot accounts support

v2.0 removes all the previously depreciated user endpoints. Please note that userbots are against Discord ToS. This library will not provide coverage to such things that are against ToS.

This includes the following methods and attributes:

  • Bot.fetch_user_profile()

  • ClientUser.unblock()

  • ClientUser.relationships

  • ClientUser.friends

  • ClientUser.create_group()

  • ClientUser.edit_settings()

  • User.relationships

  • User.mutual_friends()

  • User.is_friend()

  • User.is_blocked()

  • User.block()

  • User.unblock()

  • User.remove_friend()

  • User.send_friend_request()

  • User.profile()

  • Member.relationships

  • Member.mutual_friends()

  • Member.is_friend()

  • Member.is_blocked()

  • Member.block()

  • Member.unblock()

  • Member.remove_friend()

  • Member.send_friend_request()

  • Member.profile()

  • The afk parameter from Client.change_presence()

  • Events: on_relationship_add and on_relationship_update

  • Classes: Profile, Relationship, CallMessage, GroupCall

Removals and Deprecations

Certain methods, attributes or parameters etc. have been removed or deprecated in v2.0 in favor of some other methods. The below table comprehensively lists some removed things with reasons and the methods to be replaced with:

Deprecated

In favor of

Extra info (if any)

Client.logout()

Client.close()

Guild/Client.request_offline_members

Guild.chunk()

ExtensionNotFound.original

none (See info)

Had no use and was unnecessary.

on_private_channel_create, on_private_channel_delete

none (See info)

Bots no longer get these events.

commands.HelpCommand.clean_prefix

clean_prefix

fetch_offline_members parameter in Client

Client.chunk_guilds_at_startup

Was deprecated since v1.5.

User.permissions_in, Member.permissions_in

abc.GuildChannel.permissions_for()

Sticker.preview_image

none (See info)

Discord no longer provides this.

commands.Bot.self_bot

none (See info)

Userbots are no longer supported

Sticker.tags

StandardSticker.tags

Renaming and fixes

Certain things are renamed and fixed in v2.x, Here’s a list:

i.e Client.get_member(id=...) is no longer supported, you must specify id as positional argument. i.e Client.get_member(id) * IntegrationAccount.id is now str, instead of int, due to Discord changes.

[*] Color.blurple() returns the new blurple color whereas Color.og_blurple() returns old one.

[**] Old name is used for a new enum with different purpose (checking if the sticker is guild sticker or Nitro sticker)

Webhook Types Split

Previously, Webhook had one class Webhook for both asynchronous and synchronous operations. In v2.x, This has been splitted to Webhook and SyncWebhook for async and sync operations respectively.

Before:

from diskord import Webhook, RequestsWebhookAdapter, AsyncWebhookAdapter

webhook = Webhook.from_url('url-here', adapter=RequestsWebhookAdapter()) # for sync
webhook = Webhook.from_url('url-here', adapter=AsyncWebhookAdapter(session)) # for async

Now:

from diskord import Webhook, SyncWebhook
import aiohttp

async with aiohttp.ClientSession() as session: # async
    webhook = Webhook.partial(
        id,
        token,
        session=session
    )
    await webhook.send("Hello world.")

webhook = SyncWebhook.from_url('url-here') # for sync

Assets Redesign

Assets have been completely redesigned in v2.x.

  • Asset-related attributes that previously returned hash strings (e.g. User.avatar) now returns Asset. Asset.key returns the hash from now on.

  • Class.x_url and Class.x_url_as are removed. Asset.replace() or Asset.with_x() methods can be used to get specific asset sizes or types.

  • Emoji.url and PartialEmoji.url are now str. Emoji.save() and Emoji.read() are added to save or read emojis.

  • Emoji.url_as and PartialEmoji.url_as are removed.

  • Some AuditLogDiff attributes now return Asset instead of str: splash, icon, avatar

  • User.avatar returns None if the avatar is not set and is instead the default avatar; use User.display_avatar for pre-2.0 behavior.

  • Attributes that returned Asset are renamed, e.g. attributes ending with _url (i.e. avatar_url) are changed to avatar.url. User.avatar returns None in case the default avatar is used.

Use of timezone aware time

TL;DR: utcnow becomes now(datetime.timezone.utc). If you are constructing datetime yourself, pass tzinfo=datetime.timezone.utc.

Example:

embed = diskord.Embed(
    title = "Embed with timestamp",
    timestamp = datetime(2021, 3, 14, 15, 9, 2, tzinfo=timezone.utc)
)

# or

embed = diskord.Embed(
    title='Embed with timestamp',
    timestamp=diskord.utils.utcnow()
)

Note that newly-added utils.utcnow() can be used as a short-hand of datetime.datetime.now(datetime.timezone.utc).

Edit Behaviour Changes

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

on_socket_raw_receive() behavior

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.

Context attributes

The following Context attributes can now be None: * prefix * command * invoked_with * invoked_subcommand.

Threads Support

Thread support was added in v2.0 and with this addition, There’re some breaking changes.

TL;DR: Most Methods and attributes that returned TextChannel, etc can now return Thread.

Splitting up of status activity listeners

on_member_update() event is no longer dispatched for status/activity changes. Use on_presence_update() instead.

Additions

These are not breaking changes but few major additions in v2.x.

There are many other minor changes that’re not listed here.