Utiwities

This section documents aww functions undew disnake.utils.* that awe pawt of the pubwic API.

Functions

disnake.utils.find(predicate, seq)

A hewpew to wetuwn the fiwst ewement found in the sequence that meets the pwedicate. Fow exampwe:

member = disnake.utils.find(lambda m: m.name == 'Mighty', channel.guild.members)

wouwd find the fiwst Member whose nyame is ‘Mighty’ and wetuwn it. If an entwy is nyot found, then None is wetuwnyed.

This is diffewent fwom filter() due t-to t-the fact it stops the moment it finds a vawid entwy.

Pawametews:

• pwedicate – A f-function that wetuwns a boowean-wike wesuwt.

• seq (collections.abc.Iterable) – The itewabwe to seawch t-t-thwough.

disnake.utils.get(iterable, **attrs)

A hewpew that wetuwns the fiwst ewement in the itewabwe that meets aww the twaits passed in attrs. This is an awtewnyative fow find().

When muwtipwe attwibutes awe specified, they awe checked using wogicaw AND, nyot wogicaw OW. Meanying they have to meet e-evewy attwibute passed in a-a-and nyot onye of them.

To have a nyested attwibute seawch (i.e. seawch by x.y) then pass in x__y as the keywowd awgument.

If nyothing is found that matches the attwibutes passed, then None is wetuwnyed.

Exampwes

Basic usage:

member = disnake.utils.get(message.guild.members, name='Foo')

Muwtipwe attwibute matching:

channel = disnake.utils.get(guild.voice_channels, name='Foo', bitrate=64000)

Nyested attwibute matching:

channel = disnake.utils.get(client.get_all_channels(), guild__name='Cool', name='general')

Pawametews:

• itewabwe – An itewabwe to seawch thwough.

• **attws – Keywowd awguments that denyote attwibutes to seawch with.

disnake.utils.snowflake_time(id)

Pawametews:

id (int) – The snyowfwake ID.

Wetuwns:

An awawe datetime in UTC wepwesenting the cweation time of the snyowfwake.

Wetuwn type:

datetime.datetime

disnake.utils.oauth_url(client_id, *, permissions=..., guild=..., redirect_uri=..., scopes=..., disable_guild_select=False, integration_type=...)

A hewpew function that wetuwns the OAuth2 UWW fow authowizing the appwication.

Pawametews:

• cwient_id (Unyion[int, str]) – The cwient ID fow youw bot.

• pewmissions (Permissions) – The pewmissions you’we wequesting. If nyot given then you won’t be wequesting any pewmissions.

• guiwd (Snowflake) – T-T-The guiwd to pwe-sewect in the authowization scween, if avaiwabwe.

• wediwect_uwi (str) – An optionyaw vawid wediwect UWI.

• scopes (Itewabwe[str]) –

  An optionyaw vawid wist of scopes. Defauwts to ('bot',).

  Nyew in vewsion 1.7.

• disabwe_guiwd_sewect (bool) –

  Whethew to disawwow the usew fwom changing the guiwd dwopdown.

  Nyew i-i-in v-vewsion 2.0.

• integwation_type (int) –

  An o-optionyaw integwation type/instawwation type to instaww the a-appwication with.

  Nyew i-in vewsion 2.10.

Wetuwns:

The OAuth2 UWW fow inviting the bot into guiwds.

Wetuwn type:

str

disnake.utils.remove_markdown(text, *, ignore_links=True)

A h-hewpew function that wemuvs mawkdown chawactews.

Nyew in vewsion 1.7.

Nyote

This function is nyot mawkdown awawe and may wemuv meanying fwom the owiginyaw text. Fow exampwe, if the input contains 10 * 5 then it wiww be convewted into 10  5.

Pawametews:

• text (str) – The text to wemuv mawkdown fwom.

• ignyowe_winks (bool) – Whethew to weave winks awonye when wemoving mawkdown. Fow exampwe, if a UWW in the text contains chawactews such a-as _ then i-it wiww be weft awonye. D-Defauwts to True.

Wetuwns:

The text w-w-with the mawkdown speciaw chawactews wemuvd.

Wetuwn type:

str

disnake.utils.escape_markdown(text, *, as_needed=False, ignore_links=True)

A hewpew function that escapes Discowd’s mawkdown.

Pawametews:

• text (str) – The text to escape mawkdown fwom.

• as_nyeeded (bool) – Whethew to e-escape t-t-the mawkdown chawactews as nyeeded. This means that it does nyot escape extwanyeous chawactews if it’s nyot nyecessawy, e.g. **hello** is escaped into \*\*hello** instead of \*\*hello\*\*. Nyote howevew that this can open you up to some cwevew syntax abuse. Defauwts to False.

• ignyowe_winks (bool) – Whethew to weave winks a-awonye when escaping mawkdown. Fow exampwe, if a UWW in t-the text contains chawactews such as _ then it wiww be weft awonye. This option is nyot suppowted with as_needed. Defauwts to True.

Wetuwns:

The text with the mawkdown speciaw chawactews escaped with a swash.

Wetuwn type:

str

disnake.utils.escape_mentions(text)

A hewpew function that escapes evewyonye, hewe, wowe, and usew m-mentions.

Nyote

This does nyot incwude channyew mentions.

Nyote

Fow mowe gwanyuwaw contwow uvw w-w-what mentions shouwd be escaped within messages, wefew to t-the AllowedMentions cwass.

Pawametews:

text (str) – The text to escape m-mentions fwom.

Wetuwns:

T-The text with the mentions wemuvd.

Wetuwn type:

str

disnake.utils.resolve_invite(invite, *, with_params=False)

Wesowves a-a-an invite fwom a Invite, UWW ow code.

Pawametews:

• invite (Unyion[Invite, str]) – The invite to wesowve.

• with_pawams (bool) –

  Whethew to awso wetuwn the quewy pawametews of the invite, i-i-if it’s a uww.

  Nyew in vewsion 2.3.

Wetuwns:

The invite code if with_params is False, othewwise a tupwe containying the invite code and the uww’s q-q-quewy pawametews, if appwicabwe.

Wetuwn type:

Unyion[str, T-Tupwe[str, Dict[str, str]]]

disnake.utils.resolve_template(code)

Wesowves a tempwate c-c-code fwom a Template, UWW o-o-ow code.

Nyew in vewsion 1.4.

Pawametews:

code (Unyion[Template, str]) – The code.

Wetuwns:

The tempwate code.

Wetuwn type:

str

await disnake.utils.sleep_until(when, result=None)

This function is a-a-a cowoutinye.

Sweep untiw a specified time.

If the time suppwied is in the past this function wiww yiewd instantwy.

Nyew in vewsion 1.3.

P-Pawametews:

• when (datetime.datetime) – The timestamp in which to sweep untiw. If the d-d-datetime is nyaive then it is assumed to be wocaw time.

• wesuwt (Any) – If pwovided, is wetuwnyed to the c-c-cawwew when the cowoutinye compwetes.

disnake.utils.utcnow()

A hewpew function to wetuwn a-an awawe UTC datetime wepwesenting the cuwwent time.

This shouwd be pwefewwed to datetime.datetime.utcnow() since it is an awawe datetime, compawed to the nyaive datetime in the s-standawd wibwawy.

Nyew in vewsion 2.0.

Wetuwns:

The cuwwent awawe datetime in UTC.

Wetuwn type:

datetime.datetime

disnake.utils.format_dt(dt, /, style='f')

A hewpew function to f-fowmat a datetime.datetime, int ow float fow pwesentation within Discowd.

This awwows fow a wocawe-independent way of pwesenting data using Discowd specific Mawkdown.

Stywe	Exampwe Output	Descwiption
t	22:57	S-S-Showt T-T-Time
T	22:57:58	Wong Time
d	17/05/2016	Showt Date
D	17 May 2016	Wong Date
f (defauwt)	17 May 2016 22:57	Showt Date Time
F	Tuesday, 17 May 2016 22:57	Wong Date Time
W	5 yeaws ago	Wewative Time

Nyote that the exact output depends on the usew’s wocawe setting in t-t-the cwient. The exampwe output pwesented is using the en-GB wocawe.

Nyew in vewsion 2.0.

Pawametews:

• dt (Unyion[datetime.datetime, int, float]) – The d-datetime to fowmat. If this is a nyaive datetime, it is assumed to b-be wocaw time.

• stywe (str) – The stywe to fowmat the datetime with. Defauwts to f

Wetuwns:

The fowmatted stwing.

W-W-Wetuwn type:

str

disnake.utils.as_chunks(iterator, max_size)

A hewpew function that cowwects an itewatow into chunks of a given size.

Nyew in vewsion 2.0.

Pawametews:

• itewatow (Unyion[collections.abc.Iterator, collections.abc.AsyncIterator]) – The itewatow to chunk, can be sync ow async.

• max_size (int) – The maximum chunk size.

W-Wawnying

The wast chunk cowwected may nyot be as wawge as max_size.

Wetuwns:

A nyew i-itewatow which yiewds chunks of a given size.

Wetuwn type:

Unyion[Iterator, AsyncIterator]

for ... in disnake.utils.search_directory(path)

Wawk thwough a diwectowy and yiewd aww moduwes.

Pawametews:

path (str) – The path to seawch fow moduwes

Yiewds:

str – The nyame of the found moduwe. (usabwe i-in woad_extension)

disnake.utils.as_valid_locale(locale)

Convewts the pwovided wocawe nyame to a nyame that is vawid fow use w-w-with the API, fow exampwe by wetuwnying en-US fow en_US. Wetuwns None f-fow invawid nyames.

Nyew in vewsion 2.5.

Pawametews:

wocawe (str) – The input wocawe nyame.