Interfaz de línea de comandos

La instalación de Flask instala el script flask, una interfaz de línea de comandos Click, en su virtualenv. Ejecutado desde el terminal, este script da acceso a los comandos incorporados, a las extensiones y a los definidos por la aplicación. La opción --help dará más información sobre los comandos y opciones.

Descubrimiento de aplicaciones

El comando flask es instalado por Flask, no por tu aplicación; hay que decirle dónde encontrar tu aplicación para poder usarla. La opción --app se utiliza para especificar cómo cargar la aplicación.

Aunque --app admite una variedad de opciones para especificar su aplicación, la mayoría de los casos de uso deberían ser sencillos. Estos son los valores típicos:

(nada)

El nombre «app» o «wsgi» se importa (como un archivo «.py», o paquete), detectando automáticamente una aplicación (app o application) o fábrica (create_app o make_app).

--app hello

Se importa el nombre dado, detectando automáticamente una aplicación (app o application) o fábrica (create_app o make_app).

--app tiene tres partes: una ruta opcional que establece el directorio de trabajo actual, un archivo de Python o una ruta de importación con puntos, y un nombre variable opcional de la instancia o fábrica. Si el nombre es una fábrica, puede ir opcionalmente seguido de argumentos entre paréntesis. Los siguientes valores demuestran estas partes:

--app src/hello

Establece el directorio de trabajo actual en src y luego importa hello.

--app hello.web

Imports the path hello.web.

--app hello:app2

Utiliza la instancia de Flask de app2 en hello.

--app 'hello:create_app("dev")'

La fábrica create_app en hello es llamada con la cadena 'dev' como argumento.

Si --app no se establece, el comando tratará de importar «app» o «wsgi» (como un archivo «.py», o paquete) y tratará de detectar una instancia de aplicación o fábrica.

Dentro de la importación dada, el comando busca una instancia de aplicación llamada app o application, y luego cualquier instancia de aplicación. Si no se encuentra ninguna instancia, el comando busca una función de fábrica llamada create_app o make_app que devuelva una instancia.

Si los paréntesis siguen al nombre de la fábrica, su contenido se analiza como literales de Python y se pasa como argumentos y palabras clave a la función. Esto significa que las cadenas deben seguir estando entre comillas.

Ejecutar el servidor de desarrollo

El comando run iniciará el servidor de desarrollo. Sustituye al método Flask.run() en la mayoría de los casos.

$ flask --app hello run
 * Serving Flask app "hello"
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

Advertencia

No utilice este comando para ejecutar su aplicación en producción. Utilice el servidor de desarrollo sólo durante el desarrollo. El servidor de desarrollo se proporciona por conveniencia, pero no está diseñado para ser particularmente seguro, estable o eficiente. Vea Despliegue en producción para saber cómo ejecutar en producción.

Si otro programa ya está usando el puerto 5000, verás OSError: [Errno 98] o OSError: [WinError 10013] cuando el servidor intente iniciarse. Ver Dirección ya utilizada para saber cómo manejar esto.

Modo depuración

In debug mode, the flask run command will enable the interactive debugger and the reloader by default, and make errors easier to see and debug. To enable debug mode, use the --debug option.

$ flask --app hello run --debug
 * Serving Flask app "hello"
 * Debug mode: on
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with inotify reloader
 * Debugger is active!
 * Debugger PIN: 223-456-919

The --debug option can also be passed to the top level flask command to enable debug mode for any command. The following two run calls are equivalent.

$ flask --app hello --debug run
$ flask --app hello run --debug

Watch and Ignore Files with the Reloader

When using debug mode, the reloader will trigger whenever your Python code or imported modules change. The reloader can watch additional files with the --extra-files option. Multiple paths are separated with :, or ; on Windows.

$ flask run --extra-files file1:dirA/file2:dirB/
 * Running on http://127.0.0.1:8000/
 * Detected change in '/path/to/file1', reloading

El recargador también puede ignorar los archivos que utilizan patrones fnmatch con la opción --exclude-patterns. Los patrones múltiples se separan con :, o ; en Windows.

Abrir un Shell

Para explorar los datos de tu aplicación, puedes iniciar un shell interactivo de Python con el comando shell. Se activará un contexto de aplicación y se importará la instancia de la app

$ flask shell
Python 3.10.0 (default, Oct 27 2021, 06:59:51) [GCC 11.1.0] on linux
App: example [production]
Instance: /home/david/Projects/pallets/flask/instance
>>>

Utilice shell_context_processor() para añadir otras importaciones automáticas.

Variables de entorno de dotenv

El comando flask permite establecer cualquier opción para cualquier comando con variables de entorno. Las variables se denominan FLASK_OPTION o FLASK_COMMAND_OPTION, por ejemplo FLASK_APP o FLASK_RUN_PORT.

En lugar de pasar opciones cada vez que se ejecuta un comando, o variables de entorno cada vez que se abre un nuevo terminal, se puede utilizar el soporte dotenv de Flask para establecer variables de entorno automáticamente.

Si python-dotenv está instalado, al ejecutar el comando flask se establecerán las variables de entorno definidas en los archivos .env y .flaskenv. También puedes especificar un archivo extra para cargar con la opción --env-file. Los archivos Dotenv se pueden utilizar para evitar tener que establecer --app o FLASK_APP manualmente, y para establecer la configuración utilizando variables de entorno de forma similar a como funcionan algunos servicios de despliegue.

Las variables establecidas en la línea de comandos se utilizan sobre las establecidas en .env, que se utilizan sobre las establecidas en .flaskenv. .flaskenv debe utilizarse para las variables públicas, como FLASK_APP, mientras que .env no debe confirmarse en su repositorio para que pueda establecer variables privadas.

Los directorios se exploran hacia arriba desde el directorio desde el que se llama a flask para localizar los archivos.

Los archivos sólo se cargan con el comando flask o llamando a run(). Si desea cargar estos archivos cuando se ejecuta en producción, debe llamar a load_dotenv() manualmente.

Configuración de las opciones de comando

Click está configurado para cargar los valores por defecto de las opciones de comando desde las variables de entorno. Las variables utilizan el patrón FLASK_COMMAND_OPTION. Por ejemplo, para establecer el puerto para el comando de ejecución, en lugar de flask run --port 8000:

$ export FLASK_RUN_PORT=8000
$ flask run
 * Running on http://127.0.0.1:8000/

Se pueden añadir al archivo .flaskenv al igual que FLASK_APP para controlar las opciones de los comandos por defecto.

Desactivar dotenv

El comando flask mostrará un mensaje si detecta archivos dotenv pero python-dotenv no está instalado.

$ flask run
 * Tip: There are .env files present. Do "pip install python-dotenv" to use them.

Puedes decirle a Flask que no cargue los archivos dotenv incluso cuando python-dotenv está instalado estableciendo la variable de entorno FLASK_SKIP_DOTENV. Esto puede ser útil si quieres cargarlos manualmente, o si estás usando un ejecutor de proyecto que ya los carga. Ten en cuenta que las variables de entorno deben establecerse antes de que la aplicación se cargue o no se configurará como se espera.

$ export FLASK_SKIP_DOTENV=1
$ flask run

Variables de entorno de virtualenv

Si no quieres instalar el soporte de dotenv, puedes establecer las variables de entorno añadiéndolas al final del script activate del virtualenv. Al activar el virtualenv se establecerán las variables.

Unix Bash, .venv/bin/activate:

$ export FLASK_APP=hello

Es preferible usar el soporte de dotenv sobre esto, ya que .flaskenv puede ser comprometido en el repositorio para que funcione automáticamente dondequiera que el proyecto sea revisado.

Comandos personalizados

El comando flask se implementa usando Click. Consulte la documentación de ese proyecto para obtener información completa sobre la escritura de comandos.

Este ejemplo añade el comando create-user que toma el argumento name.

import click
from flask import Flask

app = Flask(__name__)

@app.cli.command("create-user")
@click.argument("name")
def create_user(name):
    ...

$ flask create-user admin

Este ejemplo añade el mismo comando, pero como user create, un comando en un grupo. Esto es útil si quieres organizar múltiples comandos relacionados

import click
from flask import Flask
from flask.cli import AppGroup

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

@user_cli.command('create')
@click.argument('name')
def create_user(name):
    ...

app.cli.add_command(user_cli)

$ flask user create demo

Vea Ejecución de comandos con el CLI Runner para una visión general de cómo probar sus comandos personalizados.

Registro de comandos con Blueprints

Si tu aplicación utiliza blueprints, puedes registrar opcionalmente comandos CLI directamente en ellos. Cuando tu blueprint esté registrado en tu aplicación, los comandos asociados estarán disponibles para el comando flask. Por defecto, esos comandos estarán anidados en un grupo que coincide con el nombre del blueprint.

from flask import Blueprint

bp = Blueprint('students', __name__)

@bp.cli.command('create')
@click.argument('name')
def create(name):
    ...

app.register_blueprint(bp)

$ flask students create alice

Se puede modificar el nombre del grupo especificando el parámetro cli_group al crear el objeto Blueprint, o posteriormente con app.register_blueprint(bp, cli_group='...'). Los siguientes son equivalentes:

bp = Blueprint('students', __name__, cli_group='other')
# or
app.register_blueprint(bp, cli_group='other')

$ flask other create alice

Especificando cli_group=None se eliminará el anidamiento y se fusionarán los comandos directamente al nivel de la aplicación:

bp = Blueprint('students', __name__, cli_group=None)
# or
app.register_blueprint(bp, cli_group=None)

$ flask create alice

Contexto de la aplicación

Los comandos añadidos usando el decorador cli o FlaskGroup command() de la aplicación se ejecutarán con un contexto de aplicación empujado, por lo que tus comandos y parámetros personalizados tienen acceso a la aplicación y su configuración. El decorador with_appcontext() puede utilizarse para obtener el mismo comportamiento, pero no es necesario en la mayoría de los casos.

import click
from flask.cli import with_appcontext

@click.command()
@with_appcontext
def do_work():
    ...

app.cli.add_command(do_work)

Plugins

Flask will automatically load commands specified in the flask.commands entry point. This is useful for extensions that want to add commands when they are installed. Entry points are specified in pyproject.toml:

[project.entry-points."flask.commands"]
my-command = "my_extension.commands:cli"

Inside my_extension/commands.py you can then export a Click object:

import click

@click.command()
def cli():
    ...

Una vez que ese paquete está instalado en el mismo virtualenv que tu proyecto Flask, puedes ejecutar flask my-command para invocar el comando.

Scripts personalizados

Cuando se utiliza el patrón de fábrica de aplicaciones, puede ser más conveniente definir su propio script Click. En lugar de usar --app y dejar que Flask cargue tu aplicación, puedes crear tu propio objeto Click y exportarlo como un punto de entrada de script de consola.

Crea una instancia de FlaskGroup y pásale la fábrica:

import click
from flask import Flask
from flask.cli import FlaskGroup

def create_app():
    app = Flask('wiki')
    # other setup
    return app

@click.group(cls=FlaskGroup, create_app=create_app)
def cli():
    """Management script for the Wiki application."""

Define the entry point in pyproject.toml:

[project.scripts]
wiki = "wiki:cli"

Instala la aplicación en el virtualenv en modo editable y el script personalizado estará disponible. Tenga en cuenta que no es necesario establecer --app.

$ pip install -e .
$ wiki run

Errores en los scripts personalizados

Cuando se utiliza un script personalizado, si se introduce un error en el código a nivel de módulo, el recargador fallará porque ya no puede cargar el punto de entrada.

El comando flask, al estar separado de su código, no tiene este problema y se recomienda en la mayoría de los casos.

Integración de PyCharm

PyCharm Professional provides a special Flask run configuration to run the development server. For the Community Edition, and for other commands besides run, you need to create a custom run configuration. These instructions should be similar for any other IDE you use.

In PyCharm, with your project open, click on Run from the menu bar and go to Edit Configurations. You’ll see a screen similar to this:

Screenshot of PyCharm run configuration.

Once you create a configuration for the flask run, you can copy and change it to call any other command.

Click the + (Add New Configuration) button and select Python. Give the configuration a name such as «flask run».

Click the Script path dropdown and change it to Module name, then input flask.

The Parameters field is set to the CLI command to execute along with any arguments. This example uses --app hello run --debug, which will run the development server in debug mode. --app hello should be the import or file with your Flask app.

If you installed your project as a package in your virtualenv, you may uncheck the PYTHONPATH options. This will more accurately match how you deploy later.

Click OK to save and close the configuration. Select the configuration in the main PyCharm window and click the play button next to it to run the server.

Now that you have a configuration for flask run, you can copy that configuration and change the Parameters argument to run a different CLI command.