lgrez.blocs (Blocs transversaux)

lg-rez / Blocs transversaux

Chaque module de lgrez.blocs réalise une tâche non liée à une fonctionnalité spécifique du bot : connection à un service, outils divers…

.env

lg-rez / blocs / Lecture des variables d’environnement

lgrez.blocs.env.load(VAR_NAME)[source]

Lit une valeur depuis les variables d’environnement.

Les variables sont recherchées dans les variables d’environnement ; à l’import de ce module, celles-ci sont chargées par dotenv.load_dotenv à partir du fichier passé en premier argument en ligne de commande (.env par défaut).

Équivaut globalement à os.getenv() suivi d’une vérification que la variable existe.

Paramètres

VAR_NAME (str) – nom de la variable à charger (LGREZ_...)

Renvoie

str

Lève

RuntimeError – la variable d’environnement n’est pas définie

lgrez.blocs.env.__getattr__(attr)[source]

Raccourci pour accéder aux variables d’environnement.

Permet d’utiliser blocs.env.VAR_NAME comme raccourci pour blocs.env.load(VAR_NAME), à la différence près que c’est une exception AttributeError qui sera levée si la variable n’est pas définie.

.gsheets

lg-rez / blocs / Interfaçage Google Sheets

Connection, récupération de classeurs, modifications (implémentation de https://pypi.org/project/gspread)

exception lgrez.blocs.gsheets.WorksheetNotFound[source]

Alias de gspread.exceptions.WorksheetNotFound : erreur levée en cas de tentative d’appel d’une feuille non existante.

class lgrez.blocs.gsheets.Modif(row, column, val)[source]

Modification à appliquer à un Google Sheet.

row

Numéro de la ligne (0 = ligne 1)

Type

int

column

Numéro de la colonne (0 = colonne A)

Type

int

val

Nouvelle valeur

Type

Any

async lgrez.blocs.gsheets.connect(key)[source]

Charge les credentials GSheets et renvoie le classeur demandé.

Nécessite la variable d’environment LGREZ_GCP_CREDENTIALS.

Paramètres

key (str) – ID du classeur à charger (25 caractères)

Renvoie

gspread_asyncio.AsyncioGspreadWorksheet

async lgrez.blocs.gsheets.update(sheet, *modifs)[source]

Met à jour une feuille GSheets avec les modifications demandées.

Paramètres

Le type de la nouvelle valeur sera interpreté par gspread pour donner le type GSheets adéquat à la cellule (texte, numérique, temporel…)

Les entiers trop grands pour être stockés sans perte de précision (IDs des joueurs par exemple) sont convertis en str. Les None sont convertis en ''. Les membres d”Enum sont stockés par leur nom.

lgrez.blocs.gsheets.a_to_index(column)[source]

Utilitaire : convertit une colonne (« A », « B »…) en indice.

Paramètres

column (str) – nom de la colonne. Doit être composé de caractères dans [a-z, A-Z] uniquement.

Renvoie

L’indice de la colonne, indexé à partir de 0 (cellules

considérées comme une liste de liste).

Type renvoyé

int

Lève

gspread.exceptions.IncorrectCellLabel – valeur incorrecte.

lgrez.blocs.gsheets.get_doc_content(doc_id)[source]

Récupère le contenu d’un document Google Docs.

Transforme le document pour ne garder que les fragments de texte et leur mise en forme. Les paragraphes de listes à points sont transformés en ajoutant un fragment `` - `` à l’endroit adéquat ; les autres options de mise en forme des paragraphes et les autres objets GDocs sont ignorés.

Paramètres

doc_id (str) – ID du document à récupérer (doit être public ou dans le Drive partagé avec le compte de service).

Renvoie

Les différents fragments de texte du document et leur formattage (référence : https://developers. google.com/docs/api/reference/rest/v1/documents#TextStyle)

Type renvoyé

list[tuple(str, dict)]

Lève

googleapiclient.errors.HttpError – ID incorrect ou document non accessible.

lgrez.blocs.gsheets.get_files_in_folder(folder_id: str) list[dict[str, str]][source]

Récupère le contenu binaire d’un fichier Google Drive.

Paramètres

folder_id – ID du fichier à récupérer (doit être public ou dans le Drive partagé avec le compte de service).

Renvoie

A list of, for each file, a directory with "file_id", name (with extension) and extension (without dot) data.

Lève
  • googleapiclient.errors.HttpError – ID incorrect ou dossier non accessible.

  • RuntimeError – Autre erreur.

lgrez.blocs.gsheets.download_file(file_id: str) bytes[source]

Récupère le contenu binaire d’un fichier Google Drive.

Paramètres

file_id – ID du fichier à récupérer (doit être public ou dans le Drive partagé avec le compte de service).

Renvoie

Le contenu binaire du fichier.

Lève
  • googleapiclient.errors.HttpError – ID incorrect ou document non accessible.

  • RuntimeError – Autre erreur.

.one_command

lg-rez / blocs / Limitation à une commande

Système maison pour ne pas pouvoir utiliser plus d’une commande à la fois

lgrez.blocs.one_command.exempted = [<discord.ext.commands.core.Command object>, <discord.ext.commands.core.Command object>]

Commands exempted from one_command limitation, registered by do_not_limit()

Type

list[Command]

exception lgrez.blocs.one_command.AlreadyInCommand(message=None, *args)[source]

Salon déjà occupé par une commande non finissable.

Exception levée lorsqu’un membre veut lancer une commande dans un salon où une commande est déjà en cours d’exécution, et que cette commande n’a pas pu être arrêtée (ou pas assez rapidement) par un message "stop".

Dérive de discord.ext.commands.CheckFailure.

async lgrez.blocs.one_command.not_in_command(ctx)[source]

Check : assure qu’une commande n’est pas en cours dans ce salon.

Fonction à utiliser comme check global, pour toutes les commandes (enregistrer avec add_check())

Paramètres

ctx (discord.ext.commands.Context) – contexte d’invocation de la commande.

Renvoie

True

Lève

AlreadyInCommand

async lgrez.blocs.one_command.add_to_in_command(ctx)[source]

Ajoute le channel à la liste des channels dans une commande.

Fonction à appeller avant chaque appel de fonction (enregistrer avec before_invoke())

Elle est appellée seulement si les checks sont OK, donc pas si le salon est déjà dans config.bot.in_command.

Paramètres

ctx (discord.ext.commands.Context) – contexte d’invocation de la commande.

async lgrez.blocs.one_command.remove_from_in_command(ctx)[source]

Retire le channel de la liste des channels dans une commande.

Fonction à appeller après chaque appel de fonction. (enregistrer avec after_invoke())

Elle attend 0.1 secondes avant d’enlever le joueur afin d’éviter que le bot réagisse « nativement » (IA) à un message déjà traité par un tools.wait_for_message() ayant mené à la fin de la commande.

Paramètres

ctx (discord.ext.commands.Context) – contexte d’invocation de la commande.

lgrez.blocs.one_command.bypass(ctx)[source]

Context manager: bypass one-command limitation.

Paramètres

ctx (discord.ext.commands.Context) – running command context.

Use in a command callback to launch a second one without problems:

with one_command.bypass(ctx):
    await config.bot.process_commands(some_message)
lgrez.blocs.one_command.do_not_limit(command)[source]

Decorator for commands not concerned by one_command limitation.

Register the command in one_command.exempted.

Paramètres

command (discord.ext.commands.Command) – the command to register.

Renvoie

discord.ext.commands.Command

.ready_check

lg-rez / blocs / Ready-check

Classes to raise an exception when accessing attributes not respecting a given rule

exception lgrez.blocs.ready_check.NotReadyError[source]

An attribute is tried to be accessed before it is ready.

Inherits from RuntimeError.

class lgrez.blocs.ready_check.ReadyCheck(*args, **kwargs)[source]

Proxy class to prevent accessing not initialised objects.

When accessing a class attribute, this class:
  • returns its value (classic behavior) if it is evaluated ready (see below);

  • raises a NotReadyError exception otherwise.

Subclass this class to implment readiness check on class attributes and define « readiness » as needed. By default, attributes are considered not ready only if their value is None:

class NotNone(ReadyCheck):
    a = None            # NotNone.a will raise a NotReadyError
    b = <any object>    # NotNone.b will be the given object

Use check_type class-definition argument to define readiness based on attributes types (using isinstance()):

class MustBeList(ReadyCheck, check_type=list):
    a = "TDB"           # MustBeList.a will raise a NotReadyError
    b = [1, 2, 3]       # MustBeList.b will be the given list

Use check class-definition argument to define custom readiness check (value -> bool function):

class MustBePositive(ReadyCheck, check=lambda val: val > 0):
    a = 0               # MustBePositive.a will raise a NotReadyError
    b = 37              # MustBePositive.b will be 37

If both arguments are provided, attribute type will be checked first and custom check will be called only for suitable attributes.

Attributes can be added, modified and deleted the normal way. Readiness is evaluated at access time, so changing an attribute’s value will change its readiness with no aditionnal work required.

Note

Attributes whose name start with '_' (private and magic attributes) are not affected and will be returned even if not ready.

These classes can also implement iterating protocol to provide access to protected attributes names (order not reliable):

for name in NotNone:
    print(name)         # Will print 'a' then 'b'

Avertissement

Class derivating from this class are not meant to be instantiated. Due to the checking proxy on class attributes, instances will not see attributes defined at class level, and attributes defined in __init__ or after construction will not be ready-checked.

This class defines no attributes or methods, but relies on a custom metaclass: you will not be able to create mixin classes from this one and a custom-metaclass one.

classmethod get_raw(name)

Access to an attribute bypassing ready check

Paramètres

name (str) – name of the attribute. This must be a public attribute (no leading underscore).

Renvoie

The attribute value, whatever it is.

Lève

AttributeError – if the attribute doesnt exist

.realshell

lg-rez / blocs / Émulation de terminal Python (avancé)

Permet d’utiliser un terminal Python directement dans Discord (implémentation de https://pypi.org/project/asyncode).

exception lgrez.blocs.realshell.RealShellExit[source]

Terminal exited (SystemExit catched or stop button).

Derivates from RuntimeError.

class lgrez.blocs.realshell.RSCommand(value)[source]

Enum: Shell controll commands.

These commands allow to control the shell in ways impossible with plain Discord messages: change indentation (leading spaces in messages are stripped), send empty lines, send EOF (^D).

Enum values are unicode emojis codepoints used for emoji control of the shell. Override this class (you may not define all values to disable some features) to change them.

Emojis are displayed in the same order members are defined:

HOME

Reset indentation to 0.

UNTAB

Decreases indentation by one level.

TAB

Increases indentation by one level.

ENTER

Send empty line.

EOF

Send EOF signal (^D in *nix, ^Z + Enter in Windows.)

class lgrez.blocs.realshell.RealShell(channel, locals={}, filename='!shell')[source]

Python shell inside LGBot.

(subclass of asyncode.AsyncInteractiveConsole)

Paramètres
async interact(banner=None, exitmsg='Byebye!')[source]

Launchs the shell.

(see asyncode.AsyncInteractiveConsole.interact())

async control(command, times=1)[source]

Applies the effect of a shell control.

Paramètres
  • command (.RSCommand) – shell command to compute.

  • times (int) – repeat the command several times. Makes sense for RSCommand.TAB and RSCommand.UNTAB only.

Renvoie

  • None – if further instructions are needed.

  • str – if instruction is complete (push this into the shell!)

Lève

.RealShellExit – if asked to stop shell (EOF).

async get_order()[source]

Waits for an order (message or reaction) from a member.

Add reactions if not present (new message) and waits for an interaction.

Renvoie

  • None – if further instructions are needed.

  • str – if instruction is complete (push this into the shell!)

Lève

.RealShellExit – if asked to stop shell (EOF).

async write(data, *, refresh=False, show_caret=True)[source]

Method called on each print / repr / traceback…

Updates Discord message only if text ends with a prompt (sys.ps1 or sys.ps2); adds it to an internal buffer otherwise.

Paramètres
  • data (str) – text to display.

  • refresh (bool) – if True, updates message whatever data is.

  • show_caret (bool) – if False, does not display the cursor position (‸); implies that the shell is not ready for further instructions.

async raw_input(prompt='')[source]

Method called when the shell waits for next instruction.

Calls get_order() until it returns a str (or propagates RealShellExit) then displays it in the shell (without caret) before returning its value.

Paramètres

prompt (str) – optional text to send before waiting for input.

Renvoie

str – new instruction to compute.

.structure

lg-rez / blocs / Vérification de structure

class lgrez.blocs.structure.Union(*args)[source]

Represent a union of possible structures.

Paramètres

*args – Accepted structures.

exception lgrez.blocs.structure.MatchError(msg: str, data: dict | list | str | int | float | bool | None, model: lgrez.blocs.structure.Union | type | types.UnionType | dict | list | None, path: list[str])[source]

Error occuring when matching a structure.

Derives from RuntimeError.

Paramètres
  • msg – Exception message.

  • data – Object we try to match.

  • model – Structure we want to match on.

  • path – JSON-like path from the structure root.

lgrez.blocs.structure.check_structure(data: dict | list | str | int | float | bool | None, model: lgrez.blocs.structure.Union | type | types.UnionType | dict | list | None) None[source]

Check that a given object matches a required structure.

Paramètres
  • data – Object to match.

  • model – Structure to match on.

Lève

.MatchError – If matching failed.

lgrez.blocs.structure.check_server_structure(structure: dict, required_roles: Iterable[str], required_channels: Iterable[str], required_emojis: Iterable[str]) None[source]

Check that the given dict represents a valid server structure.

Paramètres
  • structure – The dict to check.

  • required_roles – The slugs of roles needed in the structure.

  • required_channels – The slugs of channels needed in the structure.

  • required_emojis – The slugs of emojis needed in the structure.

Lève

.MatchError – If matching failed.

.tools

lg-rez / blocs / Outils divers et variés

Récupération d’objets Discord, décorateurs pour commandes, structures d’interaction dans les channels, utilitaires d’emojis, de date/temps, de formatage…

lgrez.blocs.tools.get(iterable, **attrs)[source]

Raccourci pour discord.utils.get()

lgrez.blocs.tools.channel(nom, must_be_found=True)[source]

Renvoie l’objet associé au salon #nom.

Paramètres
  • nom (str) – nom du channel (texte/vocal/catégorie) ou sa mention (détection directe par regex)

  • must_be_found (bool) – si True (défaut), raise une ValueError si le channel #nom n’existe pas (si False, renvoie None)

Renvoie

discord.abc.GuildChannel

lgrez.blocs.tools.role(nom, must_be_found=True)[source]

Renvoie l’objet associé au rôle @&nom.

Paramètres
  • nom (str) – nom du rôle ou sa mention (détection directe par regex)

  • must_be_found (bool) – si True (défaut), raise une ValueError si le channel @&nom n’existe pas (si False, renvoie None)

Renvoie

discord.Role

lgrez.blocs.tools.member(nom, must_be_found=True)[source]

Renvoie l’objet associé au membre @nom.

Paramètres
  • nom (str) – nom du joueur ou sa mention (détection directe par regex)

  • must_be_found (bool) – si True (défaut), raise une ValueError si le membre @nom n’existe pas (si False, renvoie None)

Renvoie

discord.Member

lgrez.blocs.tools.emoji(nom, must_be_found=True)[source]

Renvoie l’objet associé à l’emoji :nom:.

Paramètres
  • nom (str) – nom de l’emoji (texte/vocal/catégorie) ou son utilisation (détection directe par regex)

  • must_be_found (bool) – si True (défaut), raise une ValueError si l’emoji :nom: n’existe pas (si False, renvoie None)

Renvoie

discord.Emoji

lgrez.blocs.tools.mention_MJ(arg)[source]

Renvoie la mention ou le nom du rôle MJ

  • Si le joueur n’est pas un MJ, renvoie la mention de config.Role.mj

  • Sinon, renvoie son nom (pour ne pas rameuter tout le monde).

Paramètres

arg (Member | Context) – membre ou contexte d’un message envoyé par un membre

Renvoie

str

exception lgrez.blocs.tools.CommandExit[source]

Fin de commande demandée.

Lever cette exception force l’arrêt immédiat d’une commande, et empêche le bot de réagir à nouveau.

Dérive de RuntimeError.

lgrez.blocs.tools.mjs_only(func)

Décorateur pour commande (discord.ext.commands.check()) : commande exécutable uniquement par un MJ ou un webhook (tâche planifiée)

lgrez.blocs.tools.mjs_et_redacteurs(func)

Décorateur pour commandes d’IA (discord.ext.commands.check()) : commande exécutable par un MJ, un Rédacteur ou un webhook (tâche planifiée)

lgrez.blocs.tools.joueurs_only(func)

Décorateur pour commande (discord.ext.commands.check()) : commande exécutable uniquement par un joueur, vivant ou mort.

lgrez.blocs.tools.vivants_only(func)

Décorateur pour commande (discord.ext.commands.check()) : commande exécutable uniquement par un joueur vivant

lgrez.blocs.tools.private(callback)[source]

Décorateur : commande utilisable dans son chan privé uniquement.

Lors d’une invocation de la commande décorée hors d’un channel privé (commençant par config.private_chan_prefix), supprime le message d’invocation et exécute la commande dans le channel privé de l’invoqueur.

Ce décorateur n’est utilisable que sur une commande définie dans un Cog. Si le joueur ayant utilisé la commande n’a pas de chan privé (pas en base), raise une ValueError.

Utilisable en combinaison avec joueurs_only() et vivants_only() (pas avec les autres attention, vu que seuls les joueurs ont un channel privé).

async lgrez.blocs.tools.wait_for_message(check, trigger_on_commands=False, chan=None)[source]

Attend le premier message reçu rencontrant les critères demandés.

Surcouche de discord.ext.commands.Bot.wait_for() permettant d’ignorer les commandes et de réagir au mot-clé stop.

Paramètres
  • check (Callable[discord.Message -> bool]) – fonction validant ou non chaque message.

  • trigger_on_commands (bool) – si False (défaut), un message respectant check sera ignoré si c’est une commande.

  • chan (discord.TextChannel) – le channel dans lequel le message est attendu (si applicable). Si None, les messages d’arrêt (config.stop_keywords) peuvent ne pas être détectés (la fonction émettera un warning en ce sens).

Renvoie

discord.Message

Lève

.CommandExit – si le message est un des config.stop_keywords (insensible à la casse), même si il respecte check

async lgrez.blocs.tools.wait_for_message_here(ctx, trigger_on_commands=False)[source]

Attend et renvoie le premier message reçu dans <ctx>.

Surcouche de wait_for_message() filtrant uniquement les messages envoyés dans ctx.channel par quelqu’un d’autre que le bot.

Paramètres
Renvoie

discord.Message

async lgrez.blocs.tools.boucle_message(chan, in_message, condition_sortie, rep_message=None)[source]

Boucle question/réponse jusqu’à qu’une condition soit vérifiée.

Paramètres
  • chan (discord.TextChannel) – salon dans lequel lancer la boucle.

  • condition_sortie (Callable[discord.Message -> bool]) – fonction validant ou non chaque message.

  • in_message (str) – si défini, message à envoyer avant la boucle.

  • rep_message (str) – si défini, permet de définir un message de boucle différent de in_message (identique si None). Doit être défini si in_message n’est pas défini.

Renvoie

discord.Message

async lgrez.blocs.tools.boucle_query(ctx, table, col=None, cible=None, filtre=None, sensi=0.5, direct_detector=None, message=None)[source]

Fait trouver à l’utilisateur une entrée de BDD d’après son nom.

Paramètres
  • ctx (discord.ext.commands.Context) – contexte d’une commande.

  • table (.bdd.base.TableMeta) – table dans laquelle rechercher.

  • col (Column) – colonne dans laquelle rechercher (passé à find_nearest()).

  • cible (str) – premier essai de cible (donnée par le joueur dans l’appel à une commande, par exemple).

  • filtre – passé à find_nearest().

  • sensi (float) – sensibilité de la recherche (voir find_nearest()).

  • direct_detector (Callable[str] -> table | None) – pré-détecteur éventuel, appellé sur l’entrée utilisateur avant find_nearest() ; si cette fonction renvoie un résultat, il est immédiatement renvoyé.

  • message (str) – si défini (et cible non défini), message à envoyer avant la boucle.

Renvoie

Instance de table sélectionnée

Attend que le joueur entre un nom, et boucle 5 fois au max (avant de l’insulter et de raise une erreur) pour chercher l’entrée la plus proche.

async lgrez.blocs.tools.boucle_query_joueur(ctx, cible=None, message=None, sensi=0.5, filtre=None)[source]

Retourne un joueur (entrée de BDD) d’après son nom.

Paramètres
  • ctx (discord.ext.commands.Context) – contexte d’une commande.

  • cible (str) – premier essai de cible (donnée par le joueur dans l’appel à une commande, par exemple).

  • message (str) – si défini (et cible non défini), message à envoyer avant la boucle.

  • sensi (float) – sensibilité de la recherche (voir find_nearest()).

  • filtre – passé à find_nearest().

Renvoie

bdd.Joueur

Attend que le joueur entre un nom de joueur, et boucle 5 fois au max (avant de l’insulter et de raise une erreur) pour chercher le plus proche joueur dans la table bdd.Joueur.

async lgrez.blocs.tools.wait_for_react_clic(message, emojis={}, *, process_text=False, text_filter=None, first_text=None, post_converter=None, trigger_all_reacts=False, trigger_on_commands=False)[source]

Ajoute des reacts à un message et attend une interaction.

Paramètres
  • message (discord.Message) – message où ajouter les réactions.

  • emojis (list | dict) – reacts à ajouter, éventuellement associés à une valeur qui sera retournée si clic sur l’emoji.

  • process_text (bool) – si True, détecte aussi la réponse par message et retourne le texte du message (défaut : False).

  • text_filter (Callable[str -> bool]) – si process_text, ne réagit qu’aux messages pour lesquels text_filter(message) renvoie True (défaut : tous).

  • first_text (str) – si process_text, texte considéré comme la première réponse textuelle reçue (si il vérifie text_filter, les emojis ne sont pas ajoutés et cette fonction retourne directement).

  • post_converter (Callable[str -> Any]) – si process_text et que l’argument est défini, le message détecté est passé dans cette fonction avant d’être renvoyé.

  • trigger_all_reacts (bool) – si True, détecte l’ajout de toutes les réactions (pas seulement celles dans emojis) et renvoie l’emoji directement si il n’est pas dans emojis (défaut : False).

  • trigger_on_commands (bool) – passé à wait_for_message().

Renvoie

  • str – représentant
    • le nom de l’emoji si emojis est une liste et clic sur une des reacts, ou si trigger_all_reacts vaut True et ajout d’une autre react ;

    • le message reçu si process_text vaut True, que post_converter n’est pas défini et réaction à un message ;

  • Any – représentant
    • la valeur associée si emojis est un dictionnaire et clic sur une des reacts ;

    • la valeur retournée par post_converter si il est défini, que process_text vaut True et réaction à un message.

async lgrez.blocs.tools.yes_no(message, first_text=None)[source]

Demande une confirmation / question fermée à l’utilisateur.

Surcouche de wait_for_react_clic() : ajoute les reacts ✅ et ❎ à un message et renvoie True ou False en fonction de l’emoji cliqué OU de la réponse textuelle détectée.

Paramètres
Réponses textuelles reconnues :
  • Pour True : ["oui", "o", "yes", "y", "1", "true"]

  • Pour False : ["non", "n", "no", "n", "0", "false"]

ainsi que toutes leurs variations de casse.

Renvoie

bool

async lgrez.blocs.tools.yes_no_maybe_i_dont_know_can_you_repeat_the_question(message, first_text=None)

Demande une confirmation / question fermée à l’utilisateur.

Surcouche de wait_for_react_clic() : ajoute les reacts ✅ et ❎ à un message et renvoie True ou False en fonction de l’emoji cliqué OU de la réponse textuelle détectée.

Paramètres
Réponses textuelles reconnues :
  • Pour True : ["oui", "o", "yes", "y", "1", "true"]

  • Pour False : ["non", "n", "no", "n", "0", "false"]

ainsi que toutes leurs variations de casse.

Renvoie

bool

async lgrez.blocs.tools.choice(message, N, start=1, *, additionnal={})[source]

Demande à l’utilisateur de choisir entre plusieurs options numérotées.

Surcouche de wait_for_react_clic() : ajoute des reacts chiffres (1️⃣, 2️⃣, 3️⃣…) et renvoie le numéro cliqué OU détecté par réponse textuelle.

Paramètres
  • message (discord.Message) – message où ajouter les réactions.

  • N (int) – chiffre jusqu’auquel aller, inclus (<= 10).

  • start (int) – chiffre auquel commencer (entre 0 et N, défaut 1).

  • additionnal (dict[discord.Emoji | str, Any]) – emojis optionnels à ajouter après les chiffres et valeur renvoyée si cliqué.

Réponses textuelles reconnues : chiffres entre start et N.

Renvoie

int (ou la valeur associée si emoji choisi dans additionnal)

async lgrez.blocs.tools.sleep(chan, tps)[source]

Attend un temps donné en avertissant l’utilisateur.

Pause l’exécution d’une commande en affichant l’indicateur typing ( »LGBot est en train d’écrire… ») sur un salon.

Permat d’afficher plusieurs messages d’affillée en laissant le temps de lire, tout en indiquant que le bot n’a pas fini d’écrire.

Paramètres
lgrez.blocs.tools.montre(heure=None)[source]

Renvoie l’emoji horloge le plus proche d’une heure donnée.

Paramètres

heure (str) – heure à représenter, au format "XXh" ou "XXhMM" (défaut : heure actuelle).

Renvoie

str (🕧, 🕓, 🕝…)

lgrez.blocs.tools.emoji_chiffre(chiffre, multi=False)[source]

Renvoie l’emoji / les emojis chiffre correspondant à un chiffre/nombre.

Paramètres
  • chiffre (int) – chiffre/nombre à représenter.

  • multi (bool) – si True, chiffre peut être n’importe quel entier positif, dont les chiffres seront convertis séparément ; sinon (par défaut), chiffre doit être un entier entre 0 et 10.

Renvoie

str (0️⃣, 1️⃣, 2️⃣…)

lgrez.blocs.tools.super_chiffre(chiffre, multi=False)[source]

Renvoie le(s) caractère(s) exposant correspondant à un chiffre/nombre.

Paramètres
  • chiffre (int) – chiffre/nombre à représenter.

  • multi (bool) – si True, chiffre peut être n’importe quel entier positif, dont les chiffres seront convertis séparément ; sinon (par défaut), chiffre doit être un entier entre 0 et 9.

Renvoie

str (⁰, ¹, ²…)

lgrez.blocs.tools.sub_chiffre(chiffre, multi=False)[source]

Renvoie le(s) caractère(s) indice correspondant à un chiffre/nombre.

Paramètres
  • chiffre (int) – chiffre/nombre à représenter.

  • multi (bool) – si True, chiffre peut être n’importe quel entier positif, dont les chiffres seront convertis séparément ; sinon (par défaut), chiffre doit être un entier entre 0 et 9.

Renvoie

str (₀, ₁, ₂…)

lgrez.blocs.tools.heure_to_time(heure)[source]

Convertit l’écriture d’une heure en objet datetime.time.

Paramètres

heure (str) – heure au format HHh, HHhMM ou HH:MM.

Renvoie

datetime.time

Lève

ValueError – conversion impossible (mauvais format)

lgrez.blocs.tools.time_to_heure(tps, sep='h', force_minutes=False)[source]

Convertit un objet datetime.time en heure.

(version maison de datetime.time.strftime())

Paramètres
  • tps (datetime.time) – temps à convertir.

  • sep (str) – séparateur heures / minutes à utiliser (défaut "h").

  • force_minutes (bool) – si False (défaut), les minutes ne sont indiquées que si différentes de 0.

Renvoie

str ("" si tps est None)

lgrez.blocs.tools.next_occurence(tps)[source]

Renvoie la prochaine occurence temporelle d’une heure donnée.

Renvoie le prochain timestamp arrivant DANS LES HORAIRES DU JEU : entre tools.fin_pause() et tools.debut_pause().

Paramètres

tps (datetime.time) – heure dont on veut connaître la prochaine occurence.

Renvoie

datetime.datetime

lgrez.blocs.tools.debut_pause()[source]

Renvoie le timestamp correspondant au prochain vendredi 19h.

Renvoie

datetime.datetime

lgrez.blocs.tools.fin_pause()[source]

Renvoie le timestamp correspondant au prochain dimanche 19h.

Renvoie

datetime.datetime

lgrez.blocs.tools.en_pause()[source]

Détermine si le jeu est actuellement en pause hebdomadaire.

Si il n’y a pas de pause (fin_pause() = debut_pause()), renvoie toujours False.

Renvoie

bool

lgrez.blocs.tools.smooth_split(mess, N=1990, sep='\n', rep='')[source]

Sépare un message en une blocs moins longs qu’une limite donnée.

Très utile pour envoyer des messages de (potentiellement) plus de 2000 caractères (limitation Discord).

Paramètres
  • mess (str) – message à découper.

  • N (int) – taille maximale des messages formés (défaut 1990, pour avoir un peu de marge par rapport à la limitation, et permettre d’entourer de ``` par exemple)

  • sep (str) – caractères où séparer préférentiellement le texte (défaut : sauts de ligne). Si mess contient une sous-chaîne plus longue que N ne contenant pas sep, le message sera tronqué à la limite.

  • rep (str) – chaîne ajoutée à la fin de chaque message formé (tronqué du séparateur final) (défaut : aucune).

Renvoie

list[str]

async lgrez.blocs.tools.send_blocs(messageable, mess, *, N=1990, sep='\n', rep='')[source]

Envoie un message en le coupant en blocs si nécaissaire.

Surcouche de smooth_split() envoyant directement les messages formés.

Paramètres
Renvoie

La liste des messages envoyés.

Type renvoyé

list[discord.Message]

async lgrez.blocs.tools.send_code_blocs(messageable, mess, *, N=1990, sep='\n', rep='', prefixe='', langage='')[source]

Envoie un (potentiellement long) message sous forme de bloc(s) de code.

Équivalent de send_blocs() avec formatage de chaque bloc dans un bloc de code.

Paramètres
Renvoie

La liste des messages envoyés.

Type renvoyé

list[discord.Message]

async lgrez.blocs.tools.log(message, *, code=False, N=1990, sep='\n', rep='', prefixe='', langage='')[source]

Envoie un message dans le channel config.Channel.logs.

Surcouche de send_blocs() / send_code_blocs().

Paramètres
Renvoie

La liste des messages envoyés.

Type renvoyé

list[discord.Message]

async lgrez.blocs.tools.create_context(member, content)[source]

Génère le contexte associé au message d’un membre dans son chan privé.

Paramètres
  • member (discord.Member) – membre dont on veut simuler l’action. Doit être inscrit en base (pour avoir un chan privé).

  • content (str) – message à « faire envoyer » au joueur, généralement une commande.

Utile notemment pour simuler des commandes à partir de clics sur des réactions.

Renvoie

discord.ext.commands.Context

lgrez.blocs.tools.remove_accents(text)[source]

Enlève les accents d’un chaîne, mais conserve les caractères spéciaux.

Version plus douce de unidecode.unidecode, conservant notemment les emojis, …

Paramètres

text (str) – chaîne à désaccentuer.

Renvoie

str

lgrez.blocs.tools.eval_accols(rep, globals_=None, locals_=None, debug=False)[source]

Replace chaque bloc entouré par des {} par leur évaluation Python.

Paramètres
  • globals (dict) – variables globales du contexte d’évaluation (passé à eval()).

  • locals (dict) – variables locales du contexte d’évaluation (passé à eval()).

  • debug (bool) – si True, insère le message d’erreur (type et texte de l’exception) dans le message à l’endroit où une exception est levée durant l’évaluation (défaut False).

Penser à passer les globals() et locals() si besoin. Généralement, il faut passer locals() qui contient ctx, etc… mais pas globals() si on veut bénéficier de tous les modules importés dans tools.py.

async lgrez.blocs.tools.multicateg(base_name: str) discord.channel.CategoryChannel[source]

Permet de gérer des groupes de catégories (plus de 50 salons).

Renvoie la première catégorie pouvant accueillir un nouveau salon ; en crée une nouvelle si besoin.

Paramètres

base_name (str) – le nom du groupe de catégorie (nom de la première catégorie, puis sera suivi de 2, 3…)

Avertissement

Une catégorie appellée base_name doit exister au préalable dans le serveur (config.guild).

Renvoie

discord.CategoryChannel

lgrez.blocs.tools.in_multicateg(categ: discord.channel.CategoryChannel, base_name: str) bool[source]

Détecte si une catégorie appartient à un groupe de catégories.

Paramètres
Renvoie

bool

lgrez.blocs.tools.bold(text)[source]

Formate une chaîne comme texte en gras dans Discord.

Paramètres

text (str) – chaîne à formater.

Renvoie

str

lgrez.blocs.tools.ital(text)[source]

Formate une chaîne comme texte en italique dans Discord.

Paramètres

text (str) – chaîne à formater.

Renvoie

str

lgrez.blocs.tools.soul(text)[source]

Formate une chaîne comme texte souligné dans Discord.

Paramètres

text (str) – chaîne à formater.

Renvoie

str

lgrez.blocs.tools.strike(text)[source]

Formate une chaîne comme texte barré dans Discord.

Paramètres

text (str) – chaîne à formater.

Renvoie

str

lgrez.blocs.tools.code(text)[source]

Formate une chaîne comme code (inline) dans Discord.

Paramètres

text (str) – chaîne à formater.

Renvoie

str

lgrez.blocs.tools.code_bloc(text, langage='')[source]

Formate une chaîne comme un bloc de code dans Discord.

Paramètres
  • text (str) – chaîne à formater.

  • langage (str) – langage du code, pour coloration syntaxique.

Langages supportés (non exhaustif ?) : asciidoc, autohotkey, bash, coffeescript, cpp (C++), cs (C#), css, diff, fix, glsl, ini, json, md, (markdown), ml, prolog, py, tex, xl, xml

Renvoie

str

lgrez.blocs.tools.quote(text)[source]

Formate une chaîne comme citation (inline) dans Discord.

Paramètres

text (str) – chaîne à formater.

Renvoie

str

lgrez.blocs.tools.quote_bloc(text)[source]

Formate une chaîne comme bloc de citation (multiline) dans Discord.

Paramètres

text (str) – chaîne à formater.

Renvoie

str

lgrez.blocs.tools.spoiler(text)[source]

Formate une chaîne comme spoiler (cliquer pour afficher) dans Discord.

Paramètres

text (str) – chaîne à formater.

Renvoie

str

.console

lg-rez / blocs / Console d’administration (avancé)

Permet de contrôler le bot depuis la console le faisant tourner.

class lgrez.blocs.console.CaptureLogs[source]

Context manager: capture the messages posted to a Discord channel.

Only capture messages posted by the bot itself: these messages are not sent at all to Discord.

Paramètres

chan (discord.TextChannel) – the channel to capture.

property text

The messages sent in the channel, joined with newlines.

Type

str

class lgrez.blocs.console.AdminConsole(locals={}, filename='__console__')[source]

Python console to control LGBot from the running shell.

(subclass of asyncode.AsyncInteractiveConsole)

Paramètres
async interact(banner=None, exitmsg='Byebye!')[source]

Launchs the console.

(see asyncode.AsyncInteractiveConsole.interact())

async write(data)[source]

Method called on each print / repr / traceback…

Relies on aioconsole.aprint().

Paramètres

data (str) – text to display.

async raw_input(prompt='')[source]

Method called when the console waits for next instruction.

Relies on aioconsole.ainput().

Paramètres

prompt (str) – optional text to send before waiting for input.

Renvoie

The new instruction to compute.

Type renvoyé

str

async lgrez.blocs.console.run_admin_console(locals)[source]

Launch the Admin console and restart it if crashing.

Paramètres

locals (dict) – the objects accessible from the console.

async lgrez.blocs.console.execute_command(entree)[source]

Execute a command.

Create a fake message in the #logs channel by the server owner, and process it while capturing the output in the channel.

Paramètres

entree (str) – The command to execute (must begin with the command prefix)

Renvoie

The messages get in response to the command execution, joined with newlines.

Type renvoyé

str