Oauth2User

Represents a Discord user with extra personal information. If a Oauth2User is created it will NOT overwrite the already existing user with the same ID, if exists.

Attributes

access : Oauth2Access

Source oauth2 access.

avatar_decoration : None, AvatarDecoration

The user's avatar decorations.

avatar_hash : int

The user's avatar's hash in uint128.

avatar_type : IconType

The user's avatar's type.

banner_color : None, Color

The user's banner color if has any.

banner_hash : int

The user's banner's hash in uint128.

banner_type : IconType

The user's banner's type.

discriminator : int

The user's discriminator. Given to avoid overlapping names.

display_name : None, str

The user's non-unique display name.

email : None, str

The user's email. Defaults to None.

email_verified : bool

Whether the email of the user is verified.

flags : UserFlag

The user's user flags.

id : int

The user's unique identifier number.

locale : Locale

The preferred locale by the user.

mfa_enabled : bool

Whether the user has two factor authorization enabled on the account.

name : str

The user's username.

premium_type : PremiumType

The Nitro subscription type of the user.

Properties

access_token

Returns the oauth2 user's access's token.

Returns

access_token : str

activity

Returns the user's top activity if applicable. If not.

Returns

activity : Activity, None

avatar

Returns the respective icon.

Returns

icon : Icon

avatar_decoration_url

Returns the user's avatar decoration's url. If the user has no avatar decoration returns None.

This function is a property of UserBase.

Returns

url : None, str

avatar_url

Returns the user's avatar's url. If the user has no avatar, then returns it's default avatar's url.

This function is a shared property of UserBase-s.

Returns

url : None, str

banner

Returns the respective icon.

Returns

icon : Icon

banner_url

Returns the user's banner's url. If the user has no banner, then returns None.

This function is a shared property of UserBase-s.

Returns

url : None, str

created_at

When the entity was created.

Returns

created_at : datetime

custom_activity

Returns the user's custom activity if applicable.

Returns

activity : Activity, None

default_avatar

Returns the user's default avatar.

Returns

default_avatar : DefaultAvatar

default_avatar_url

Returns the user's default avatar's url.

Returns

default_avatar_url : str

full_name

The user's name with it's discriminator.

Returns

full_name : str

mention

The mention of the user.

Returns

mention : str

mention_nick

The mention to the user's nick.

Returns

mention : str

Notes

It actually has nothing to do with the user's nickname > <.

mfa

Returns whether the user has multi factory authentication enabled.

This property is deprecated and will be removed in 2024 April. Please use mfa_enabled instead.

Returns

mfa_enabled : bool

partial

Returns whether the user is partial. Partial users have only their .id set and every other field might not reflect the reality.

Returns

partial : bool

platform

Returns the user's top status's platform. If the user is offline it will return an empty string.

Returns

platform : str

redirect_url

Returns the oauth2 user's access's redirect url.

Returns

redirect_url : str

refresh_token

Returns the oauth2 user's access's refresh token.

Returns

refresh_token : str

scopes

Returns the oauth2 user's access's scopes.

Returns

scopes : set of str

Methods

new(...)

Creates a new partial oauth2 user with the given fields.

Parameter	Type	Description
avatar	`None`, `Icon`, `str`, `bytes-like`	The user's avatar.
avatar_decoration	`None`, `AvatarDecoration`	The user's avatar decoration.
banner	`None`, `Icon`, `str`, `bytes-like`	The user's banner.
banner_color	`None`, `Color`, `int`	The user's banner color.
discriminator	`str`, `int`	The user's discriminator.
display_name	`None`, `str`	The user's non-unique display name.
email	`None,` str	The user's email.
email_verified	`bool`	Whether the email of the user is verified.
flags	`int`, `UserFlag`	The user's flags.
locale	`Locale`, `str`	The preferred locale by the user.
mfa_enabled	`bool`	Whether the user has two factor authorization enabled on the account.
name	`str`	The user's name.
premium_type	`PremiumType`, `int`	The Nitro subscription type of the user.

Raises

TypeError

If a parameter's type is incorrect.

ValueError

If a parameter's value is incorrect.

avatar_decoration_url_as(...)

Returns the user's avatar decoration's url. If the user has no avatar decoration returns None.

This function is a method of UserBase.

Parameter	Type	Optional	Default	Description
ext	`None`, `str`		`None`	The extension of the image's url. Can be any of: `png`.
size	`None`, `int`		`None`	The preferred minimal size of the image's url.

Returns

url : None, str

Raises

ValueError

If ext, size was not passed as any of the expected values.

avatar_url_as(...)

Returns the user's avatar's url. If the user has no avatar, then returns it's default avatar's url.

This function is a shared method of UserBase-s.

Parameter	Type	Optional	Default	Description
ext	`None`, `str`		`None`	The extension of the image's url. Can be any of: `'jpg'`, `'jpeg'`, `'png'`, `'webp'`. If the user has animated avatar, it can `'gif'` as well.
size	`None`, `int`		`None`	The preferred minimal size of the avatar's url.

Returns

url : None, str

Raises

ValueError

If ext, size was not passed as any of the expected values.

avatar_url_at(guild)

Returns the user's avatar's url at the guild.

This function is a shared method of UserBase-s.

Parameter	Type	Description
guild	`Guild`, `int`	The respective guild or it's identifier.

Returns

url : None, str

avatar_url_at_as(guild, ...)

Returns the user's avatar's url at the guild. If the user has no avatar, then returns it's default avatar's url.

This function is a shared method of UserBase-s.

Parameter	Type	Default	Description
guild	`Guild`, `int`		The respective guild or it's identifier.
ext	`None`, `str`	`None`	The extension of the image's url. Can be any of: `'jpg'`, `'jpeg'`, `'png'`, `'webp'`. If the user has animated avatar, it can `'gif'` as well.
size	`None`, `int`	`None`	The preferred minimal size of the avatar's url.

Returns

url : None, str

Raises

ValueError

If ext, size was not passed as any of the expected values.

avatar_url_for(guild)

Returns the user's guild specific avatar. If the user has no guild local avatar, returns None.

This function is a shared method of UserBase-s.

Parameter	Type	Description
guild	`Guild`, `int`	The respective guild or it's identifier.

Returns

url : None, str

avatar_url_for_as(guild, ...)

Returns the user's guild specific avatar. If the user has no guild local avatar, then returns None.

This function is a shared method of UserBase-s.

Parameter	Type	Default	Description
guild	`Guild`, `int`		The respective guild or it's identifier.
ext	`None`, `str`	`None`	The extension of the image's url. Can be any of: `'jpg'`, `'jpeg'`, `'png'`, `'webp'`. If the user has animated avatar, it can `'gif'` as well.
size	`None`, `int`	`None`	The preferred minimal size of the avatar's url.

Returns

url : None, str

Raises

ValueError

If ext, size was not passed as any of the expected values.

banner_url_as(...)

Returns the user's banner's url. If the user has no banner, then returns None.

This function is a shared method of UserBase-s.

Parameter	Type	Optional	Default	Description
ext	`None`, `str`		`None`	The extension of the image's url. Can be any of: `'jpg'`, `'jpeg'`, `'png'`, `'webp'`. If the user has animated banner, it can `'gif'` as well.
size	`None`, `int`		`None`	The preferred minimal size of the avatar's url.

Returns

url : None, str

Raises

ValueError

If ext, size was not passed as any of the expected values.

can_use_emoji(emoji)

Returns whether the user can use the given emoji.

Parameter	Type	Description
emoji	`Emoji`	The emoji to check.

Returns

can_use_emoji : bool

color_at(guild)

Returns the user's color at the given guild.

Parameter Type Description

guild

Parameter	Type	Description
guild	`None`, `Guild`, `int`	The guild, where the user's color will be checked. Can be given as `None`.

None, Guild, int

The guild, where the user's color will be checked.

Can be given as None.

Returns

color : Color

copy()

Sets the user's attribute's to their default.

copy_with(...)

Creates a new partial oauth2 user with the given fields.

Parameter	Type	Description
avatar	`None`, `Icon`, `str`, `bytes-like`	The user's avatar.
avatar_decoration	`None`, `AvatarDecoration`	The user's avatar decoration.
banner	`None`, `Icon`, `str`, `bytes-like`	The user's banner.
banner_color	`None`, `Color`, `int`	The user's banner color.
discriminator	`str`, `int`	The user's discriminator.
display_name	`None`, `str`	The user's non-unique display name.
email	`None,` str	The user's email.
email_verified	`bool`	Whether the email of the user is verified.
flags	`int`, `UserFlag`	The user's flags.
locale	`Locale`, `str`	The preferred locale by the user.
mfa_enabled	`bool`	Whether the user has two factor authorization enabled on the account.
name	`str`	The user's name.
premium_type	`PremiumType`, `int`	The Nitro subscription type of the user.

Raises

TypeError

If a parameter's type is incorrect.

ValueError

If a parameter's value is incorrect.

from_data(data, access)

Creates a new Oauth2User instance.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	User data.
access	`Oauth2Access`	Source oauth2 access.

Returns

self : instance<cls>

get_guild_profile_for(guild)

Returns the user's guild profile for the given guild.

Parameter	Type	Description
guild	`None`, `Guild`, `int`	The guild to get guild profile for.

Returns

guild_profile : None, Guild

get_status_by_platform(platform)

Gets the user's status by the given platform.

Parameter	Type	Description
platform	`str`	The platform to get the status for.

Returns

status : Status

Defaults to status.offline if the user has no specific status for the given platform.

has_higher_role_than(role)

Returns whether the user has higher role than the given role at it's respective guild.

If the user is the owner of the guild, then returns True even if it has lower role.

Parameter	Type	Description
role	`Role`	The role to check.

Returns

has_higher_role_than : bool

has_higher_role_than_at(user, guild)

Returns whether the user has higher role as the other one at the given guild.

Parameter Type Description

user

Parameter	Type	Description
user	`User`	The other user to check.
guild	`Guild`, `None`, `int`	The guild where the users' top roles will be checked. Can be given as `None`.

User

The other user to check.

guild

Guild, None, int

The guild where the users' top roles will be checked.

Can be given as None.

Returns

has_higher_role_than_at : bool

has_name_like(name)

Returns whether the user's name is like the given string.

Parameter	Type	Description
name	`str`	The name of the user.

Returns

has_name_like : bool

has_name_like_at(name, guild)

Returns whether the user's name is like the given string.

Parameter Type Description

name

str

The name of the user.

guild

None, Guild, int

The guild, where the user's nick will be also checked.

Can be given as None.

Returns

has_name_like : bool

has_role(role)

Returns whether the user has the given role.

Parameter	Type	Description
role	`Role`	The role what will be checked.

Returns

has_role : bool

has_scope(scope)

Returns whether the oauth2 user's access has the given scope.

Parameter	Type	Description
scope	`Oauth2Scope`, `str`	The scope to check out.

Returns

has_scope : bool

Raises

TypeError

If scope is neither str, Oauth2Scope.

is_boosting(guild)

Returns whether the user is boosting the given guild.

Parameter	Type	Description
guild	`None`, `Guild`, `int`	The guild to get whether the user is booster of.

Returns

is_boosting : bool

iter_activities()

Iterates over the user's activities.

This method is an iterable generator.

Yields

activity : Activity

iter_guilds()

Iterates over the guilds of the user.

This method is an iterable generator.

Yields

guild : Guild

The guild profile's guild.

iter_guilds_and_profiles()

Iterates over the guild profiles of the user.

This method is an iterable generator.

Yields

guild : Guild

The guild profile's guild.

guild_profile : GuildProfile

The user's guild profile in the guild.

iter_scopes()

Iterates over the oauth2 user's scopes.

This method is an iterable generator.

Yields

scope : Oauth2Scope

mentioned_in(message)

Returns whether the user is mentioned at a given message.

Parameter	Type	Description
message	`Message`	The message, what's mentions will be checked.

Returns

mentioned : bool

name_at(guild)

Returns the user's name at the given guild.

Parameter Type Description

guild

Parameter	Type	Description
guild	`None`, `Guild`, `int`	The guild, where the user's nick will be checked. Can be given as `None`.

None, Guild, int

The guild, where the user's nick will be checked.

Can be given as None.

Returns

name : str

to_data(...)

Tries to convert the user back to a json serializable dictionary.

Parameter	Type	Optional	Keyword only	Default	Description
defaults	`bool`			`False`	Whether default values should be included as well.
include_internals	`bool`			`False`	Whether internal fields should be included as well.

Returns

data : dict of (str, object) items

top_role_at(guild, ...)

Returns the top role of the user at the given guild.

Parameter	Type	Optional	Default	Description
guild	`None`, `Guild`, `int`			The guild where the user's top role will be looked up.
default	`object`		`None`	If the user is not a member of the guild, or if has no roles there, then the given default value is returned. Defaults to `None`.

Returns

top_role Role, default

_compare_attributes(other)

Compares the two user's user attributes (excluding id obviously).

Parameter	Type	Description
other	`instance<type<self>>`	The other user.

Returns

is_equal : bool

_compare_user_attributes_extended(other)

Compares the two user's user attributes (excluding id obviously).

Parameter	Type	Description
other	`instance<type<self>>`	The other user.

Returns

is_equal : bool

_create_empty(user_id)

Creates a user with its default attributes values set.

Parameter	Type	Description
user_id	`int`	The user's identifier.

Returns

self : instance<cls>

_delete()

Deletes the user from it's guilds.

_difference_update_attributes(data)

Updates the user and returns it's overwritten attributes as a dict with a attribute-name- old-value relation.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	User data received from Discord.

Returns

old_attributes : dict of (str, object) items

All item in the returned dict is optional.

Returned Data Structure

Keys	Values	Applicable for
avatar	`Icon`	all
avatar_decoration	`None`, `AvatarDecoration`	`Client`, `User`
banner	`Icon`	`Client`, `User`
banner_color	`None`, `Color`	`Client`, `User`
channel_id	`int`	`Webhook`
discriminator	`int`	`Client`, `User`
display_name	`None`, `str`	`Client`, `User`
email	`None`, `str`	`Client`
email_verified	`bool`	`Client`
flags	`UserFlag`	`Client`, `User`
locale	`Locale`	`Client`
mfa_enabled	`bool`	`Client`
name	`str`	all
premium_type	`PremiumType`	`Client`

_difference_update_presence(data)

Updates the user's presence and returns it's overwritten attributes as a dict with a attribute-name- old-value relation. An exception from this is activities, because that's a ActivityChange containing all the changes of the user's activities.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Received guild member data.

Returns

old_attributes : dict of (str, object) items

All item in the returned dict is optional.

Returned Data Structure

Keys	Values
activities	`ActivityChange`
status	`Status`
statuses	`None`, `dict` of (`str`, `str`) items

_difference_update_profile(data, guild)

Tries to find the user's respective guild profile. If it cannot find it, creates it.

Parameter	Type	Description
data	`dict<str, object>`	Received guild profile data.
guild	`Guild`	The respective guild of the profile to update.

Returns

old_attributes : None | dict<str, object>

The changed attributes of the respective guild profile as a dict with attribute-name- old-attribute relation.

May return None indicating that the guild profile was not cached before so we cannot determine whether it would have been updated.

The possible keys and values within old_attributes are all optional and they can be any of the following:

Keys	Values
avatar	`Icon`
boosts_since	`None`, `DateTime`
flags	`None`, `GuildProfileFlags`
nick	`None`, `str`
pending	`bool`
role_ids	`None`, `tuple` of `int`
timed_out_until	`None`, `DateTime`

_from_data_and_difference_update_profile(data, guild)

First tries to find the user, then it's respective guild profile for the given guild to update it.

If the method cannot find the user, or the respective guild profile, then creates them.

Parameter	Type	Description
data	`dict<str, object>`	Received guild member data.
guild	`Guild`	The respective guild of the profile to update.

Returns

user : ClientUserBase

The respective user.

old_attributes : None | dict<str, object>

The changed attributes of the respective guild profile as a dict with attribute-name- old-attribute relation.

May return None indicating that the guild profile was not cached before so we cannot determine whether it would have been updated.

The possible keys and values within old_attributes are all optional and they can be any of the following:

Keys	Values
avatar	`Icon`
boosts_since	`None`, `DateTime`
flags	`None`, `GuildProfileFlags`
nick	`None`, `str`
pending	`bool`
role_ids	`None`, `tuple` of `int`
timed_out_until	`None`, `DateTime`

_from_data_and_update_profile(data, guild)

First tries to find the user, then it's respective guild profile for the given guild to update it.

If the method cannot find the user, or the respective guild profile, then creates them.

Not like ._from_data_and_difference_update_profile, this method not calculates changes.

Parameter	Type	Description
data	`dict<str, object>`	Received guild member data.
guild	`Guild`	The respective guild of the profile to update.

Returns

user : ClientUserbase

The updated user.

_get_hash_partial()

Returns a partial user's hash value.

Returns

hash_value : int

_is_equal_same_type(other)

Returns whether the two users are equal. self and other must be the same type.

Parameter	Type	Description
other	`instance<type<self>>`	The other user.

Returns

is_equal : bool

_renew(data)

Renews the oauth2 user's access with the given data.

Parameter	Type	Description
data	`None` or (`dict` of (`str`, `object`))	Requested access data.

_set_default_attributes()

Sets the user's attribute's to their default.

_update_attributes(data)

Updates the user with the given data by overwriting it's old attributes.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	User data received from Discord.

_update_presence(data)

Updates the user's presences with the given data.

Parameter	Type	Description
data	`dict` of (`str`, `object`) items	Received guild member data.

_update_profile(data, guild)

Tries to find the user's respective guild profile. If it cannot find it, creates it.

Parameter	Type	Description
data	`dict<str, object>`	Received guild profile data.
guild	`Guild`	The respective guild of the profile to update.

Returns

updated : bool

Returns True if the guild profile was updated and False when created.

eq()

Return whether the user's id is equal to the other.

format(code)

Formats the user in a format string.

Parameter	Type	Description
code	`str`	The option on based the result will be formatted.

Returns

user : str

Raises

ValueError

Unknown format code.

Examples

>>> from hata import User, now_as_id
>>> user = User.precreate(now_as_id(), name = 'Neko', discriminator = 2012)
>>> user
<User id = 730233383967260672, name = 'Neko#2012'>
>>> # no code stands for `user.name`.
>>> f'{user}'
'Neko'
>>> # 'f' stands for full name
>>> f'{user:f}'
'Neko#2012'
>>> # 'm' stands for mention.
>>> f'{user:m}'
'<@730233383967260672>'
>>> # 'c' stands for created at.
>>> f'{user:c}'
'2020.07.08-01:26:45'

ge()

Returns whether the user's id is greater or equal to the other.

getattr()

Drops a rich attribute error.

gt()

Returns whether the user's id is greater than the other's.

hash()

Returns the user's hash.

le()

Returns whether the user's id is less or equal to the other.

lt()

Returns whether the user's id is less than the other's.

ne()

Returns whether the user's id is different as the other's.

repr()

Returns the user's representation.

Oauth2User

Attributes

Properties

access_token

Returns

activity

Returns

avatar

Returns

avatar_decoration_url

Returns

avatar_url

Returns

banner

Returns

banner_url

Returns

created_at

Returns

custom_activity

Returns

default_avatar

Returns

default_avatar_url

Returns

full_name

Returns

mention

Returns

mention_nick

Returns

Notes

mfa

Returns

partial

Returns

platform

Returns

redirect_url

Returns

refresh_token

Returns

scopes

Returns

Methods

__new__(...)

Raises

avatar_decoration_url_as(...)

Returns

Raises

avatar_url_as(...)

Returns

Raises

avatar_url_at(guild)

Returns

avatar_url_at_as(guild, ...)

Returns

Raises

avatar_url_for(guild)

Returns

avatar_url_for_as(guild, ...)

Returns

Raises

banner_url_as(...)

Returns

Raises

can_use_emoji(emoji)

Returns

color_at(guild)

Returns

copy()

copy_with(...)

Raises

from_data(data, access)

Returns

get_guild_profile_for(guild)

Returns

get_status_by_platform(platform)

Returns

has_higher_role_than(role)

new(...)

eq()

format(code)

ge()

getattr()

gt()

hash()

le()

lt()