gsd
/
disco
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

Finished guild API docs

pull/177/head
Zwork101 5 years ago
parent
ef954274db
commit
7605cc859d
No known key found for this signature in database GPG Key ID: 259D6C0D5A9CCF67
1 changed files with 449 additions and 4 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 453
      disco/types/guild.py

453
disco/types/guild.py
View File

@ -286,7 +286,7 @@ class GuildMember(SlottedModel):
Returns
-------
:class:`disco.types.voice.VoiceState` or None
:class:`~disco.types.voice.VoiceState` or None
Returns the voice state for the member if they are currently connected
to the guild's voice server.
"""
@ -427,7 +427,7 @@ class Guild(SlottedModel, Permissible):
The id of this guild.
owner_id : snowflake
The id of the owner.
owner : :class:~disco.types.guild.GuildMember`
owner : :class:`~disco.types.guild.GuildMember`
The owner as a member
afk_channel_id : snowflake
The id of the afk channel.
@ -435,6 +435,8 @@ class Guild(SlottedModel, Permissible):
The id of the embed channel.
system_channel_id : snowflake
The id of the system channel.
system_channel : :class:`~disco.types.channel.Channel`
The system channel (system notifications like member joins are sent).
name : str
Guild's name.
icon : str
@ -469,6 +471,16 @@ class Guild(SlottedModel, Permissible):
Guild's premium tier.
premium_subscription_count : int
The amount of users using their Nitro boost on this guild.
icon_url : str
Shorthand for :func:`~disco.types.guild.Guild.get_icon_url`
vanity_url : str
Shorthand for :func:`~disco.types.guild.Guild.get_vanity_url`
splash_url : str
Shorthand for :func:`~disco.types.guild.Guild.get_splash_url`
banner_url : str
Shorthand for :func:`~disco.types.guild.Guild.get_banner_url`
audit_log : :class:`~disco.util.paginator.Pagniator` of :class:`~disco.types.guild.AuditLogEntry`
Shorthand for :func:`~disco.types.guild.Guild.audit_log_iter`
"""
id = Field(snowflake)
owner_id = Field(snowflake)
@ -592,18 +604,55 @@ class Guild(SlottedModel, Permissible):
return self.members.get(user)
def get_prune_count(self, days=None):
"""
Get prune count
Before pruning a discord, you should use this method to tell you how many people will be removed.
Parameters
----------
days : int
The amount of days ago people to have sent a message to not be removed
Returns
-------
:class:`~disco.types.guild.PruneCount`
An object containing information on people getting pruned
"""
return self.client.api.guilds_prune_count_get(self.id, days=days)
def prune(self, days=None, compute_prune_count=None):
"""
Prunes the guild
Removes inactive people from the guild
Parameters
----------
days : int
The amount of days ago people to have sent a message to not be removed
compute_prune_count : bool
If true, will return how many people were removed
Returns
-------
:class:`~disco.types.guild.PruneCount`
An object with the pruned members, if compute_prune_count is True.
"""
return self.client.api.guilds_prune_create(self.id, days=days, compute_prune_count=compute_prune_count)
def create_role(self, **kwargs):
"""
Create a new role.
Parameters
----------
kwargs
Keyword arguments to be passed into :func:`~disco.api.client.APIClient.guilds_roles_create`
Returns
-------
:class:`Role`
:class:`~disco.types.guild.Role`
The newly created role.
"""
return self.client.api.guilds_roles_create(self.id, **kwargs)
@ -611,22 +660,80 @@ class Guild(SlottedModel, Permissible):
def delete_role(self, role, **kwargs):
"""
Delete a role.
Parameters
----------
role : :class:`~disco.types.guild.Role` or snowflake
The role to delete
kwargs
Keyword arguments to be passed into :func:`~disco.api.client.APIClient.guilds_roles_delete`
"""
self.client.api.guilds_roles_delete(self.id, to_snowflake(role), **kwargs)
def update_role(self, role, **kwargs):
"""
Update a role
Update a role's settings.
You can provide a :class:`~disco.types.permissions.PermissionValue` when updating a role's permissions.
Parameters
----------
role : :class:`~disco.types.guild.Role` or snowflake
The role that is being updated
kwargs
Keyword arguments to be passed into :func:`~disco.api.client.APIClient.guilds_roles_modify`
Returns
-------
:class:`~disco.types.guild.Role`
An updated version of the role
"""
if 'permissions' in kwargs and isinstance(kwargs['permissions'], PermissionValue):
kwargs['permissions'] = kwargs['permissions'].value
return self.client.api.guilds_roles_modify(self.id, to_snowflake(role), **kwargs)
def request_guild_members(self, query=None, limit=0, presences=False):
"""
Request guild members
Fetch all guild members from a guild, and update the current guild's members with the returned members.
Parameters
----------
query : str
Return members who's usernames start with this query
limit : int
Return members up until this limit
presences : bool
Return the member presences with the members
"""
self.client.gw.request_guild_members(self.id, query, limit, presences)
def request_guild_members_by_id(self, user_id_or_ids, limit=0, presences=False):
"""
Request guild members
Fetch specified guild members from a guild, and update the current guild's members with the returned members.
Parameters
----------
user_id_or_ids : snowflake or list of snowflake
The user or users to be appended to the guild's members
limit : int
Limit the amount of responses, not recommended
presences : bool
If the member presences should be fetched as well
"""
self.client.gw.request_guild_members_by_id(self.id, user_id_or_ids, limit, presences)
def sync(self):
"""
Update guild members
Update this guild object with all the members in the guild
"""
warnings.warn(
'Guild.sync has been deprecated in place of Guild.request_guild_members',
DeprecationWarning)
@ -634,18 +741,75 @@ class Guild(SlottedModel, Permissible):
self.request_guild_members()
def get_bans(self):
"""
Get all guild bans
Returns
-------
:class:`~disco.util.hashmap.HashMap` of snowflake to :class:`~disco.types.guild.GuildBan`
"""
return self.client.api.guilds_bans_list(self.id)
def get_ban(self, user):
"""
Get a user's ban
Parameters
----------
user : snowflake or :class:`~disco.types.user.User`
The user that is banned
Returns
-------
:class:`~disco.types.guild.GuildBan`
The user's ban
"""
return self.client.api.guilds_bans_get(self.id, user)
def delete_ban(self, user, **kwargs):
"""
Remove a user's ban
Parameters
----------
user : snowflake or :class:`~disco.types.user.User`
The user that was banned
kwargs
Keyword arguments to be passed into :func:`~disco.api.client.APIClient.guilds_bans_delete`
"""
self.client.api.guilds_bans_delete(self.id, to_snowflake(user), **kwargs)
def create_ban(self, user, *args, **kwargs):
"""
Ban a user for the guild
Parameters
----------
user : snowflake or :class:`~disco.types.user.User`
The user to be banned
args
Arguments to be passed into :func:`~disco.api.client.APIClient.guilds_bans_create`
kwargs
Keyword arguments to be passed into :func:`~disco.api.client.APIClient.guilds_bans_create`
"""
self.client.api.guilds_bans_create(self.id, to_snowflake(user), *args, **kwargs)
def create_channel(self, *args, **kwargs):
"""
Create a channel (deprecated)
Parameters
----------
args
Arguments to be passed into :func:`~disco.api.client.APIClient.guilds_channels_create`
kwargs
Keyword arguments to be passed into :func:`~disco.api.client.APIClient.guilds_channels_create`
Returns
-------
channel : :class:`~disco.types.channel.Channel`
The freshly made channel
"""
warnings.warn(
'Guild.create_channel will be deprecated soon, please use:'
' Guild.create_text_channel or Guild.create_category or Guild.create_voice_channel',
@ -656,6 +820,24 @@ class Guild(SlottedModel, Permissible):
def create_category(self, name, permission_overwrites=[], position=None, reason=None):
"""
Creates a category within the guild.
Categories are usd to organize channels, and can be used to create default permissions for new channels.
Parameters
----------
name : str
the name of the category
permission_overwrites : list of :class:`~disco.types.channel.PermissionOverwrite`
Permission overwrites that will be applied to the channel's permissions
position : int
If the channel should be above or below other channels, by default appended to end.
reason : str
the reason for creating the channel
Returns
-------
:class:`~disco.types.channel.Channel`
A freshly made category
"""
return self.client.api.guilds_channels_create(
self.id, ChannelType.GUILD_CATEGORY, name=name, permission_overwrites=permission_overwrites,
@ -672,6 +854,26 @@ class Guild(SlottedModel, Permissible):
reason=None):
"""
Creates a text channel within the guild.
Parameters
----------
name : str
The name of the text channel
permission_overwrites : list of :class:`~disco.types.channel.PermissionOverwrite`
Permission overwrites to apply to the channel
parent_id : snowflake
the ID of the parent channel
nsfw : bool
Whether the new channel will ne nsfw or not
position : int
The position in channel order the new channel will be
reason : str
The reason for creating the new channel
Returns
-------
:class:`~disco.types.channel.Channel`
The freshly made channel
"""
return self.client.api.guilds_channels_create(
self.id, ChannelType.GUILD_TEXT, name=name, permission_overwrites=permission_overwrites,
@ -689,27 +891,108 @@ class Guild(SlottedModel, Permissible):
reason=None):
"""
Creates a voice channel within the guild.
Parameters
----------
name : str
The name of the text channel
permission_overwrites : list of :class:`~disco.types.channel.PermissionOverwrite`
Permission overwrites to apply to the channel
parent_id : snowflake
The ID of the parent channel
bitrate : int
The channel bitrate
user_limit : int
the max amount of people that can be in the voice channel
position : int
The position in channel order the new channel will be
reason : str
The reason for creating the new channel
Returns
-------
:class:`~disco.types.channel.Channel`
The freshly made voice channel
"""
return self.client.api.guilds_channels_create(
self.id, ChannelType.GUILD_VOICE, name=name, permission_overwrites=permission_overwrites,
parent_id=parent_id, bitrate=bitrate, user_limit=user_limit, position=position, reason=None)
parent_id=parent_id, bitrate=bitrate, user_limit=user_limit, position=position, reason=reason)
def leave(self):
"""
Leave this guild
If you rejoin, the bot's permissions will have to be reset.
"""
return self.client.api.users_me_guilds_delete(self.id)
def get_invites(self):
"""
Get all invites that link to the guild
Returns
-------
list of :class:`~disco.types.invite.Invite`
Invites to this guild
"""
return self.client.api.guilds_invites_list(self.id)
def get_emojis(self):
"""
Get all emojis that were added to the guild
Returns
-------
list of :class:`~disco.types.message.Emoji`
Emojis added to this guild
"""
return self.client.api.guilds_emojis_list(self.id)
def get_emoji(self, emoji):
"""
Fetch the an emoji from the guild
Parameters
----------
emoji : snowflake
The emoji ID of the emoji to get
Returns
-------
:class:`~disco.types.message.Emoji`
The fetched emoji
"""
return self.client.api.guilds_emojis_get(self.id, emoji)
def get_voice_regions(self):
"""
Get all available voice regions for the guild's voice channels
Returns
-------
:class:`~disco.types.base.Hashmap`
hashmap of snowflake to :class:`~disco.types.voice.VoiceRegion`
"""
return self.client.api.guilds_voice_regions_list(self.id)
def get_icon_url(self, still_format='webp', animated_format='gif', size=1024):
"""
Get the guilds icon's url. (if applicable)
Parameters
----------
still_format : str
The image type to return if the guild icon is a still image
animated_format : str
the image type to return if the guild icon is a animated image
size : int
The size of width and height of the image
Returns
-------
str
The icon url, or an empty string if no guild icon was uploaded
"""
if not self.icon:
return ''
@ -723,18 +1006,56 @@ class Guild(SlottedModel, Permissible):
)
def get_vanity_url(self):
"""
get the guild's vanity url. (If applicable)
Returns
-------
str
The vanity url, or an empty string if there is none
"""
if not self.vanity_url_code:
return ''
return 'https://discord.gg/' + self.vanity_url_code
def get_splash_url(self, fmt='webp', size=1024):
"""
Get the guild's splash url
Parameters
----------
fmt : str
The format of the splash image
size : int
The width and height of the image
Returns
-------
str
The splash image url, or an empty string if a splash image was not uploaded
"""
if not self.splash:
return ''
return 'https://cdn.discordapp.com/splashes/{}/{}.{}?size={}'.format(self.id, self.splash, fmt, size)
def get_banner_url(self, fmt='webp', size=1024):
"""
Get the guild's banner image
Parameters
----------
fmt : str
The format of the splash image
size : int
The width and height of the image
Returns
-------
str
The banner image url, or an empty string is a banner image was not uploaded
"""
if not self.banner:
return ''
@ -765,6 +1086,18 @@ class Guild(SlottedModel, Permissible):
return self.audit_log_iter()
def audit_log_iter(self, **kwargs):
"""
Iterate through audit logs
Parameters
----------
kwargs
Keyword arguments to be passed into :class:`~disco.util.paginator.Paginator`
Returns
-------
:class:`~disco.util.paginator.Paginator` of :class:`~disco.types.guild.AuditLogEntry`
"""
return Paginator(
self.client.api.guilds_auditlogs_list,
'before',
@ -773,15 +1106,63 @@ class Guild(SlottedModel, Permissible):
)
def get_audit_log_entries(self, *args, **kwargs):
"""
Get all AuditLog entries
Parameters
----------
args
Arguments to be passed into :func:`~disco.api.client.APIClient.guilds_auditlogs_list`
kwargs
Keyword arguments to be passed into :func:`~disco.api.client.APIClient.guilds_auditlogs_list`
"""
return self.client.api.guilds_auditlogs_list(self.id, *args, **kwargs)
class IntegrationAccount(SlottedModel):
"""
The account associated with an integration
Attributes
----------
id : str
The ID of the account (not a snowflake)
name : str
The name of the account
"""
id = Field(text)
name = Field(text)
class Integration(SlottedModel):
"""
Guild integration object
Attributes
----------
id : snowflake
The ID of the integration
name : str
The name of the integration
type : str
integration type (twitch, youtube, etc)
enabled : bool
If the integration is enabled
syncing : bool
If the integration is syncing
role_id : snowflake
The ID the integration uses for subscribers
expire_behavior : int
The behavior when the integration expires (0, Remove role. 1, Kick)
expire_grace_period : int
The grace period (in days) before expiring subscribers
user : :class:`~disco.types.user.User`
The user this integration is for
account : :class:`~disco.types.guild.IntegrationAccount`
The integration's account
synced_at : datetime
The last time the integration was synced
"""
id = Field(snowflake)
name = Field(text)
type = Field(text)
@ -876,12 +1257,52 @@ MESSAGE_ACTIONS = (
class AuditLogObjectChange(SlottedModel):
"""
Audit log change object
Attributes
----------
key : str
name of audit log change key
new_value : str
New value of the key
old_value : str
Old value of the key
"""
key = Field(text)
new_value = Field(text)
old_value = Field(text)
class AuditLogEntry(SlottedModel):
"""
An audit log entry
Attributes
----------
id : snowflake
The snowflake of the audit log entry
guild_id : snowflake
The snowflake of the guild this audit log entry belongs too
user_id : snowflake
The user who made the changes
target_id : snowflake
Snowflake of the affected entity (webhook, user, role, etc.)
action_type : :class:`~disco.types.guild.AuditLogActionTypes`
The type of action that occurred
changes : list of :class:`~disco.types.guild.AuditLogObjectChange`
Changes made to the target_id
options : dict of str to str
Additional info for certain action types
reason : str
The reason for the action
guild : :class:`~disco.types.guild.Guild`
The guild this audit log entry belongs too
user : :class:`~disco.types.user.User`
the user this entry involves (if applicable)
target : Any type
The target of this audit log entry
"""
id = Field(snowflake)
guild_id = Field(snowflake)
user_id = Field(snowflake)
@ -895,6 +1316,30 @@ class AuditLogEntry(SlottedModel):
@classmethod
def create(cls, client, users, webhooks, data, **kwargs):
"""
Initializes a new audit log entry based on the input
There's little reason to use this in practice, as you should be fetching audit logs from the guild.
Making an audit doesn't execute the logged action.
Parameters
----------
client : :class:`~disco.client.Client`
The client object used so models can interact with the API
users : list of :class:`~disco.types.user.User`
A list of all users on the respective guild
webhooks : list of :class:`~disco.types.webhook.Webhook`
A list of all webhooks on the respective guild
data : dict of str to Any
Audit log entry data
kwargs
Keyword arguments that will be merged with data
Returns
-------
:class:`~disco.types.guild.AuditLogEntry`
A freshly made audit log entry
"""
self = super(SlottedModel, cls).create(client, data, **kwargs)
if self.action_type in MEMBER_ACTIONS:

Write Preview
Loading…
Cancel
Save