@ -22,22 +22,28 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE . DEALINGS IN THE SOFTWARE .
""" """
from __future__ import annotations
import io import io
from typing import Literal , TYPE_CHECKING import os
from typing import BinaryIO , Literal , TYPE_CHECKING , Tuple , Union
from . errors import DiscordException from . errors import DiscordException
from . errors import InvalidArgument from . errors import InvalidArgument
from . import utils from . import utils
import yarl
__all__ = ( __all__ = (
' Asset ' , ' Asset ' ,
) )
if TYPE_CHECKING : if TYPE_CHECKING :
ValidStaticFormatTypes = Literal [ ' webp ' , ' jpeg ' , ' jpg ' , ' png ' ] ValidStaticFormatTypes = Literal [ ' webp ' , ' jpeg ' , ' jpg ' , ' png ' ]
ValidAvatar FormatTypes = Literal [ ' webp ' , ' jpeg ' , ' jpg ' , ' png ' , ' gif ' ] ValidAsset FormatTypes = Literal [ ' webp ' , ' jpeg ' , ' jpg ' , ' png ' , ' gif ' ]
VALID_STATIC_FORMATS = frozenset ( { " jpeg " , " jpg " , " webp " , " png " } ) VALID_STATIC_FORMATS = frozenset ( { " jpeg " , " jpg " , " webp " , " png " } )
VALID_AVATAR_FORMATS = VALID_STATIC_FORMATS | { " gif " } VALID_ASSET_FORMATS = VALID_STATIC_FORMATS | { " gif " }
class Asset : class Asset :
""" Represents a CDN asset on Discord. """ Represents a CDN asset on Discord.
@ -52,10 +58,6 @@ class Asset:
Returns the length of the CDN asset ' s URL. Returns the length of the CDN asset ' s URL.
. . describe : : bool ( x )
Checks if the Asset has a URL .
. . describe : : x == y . . describe : : x == y
Checks if the asset is equal to another asset . Checks if the asset is equal to another asset .
@ -68,96 +70,88 @@ class Asset:
Returns the hash of the asset . Returns the hash of the asset .
""" """
__slots__ = ( ' _state ' , ' _url ' )
__slots__ : Tuple [ str , . . . ] = (
' _state ' ,
' _url ' ,
' _animated ' ,
' _key ' ,
)
BASE = ' https://cdn.discordapp.com ' BASE = ' https://cdn.discordapp.com '
def __init__ ( self , state , url = None ) : def __init__ ( self , state , * , url : str , key : str , animated : bool = Fals e) :
self . _state = state self . _state = state
self . _url = url self . _url = url
self . _animated = animated
self . _key = key
@classmethod @classmethod
def _from_avatar ( cls , state , user , * , format = None , static_format = ' webp ' , size = 1024 ) : def _from_default_avatar ( cls , state , index : int ) - > Asset :
if not utils . valid_icon_size ( size ) : return cls (
raise InvalidArgument ( " size must be a power of 2 between 16 and 4096 " ) state ,
if format is not None and format not in VALID_AVATAR_FORMATS : url = f ' { cls . BASE } /embed/avatars/ { index } .png ' ,
raise InvalidArgument ( f " format must be None or one of { VALID_AVATAR_FORMATS } " ) key = str ( index ) ,
if format == " gif " and not user . is_avatar_animated ( ) : animated = False ,
raise InvalidArgument ( " non animated avatars do not support gif format " ) )
if static_format not in VALID_STATIC_FORMATS :
raise InvalidArgument ( f " static_format must be one of { VALID_STATIC_FORMATS } " )
if user . avatar is None :
return user . default_avatar_url
if format is None :
format = ' gif ' if user . is_avatar_animated ( ) else static_format
return cls ( state , f ' /avatars/ { user . id } / { user . avatar } . { format } ?size= { size } ' )
@classmethod @classmethod
def _from_icon ( cls , state , object , path , * , format = ' webp ' , size = 1024 ) : def _from_avatar ( cls , state , user_id : int , avatar : str ) - > Asset :
if object . icon is None : animated = avatar . startswith ( ' a_ ' )
return cls ( state ) format = ' gif ' if animated else ' png '
return cls (
if not utils . valid_icon_size ( size ) : state ,
raise InvalidArgument ( " size must be a power of 2 between 16 and 4096 " ) url = f ' { cls . BASE } /avatars/ { user_id } / { avatar } . { format } ?size=1024 ' ,
if format not in VALID_STATIC_FORMATS : key = avatar ,
raise InvalidArgument ( f " format must be None or one of { VALID_STATIC_FORMATS } " ) animated = animated ,
)
url = f ' / { path } -icons/ { object . id } / { object . icon } . { format } ?size= { size } '
return cls ( state , url )
@classmethod @classmethod
def _from_cover_image ( cls , state , obj , * , format = ' webp ' , size = 1024 ) : def _from_icon ( cls , state , object_id : int , icon_hash : str , path : str ) - > Asset :
if obj . cover_image is None : return cls (
return cls ( state ) state ,
url = f ' { cls . BASE } / { path } -icons/ { object_id } / { icon_hash } .png?size=1024 ' ,
if not utils . valid_icon_size ( size ) : key = icon_hash ,
raise InvalidArgument ( " size must be a power of 2 between 16 and 4096 " ) animated = False ,
if format not in VALID_STATIC_FORMATS : )
raise InvalidArgument ( f " format must be None or one of { VALID_STATIC_FORMATS } " )
url = f ' /app-assets/ { obj . id } /store/ { obj . cover_image } . { format } ?size= { size } '
return cls ( state , url )
@classmethod @classmethod
def _from_guild_image ( cls , state , id , hash , key , * , format = ' webp ' , size = 1024 ) : def _from_cover_image ( cls , state , object_id : int , cover_image_hash : str ) - > Asset :
if not utils . valid_icon_size ( size ) : return cls (
raise InvalidArgument ( " size must be a power of 2 between 16 and 4096 " ) state ,
if format not in VALID_STATIC_FORMATS : url = f ' { cls . BASE } /app-assets/ { object_id } /store/ { cover_image_hash } .png?size=1024 ' ,
raise InvalidArgument ( f " format must be one of { VALID_STATIC_FORMATS } " ) key = cover_image_hash ,
animated = False ,
if hash is None : )
return cls ( state )
return cls ( state , f ' / { key } / { id } / { hash } . { format } ?size= { size } ' )
@classmethod @classmethod
def _from_guild_icon ( cls , state , guild , * , format = None , static_format = ' webp ' , size = 1024 ) : def _from_guild_image ( cls , state , guild_id : int , image : str , path : str ) - > Asset :
if not utils . valid_icon_size ( size ) : return cls (
raise InvalidArgument ( " size must be a power of 2 between 16 and 4096 " ) state ,
if format is not None and format not in VALID_AVATAR_FORMATS : url = f ' { cls . BASE } / { path } / { guild_id } / { image } .png?size=1024 ' ,
raise InvalidArgument ( f " format must be one of { VALID_AVATAR_FORMATS } " ) key = image ,
if format == " gif " and not guild . is_icon_animated ( ) : animated = False ,
raise InvalidArgument ( " non animated guild icons do not support gif format " ) )
if static_format not in VALID_STATIC_FORMATS :
raise InvalidArgument ( f " static_format must be one of { VALID_STATIC_FORMATS } " )
if guild . icon is None :
return cls ( state )
if format is None :
format = ' gif ' if guild . is_icon_animated ( ) else static_format
return cls ( state , f ' /icons/ { guild . id } / { guild . icon } . { format } ?size= { size } ' )
@classmethod @classmethod
def _from_sticker_url ( cls , state , sticker , * , size = 1024 ) : def _from_guild_icon ( cls , state , guild_id : int , icon_hash : str ) - > Asset :
if not utils . valid_icon_size ( size ) : animated = icon_hash . startswith ( ' a_ ' )
raise InvalidArgument ( " size must be a power of 2 between 16 and 4096 " ) format = ' gif ' if animated else ' png '
return cls (
state ,
url = f ' { cls . BASE } /icons/ { guild_id } / { icon_hash } . { format } ?size=1024 ' ,
key = icon_hash ,
animated = animated ,
)
return cls ( state , f ' /stickers/ { sticker . id } / { sticker . image } .png?size= { size } ' ) @classmethod
def _from_sticker ( cls , state , sticker_id : int , sticker_hash : str ) - > Asset :
return cls (
state ,
url = f ' { cls . BASE } /stickers/ { sticker_id } / { sticker_hash } .png?size=1024 ' ,
key = sticker_hash ,
animated = False ,
)
@classmethod @classmethod
def _from_emoji ( cls , state , emoji , * , format = None , static_format = ' png ' ) : def _from_emoji ( cls , state , emoji , * , format = None , static_format = ' png ' ) :
@ -172,46 +166,184 @@ class Asset:
return cls ( state , f ' /emojis/ { emoji . id } . { format } ' ) return cls ( state , f ' /emojis/ { emoji . id } . { format } ' )
def __str__ ( self ) : def __str__ ( self ) - > str :
return self . BASE + self . _url if self . _url is not None else ' ' return self . _url
def __len__ ( self ) :
if self . _url :
return len ( self . BASE + self . _url )
return 0
def __boo l__ ( self ) : def __len__ ( self ) - > int :
return self . _url is not None return len ( self . _url )
def __repr__ ( self ) : def __repr__ ( self ) :
return f ' <Asset url= { self . _url !r} > ' shorten = self . _url . replace ( self . BASE , ' ' )
return f ' <Asset url= { shorten !r} > '
def __eq__ ( self , other ) : def __eq__ ( self , other ) :
return isinstance ( other , Asset ) and self . _url == other . _url return isinstance ( other , Asset ) and self . _url == other . _url
def __ne__ ( self , other ) :
return not self . __eq__ ( other )
def __hash__ ( self ) : def __hash__ ( self ) :
return hash ( self . _url ) return hash ( self . _url )
async def read ( self ) : @property
""" |coro| def url ( self ) - > str :
""" :class:`str`: Returns the underlying URL of the asset. """
return self . _url
Retrieves the content of this asset as a : class : ` bytes ` object . @property
def key ( self ) - > str :
""" :class:`str`: Returns the identifying key of the asset. """
return self . _key
. . warning : : def is_animated ( self ) - > bool :
""" :class:`bool`: Returns whether the asset is animated. """
return self . _animated
: class : ` PartialEmoji ` won ' t have a connection state if user created, def replace (
and a URL won ' t be present if a custom image isn ' t associated with self ,
the asset , e . g . a guild with no custom icon . size : int = . . . ,
format : ValidAssetFormatTypes = . . . ,
static_format : ValidStaticFormatTypes = . . . ,
) - > Asset :
""" Returns a new asset with the passed components replaced.
Parameters
- - - - - - - - - - -
size : : class : ` int `
The new size of the asset .
format : : class : ` str `
The new format to change it to . Must be either
' webp ' , ' jpeg ' , ' jpg ' , ' png ' , or ' gif ' if it ' s animated.
static_format : : class : ` str `
The new format to change it to if the asset isn ' t animated.
Must be either ' webp ' , ' jpeg ' , ' jpg ' , or ' png ' .
Raises
- - - - - - -
InvalidArgument
An invalid size or format was passed .
Returns
- - - - - - - -
: class : ` Asset `
The newly updated asset .
"""
url = yarl . URL ( self . _url )
path , _ = os . path . splitext ( url . path )
if format is not . . . :
if self . _animated :
if format not in VALID_ASSET_FORMATS :
raise InvalidArgument ( f ' format must be one of { VALID_ASSET_FORMATS } ' )
else :
if format not in VALID_STATIC_FORMATS :
raise InvalidArgument ( f ' format must be one of { VALID_STATIC_FORMATS } ' )
url = url . with_path ( f ' { path } . { format } ' )
if static_format is not . . . and not self . _animated :
if static_format not in VALID_STATIC_FORMATS :
raise InvalidArgument ( f ' static_format must be one of { VALID_STATIC_FORMATS } ' )
url = url . with_path ( f ' { path } . { static_format } ' )
if size is not . . . :
if not utils . valid_icon_size ( size ) :
raise InvalidArgument ( ' size must be a power of 2 between 16 and 4096 ' )
url = url . with_query ( size = size )
else :
url = url . with_query ( url . raw_query_string )
url = str ( url )
return Asset ( state = self . _state , url = url , key = self . _key , animated = self . _animated )
def with_size ( self , size : int ) - > Asset :
""" Returns a new asset with the specified size.
Parameters
- - - - - - - - - - - -
size : : class : ` int `
The new size of the asset .
Raises
- - - - - - -
InvalidArgument
The asset had an invalid size .
Returns
- - - - - - - -
: class : ` Asset `
The new updated asset .
"""
if not utils . valid_icon_size ( size ) :
raise InvalidArgument ( ' size must be a power of 2 between 16 and 4096 ' )
url = str ( yarl . URL ( self . _url ) . with_query ( size = size ) )
return Asset ( state = self . _state , url = url , key = self . _key , animated = self . _animated )
def with_format ( self , format : ValidAssetFormatTypes ) - > Asset :
""" Returns a new asset with the specified format.
Parameters
- - - - - - - - - - - -
format : : class : ` str `
The new format of the asset .
Raises
- - - - - - -
InvalidArgument
The asset had an invalid format .
Returns
- - - - - - - -
: class : ` Asset `
The new updated asset .
"""
if self . _animated :
if format not in VALID_ASSET_FORMATS :
raise InvalidArgument ( f ' format must be one of { VALID_ASSET_FORMATS } ' )
else :
if format not in VALID_STATIC_FORMATS :
raise InvalidArgument ( f ' format must be one of { VALID_STATIC_FORMATS } ' )
url = yarl . URL ( self . _url )
path , _ = os . path . splitext ( url . path )
url = str ( url . with_path ( f ' { path } . { format } ' ) . with_query ( url . raw_query_string ) )
return Asset ( state = self . _state , url = url , key = self . _key , animated = self . _animated )
def with_static_format ( self , format : ValidStaticFormatTypes ) - > Asset :
""" Returns a new asset with the specified static format.
This only changes the format if the underlying asset is
not animated . Otherwise , the asset is not changed .
Parameters
- - - - - - - - - - - -
format : : class : ` str `
The new static format of the asset .
Raises
- - - - - - -
InvalidArgument
The asset had an invalid format .
Returns
- - - - - - - -
: class : ` Asset `
The new updated asset .
"""
if self . _animated :
return self
return self . with_format ( format )
async def read ( self ) - > bytes :
""" |coro|
Retrieves the content of this asset as a : class : ` bytes ` object .
. . versionadded : : 1.1 . . versionadded : : 1.1
Raises Raises
- - - - - - - - - - - -
DiscordException DiscordException
There was no valid URL or internal connection state . There was no internal connection state .
HTTPException HTTPException
Downloading the asset failed . Downloading the asset failed .
NotFound NotFound
@ -222,15 +354,12 @@ class Asset:
: class : ` bytes ` : class : ` bytes `
The content of the asset . The content of the asset .
""" """
if not self . _url :
raise DiscordException ( ' Invalid asset (no URL provided) ' )
if self . _state is None : if self . _state is None :
raise DiscordException ( ' Invalid state (no ConnectionState provided) ' ) raise DiscordException ( ' Invalid state (no ConnectionState provided) ' )
return await self . _state . http . get_from_cdn ( self . BASE + self . _url ) return await self . _state . http . get_from_cdn ( self . BASE + self . _url )
async def save ( self , fp , * , seek_begin = True ) : async def save ( self , fp : Union [ str , bytes , os . PathLike , BinaryIO ] , * , seek_begin : bool = True ) - > int :
""" |coro| """ |coro|
Saves this asset into a file - like object . Saves this asset into a file - like object .
@ -245,7 +374,7 @@ class Asset:
Raises Raises
- - - - - - - - - - - -
DiscordException DiscordException
There was no valid URL or internal connection state . There was no internal connection state .
HTTPException HTTPException
Downloading the asset failed . Downloading the asset failed .
NotFound NotFound
Rapptz
4 years ago