{{tag>dev python flask cli commande}}


====== Flask : Définir une commande CLI ======

Le framework Flask s'appuie sur le paquetage Python [[https://click.palletsprojects.com/en/stable/|Click]] pour la gestion de la ligne de commande.

On utilise les décorateurs pour déclarer une commande. Ci-dessous un exemple simple de commande sans argument :

<code python>
from flask import Flask

app = Flask(__name__)

@app.cli.command("version")
def version():
  """Show application version.""" 
  print("0.0.1")
</code>

La commande ''version'' retourne simplement le numéro de version du programme. On peut maintenant invoquer la commande depuis l'interpréteur :

<code bash>
flask version
</code>


===== Groupes de commandes ===== 

Il est possible d'organiser les commandes dans des groupes.

On peut par exemple créer un groupe ''user'' pour contenir un ensemble de commandes s'appliquant sur les utilisateurs.

<code python>
import click
from flask import Flask
from flask.cli import AppGroup

app = Flask(__name__)
user_commands = AppGroup('user')

@user_commands.command('add')
@click.argument('name')
def create_user(name):
  """Add an user with name in argument."""
  click.echo(f"Add an user with name : {name}.")

@user_commands.command('remove')
@click.argument('name')
def delete_user(name):
  """Remove user with name in argument."""
  click.echo(f"Remove an user with name : {name}.")

app.cli.add_command(user_commands)
</code>

===== Utilisation avec les Blueprints =====

Si l'application utilise des Blueprints, on peut directement associer (register) les commandes à ceux-ci :

<code python cli.py>
"""
Blueprint regroupant les commandes CLI globales pour l'application
"""

from flask import Blueprint
from app.config import DefaultConfig
import click

cmd_bp = Blueprint( 'cli', __name__, cli_group=None)

@cmd_bp.cli.command('version')
def version():
    """Show application version/revision"""
    click.echo(f"{DefaultConfig.APP_NAME} {DefaultConfig.APP_VERSION}")
</code> 

Ici, lors de l'instanciation du Blueprint, on utilise l'option ''cli_group'' avec la valeur ''None'' pour spécifier que nous ne souhaitons pas regrouper la ou les commandes du Blueprint.

Ensuite, dans l'application factory on enregistrera le Blueprint :
<code python>
from flask import Flask
from app.cli import cmd_bp

# Charge les classes de configuration
from app.config import DevelopmentConfig


def create_app() -> Flask:
    app = Flask(__name__)
    app.config.from_object(DevelopmentConfig)

    ...

    app.register_blueprint(cmd_bp)

    return app
</code>


===== Arguments et options =====

La documentation officielle du package Click détaille la [[https://click.palletsprojects.com/en/stable/options/#|syntaxe de définition des arguments et des options]].

 
===== Références =====

  * [[https://flask.palletsprojects.com/en/stable/cli/|La CLI Flask (documentation officielle Flask)(en)]]
  * [[https://www.compilenrun.com/docs/framework/flask/flask-fundamentals/flask-command-line/|Tutoriel CLI Flask (compilenrun.com)(en)]]