Discord.py: differenze tra le versioni

Versione delle 17:11, 11 mag 2021

Versione attuale delle 14:33, 28 feb 2025

(36 versioni intermedie di 13 utenti non mostrate)

Riga 1:

'''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]].

{{WIP|FLAK-ZOSO}}

{{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:

* leggere e inviare messaggi

* allegare file ad essi messaggi

* scrivere in privato agli utenti

* bannare, espellere e moderare gli utenti

* eliminare messaggi e canali

* creare guilds<ref>Funzione disponibile solo se il bot è in meno di 10 guild.</ref>

* collegarsi a canali vocali e riprodurre audio

Non 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>{{Cita web|url=https://discordpy.readthedocs.io/en/stable/api.html#discord.Guild.owner|titolo=discord.Guild.owner — API Reference|sito=discordpy.readthedocs.io|lingua=EN|accesso=2023-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.

=== Esempi di codice ===

Questo codice crea un semplice bot che quando si esegue il comando '!ciao', lui risponde.

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">

# Questo esempio necessita avere l'intento 'message_content' abilitato.

import discord

class MyClient(discord.Client):

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):

"""Evento chiamato quando il cliente riceve un messaggio."""

# non vogliamo che il bot risponda a se stesso.

* Leggere i messaggi

if message.author == self.user:

* Inviare messaggi

return

* 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>

* 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>)

* Scrivere in privato agli utenti

# Se il messaggio inizia con '!ciao', noi rispondiamo.

Non potrà 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.

if message.content.startswith('!ciao'):

await message.reply('Ciao da Wikipedia!', mention_author=True)

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://github.com/Rapptz/discord.py/issues/302|titolo=Server vs Guild|sito=GitHub|data=15 Agosto 2016|accesso=11 Maggio 2021}}</ref>) potrebbe subire limitazioni nei permessi per:

# Intenti di base, più l'intento necessario per leggere il contenuto dei messaggi.

* Scrivere in privato agli utenti

intents = discord.Intents.default()

* Menzionare gli utenti

intents.message_content = True

* 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

# Attività: messaggio mostrato sotto il nome del bot.

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.

activity = discord.CustomActivity(name="Ciao da Wikipedia!")

client = MyClient(intents=intents, activity=activity)

In caso di mancata autorizzazione, il [[compilatore]] restituirà l'errore seguente:<syntaxhighlight lang="python3">

client.run('token del bot')

discord.ext.command.errors.MissingPermission

</syntaxhighlight>''Questo esempio è una copia modificata e tradotta dell'esempio ufficiale [https://github.com/Rapptz/discord.py/blob/master/examples/reply.py reply.py]''

</syntaxhighlight>

=== ApplicazioniNote ===

<references />

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:

== Collegamenti esterni ==

* Ban/Kick a tempo determinato

* [https://discordpy.readthedocs.io/en/latest/api.html La documentazione ufficiale della libreria]

<syntaxhighlight lang="python3">

* [https://pypi.org/project/discord.py/ Istruzioni di installazione del modulo]

async def ban_temporaneo(member, tempo):

* [https://stackoverflow.com/questions/tagged/discord.py Hashtag Discord.py su Stack Overflow]

await member.ban()

* [https://github.com/Kapz/Wikipedia-Bot Esempio di Bot-Wikipediano su Github]

await asyncio.sleep(tempo)

* [https://github.com/FLAK-ZOSO/Discord.py Esempi di alcuni Bot su Github]

await member.unban()

</syntaxhighlight>

{{Portale|informatica|software libero}}

* Stato del Bot a tempo determinato

[[Categoria:Librerie Python]]

=== Esempio di codice ===

{{Sezione vuota|informatica}}