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 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.

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.

Entornos

Changelog

Nuevo en la versión 1.0.

El entorno en el que se ejecuta la aplicación Flask se establece mediante la variable de entorno FLASK_ENV. Cuando se utiliza el comando flask, también se puede establecer con la opción --env. Si no se establece, el valor por defecto es production. El otro entorno reconocido es development. Flask y las extensiones pueden elegir habilitar comportamientos basados en el entorno.

Si el entorno está configurado como development, el comando flask habilitará el modo de depuración y flask run habilitará el depurador interactivo y el recargador.

$ flask --app hello --env development run
 * Serving Flask app "hello"
 * Environment: development
 * 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

Vigilar los archivos extra con el Recargador

Cuando se utiliza el modo de desarrollo, el recargador se activará cada vez que el código Python o los módulos importados cambien. El recargador puede observar 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

Ignorar archivos con el Reloader

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.

Modo depuración

El modo de depuración se activará cuando el entorno de ejecución sea development, como se ha descrito anteriormente. Si desea controlar el modo de depuración por separado, utilice la opción --debug/--no-debug o la variable de entorno FLASK_DEBUG.

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 el flask.commands entry point. Esto es útil para las extensiones que quieren añadir comandos cuando se instalan. Los puntos de entrada se especifican en setup.py

from setuptools import setup

setup(
    name='flask-my-extension',
    ...,
    entry_points={
        'flask.commands': [
            'my-command=flask_my_extension.commands:cli'
        ],
    },
)

Dentro de flask_my_extension/commands.py puedes entonces 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."""

Definir el entry point en setup.py:

from setuptools import setup

setup(
    name='flask-my-extension',
    ...,
    entry_points={
        'console_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 para la ejecución de Flask. Para la Community Edition, necesitamos configurarlo para llamar al comando CLI flask run con las variables de entorno correctas. Estas instrucciones deberían ser similares para cualquier otro IDE que quieras utilizar.

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

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

Hay bastantes opciones para cambiar, pero una vez que lo hayamos hecho para un comando, podemos copiar fácilmente toda la configuración y hacer un solo ajuste para darnos acceso a otros comandos, incluyendo los personalizados que puedas implementar tú mismo.

Haz clic en el botón + (Add New Configuration) y selecciona Python. Dale a la configuración un nombre como «flask run». Para el comando flask run, marca «Single instance only» ya que no puedes ejecutar el servidor más de una vez al mismo tiempo.

Seleccione Module name en el desplegable (A) y luego introduzca flask.

El campo Parameters (B) se establece con el comando CLI a ejecutar (con cualquier argumento). En este ejemplo usamos run, que ejecutará el servidor de desarrollo.

Puedes omitir este paso si utilizas Variables de entorno de dotenv. Necesitamos añadir una variable de entorno (C) para identificar nuestra aplicación. Haz clic en el botón Examinar y añade una entrada con FLASK_APP a la izquierda y la importación o archivo de Python a la derecha (hello por ejemplo). Añade una entrada con FLASK_ENV y ponla en development.

A continuación tenemos que establecer el directorio de trabajo (D) para que sea la carpeta donde reside nuestra aplicación.

Si has instalado tu proyecto como un paquete en tu virtualenv, puedes desmarcar las opciones PYTHONPATH (E). Esto se ajustará mejor a la forma de desplegar la aplicación más adelante.

Haga clic en Apply para guardar la configuración, o en Aceptar para guardar y cerrar la ventana. 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 tenemos una configuración que ejecuta flask run desde PyCharm, podemos copiar esa configuración y alterar el argumento Script para ejecutar un comando CLI diferente, por ejemplo flask shell.