Les terminaux#

Les terminaux sont en gros des "IDEs sans éditeur".

Le but premier des terminaux isolés n'est pas forcément d'utiliser toute la logistique qui va avec les IDEs (notamment en ce qui concerne les codes python), mais il est tout de même possible de leur appliquer les mêmes réglages, à quelques détails près.

La macro terminal fonctionne donc dans les grandes lignes de la même manière que la macro IDE.

Bugs d'affichage connus pour les terminaux (isolés ou avec IDEs)

Spécifique

Plateformes : Windows 11 + Chrome
Après avoir déplié une admonition (??? tip ...)

Si le terminal est créé dans une admonition repliée, il peut arriver qu'après avoir déplié celle-ci, le terminal affiche le feedback en mettant un seul caractère par ligne.

Il n'y a pas de solution connue à ce bug (interne au terminal), mais l'utilisateur peut contourner le problème en redimensionnant la fenêtre, d'une façon ou d'une autre :
- Changer le mode de la fenêtre (agrandie / fenêtrée / plein écran).
- Ouvrir puis fermer la console du navigateur ( F12 ).

Multi-plateformes

Plateformes : toutes
Après avoir déplié une admonition (??? tip ...)
Après avoir changé d'onglet, dans des panneaux coulissants (=== "tabbed")

Il peut également arriver que le terminal semble rester vide (sans même les chevrons à gauche de la ligne de saisie).
Ceci est un bug provenant d'interactions malheureuses entre des codes de différentes sources (material, pymdown-extensions et jQuery.terminal) et ne peut donc pas être corrigé. Une correction du symptôme a par contre été mise en place, et il suffit de cliquer sur la zone du terminal ou de lancer les exécutions pour que le contenu du terminal apparaisse.

Performances d'affichage#

Les terminaux jQuery deviennent extrêmement lents si beaucoup de contenu y est affiché. Cela devient particulièrement visible lorsque la taille de la fenêtre du navigateur est modifiée.

Pour cette raison, le bouton dans le coin supérieur droit de chaque terminal permet de régler si la sortie standard et les messages d'erreurs sont automatiquement tronqués ou non. Il est vivement conseillé de garder ce réglage activé.

Il est également possible de configurer ce comportement via l'option terms.stdout_cut_off du plugin :

plugins:
    ...
    - pyodide_macros:
        terms:
            cut_feedback: true     # (valeur par défaut)

Un autre réglage, au niveau du plugin lui-même, permet par ailleurs de limiter le nombre de lignes restant affichées à tout instant dans les terminaux.
C'est l'option terms.stdout_cut_off :

plugins:
    ...
    - pyodide_macros:
        terms:
            stdout_cut_off: 200     # (valeur par défaut)

Par défaut, 200 lignes au plus sont affichées, ce qui devrait suffire pour éviter les cas les plus courants de chutes de performances.

Ne cependant pas oublier qu'un plaisantin entrant quelque chose comme "a" * 1_000_000 dans le terminal se retrouvera avec une unique ligne mais une page de navigateur inutilisable car le terminal contiendra trop de caractères...
L'option pour tronquer la sortie standard, terms.cut_feedback, évite ce type de problèmes.

Signature#

{{ terminal() }}

{{ terminal(
    py_name:   str = '',
    *,
    ID:   None|int = None,
    SANS:      str = '',
    WHITE:     str = '',
    REC_LIMIT: int = -1,
    SHOW:      str = '',
    MERMAID:  bool = False,
    AUTO_RUN: bool = False,
    TERM_H:    int = 10,
    FILL:      str = '',
) }}

Tous les arguments sont optionnels.
À part pour le premier, déclarer les arguments en précisant leur nom (donc sous forme d'arguments nommés).

Argument	Type/défaut	Rôle
`py_name`	`''`	Crée un terminal isolé utilisant le fichier python correspondant (sections autorisées: `env`, `env_term`, `post_term`, `post` et `ignore`). (plus d'informations)
`ID`	`int`	À utiliser pour différencier deux appels de macros différents, dans le cas où vous tomberiez sur une collision d'id (très improbable, car des hachages sont utilisés. Cet argument ne devrait normalement pas être nécessaire pour cette macro). (plus d'informations)
`SANS`	`''`	Pour interdire des fonctions builtins, des modules, des accès d'attributs ou de méthodes, ou des mots clefs : chaîne de noms séparés par des virgules, des points-virgules et/ou espaces. Les mots clefs viennent en dernier, après le séparateur `AST:`. (plus d'informations)
`WHITE`	`''`	("White list") Ensemble de noms de modules/packages à pré-importer avant que les interdictions ne soient mises en place (voir argument `SANS`. L'argument `WHITE` est normalement obsolète). (plus d'informations)
`REC_LIMIT`	`-1`	Pour imposer une profondeur de récursion maximale. Nota: ne jamais descendre en-dessous de 20. La valeur par défaut, `-1`, signifie que l'argument n'est pas utilisé. (plus d'informations)
`SHOW`	`''`	Affiche des données sur l'appel de macro dans le terminal, durant le `mkdocs serve` : `''`: Ne fait rien (défaut). `'args'`: Affiche tous les arguments de l'appel de macro. `'python'`: Affiche les contenus des sections, telles que vues par PMT. `'all'`: Combine `'args'` et `'python'`. (plus d'informations)
`MERMAID`	`False`	Signale qu'un rendu de graphe mermaid sera attendu à un moment ou un autre des exécutions. Nota : l'extension markdown `pymdownx.superfences` doit être configurée pour accepter les blocs de code `mermaid`. Voir la configuration par défaut du mkdocs.yml via les scripts du thème, par exemple avec : `python -m pyodide_mkdocs_theme --yml`. (plus d'informations)
`AUTO_RUN`	`False`	Lance automatiquement le code après avoir affiché la page. (plus d'informations)
`TERM_H`	`10`	Nombre de lignes initiales utilisées pour la hauteur du terminal (approximatif). (plus d'informations)
`FILL`	`''`	Commande à afficher dans le terminal lors de sa création. Uniquement pour les terminaux isolés.

Modifier les valeurs par défaut des arguments

La configuration du plugin pyodide_macros comporte, outre les réglages du plugin lui-même, les valeurs par défaut pour la quasi totalité des macros proposées par le thème.

Ces réglages peuvent être modifiés de différentes façons pour affecter un fichier, un dossier ou une hiérarchie de dossiers :

Via le fichier mkdocs.yml du thème, bien sûr (dans la section plugins.pyodide_macros).
Via des fichiers .meta.pmt.yml, qui peuvent être placés n'importe où dans la hiérarchie de la documentation et qui affectent tous les fichiers "descendants".
Via les métadonnées placées dans les entêtes des pages markdown elles-mêmes.

Informations sur les fichiers pythons associés

Voir la page des IDEs concernant la structure des fichiers associés à l'argument py_name.

Remarques sur l'argument FILL

Il n'est utilisable que pour des terminaux isolés.
Il est possible d'utiliser des commandes multilignes, mais elle seront affichées bizarrement dans la console car elles ne présenteront pas le "prompt" en début de ligne (...) et apparaîtront donc "mal indentées".
La commande de l'argument FILL est insérée dans l'historique du terminal et peut donc y être retrouvée si besoin.

L'ancien argument SIZE

Une version antérieure du thème proposait un argument SIZE, qui est maintenant remplacé par TERM_H.

Il était toujours utilisable jusqu'à la version 3.0 du thème. À partir de cette version, l'argument lève une erreur s'il est utilisé, mais il est possible de transformer cette erreur en warning en modifiant l'option de configuration du plugin pyodide_macros: build.deprecation_level: warn.

Fichiers python & exécutions #

Les sections code, tests, secrets, corr, ainsi que les fichiers {exo}_REM.md et {exo}_VIS_REM.md sont interdits pour les terminaux isolés et une erreur est levée si l'une de ces données est trouvée.
Les sections env, env_term, post_term et post (ou ignore...) peuvent être utilisées, avec un fonctionnement similaire à celui des IDEs.
Les exécutions globales des commandes entrées dans des terminaux se déroulent comme dans la figure ci-contre. Il est à noter que :
- Les sections env et post, si elles existent, ne sont exécutées que si elles ne l'ont jamais été auparavant
- La commande entrée dans le terminal est exécutée en mode async, ce qui permet d'utiliser await ... depuis un terminal.

Particularité des commandes multilignes

Du fait de la façon dont le terminal jQuery est articulé avec la console python sous-jacente, les sections env_term et post_term doivent être exécutées à chaque fois que l'utilisateur appuie sur la touche entrée, afin de garantir que les restrictions de code, quand elles existent, seront effectivement appliquées au moment de l'exécution de la commande dans le moteur python.

Cela implique que les sections env_term ou post_term sont également exécutées entre deux lignes successives d'une commande multiligne, que l'utilisateur n'a pas encore fini de taper...

Et donc, il faut absolument éviter d'avoir des sections env_term ou post_term qui affichent des choses dans le terminal, car ces contenus apparaîtraient au beau milieu de la commande multilignes tapée par l'utilisateur, comme dans cet exemple :

>>> """début commande...
Print depuis env_term !!
... ...suite commande...
Print depuis env_term !!
... fin de commande !"""
Print depuis env_term !!
'début commande...\n...suite commande...\nfin de commande !'
>>>

La variable globale __USER_CMD__ présente une problématique similaire, pour les commandes multilignes.
Étant vue dans la section env_term, elle peut donc présenter du code incomplet tant que toute la commande n'est pas finalisée.

À noter également que la commande n'est réellement exécutée que lorsque celle-ci est complète (ou erronée). Concrètement :

Dans le terminal	Executions	`__USER_CMD__`, vue depuis `env_term` ou `post_term`
`"""début commande...`	`env_term` `post_term`	`'"""début commande...'`
`...suite commande...`	`env_term` `post_term`	`'"""début commande...\n...suite commande...'`
`...fin de commande !"""`	`env_term` `cmd dans pyodide` `post_term`	`'"""début commande...\n...suite commande...\nfin de commande !"""'`

`__USER_CMD__`#

À chaque lancement du terminal, une variable globale __USER_CMD__ (cachée, mais accessible) est mise à jour dans l'environnement avec le contenu de la commande en cours (potentiellement incomplète : voir l'encadré ci-dessus à propos des commandes multilignes).

Cette variable, si utilisée, devrait l'être depuis la section env_term.
Les problématiques autour de l'utilisation de __USER_CMD__ pour imposer des restrictions sont exactement les mêmes que celles concernant la variable globale __USER_CODE__ pour les éditeurs des IDEs.

Exemple#

Voici un exemple permettant de voir comment les différentes sections se comportent lors des exécutions, et utilisant divers arguments des terminaux.

Le terminal plus bas étant créé avec l'appel de macro suivant :

{{ terminal('exo', SANS="sorted .count", REC_LIMIT=42, TERM_H=12, FILL="inf_rec()") }}

Et le contenu du fichier exo.py est le suivant :

# --- PYODIDE:env --- #
print('...env! (once only)')

# --- PYODIDE:env_term --- #

print('In env_term, with __USER_CMD__ =', __USER_CMD__)

def inf_rec():
    def rec(n):
        if n<50: rec(n+1)
    rec(0)

# --- PYODIDE:post_term --- #
print('In post_term...')
print("Try inf_rec(), sorted()")

# --- PYODIDE:post --- #
print('...post! (once only)')

Dans le terminal ci-dessous :

Essayer d'y utiliser inf_rec(), pour voir l'effet de la limite de récursion.
Essayer d'y utiliser sorted(), ou [].count(1) pour voir l'effet des restrictions.

Les terminaux#

Performances d'affichage#

Signature#

Fichiers python & exécutions #

__USER_CMD__#

Exemple#

`__USER_CMD__`#