|
'''Discord.py''' è una [[Libreria (software)|libreria]] [[open source]]<ref>{{Cita web|url=https://awesomeopensource.com/projects/discord-py|titolo=Discord.py|sito=awesomeopensource.com|lingua=EN|accesso=11 Maggio 2021}}</ref> per il linguaggio di programmazione [[Python]], che permette di sviluppare [[Bot (informatica)|Bot]] per il [[social media]] [[Discord (software)|Discord]].
{{O|software|maggio 2021}}
{{tmp|Software}}
|Nome = discord.py
|Sviluppatore = Rapptz
|UltimaVersione = 2.4.0
|SistemaOperativo = multipiattaforma
|Linguaggio = Python
|Genere = python
|Licenza = [[Licenza MIT|MIT]]
|Lingua = [[lingua inglese|inglese]]
|SoftwareLibero = sì
|SitoWeb = https://discordpy.rtfd.org/en/latest
}}
== Storia ==
'''Discord.py''' è una [[Libreria (software)|libreria]] [[open source]]<ref>{{Cita web|url=https://awesomeopensource.com/projects/discord-py|titolo=Discord.py|sito=awesomeopensource.com|accesso=11 Maggio 2021}}</ref> per il linguaggio di programmazione [[Python]], che permette di sviluppare [[Bot (informatica)|Bot]] per il social media [[Discord (software)|Discord]].
La libreria discord.py è stata sviluppata da Rapptz come modulo Python per sviluppare Bot per la piattaforma [[VoIP]] [[Discord (software)|Discord]].
La prima versione della libreria è stata rilasciata il 23 agosto 2015<ref>{{Cita web|url=https://github.com/Rapptz/discord.py/releases/tag/v0.1.0|titolo=Release v0.1.0 · Rapptz/discord.py|sito=GitHub|lingua=en|accesso=2021-05-12}}</ref>, compatibile con versioni di Python 2.7+ e 3.3+. La versione 0.10.0 è stata rilasciata il 28 giugno 2016<ref>{{Cita web|url=https://github.com/Rapptz/discord.py/releases/tag/v0.10.0|titolo=Release v0.10.0 · Rapptz/discord.py|sito=GitHub|lingua=en|accesso=2021-05-12}}</ref> è stata la prima versione totalmente compatibile col modulo ''asyncio'', che permette di scrivere codice Python usando la [[sintassi]] async/await<ref>{{Cita web|url=https://docs.python.org/3/library/asyncio.html|titolo=asyncio — Asynchronous I/O — Python 3.9.5 documentation|sito=docs.python.org|lingua=EN|accesso=2021-05-12}}</ref>.
Il 9 aprile 2019 è stata rilasciata la versione v1.0.0<ref>{{Cita web|url=https://github.com/Rapptz/discord.py/releases/tag/v1.0.0|titolo=Release v1.0.0 · Rapptz/discord.py|sito=GitHub|lingua=en|accesso=2021-05-12}}</ref>, frutto di una completa ristrutturazione<ref>{{Cita web|url=https://discordpy.readthedocs.io/en/stable/migrating.html#migrating-1-0|titolo=Migrating to v1.0|sito=discordpy.readthedocs.io|lingua=EN|accesso=2021-05-12}}</ref> e con molteplici cambiamenti non retrocompatibili; inoltre, è stato abbandonato il supporto per Python 3.4 e precedenti.
I creatori hanno annunciato la fine dello sviluppo della libreria<ref name=":1">{{Cita web|url=https://gist.github.com/Rapptz/4a2f62751b9600a31a0d3c78100287f1|titolo=The future of Discord.py|autore=Rapptz|sito=Github|data=28 Agosto 2021|lingua=EN|accesso=21 Ottobre 2021}}</ref> a fine Agosto 2021<ref name=":1" />, per poi riprendere lo sviluppo<ref>{{Cita web|url=https://gist.github.com/Rapptz/c4324f17a80c94776832430007ad40e6|titolo=On Resuming discord.py Development|autore=Rapptz|sito=GitHub Gists|lingua=en|accesso=2022-03-26}}</ref> nei primi giorni di Marzo 2022.
Il 18 agosto 2022 è stata rilasciata la version v2.0.0<ref>{{Cita web|url=https://github.com/Rapptz/discord.py/releases/tag/v2.0.0|titolo=Release v2.0.0 · Rapptz/discord.py|sito=GitHub|lingua=en|accesso=2023-10-26}}</ref>, che portò molti cambiamenti non retrocompatibili<ref>{{Cita web|url=https://discordpy.readthedocs.io/en/stable/whats_new.html#v2-0-0|titolo=Changelog — v2.0.0|sito=discordpy.readthedocs.io|lingua=EN|accesso=2023-10-26}}</ref>, i più notevoli sono una completa revisione di molte componenti async<ref>{{Cita web|url=https://discordpy.readthedocs.io/en/stable/migrating.html#asyncio-event-loop-changes|titolo=asyncio Event Loop Changes|sito=discordpy.readthedocs.io|accesso=2023-10-26}}</ref>, e la rimozione del supporto per gli account utente<ref>{{Cita web|url=https://discordpy.readthedocs.io/en/stable/migrating.html#removal-of-support-for-user-accounts|titolo=Removal of Support For User Accounts|sito=discordpy.readthedocs.io|accesso=2023-10-26}}</ref>, consentendo fare [[login]] solo con gli account bot, in conformità con le modifiche ai termini di servizio di Discord<ref>{{Cita web|url=https://support.discord.com/hc/en-us/articles/115002192352-Automated-user-accounts-self-bots|titolo=Automated user accounts (self-bots)|lingua=EN}}</ref>; inoltre, è stato abbandonato il supporto per Python 3.7 e precedenti.
La versione più recente è la 2.4.0<ref name=":0">{{Cita web|url=https://discordpy.readthedocs.io/en/stable/whats_new.html|titolo=Versioni di Discord.py|sito=discordpy.readthedocs.io|lingua=EN}}</ref>.
== Utilizzo ==
Dopo aver importato il modulo discord.py in un programma, è possibile utilizzare i suoi metodi per creare il codice di un Bot, il quale a tutti gli effetti può agire su Discord come un utente umano, ma avendo anche certe funzioni extra come i comandi applicazione<ref>{{Cita web|url=https://discord.com/developers/docs/interactions/application-commands|titolo=Application Commands|sito=Discord Developer Portal|lingua=EN|accesso=2023-10-26}}</ref> e le componenti di messaggio<ref>{{Cita web|url=https://discord.com/developers/docs/interactions/message-components|titolo=Message Components|sito=Discord Developer Portal|lingua=EN|accesso=2023-10-26}}</ref>.
Con l'importazione del modulo all'interno di un programma, è possibile dare vita a un Bot il quale, attraverso le funzioni e le variabili della libreria, potrà comportarsi su Discord esattamente come un utente umano.
=== Funzioni ===
Il Bot potrà quindipuò eseguire, così come un normale utente, le seguenti operazioni:
* Leggereleggere ie inviare messaggi
* Inviareallegare file ad essi messaggi
* scrivere in privato agli utenti
* Allegare file<ref>Che devono però essere presenti nella stessa cartella del programma, e che vanno quindi consegnati nel caso ci si avvalga di un [[Hosting|servizio di hosting]].</ref>
* bannare, espellere e moderare gli utenti
* Accedere alla lista degli utenti. (Lista che dopo l'ultimo aggiornamento [https://stackoverflow.com/questions/64518536/discord-py-ctx-guild-members-only-returns-bot ha causato problemi], in quanto necessita di abilitare da Discord Developer Portal<ref>{{Cita web|url=https://python.tutorialink.com/how-to-get-all-members-of-a-guild-in-discord-py/|titolo=discord.guild.members|sito=Python.tutoriallink.com}}</ref> una funzione privilegiata<ref>{{Cita web|url=https://discordpy.readthedocs.io/en/latest/intents.html|titolo=discord.Intents|sito=https://discordpy.readthedocs.io/|accesso=11 Maggio 2021}}</ref>)
* eliminare messaggi e canali
* Scrivere in privato agli utenti
* creare guilds<ref>Funzione disponibile solo se il bot è in meno di 10 guild.</ref>
* collegarsi a canali vocali e riprodurre audio
Non potràpuò naturalmente leggere i messaggi di canali<ref>Si veda [[Discord]], alla definizione di canale, sottodivisione del "server".</ref> che per questioni di autorizzazione<ref>Si veda [[Discord]], nella sezione riguardante la gerarchia dei ruoli, e i vari permessi.</ref> non possa vedere. Non può neanche leggere il contenuto dei messaggi se gli appositi intenti non sono attivati<ref>{{Cita web|url=https://discordpy.readthedocs.io/en/stable/intents.html#message-content|titolo=A Primer to Gateway Intents|sito=discordpy.readthedocs.io|lingua=EN|accesso=2023-10-26}}</ref>.
Allo stesso modo, per mancanza di autorizzazione da parte del proprietario<ref>Dalla stessa libreria '''Discord.py''' definito ''(discord.guild.)owner.user''</ref> del server (che i programmatori usano chiamare Guild<ref>{{Cita web|url=https://githubdiscordpy.comreadthedocs.io/Rapptzen/stable/api.html#discord.py/issues/302Guild.owner|titolo=Serverdiscord.Guild.owner vs— GuildAPI Reference|sito=GitHubdiscordpy.readthedocs.io|datalingua=15 Agosto 2016EN|accesso=11 Maggio 20212023-10-26}}</ref>) o dagli amministratori del guild, il bot potrebbe subire limitazioni nei permessi per eseguire diverse azioni, esse elencate nella [https://discordpy.readthedocs.io/en/stable/api.html#discord.Permissions documentazione dei permessi].
Le autorizzazioni dei singoli Bot sono gestite da [[discord:developers/applications|Discord Developer Portal]], che genera link di invito al guild per i Bot a seconda dei permessi selezionati. In caso di mancata autorizzazione, l'[[Interprete (informatica)|interprete]] restituisce un errore. I permessi per ogni particolare guild possono essere sempre modificati dagli amministratori del guild.
* Scrivere in privato agli utenti
* Menzionare gli utenti
* Espellere gli utenti<ref>Esiste il comando apposito<syntaxhighlight lang="python3">
member.kick()
</syntaxhighlight>Con il [[Parametro (programmazione)|parametro]] [[None (informatica)|opzionale]] ''reason''</ref>
* Bannare gli utenti<ref>Esiste il comando apposito<syntaxhighlight lang="python3">
member.ban()
</syntaxhighlight>Con il [[Parametro (programmazione)|parametro]] [[None (informatica)|opzionale]] ''reason''</ref>
* Modificare il nickname degli altri utenti
=== Esempi di codice ===
Le autorizzazioni dei singoli Bot sono gestite da Discord Developer Portal, che genera link di invito al server per i Bot a seconda dei permessi che il ruolo personalizzato richiede.
Questo codice crea un semplice bot che quando si esegue il comando '!ciao', lui risponde.
In caso di mancata autorizzazione, il [[compilatore]] restituirà l'errore seguente:<syntaxhighlight lang="python3">
discord.ext.command.errors.MissingPermission
</syntaxhighlight>
Per fare bot più complessi, è suggerito usare la libreria ''discord.ext.commands''<ref>{{Cita web|url=https://discordpy.readthedocs.io/en/stable/ext/commands/index.html|titolo=discord.ext.commands – Bot commands framework|sito=discordpy.readthedocs.io|lingua=EN|accesso=2023-10-26}}</ref>, compresa in ogni installazione di discord.py. Esempi più avanzati si possono trovare [https://github.com/Rapptz/discord.py/tree/master/examples sul sito GitHub della libreria].<syntaxhighlight lang="python3" line="1">
=== Applicazioni ===
# Questo esempio necessita avere l'intento 'message_content' abilitato.
A partire dalle funzioni di base, utilizzando altri moduli tra i quali [[asyncio.py]] e [[time.py]]<ref>L'equivalente di <locale> (lettura "local-e") in [[C++]], importa una serie di variabili a seconda del luogo nel quale ci si trova, tra le quali il fuso orario e i caratteri UTF-8 della lingua locale.</ref>, si possono creare applicazioni utili, tra le quali:
import discord
* Ban/Kick a tempo determinato
<syntaxhighlight lang="python3">
async def ban_temporaneo(member, tempo):
await member.ban()
await asyncio.sleep(tempo)
await member.unban()
</syntaxhighlight>
* Stato del Bot a tempo determinato
<syntaxhighlight lang="python3">
async def Cambia_stato(ctx, tempo, nuovo_stato):
nuovo_stato = discord.Game(str(nuovo_stato))
await Bot.change_presence(status = discord.Status.idle, activity = nuovo_stato)
tempo = float(tempo)
from asyncio import sleep
await sleep(tempo)
await Bot.change_presence(status = discord.Status.idle, activity = gioco)
</syntaxhighlight>
class MyClient(discord.Client):
== Esempi di codice ==
async def on_ready(self):
"""Funzione chiamata dalla libreria quando il cache
interno del cliente è completamente popolato."""
print(f'Autenticato come {self.user} (ID: {self.user.id})')
print(f'Sono in {len(self.guilds)} server, e vedo {len(bot.users)} utenti.')
print('------')
async def on_message(self, message):
Il codice seguente è lo stretto necessario per un programma che semplicemente porti il Bot online.<syntaxhighlight lang="python3">
"""Evento chiamato quando il cliente riceve un messaggio."""
import discord #L'alternativa è di importare discord.client, discord.ban, discord.kick, discord.events e così via
import discord.ext.commands.errors
from discord.ext import commands
from discord import client
# non vogliamo che il bot risponda a se stesso.
token = "<inserisci-qui-il-token-del-bot>" #I token dei Bot vengono presi da Discord Developer Portal, e vengono immediatamente rinnovati se trovati online dal sistema di Discord
if message.author == self.user:
Bot = commands.Bot(command_prefix = "£", description = "<inserisci-qui-la-descrizione-del-bot>")
return
gioco = discord.Game("£Aiuto | Bot | @Bot#1127")
# Se il messaggio inizia con '!ciao', noi rispondiamo.
Bot.run(token)
if message.content.startswith('!ciao'):
</syntaxhighlight>Il codice di cui sotto contiene un piccolo evento aggiunto, che stampa a schermata ''<code>Bot#1127 è ora online ID: 12345678</code>''<syntaxhighlight lang="python3">
await message.reply('Ciao da Wikipedia!', mention_author=True)
@Bot.event
async def on_ready():
print(Bot.user, " è ora online ", "ID: ", Bot.user.id)
await Bot.change_presence(status = discord.Status.idle, activity = gioco)
</syntaxhighlight>
=== Bot.help ===
Ogni Bot possiede di default un suo comando per inviare l'elenco delle funzioni che può svolgere, che può essere però rimosso se se ne volesse implementare uno simile e che si giudichi maggiormente funzionale<ref>{{Cita web|url=https://stackoverflow.com/questions/45951224/how-to-remove-default-help-command-or-change-the-format-of-it-in-discord-py|titolo=Bot.remove_command(help)|sito=stackoverflow.com|data=11 Maggio 2021}}</ref>.<syntaxhighlight lang="python3">
Bot.remove_command('help')
</syntaxhighlight>Sono esempi di comandi di aiuto migliorati rispetto a quello di default ad esempio quello di [https://lawlietbot.xyz/ Lawliet], basato sulle reazioni<ref>[[Emoji]] che si possono attaccare al di sotto di un messaggio, e che tramite '''Discord.py''' possono essere percepite dal Bot con:<syntaxhighlight lang="python3">
@Bot.event
async def on_reaction():
</syntaxhighlight></ref>, o quello di [https://unbelievaboat.com/ Unbelievaboat], che ha sostanziali modifiche nella grafica.
# Intenti di base, più l'intento necessario per leggere il contenuto dei messaggi.
=== Anti-spam ===
intents = discord.Intents.default()
I Bot possono essere usati per limitare la spam, come nell'esempio che segue:<syntaxhighlight lang="python3" line="1">
intents.message_content = True
@Bot.event
async def on_message(messaggio):
global messaggi
author = messaggio.author
if author != Bot.user:
messaggi.append(messaggio.content)
for i in messaggi:
if i == messaggio.content:
if len(messaggi) > 2:
lunghezza = len(messaggi)
if messaggi[lunghezza-1] == messaggi[lunghezza-2] == messaggi[lunghezza-3]:
if messaggi[lunghezza-1] == messaggi[lunghezza-2] == messaggi[lunghezza-3] == messaggi[lunghezza-4]:
if messaggi[lunghezza-1] == messaggi[lunghezza-2] == messaggi[lunghezza-3] == messaggi[lunghezza-4] == messaggi[lunghezza-5]:
try:
await author.kick(reason = 'spam')
print(f"{author} stava spammando un messaggio in {messaggio.channel}, quindi l'ho espulso.")
await messaggio.reply(f"{author.mention} stava spammando questo messaggio, quindi l'ho espulso.")
print(messaggi)
messaggi = []
return
except discord.errors.Forbidden:
await messaggio.reply(f"{author.mention} stava spammando questo messaggio, quindi ho provato ad espellerlo. Purtroppo non ho l'autorizzazione necessaria per farlo.")
print(messaggi)
messaggi = []
return
else:
await messaggio.reply(f'{author.mention}, questo è il tuo ultimo avvertimento!')
return
else:
await messaggio.reply(f'{author.mention}, smettila di scrivere lo stesso messaggio. Se lo farai altre due volte sarai espulso dal server!')
return messaggi
else:
return messaggi
else:
return
</syntaxhighlight>Sono inseriti (ad esempio a riga 21) degli <code>except</code> riguardanti degli errori diversi da quelli built-in<ref>Come <code>TypeError</code> e <code>ValueError</code></ref>, che richiedono l'importazione di <code>discord.exe.errors</code>, o (nel caso specifico) soltanto di <code>discord.py</code>.
# Attività: messaggio mostrato sotto il nome del bot.
== Collegamenti esterni ==
activity = discord.CustomActivity(name="Ciao da Wikipedia!")
client = MyClient(intents=intents, activity=activity)
=== Esempi ===
client.run('token del bot')
</syntaxhighlight>''Questo esempio è una copia modificata e tradotta dell'esempio ufficiale [https://github.com/Rapptz/discord.py/blob/master/examples/reply.py reply.py]''
== Note ==
* [https://github.com/FLAK-ZOSO/Wikipedia-Bot/blob/master/bot.py Esempio di Bot-Wikipediano su Github]
<references />
* [https://github.com/FLAK-ZOSO/Discord.py/blob/main/BOT%20Lillo%2C%20parte%20di%20on_message%2C%20censura.py Esempio di Bot-censura su Github]
* [https://github.com/FLAK-ZOSO/Discord.py/blob/main/BOT%20Lillo%2C%20parte%20di%20on_message%2C%20spam.py Esempio di Bot-anti-spam su Github]
* [https://github.com/FLAK-ZOSO/Discord.py/blob/main/BOT%20Lillo.py Esempio di codice principale di un Bot, contenente i comandi]
=== Documentazione ===
== Collegamenti esterni ==
* [https://discordpy.readthedocs.io/en/latest/api.html La documentazione ufficiale della libreria]
* [https://pypi.org/project/discord.py/ Istruzioni di installazione del modulo]<ref>Per installare il modulo è sufficiente digitare nel prompt dei comandi <code>pip install discord.py</code> ovviamente dopo aver installato pip e Python.</ref>
* [https://stackoverflow.com/questions/tagged/discord.py Hashtag Discord.py su Stack Overflow]
* [https://github.com/Kapz/Wikipedia-Bot Esempio di Bot-Wikipediano su Github]
* [https://github.com/FLAK-ZOSO/Discord.py Esempi di alcuni Bot su Github]
{{Portale|informatica|software libero}}
== Note ==
<references />
{{Portale|Informatica}}
[[Categoria:Librerie Python]]
| 