From fc07af5777c3a80142a977fbc60681a3043ebd95 Mon Sep 17 00:00:00 2001 From: Jakub Kuczys Date: Sat, 13 May 2023 20:13:55 +0200 Subject: [PATCH] Document the change in behaviour of bool(flag_obj) --- discord/flags.py | 107 ++++++++++++++++++++++++++++++++--------- discord/permissions.py | 6 +++ docs/migrating.rst | 14 ++++++ 3 files changed, 105 insertions(+), 22 deletions(-) diff --git a/discord/flags.py b/discord/flags.py index 6af1bc138..5cd929192 100644 --- a/discord/flags.py +++ b/discord/flags.py @@ -263,6 +263,9 @@ class Capabilities(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -401,6 +404,11 @@ class SystemChannelFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. + + .. versionadded:: 2.0 Attributes ----------- @@ -518,6 +526,11 @@ class MessageFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. + + .. versionadded:: 2.0 .. versionadded:: 1.3 @@ -670,6 +683,11 @@ class PublicUserFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. + + .. versionadded:: 2.0 .. versionadded:: 1.4 @@ -837,12 +855,16 @@ class PrivateUserFlags(PublicUserFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases or inherited flags are not shown. + .. describe:: bool(b) - .. versionadded:: 2.0 + Returns whether any flag is set to ``True``. .. note:: + These are only available on your own user flags. + .. versionadded:: 2.0 + Attributes ----------- value: :class:`int` @@ -924,6 +946,9 @@ class PremiumUsageFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -988,6 +1013,9 @@ class PurchasedFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -1076,6 +1104,11 @@ class MemberCacheFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. + + .. versionadded:: 2.0 Attributes ----------- @@ -1182,6 +1215,9 @@ class ApplicationFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -1349,6 +1385,9 @@ class ChannelFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -1407,6 +1446,9 @@ class PaymentSourceFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -1465,6 +1507,9 @@ class SKUFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -1561,6 +1606,9 @@ class PaymentFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -1631,6 +1679,9 @@ class PromotionFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -1714,6 +1765,9 @@ class GiftFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -1785,6 +1839,9 @@ class LibraryApplicationFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -1859,6 +1916,9 @@ class ApplicationDiscoveryFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -1995,6 +2055,9 @@ class FriendSourceFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -2092,6 +2155,9 @@ class FriendDiscoveryFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -2166,6 +2232,9 @@ class HubProgressFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -2232,6 +2301,9 @@ class OnboardingProgressFlags(BaseFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -2290,6 +2362,9 @@ class AutoModPresets(ArrayFlags): Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -2343,39 +2418,35 @@ class MemberFlags(BaseFlags): .. describe:: x == y Checks if two MemberFlags are equal. - .. describe:: x != y Checks if two MemberFlags are not equal. - .. describe:: x | y, x |= y Returns a MemberFlags instance with all enabled flags from both x and y. - .. describe:: x & y, x &= y Returns a MemberFlags instance with only flags enabled on both x and y. - .. describe:: x ^ y, x ^= y Returns a MemberFlags instance with only flags enabled on only one of x or y, not on both. - .. describe:: ~x Returns a MemberFlags instance with all flags inverted from x. - .. describe:: hash(x) Return the flag's hash. - .. describe:: iter(x) Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.0 @@ -2427,39 +2498,35 @@ class ReadStateFlags(BaseFlags): .. describe:: x == y Checks if two ReadStateFlags are equal. - .. describe:: x != y Checks if two ReadStateFlags are not equal. - .. describe:: x | y, x |= y Returns a ReadStateFlags instance with all enabled flags from both x and y. - .. describe:: x & y, x &= y Returns a ReadStateFlags instance with only flags enabled on both x and y. - .. describe:: x ^ y, x ^= y Returns a ReadStateFlags instance with only flags enabled on only one of x or y, not on both. - .. describe:: ~x Returns a ReadStateFlags instance with all flags inverted from x. - .. describe:: hash(x) Return the flag's hash. - .. describe:: iter(x) Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.1 @@ -2492,39 +2559,35 @@ class InviteFlags(BaseFlags): .. describe:: x == y Checks if two InviteFlags are equal. - .. describe:: x != y Checks if two InviteFlags are not equal. - .. describe:: x | y, x |= y Returns a InviteFlags instance with all enabled flags from both x and y. - .. describe:: x & y, x &= y Returns a InviteFlags instance with only flags enabled on both x and y. - .. describe:: x ^ y, x ^= y Returns a InviteFlags instance with only flags enabled on only one of x or y, not on both. - .. describe:: ~x Returns a InviteFlags instance with all flags inverted from x. - .. describe:: hash(x) Return the flag's hash. - .. describe:: iter(x) Returns an iterator of ``(name, value)`` pairs. This allows it to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether any flag is set to ``True``. .. versionadded:: 2.1 diff --git a/discord/permissions.py b/discord/permissions.py index 0232cbff0..76afe784b 100644 --- a/discord/permissions.py +++ b/discord/permissions.py @@ -119,6 +119,12 @@ class Permissions(BaseFlags): to be, for example, constructed as a dict or a list of pairs. Note that aliases are not shown. + .. describe:: bool(b) + + Returns whether the permissions object has any permissions set to ``True``. + + .. versionadded:: 2.0 + Attributes ----------- value: :class:`int` diff --git a/docs/migrating.rst b/docs/migrating.rst index 36421a5ef..52cf059ff 100644 --- a/docs/migrating.rst +++ b/docs/migrating.rst @@ -916,6 +916,20 @@ Due to a breaking API change by Discord, :meth:`Guild.bans` no longer returns a async for ban in guild.bans(limit=1000): ... +Flag classes now have a custom ``bool()`` implementation +-------------------------------------------------------- + +To allow library users to easily check whether an instance of a flag class has any flags enabled, +using `bool` on them will now only return ``True`` if at least one flag is enabled. + +This means that evaluating instances of the following classes in a bool context (such as ``if obj:``) may no longer return ``True``: + +- :class:`Intents` +- :class:`MemberCacheFlags` +- :class:`MessageFlags` +- :class:`Permissions` +- :class:`PublicUserFlags` +- :class:`SystemChannelFlags` Function Signature Changes ----------------------------