From 203b6a9114346cb5aaa88a2fa599d3eec5aa4a60 Mon Sep 17 00:00:00 2001 From: R3T4RD3D Date: Tue, 11 Apr 2017 00:49:23 +0200 Subject: [PATCH 1/2] Add documentation to user class --- disco/types/user.py | 71 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/disco/types/user.py b/disco/types/user.py index 3192abc..03e2388 100644 --- a/disco/types/user.py +++ b/disco/types/user.py @@ -12,6 +12,26 @@ DefaultAvatars = Enum( class User(SlottedModel, with_equality('id'), with_hash('id')): + """ + User object. + + Attributes + ---------- + id : snowflake + The ID of this user. + username : str + The name of the user. + avatar : str + The user\'s avatar hash. + discriminator : str + The user\'s discriminator (4-digit discord-tag). + bot : bool + Whether this user is a bot. + verified : bool + Whether the email on this account has been verified. + email : str + The user\'s email address. + """ id = Field(snowflake) username = Field(text) avatar = Field(binary) @@ -23,6 +43,21 @@ class User(SlottedModel, with_equality('id'), with_hash('id')): presence = Field(None) def get_avatar_url(self, fmt='webp', size=1024): + """ + Returns the URL to the user\'s avatar. + + Args + ---- + fmt : str + Imageformat of the avatar. + size : int + Size of the avatar. + + Returns + ------- + str + The URL to the user\'s avatar. + """ if not self.avatar: return 'https://cdn.discordapp.com/embed/avatars/{}.png'.format(self.default_avatar.value) @@ -35,14 +70,23 @@ class User(SlottedModel, with_equality('id'), with_hash('id')): @property def default_avatar(self): + """ + Returns the Default avatar url of the user. + """ return DefaultAvatars[int(self.discriminator) % len(DefaultAvatars.attrs)] @property def avatar_url(self): + """ + Returns the avatar url of the user. + """ return self.get_avatar_url() @property def mention(self): + """ + Formated string that mentions the user. + """ return '<@{}>'.format(self.id) def __str__(self): @@ -67,12 +111,39 @@ Status = Enum( class Game(SlottedModel): + """ + Represents the activity of a user. + + Attributes + ---------- + type : `GameType` + Whether the user is just playing the game or streaming. + + Possible values are: `DEFAULT` (Playing ...) and `STREAMING` (Streaming ...). + name : str + Name of the Game. + url : str + Stream URL. Only validated when `GameType` is `STREAMING`. + """ type = Field(GameType) name = Field(text) url = Field(text) class Presence(SlottedModel): + """ + Represents the Presence of a user. + + Attributes + ---------- + user : :class:`disco.types.user.User` + game : :class:`disco.types.user.Game` + The user\'s current activity. + status : `Status` + The user\'s current status. + + Possible values are: `ONLINE`, `IDLE`, `DND` (Do not Disturb) and `OFFLINE`. + """ user = Field(User, alias='user', ignore_dump=['presence']) game = Field(Game) status = Field(Status) From 1015ba4704b81717f2754a462030c508726253c8 Mon Sep 17 00:00:00 2001 From: R3T4RD3D Date: Tue, 11 Apr 2017 01:49:09 +0200 Subject: [PATCH 2/2] Add documentation to MessageEmbed* objects --- disco/types/message.py | 110 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) diff --git a/disco/types/message.py b/disco/types/message.py index 9b33d11..a005337 100644 --- a/disco/types/message.py +++ b/disco/types/message.py @@ -51,12 +51,38 @@ class MessageReaction(SlottedModel): class MessageEmbedFooter(SlottedModel): + """ + Message embed footer object. + + Attributes + ---------- + text : str + Footer text. + icon_url : str + URL of footer icon. + proxy_icon_url : str + Proxied URL of the footer icon. + """ text = Field(text) icon_url = Field(text) proxy_icon_url = Field(text) class MessageEmbedImage(SlottedModel): + """ + Message embed image object. + + Attributes + ---------- + url : str + Source URL of image. + proxy_url : str + Proxied URL of the image. + height : int + height of image. + width : int + width of image. + """ url = Field(text) proxy_url = Field(text) width = Field(int) @@ -64,6 +90,20 @@ class MessageEmbedImage(SlottedModel): class MessageEmbedThumbnail(SlottedModel): + """ + Message embed thumbnail object. + + Attributes + ---------- + url : str + Source URL of thumbnail. + proxy_url : str + Proxied URL of the thumbnail. + height : int + height of thumbnail. + width : int + width of thumbnail. + """ url = Field(text) proxy_url = Field(text) width = Field(int) @@ -71,12 +111,38 @@ class MessageEmbedThumbnail(SlottedModel): class MessageEmbedVideo(SlottedModel): + """ + Message embed video object. + + Attributes + ---------- + url : str + Source URL of video. + height : int + height of video. + width : int + width of video. + """ url = Field(text) height = Field(int) width = Field(int) class MessageEmbedAuthor(SlottedModel): + """ + Message embed author object. + + Attributes + ---------- + name : str + Name of author. + url : str + URL of author. + icon_url : str + URL of author icon. + icon_proxy_url : str + Proxied URL of the author icon. + """ name = Field(text) url = Field(text) icon_url = Field(text) @@ -84,6 +150,18 @@ class MessageEmbedAuthor(SlottedModel): class MessageEmbedField(SlottedModel): + """ + Message embed field object. + + Attributes + ---------- + name : str + Name of the field. + value : str + Value of the field. + inline : bool + Whether or not this field should display inline. + """ name = Field(text) value = Field(text) inline = Field(bool) @@ -103,6 +181,20 @@ class MessageEmbed(SlottedModel): Description of the embed. url : str URL of the embed. + timestamp : datetime + Timestamp of the embed content. + color : int + Color code of the embed. + footer : :class:`MessageEmbedFooter` + Footer information. + image : :class:`MessageEmbedImage` + Image information. + thumbnail : :class:`MessageEmbedThumbnail` + Thumbnail information. + video : :class:`MessageEmbedVideo` + Video information. + fields : list(:class:`MessageEmbedField`) + Fields information. """ title = Field(text) type = Field(str, default='rich') @@ -118,21 +210,39 @@ class MessageEmbed(SlottedModel): fields = ListField(MessageEmbedField) def set_footer(self, *args, **kwargs): + """ + Adds :class:`MessageEmbedFooter` to the embed. + """ self.footer = MessageEmbedFooter(*args, **kwargs) def set_image(self, *args, **kwargs): + """ + Adds :class:`MessageEmbedImage` to the embed. + """ self.image = MessageEmbedImage(*args, **kwargs) def set_thumbnail(self, *args, **kwargs): + """ + Adds :class:`MessageEmbedThumbnail` to the embed. + """ self.thumbnail = MessageEmbedThumbnail(*args, **kwargs) def set_video(self, *args, **kwargs): + """ + Adds :class:`MessageEmbedVideo` to the embed. + """ self.video = MessageEmbedVideo(*args, **kwargs) def set_author(self, *args, **kwargs): + """ + Adds :class:`MessageEmbedAuthor` to the embed. + """ self.author = MessageEmbedAuthor(*args, **kwargs) def add_field(self, *args, **kwargs): + """ + Appends :class:`MessageEmbedField` to the embed. + """ self.fields.append(MessageEmbedField(*args, **kwargs))