forked from orbit-oss/flask
da60039486
When the 'flask' command is used with only the '--help' parameter, this change will make sure to try and load the app before the help callback is run. This was previously only being done when the 'flask' command was used by itself. This meant when passing in '--help', any custom commands were not getting shown in the help message. With this change, custom commands will be included in the help message when running 'flask' on the command line by itself or with the '--help' parameter.
1135 lines
36 KiB
Python
1135 lines
36 KiB
Python
from __future__ import annotations
|
|
|
|
import ast
|
|
import collections.abc as cabc
|
|
import importlib.metadata
|
|
import inspect
|
|
import os
|
|
import platform
|
|
import re
|
|
import sys
|
|
import traceback
|
|
import typing as t
|
|
from functools import update_wrapper
|
|
from operator import itemgetter
|
|
from types import ModuleType
|
|
|
|
import click
|
|
from click.core import ParameterSource
|
|
from werkzeug import run_simple
|
|
from werkzeug.serving import is_running_from_reloader
|
|
from werkzeug.utils import import_string
|
|
|
|
from .globals import current_app
|
|
from .helpers import get_debug_flag
|
|
from .helpers import get_load_dotenv
|
|
|
|
if t.TYPE_CHECKING:
|
|
import ssl
|
|
|
|
from _typeshed.wsgi import StartResponse
|
|
from _typeshed.wsgi import WSGIApplication
|
|
from _typeshed.wsgi import WSGIEnvironment
|
|
|
|
from .app import Flask
|
|
|
|
|
|
class NoAppException(click.UsageError):
|
|
"""Raised if an application cannot be found or loaded."""
|
|
|
|
|
|
def find_best_app(module: ModuleType) -> Flask:
|
|
"""Given a module instance this tries to find the best possible
|
|
application in the module or raises an exception.
|
|
"""
|
|
from . import Flask
|
|
|
|
# Search for the most common names first.
|
|
for attr_name in ("app", "application"):
|
|
app = getattr(module, attr_name, None)
|
|
|
|
if isinstance(app, Flask):
|
|
return app
|
|
|
|
# Otherwise find the only object that is a Flask instance.
|
|
matches = [v for v in module.__dict__.values() if isinstance(v, Flask)]
|
|
|
|
if len(matches) == 1:
|
|
return matches[0]
|
|
elif len(matches) > 1:
|
|
raise NoAppException(
|
|
"Detected multiple Flask applications in module"
|
|
f" '{module.__name__}'. Use '{module.__name__}:name'"
|
|
" to specify the correct one."
|
|
)
|
|
|
|
# Search for app factory functions.
|
|
for attr_name in ("create_app", "make_app"):
|
|
app_factory = getattr(module, attr_name, None)
|
|
|
|
if inspect.isfunction(app_factory):
|
|
try:
|
|
app = app_factory()
|
|
|
|
if isinstance(app, Flask):
|
|
return app
|
|
except TypeError as e:
|
|
if not _called_with_wrong_args(app_factory):
|
|
raise
|
|
|
|
raise NoAppException(
|
|
f"Detected factory '{attr_name}' in module '{module.__name__}',"
|
|
" but could not call it without arguments. Use"
|
|
f" '{module.__name__}:{attr_name}(args)'"
|
|
" to specify arguments."
|
|
) from e
|
|
|
|
raise NoAppException(
|
|
"Failed to find Flask application or factory in module"
|
|
f" '{module.__name__}'. Use '{module.__name__}:name'"
|
|
" to specify one."
|
|
)
|
|
|
|
|
|
def _called_with_wrong_args(f: t.Callable[..., Flask]) -> bool:
|
|
"""Check whether calling a function raised a ``TypeError`` because
|
|
the call failed or because something in the factory raised the
|
|
error.
|
|
|
|
:param f: The function that was called.
|
|
:return: ``True`` if the call failed.
|
|
"""
|
|
tb = sys.exc_info()[2]
|
|
|
|
try:
|
|
while tb is not None:
|
|
if tb.tb_frame.f_code is f.__code__:
|
|
# In the function, it was called successfully.
|
|
return False
|
|
|
|
tb = tb.tb_next
|
|
|
|
# Didn't reach the function.
|
|
return True
|
|
finally:
|
|
# Delete tb to break a circular reference.
|
|
# https://docs.python.org/2/library/sys.html#sys.exc_info
|
|
del tb
|
|
|
|
|
|
def find_app_by_string(module: ModuleType, app_name: str) -> Flask:
|
|
"""Check if the given string is a variable name or a function. Call
|
|
a function to get the app instance, or return the variable directly.
|
|
"""
|
|
from . import Flask
|
|
|
|
# Parse app_name as a single expression to determine if it's a valid
|
|
# attribute name or function call.
|
|
try:
|
|
expr = ast.parse(app_name.strip(), mode="eval").body
|
|
except SyntaxError:
|
|
raise NoAppException(
|
|
f"Failed to parse {app_name!r} as an attribute name or function call."
|
|
) from None
|
|
|
|
if isinstance(expr, ast.Name):
|
|
name = expr.id
|
|
args = []
|
|
kwargs = {}
|
|
elif isinstance(expr, ast.Call):
|
|
# Ensure the function name is an attribute name only.
|
|
if not isinstance(expr.func, ast.Name):
|
|
raise NoAppException(
|
|
f"Function reference must be a simple name: {app_name!r}."
|
|
)
|
|
|
|
name = expr.func.id
|
|
|
|
# Parse the positional and keyword arguments as literals.
|
|
try:
|
|
args = [ast.literal_eval(arg) for arg in expr.args]
|
|
kwargs = {
|
|
kw.arg: ast.literal_eval(kw.value)
|
|
for kw in expr.keywords
|
|
if kw.arg is not None
|
|
}
|
|
except ValueError:
|
|
# literal_eval gives cryptic error messages, show a generic
|
|
# message with the full expression instead.
|
|
raise NoAppException(
|
|
f"Failed to parse arguments as literal values: {app_name!r}."
|
|
) from None
|
|
else:
|
|
raise NoAppException(
|
|
f"Failed to parse {app_name!r} as an attribute name or function call."
|
|
)
|
|
|
|
try:
|
|
attr = getattr(module, name)
|
|
except AttributeError as e:
|
|
raise NoAppException(
|
|
f"Failed to find attribute {name!r} in {module.__name__!r}."
|
|
) from e
|
|
|
|
# If the attribute is a function, call it with any args and kwargs
|
|
# to get the real application.
|
|
if inspect.isfunction(attr):
|
|
try:
|
|
app = attr(*args, **kwargs)
|
|
except TypeError as e:
|
|
if not _called_with_wrong_args(attr):
|
|
raise
|
|
|
|
raise NoAppException(
|
|
f"The factory {app_name!r} in module"
|
|
f" {module.__name__!r} could not be called with the"
|
|
" specified arguments."
|
|
) from e
|
|
else:
|
|
app = attr
|
|
|
|
if isinstance(app, Flask):
|
|
return app
|
|
|
|
raise NoAppException(
|
|
"A valid Flask application was not obtained from"
|
|
f" '{module.__name__}:{app_name}'."
|
|
)
|
|
|
|
|
|
def prepare_import(path: str) -> str:
|
|
"""Given a filename this will try to calculate the python path, add it
|
|
to the search path and return the actual module name that is expected.
|
|
"""
|
|
path = os.path.realpath(path)
|
|
|
|
fname, ext = os.path.splitext(path)
|
|
if ext == ".py":
|
|
path = fname
|
|
|
|
if os.path.basename(path) == "__init__":
|
|
path = os.path.dirname(path)
|
|
|
|
module_name = []
|
|
|
|
# move up until outside package structure (no __init__.py)
|
|
while True:
|
|
path, name = os.path.split(path)
|
|
module_name.append(name)
|
|
|
|
if not os.path.exists(os.path.join(path, "__init__.py")):
|
|
break
|
|
|
|
if sys.path[0] != path:
|
|
sys.path.insert(0, path)
|
|
|
|
return ".".join(module_name[::-1])
|
|
|
|
|
|
@t.overload
|
|
def locate_app(
|
|
module_name: str, app_name: str | None, raise_if_not_found: t.Literal[True] = True
|
|
) -> Flask: ...
|
|
|
|
|
|
@t.overload
|
|
def locate_app(
|
|
module_name: str, app_name: str | None, raise_if_not_found: t.Literal[False] = ...
|
|
) -> Flask | None: ...
|
|
|
|
|
|
def locate_app(
|
|
module_name: str, app_name: str | None, raise_if_not_found: bool = True
|
|
) -> Flask | None:
|
|
try:
|
|
__import__(module_name)
|
|
except ImportError:
|
|
# Reraise the ImportError if it occurred within the imported module.
|
|
# Determine this by checking whether the trace has a depth > 1.
|
|
if sys.exc_info()[2].tb_next: # type: ignore[union-attr]
|
|
raise NoAppException(
|
|
f"While importing {module_name!r}, an ImportError was"
|
|
f" raised:\n\n{traceback.format_exc()}"
|
|
) from None
|
|
elif raise_if_not_found:
|
|
raise NoAppException(f"Could not import {module_name!r}.") from None
|
|
else:
|
|
return None
|
|
|
|
module = sys.modules[module_name]
|
|
|
|
if app_name is None:
|
|
return find_best_app(module)
|
|
else:
|
|
return find_app_by_string(module, app_name)
|
|
|
|
|
|
def get_version(ctx: click.Context, param: click.Parameter, value: t.Any) -> None:
|
|
if not value or ctx.resilient_parsing:
|
|
return
|
|
|
|
flask_version = importlib.metadata.version("flask")
|
|
werkzeug_version = importlib.metadata.version("werkzeug")
|
|
|
|
click.echo(
|
|
f"Python {platform.python_version()}\n"
|
|
f"Flask {flask_version}\n"
|
|
f"Werkzeug {werkzeug_version}",
|
|
color=ctx.color,
|
|
)
|
|
ctx.exit()
|
|
|
|
|
|
version_option = click.Option(
|
|
["--version"],
|
|
help="Show the Flask version.",
|
|
expose_value=False,
|
|
callback=get_version,
|
|
is_flag=True,
|
|
is_eager=True,
|
|
)
|
|
|
|
|
|
class ScriptInfo:
|
|
"""Helper object to deal with Flask applications. This is usually not
|
|
necessary to interface with as it's used internally in the dispatching
|
|
to click. In future versions of Flask this object will most likely play
|
|
a bigger role. Typically it's created automatically by the
|
|
:class:`FlaskGroup` but you can also manually create it and pass it
|
|
onwards as click object.
|
|
|
|
.. versionchanged:: 3.1
|
|
Added the ``load_dotenv_defaults`` parameter and attribute.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
app_import_path: str | None = None,
|
|
create_app: t.Callable[..., Flask] | None = None,
|
|
set_debug_flag: bool = True,
|
|
load_dotenv_defaults: bool = True,
|
|
) -> None:
|
|
#: Optionally the import path for the Flask application.
|
|
self.app_import_path = app_import_path
|
|
#: Optionally a function that is passed the script info to create
|
|
#: the instance of the application.
|
|
self.create_app = create_app
|
|
#: A dictionary with arbitrary data that can be associated with
|
|
#: this script info.
|
|
self.data: dict[t.Any, t.Any] = {}
|
|
self.set_debug_flag = set_debug_flag
|
|
|
|
self.load_dotenv_defaults = get_load_dotenv(load_dotenv_defaults)
|
|
"""Whether default ``.flaskenv`` and ``.env`` files should be loaded.
|
|
|
|
``ScriptInfo`` doesn't load anything, this is for reference when doing
|
|
the load elsewhere during processing.
|
|
|
|
.. versionadded:: 3.1
|
|
"""
|
|
|
|
self._loaded_app: Flask | None = None
|
|
|
|
def load_app(self) -> Flask:
|
|
"""Loads the Flask app (if not yet loaded) and returns it. Calling
|
|
this multiple times will just result in the already loaded app to
|
|
be returned.
|
|
"""
|
|
if self._loaded_app is not None:
|
|
return self._loaded_app
|
|
app: Flask | None = None
|
|
if self.create_app is not None:
|
|
app = self.create_app()
|
|
else:
|
|
if self.app_import_path:
|
|
path, name = (
|
|
re.split(r":(?![\\/])", self.app_import_path, maxsplit=1) + [None]
|
|
)[:2]
|
|
import_name = prepare_import(path)
|
|
app = locate_app(import_name, name)
|
|
else:
|
|
for path in ("wsgi.py", "app.py"):
|
|
import_name = prepare_import(path)
|
|
app = locate_app(import_name, None, raise_if_not_found=False)
|
|
|
|
if app is not None:
|
|
break
|
|
|
|
if app is None:
|
|
raise NoAppException(
|
|
"Could not locate a Flask application. Use the"
|
|
" 'flask --app' option, 'FLASK_APP' environment"
|
|
" variable, or a 'wsgi.py' or 'app.py' file in the"
|
|
" current directory."
|
|
)
|
|
|
|
if self.set_debug_flag:
|
|
# Update the app's debug flag through the descriptor so that
|
|
# other values repopulate as well.
|
|
app.debug = get_debug_flag()
|
|
|
|
self._loaded_app = app
|
|
return app
|
|
|
|
|
|
pass_script_info = click.make_pass_decorator(ScriptInfo, ensure=True)
|
|
|
|
F = t.TypeVar("F", bound=t.Callable[..., t.Any])
|
|
|
|
|
|
def with_appcontext(f: F) -> F:
|
|
"""Wraps a callback so that it's guaranteed to be executed with the
|
|
script's application context.
|
|
|
|
Custom commands (and their options) registered under ``app.cli`` or
|
|
``blueprint.cli`` will always have an app context available, this
|
|
decorator is not required in that case.
|
|
|
|
.. versionchanged:: 2.2
|
|
The app context is active for subcommands as well as the
|
|
decorated callback. The app context is always available to
|
|
``app.cli`` command and parameter callbacks.
|
|
"""
|
|
|
|
@click.pass_context
|
|
def decorator(ctx: click.Context, /, *args: t.Any, **kwargs: t.Any) -> t.Any:
|
|
if not current_app:
|
|
app = ctx.ensure_object(ScriptInfo).load_app()
|
|
ctx.with_resource(app.app_context())
|
|
|
|
return ctx.invoke(f, *args, **kwargs)
|
|
|
|
return update_wrapper(decorator, f) # type: ignore[return-value]
|
|
|
|
|
|
class AppGroup(click.Group):
|
|
"""This works similar to a regular click :class:`~click.Group` but it
|
|
changes the behavior of the :meth:`command` decorator so that it
|
|
automatically wraps the functions in :func:`with_appcontext`.
|
|
|
|
Not to be confused with :class:`FlaskGroup`.
|
|
"""
|
|
|
|
def command( # type: ignore[override]
|
|
self, *args: t.Any, **kwargs: t.Any
|
|
) -> t.Callable[[t.Callable[..., t.Any]], click.Command]:
|
|
"""This works exactly like the method of the same name on a regular
|
|
:class:`click.Group` but it wraps callbacks in :func:`with_appcontext`
|
|
unless it's disabled by passing ``with_appcontext=False``.
|
|
"""
|
|
wrap_for_ctx = kwargs.pop("with_appcontext", True)
|
|
|
|
def decorator(f: t.Callable[..., t.Any]) -> click.Command:
|
|
if wrap_for_ctx:
|
|
f = with_appcontext(f)
|
|
return super(AppGroup, self).command(*args, **kwargs)(f) # type: ignore[no-any-return]
|
|
|
|
return decorator
|
|
|
|
def group( # type: ignore[override]
|
|
self, *args: t.Any, **kwargs: t.Any
|
|
) -> t.Callable[[t.Callable[..., t.Any]], click.Group]:
|
|
"""This works exactly like the method of the same name on a regular
|
|
:class:`click.Group` but it defaults the group class to
|
|
:class:`AppGroup`.
|
|
"""
|
|
kwargs.setdefault("cls", AppGroup)
|
|
return super().group(*args, **kwargs) # type: ignore[no-any-return]
|
|
|
|
|
|
def _set_app(ctx: click.Context, param: click.Option, value: str | None) -> str | None:
|
|
if value is None:
|
|
return None
|
|
|
|
info = ctx.ensure_object(ScriptInfo)
|
|
info.app_import_path = value
|
|
return value
|
|
|
|
|
|
# This option is eager so the app will be available if --help is given.
|
|
# --help is also eager, so --app must be before it in the param list.
|
|
# no_args_is_help bypasses eager processing, so this option must be
|
|
# processed manually in that case to ensure FLASK_APP gets picked up.
|
|
_app_option = click.Option(
|
|
["-A", "--app"],
|
|
metavar="IMPORT",
|
|
help=(
|
|
"The Flask application or factory function to load, in the form 'module:name'."
|
|
" Module can be a dotted import or file path. Name is not required if it is"
|
|
" 'app', 'application', 'create_app', or 'make_app', and can be 'name(args)' to"
|
|
" pass arguments."
|
|
),
|
|
is_eager=True,
|
|
expose_value=False,
|
|
callback=_set_app,
|
|
)
|
|
|
|
|
|
def _set_debug(ctx: click.Context, param: click.Option, value: bool) -> bool | None:
|
|
# If the flag isn't provided, it will default to False. Don't use
|
|
# that, let debug be set by env in that case.
|
|
source = ctx.get_parameter_source(param.name) # type: ignore[arg-type]
|
|
|
|
if source is not None and source in (
|
|
ParameterSource.DEFAULT,
|
|
ParameterSource.DEFAULT_MAP,
|
|
):
|
|
return None
|
|
|
|
# Set with env var instead of ScriptInfo.load so that it can be
|
|
# accessed early during a factory function.
|
|
os.environ["FLASK_DEBUG"] = "1" if value else "0"
|
|
return value
|
|
|
|
|
|
_debug_option = click.Option(
|
|
["--debug/--no-debug"],
|
|
help="Set debug mode.",
|
|
expose_value=False,
|
|
callback=_set_debug,
|
|
)
|
|
|
|
|
|
def _env_file_callback(
|
|
ctx: click.Context, param: click.Option, value: str | None
|
|
) -> str | None:
|
|
try:
|
|
import dotenv # noqa: F401
|
|
except ImportError:
|
|
# Only show an error if a value was passed, otherwise we still want to
|
|
# call load_dotenv and show a message without exiting.
|
|
if value is not None:
|
|
raise click.BadParameter(
|
|
"python-dotenv must be installed to load an env file.",
|
|
ctx=ctx,
|
|
param=param,
|
|
) from None
|
|
|
|
# Load if a value was passed, or we want to load default files, or both.
|
|
if value is not None or ctx.obj.load_dotenv_defaults:
|
|
load_dotenv(value, load_defaults=ctx.obj.load_dotenv_defaults)
|
|
|
|
return value
|
|
|
|
|
|
# This option is eager so env vars are loaded as early as possible to be
|
|
# used by other options.
|
|
_env_file_option = click.Option(
|
|
["-e", "--env-file"],
|
|
type=click.Path(exists=True, dir_okay=False),
|
|
help=(
|
|
"Load environment variables from this file, taking precedence over"
|
|
" those set by '.env' and '.flaskenv'. Variables set directly in the"
|
|
" environment take highest precedence. python-dotenv must be installed."
|
|
),
|
|
is_eager=True,
|
|
expose_value=False,
|
|
callback=_env_file_callback,
|
|
)
|
|
|
|
|
|
class FlaskGroup(AppGroup):
|
|
"""Special subclass of the :class:`AppGroup` group that supports
|
|
loading more commands from the configured Flask app. Normally a
|
|
developer does not have to interface with this class but there are
|
|
some very advanced use cases for which it makes sense to create an
|
|
instance of this. see :ref:`custom-scripts`.
|
|
|
|
:param add_default_commands: if this is True then the default run and
|
|
shell commands will be added.
|
|
:param add_version_option: adds the ``--version`` option.
|
|
:param create_app: an optional callback that is passed the script info and
|
|
returns the loaded app.
|
|
:param load_dotenv: Load the nearest :file:`.env` and :file:`.flaskenv`
|
|
files to set environment variables. Will also change the working
|
|
directory to the directory containing the first file found.
|
|
:param set_debug_flag: Set the app's debug flag.
|
|
|
|
.. versionchanged:: 3.1
|
|
``-e path`` takes precedence over default ``.env`` and ``.flaskenv`` files.
|
|
|
|
.. versionchanged:: 2.2
|
|
Added the ``-A/--app``, ``--debug/--no-debug``, ``-e/--env-file`` options.
|
|
|
|
.. versionchanged:: 2.2
|
|
An app context is pushed when running ``app.cli`` commands, so
|
|
``@with_appcontext`` is no longer required for those commands.
|
|
|
|
.. versionchanged:: 1.0
|
|
If installed, python-dotenv will be used to load environment variables
|
|
from :file:`.env` and :file:`.flaskenv` files.
|
|
"""
|
|
|
|
def __init__(
|
|
self,
|
|
add_default_commands: bool = True,
|
|
create_app: t.Callable[..., Flask] | None = None,
|
|
add_version_option: bool = True,
|
|
load_dotenv: bool = True,
|
|
set_debug_flag: bool = True,
|
|
**extra: t.Any,
|
|
) -> None:
|
|
params: list[click.Parameter] = list(extra.pop("params", None) or ())
|
|
# Processing is done with option callbacks instead of a group
|
|
# callback. This allows users to make a custom group callback
|
|
# without losing the behavior. --env-file must come first so
|
|
# that it is eagerly evaluated before --app.
|
|
params.extend((_env_file_option, _app_option, _debug_option))
|
|
|
|
if add_version_option:
|
|
params.append(version_option)
|
|
|
|
if "context_settings" not in extra:
|
|
extra["context_settings"] = {}
|
|
|
|
extra["context_settings"].setdefault("auto_envvar_prefix", "FLASK")
|
|
|
|
super().__init__(params=params, **extra)
|
|
|
|
self.create_app = create_app
|
|
self.load_dotenv = load_dotenv
|
|
self.set_debug_flag = set_debug_flag
|
|
|
|
if add_default_commands:
|
|
self.add_command(run_command)
|
|
self.add_command(shell_command)
|
|
self.add_command(routes_command)
|
|
|
|
self._loaded_plugin_commands = False
|
|
|
|
def _load_plugin_commands(self) -> None:
|
|
if self._loaded_plugin_commands:
|
|
return
|
|
|
|
if sys.version_info >= (3, 10):
|
|
from importlib import metadata
|
|
else:
|
|
# Use a backport on Python < 3.10. We technically have
|
|
# importlib.metadata on 3.8+, but the API changed in 3.10,
|
|
# so use the backport for consistency.
|
|
import importlib_metadata as metadata # pyright: ignore
|
|
|
|
for ep in metadata.entry_points(group="flask.commands"):
|
|
self.add_command(ep.load(), ep.name)
|
|
|
|
self._loaded_plugin_commands = True
|
|
|
|
def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
|
|
self._load_plugin_commands()
|
|
# Look up built-in and plugin commands, which should be
|
|
# available even if the app fails to load.
|
|
rv = super().get_command(ctx, name)
|
|
|
|
if rv is not None:
|
|
return rv
|
|
|
|
info = ctx.ensure_object(ScriptInfo)
|
|
|
|
# Look up commands provided by the app, showing an error and
|
|
# continuing if the app couldn't be loaded.
|
|
try:
|
|
app = info.load_app()
|
|
except NoAppException as e:
|
|
click.secho(f"Error: {e.format_message()}\n", err=True, fg="red")
|
|
return None
|
|
|
|
# Push an app context for the loaded app unless it is already
|
|
# active somehow. This makes the context available to parameter
|
|
# and command callbacks without needing @with_appcontext.
|
|
if not current_app or current_app._get_current_object() is not app: # type: ignore[attr-defined]
|
|
ctx.with_resource(app.app_context())
|
|
|
|
return app.cli.get_command(ctx, name)
|
|
|
|
def list_commands(self, ctx: click.Context) -> list[str]:
|
|
self._load_plugin_commands()
|
|
# Start with the built-in and plugin commands.
|
|
rv = set(super().list_commands(ctx))
|
|
info = ctx.ensure_object(ScriptInfo)
|
|
|
|
# Add commands provided by the app, showing an error and
|
|
# continuing if the app couldn't be loaded.
|
|
try:
|
|
rv.update(info.load_app().cli.list_commands(ctx))
|
|
except NoAppException as e:
|
|
# When an app couldn't be loaded, show the error message
|
|
# without the traceback.
|
|
click.secho(f"Error: {e.format_message()}\n", err=True, fg="red")
|
|
except Exception:
|
|
# When any other errors occurred during loading, show the
|
|
# full traceback.
|
|
click.secho(f"{traceback.format_exc()}\n", err=True, fg="red")
|
|
|
|
return sorted(rv)
|
|
|
|
def make_context(
|
|
self,
|
|
info_name: str | None,
|
|
args: list[str],
|
|
parent: click.Context | None = None,
|
|
**extra: t.Any,
|
|
) -> click.Context:
|
|
# Set a flag to tell app.run to become a no-op. If app.run was
|
|
# not in a __name__ == __main__ guard, it would start the server
|
|
# when importing, blocking whatever command is being called.
|
|
os.environ["FLASK_RUN_FROM_CLI"] = "true"
|
|
|
|
if "obj" not in extra and "obj" not in self.context_settings:
|
|
extra["obj"] = ScriptInfo(
|
|
create_app=self.create_app,
|
|
set_debug_flag=self.set_debug_flag,
|
|
load_dotenv_defaults=self.load_dotenv,
|
|
)
|
|
|
|
return super().make_context(info_name, args, parent=parent, **extra)
|
|
|
|
def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
|
|
if (not args and self.no_args_is_help) or (
|
|
len(args) == 1 and args[0] in self.get_help_option_names(ctx)
|
|
):
|
|
# Attempt to load --env-file and --app early in case they
|
|
# were given as env vars. Otherwise no_args_is_help will not
|
|
# see commands from app.cli.
|
|
_env_file_option.handle_parse_result(ctx, {}, [])
|
|
_app_option.handle_parse_result(ctx, {}, [])
|
|
|
|
return super().parse_args(ctx, args)
|
|
|
|
|
|
def _path_is_ancestor(path: str, other: str) -> bool:
|
|
"""Take ``other`` and remove the length of ``path`` from it. Then join it
|
|
to ``path``. If it is the original value, ``path`` is an ancestor of
|
|
``other``."""
|
|
return os.path.join(path, other[len(path) :].lstrip(os.sep)) == other
|
|
|
|
|
|
def load_dotenv(
|
|
path: str | os.PathLike[str] | None = None, load_defaults: bool = True
|
|
) -> bool:
|
|
"""Load "dotenv" files to set environment variables. A given path takes
|
|
precedence over ``.env``, which takes precedence over ``.flaskenv``. After
|
|
loading and combining these files, values are only set if the key is not
|
|
already set in ``os.environ``.
|
|
|
|
This is a no-op if `python-dotenv`_ is not installed.
|
|
|
|
.. _python-dotenv: https://github.com/theskumar/python-dotenv#readme
|
|
|
|
:param path: Load the file at this location.
|
|
:param load_defaults: Search for and load the default ``.flaskenv`` and
|
|
``.env`` files.
|
|
:return: ``True`` if at least one env var was loaded.
|
|
|
|
.. versionchanged:: 3.1
|
|
Added the ``load_defaults`` parameter. A given path takes precedence
|
|
over default files.
|
|
|
|
.. versionchanged:: 2.0
|
|
The current directory is not changed to the location of the
|
|
loaded file.
|
|
|
|
.. versionchanged:: 2.0
|
|
When loading the env files, set the default encoding to UTF-8.
|
|
|
|
.. versionchanged:: 1.1.0
|
|
Returns ``False`` when python-dotenv is not installed, or when
|
|
the given path isn't a file.
|
|
|
|
.. versionadded:: 1.0
|
|
"""
|
|
try:
|
|
import dotenv
|
|
except ImportError:
|
|
if path or os.path.isfile(".env") or os.path.isfile(".flaskenv"):
|
|
click.secho(
|
|
" * Tip: There are .env files present. Install python-dotenv"
|
|
" to use them.",
|
|
fg="yellow",
|
|
err=True,
|
|
)
|
|
|
|
return False
|
|
|
|
data: dict[str, str | None] = {}
|
|
|
|
if load_defaults:
|
|
for default_name in (".flaskenv", ".env"):
|
|
if not (default_path := dotenv.find_dotenv(default_name, usecwd=True)):
|
|
continue
|
|
|
|
data |= dotenv.dotenv_values(default_path, encoding="utf-8")
|
|
|
|
if path is not None and os.path.isfile(path):
|
|
data |= dotenv.dotenv_values(path, encoding="utf-8")
|
|
|
|
for key, value in data.items():
|
|
if key in os.environ or value is None:
|
|
continue
|
|
|
|
os.environ[key] = value
|
|
|
|
return bool(data) # True if at least one env var was loaded.
|
|
|
|
|
|
def show_server_banner(debug: bool, app_import_path: str | None) -> None:
|
|
"""Show extra startup messages the first time the server is run,
|
|
ignoring the reloader.
|
|
"""
|
|
if is_running_from_reloader():
|
|
return
|
|
|
|
if app_import_path is not None:
|
|
click.echo(f" * Serving Flask app '{app_import_path}'")
|
|
|
|
if debug is not None:
|
|
click.echo(f" * Debug mode: {'on' if debug else 'off'}")
|
|
|
|
|
|
class CertParamType(click.ParamType):
|
|
"""Click option type for the ``--cert`` option. Allows either an
|
|
existing file, the string ``'adhoc'``, or an import for a
|
|
:class:`~ssl.SSLContext` object.
|
|
"""
|
|
|
|
name = "path"
|
|
|
|
def __init__(self) -> None:
|
|
self.path_type = click.Path(exists=True, dir_okay=False, resolve_path=True)
|
|
|
|
def convert(
|
|
self, value: t.Any, param: click.Parameter | None, ctx: click.Context | None
|
|
) -> t.Any:
|
|
try:
|
|
import ssl
|
|
except ImportError:
|
|
raise click.BadParameter(
|
|
'Using "--cert" requires Python to be compiled with SSL support.',
|
|
ctx,
|
|
param,
|
|
) from None
|
|
|
|
try:
|
|
return self.path_type(value, param, ctx)
|
|
except click.BadParameter:
|
|
value = click.STRING(value, param, ctx).lower()
|
|
|
|
if value == "adhoc":
|
|
try:
|
|
import cryptography # noqa: F401
|
|
except ImportError:
|
|
raise click.BadParameter(
|
|
"Using ad-hoc certificates requires the cryptography library.",
|
|
ctx,
|
|
param,
|
|
) from None
|
|
|
|
return value
|
|
|
|
obj = import_string(value, silent=True)
|
|
|
|
if isinstance(obj, ssl.SSLContext):
|
|
return obj
|
|
|
|
raise
|
|
|
|
|
|
def _validate_key(ctx: click.Context, param: click.Parameter, value: t.Any) -> t.Any:
|
|
"""The ``--key`` option must be specified when ``--cert`` is a file.
|
|
Modifies the ``cert`` param to be a ``(cert, key)`` pair if needed.
|
|
"""
|
|
cert = ctx.params.get("cert")
|
|
is_adhoc = cert == "adhoc"
|
|
|
|
try:
|
|
import ssl
|
|
except ImportError:
|
|
is_context = False
|
|
else:
|
|
is_context = isinstance(cert, ssl.SSLContext)
|
|
|
|
if value is not None:
|
|
if is_adhoc:
|
|
raise click.BadParameter(
|
|
'When "--cert" is "adhoc", "--key" is not used.', ctx, param
|
|
)
|
|
|
|
if is_context:
|
|
raise click.BadParameter(
|
|
'When "--cert" is an SSLContext object, "--key" is not used.',
|
|
ctx,
|
|
param,
|
|
)
|
|
|
|
if not cert:
|
|
raise click.BadParameter('"--cert" must also be specified.', ctx, param)
|
|
|
|
ctx.params["cert"] = cert, value
|
|
|
|
else:
|
|
if cert and not (is_adhoc or is_context):
|
|
raise click.BadParameter('Required when using "--cert".', ctx, param)
|
|
|
|
return value
|
|
|
|
|
|
class SeparatedPathType(click.Path):
|
|
"""Click option type that accepts a list of values separated by the
|
|
OS's path separator (``:``, ``;`` on Windows). Each value is
|
|
validated as a :class:`click.Path` type.
|
|
"""
|
|
|
|
def convert(
|
|
self, value: t.Any, param: click.Parameter | None, ctx: click.Context | None
|
|
) -> t.Any:
|
|
items = self.split_envvar_value(value)
|
|
# can't call no-arg super() inside list comprehension until Python 3.12
|
|
super_convert = super().convert
|
|
return [super_convert(item, param, ctx) for item in items]
|
|
|
|
|
|
@click.command("run", short_help="Run a development server.")
|
|
@click.option("--host", "-h", default="127.0.0.1", help="The interface to bind to.")
|
|
@click.option("--port", "-p", default=5000, help="The port to bind to.")
|
|
@click.option(
|
|
"--cert",
|
|
type=CertParamType(),
|
|
help="Specify a certificate file to use HTTPS.",
|
|
is_eager=True,
|
|
)
|
|
@click.option(
|
|
"--key",
|
|
type=click.Path(exists=True, dir_okay=False, resolve_path=True),
|
|
callback=_validate_key,
|
|
expose_value=False,
|
|
help="The key file to use when specifying a certificate.",
|
|
)
|
|
@click.option(
|
|
"--reload/--no-reload",
|
|
default=None,
|
|
help="Enable or disable the reloader. By default the reloader "
|
|
"is active if debug is enabled.",
|
|
)
|
|
@click.option(
|
|
"--debugger/--no-debugger",
|
|
default=None,
|
|
help="Enable or disable the debugger. By default the debugger "
|
|
"is active if debug is enabled.",
|
|
)
|
|
@click.option(
|
|
"--with-threads/--without-threads",
|
|
default=True,
|
|
help="Enable or disable multithreading.",
|
|
)
|
|
@click.option(
|
|
"--extra-files",
|
|
default=None,
|
|
type=SeparatedPathType(),
|
|
help=(
|
|
"Extra files that trigger a reload on change. Multiple paths"
|
|
f" are separated by {os.path.pathsep!r}."
|
|
),
|
|
)
|
|
@click.option(
|
|
"--exclude-patterns",
|
|
default=None,
|
|
type=SeparatedPathType(),
|
|
help=(
|
|
"Files matching these fnmatch patterns will not trigger a reload"
|
|
" on change. Multiple patterns are separated by"
|
|
f" {os.path.pathsep!r}."
|
|
),
|
|
)
|
|
@pass_script_info
|
|
def run_command(
|
|
info: ScriptInfo,
|
|
host: str,
|
|
port: int,
|
|
reload: bool,
|
|
debugger: bool,
|
|
with_threads: bool,
|
|
cert: ssl.SSLContext | tuple[str, str | None] | t.Literal["adhoc"] | None,
|
|
extra_files: list[str] | None,
|
|
exclude_patterns: list[str] | None,
|
|
) -> None:
|
|
"""Run a local development server.
|
|
|
|
This server is for development purposes only. It does not provide
|
|
the stability, security, or performance of production WSGI servers.
|
|
|
|
The reloader and debugger are enabled by default with the '--debug'
|
|
option.
|
|
"""
|
|
try:
|
|
app: WSGIApplication = info.load_app() # pyright: ignore
|
|
except Exception as e:
|
|
if is_running_from_reloader():
|
|
# When reloading, print out the error immediately, but raise
|
|
# it later so the debugger or server can handle it.
|
|
traceback.print_exc()
|
|
err = e
|
|
|
|
def app(
|
|
environ: WSGIEnvironment, start_response: StartResponse
|
|
) -> cabc.Iterable[bytes]:
|
|
raise err from None
|
|
|
|
else:
|
|
# When not reloading, raise the error immediately so the
|
|
# command fails.
|
|
raise e from None
|
|
|
|
debug = get_debug_flag()
|
|
|
|
if reload is None:
|
|
reload = debug
|
|
|
|
if debugger is None:
|
|
debugger = debug
|
|
|
|
show_server_banner(debug, info.app_import_path)
|
|
|
|
run_simple(
|
|
host,
|
|
port,
|
|
app,
|
|
use_reloader=reload,
|
|
use_debugger=debugger,
|
|
threaded=with_threads,
|
|
ssl_context=cert,
|
|
extra_files=extra_files,
|
|
exclude_patterns=exclude_patterns,
|
|
)
|
|
|
|
|
|
run_command.params.insert(0, _debug_option)
|
|
|
|
|
|
@click.command("shell", short_help="Run a shell in the app context.")
|
|
@with_appcontext
|
|
def shell_command() -> None:
|
|
"""Run an interactive Python shell in the context of a given
|
|
Flask application. The application will populate the default
|
|
namespace of this shell according to its configuration.
|
|
|
|
This is useful for executing small snippets of management code
|
|
without having to manually configure the application.
|
|
"""
|
|
import code
|
|
|
|
banner = (
|
|
f"Python {sys.version} on {sys.platform}\n"
|
|
f"App: {current_app.import_name}\n"
|
|
f"Instance: {current_app.instance_path}"
|
|
)
|
|
ctx: dict[str, t.Any] = {}
|
|
|
|
# Support the regular Python interpreter startup script if someone
|
|
# is using it.
|
|
startup = os.environ.get("PYTHONSTARTUP")
|
|
if startup and os.path.isfile(startup):
|
|
with open(startup) as f:
|
|
eval(compile(f.read(), startup, "exec"), ctx)
|
|
|
|
ctx.update(current_app.make_shell_context())
|
|
|
|
# Site, customize, or startup script can set a hook to call when
|
|
# entering interactive mode. The default one sets up readline with
|
|
# tab and history completion.
|
|
interactive_hook = getattr(sys, "__interactivehook__", None)
|
|
|
|
if interactive_hook is not None:
|
|
try:
|
|
import readline
|
|
from rlcompleter import Completer
|
|
except ImportError:
|
|
pass
|
|
else:
|
|
# rlcompleter uses __main__.__dict__ by default, which is
|
|
# flask.__main__. Use the shell context instead.
|
|
readline.set_completer(Completer(ctx).complete)
|
|
|
|
interactive_hook()
|
|
|
|
code.interact(banner=banner, local=ctx)
|
|
|
|
|
|
@click.command("routes", short_help="Show the routes for the app.")
|
|
@click.option(
|
|
"--sort",
|
|
"-s",
|
|
type=click.Choice(("endpoint", "methods", "domain", "rule", "match")),
|
|
default="endpoint",
|
|
help=(
|
|
"Method to sort routes by. 'match' is the order that Flask will match routes"
|
|
" when dispatching a request."
|
|
),
|
|
)
|
|
@click.option("--all-methods", is_flag=True, help="Show HEAD and OPTIONS methods.")
|
|
@with_appcontext
|
|
def routes_command(sort: str, all_methods: bool) -> None:
|
|
"""Show all registered routes with endpoints and methods."""
|
|
rules = list(current_app.url_map.iter_rules())
|
|
|
|
if not rules:
|
|
click.echo("No routes were registered.")
|
|
return
|
|
|
|
ignored_methods = set() if all_methods else {"HEAD", "OPTIONS"}
|
|
host_matching = current_app.url_map.host_matching
|
|
has_domain = any(rule.host if host_matching else rule.subdomain for rule in rules)
|
|
rows = []
|
|
|
|
for rule in rules:
|
|
row = [
|
|
rule.endpoint,
|
|
", ".join(sorted((rule.methods or set()) - ignored_methods)),
|
|
]
|
|
|
|
if has_domain:
|
|
row.append((rule.host if host_matching else rule.subdomain) or "")
|
|
|
|
row.append(rule.rule)
|
|
rows.append(row)
|
|
|
|
headers = ["Endpoint", "Methods"]
|
|
sorts = ["endpoint", "methods"]
|
|
|
|
if has_domain:
|
|
headers.append("Host" if host_matching else "Subdomain")
|
|
sorts.append("domain")
|
|
|
|
headers.append("Rule")
|
|
sorts.append("rule")
|
|
|
|
try:
|
|
rows.sort(key=itemgetter(sorts.index(sort)))
|
|
except ValueError:
|
|
pass
|
|
|
|
rows.insert(0, headers)
|
|
widths = [max(len(row[i]) for row in rows) for i in range(len(headers))]
|
|
rows.insert(1, ["-" * w for w in widths])
|
|
template = " ".join(f"{{{i}:<{w}}}" for i, w in enumerate(widths))
|
|
|
|
for row in rows:
|
|
click.echo(template.format(*row))
|
|
|
|
|
|
cli = FlaskGroup(
|
|
name="flask",
|
|
help="""\
|
|
A general utility script for Flask applications.
|
|
|
|
An application to load must be given with the '--app' option,
|
|
'FLASK_APP' environment variable, or with a 'wsgi.py' or 'app.py' file
|
|
in the current directory.
|
|
""",
|
|
)
|
|
|
|
|
|
def main() -> None:
|
|
cli.main()
|
|
|
|
|
|
if __name__ == "__main__":
|
|
main()
|