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

Importa la ruta 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 a 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

En modo depuración, el comando flask run activará el depurador interactivo y el recargador por defecto, y hará que los errores sean más fáciles de ver y depurar. Para activar el modo de depuración, utilice la opción --debug.

$ 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

La opción --debug también se puede pasar al comando de nivel superior flask para activar el modo de depuración para cualquier comando. Las siguientes dos llamadas run son equivalentes.

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

Ver e ignorar archivos con el Reloader

Cuando se utiliza el modo de depuración, el recargador se activará cada vez que cambie tu código Python o los módulos importados. El recargador puede vigilar archivos adicionales con la opción --extra-files. Las rutas múltiples se separan con :, o ; en 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 cargará automáticamente los comandos especificados en la entrada`_ ``flask.commands. Esto es útil para extensiones que quieren añadir comandos cuando se instalan. Los puntos de entrada se especifican en pyproject.toml:

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

Dentro de my_extension/commands.py puedes exportar un objeto Click:

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 el punto de entrada en 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 proporciona una configuración especial de ejecución de Flask para ejecutar el servidor de desarrollo. Para la Community Edition, y para otros comandos además de run, necesitas crear una configuración de ejecución personalizada. Estas instrucciones deben ser similares para cualquier otro IDE que utilice.

En PyCharm, con tu proyecto abierto, haz click en Run de la barra de menú y ve a Edit Configurations. Verás una pantalla similar a esta:

Captura de pantalla de la configuración de ejecución de PyCharm.

Una vez creada una configuración para flask run, puedes copiarla y cambiarla para llamar a cualquier otro comando.

Haz clic en el botón + (Añadir nueva configuración) y selecciona Python. Dale a la configuración un nombre como «flask run».

Haga clic en el menú desplegable Ruta del script y cámbielo por Nombre del módulo, luego introduzca flask.

El campo Parameters se establece en el comando CLI a ejecutar junto con cualquier argumento. Este ejemplo usa --app hello run --debug, que ejecutará el servidor de desarrollo en modo depuración. --app hello debe ser la importación o el archivo con tu aplicación Flask.

Si ha instalado su proyecto como un paquete en su virtualenv, puede desmarcar las opciones PYTHONPATH. Esto se ajustará con mayor precisión a la forma de desplegar más tarde.

Haga clic en OK para guardar y cerrar la configuración. Seleccione la configuración en la ventana principal de PyCharm y haga clic en el botón de reproducción junto a ella para ejecutar el servidor.

Ahora que tienes una configuración para flask run, puedes copiar esa configuración y cambiar el argumento Parameters para ejecutar un comando CLI diferente.