Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/flask/cli.py: 25%
440 statements
« prev ^ index » next coverage.py v7.4.0, created at 2024-01-22 06:29 +0000
1from __future__ import annotations
3import ast
4import collections.abc as cabc
5import importlib.metadata
6import inspect
7import os
8import platform
9import re
10import sys
11import traceback
12import typing as t
13from functools import update_wrapper
14from operator import itemgetter
15from types import ModuleType
17import click
18from click.core import ParameterSource
19from werkzeug import run_simple
20from werkzeug.serving import is_running_from_reloader
21from werkzeug.utils import import_string
23from .globals import current_app
24from .helpers import get_debug_flag
25from .helpers import get_load_dotenv
27if t.TYPE_CHECKING:
28 import ssl
30 from _typeshed.wsgi import StartResponse
31 from _typeshed.wsgi import WSGIApplication
32 from _typeshed.wsgi import WSGIEnvironment
34 from .app import Flask
37class NoAppException(click.UsageError):
38 """Raised if an application cannot be found or loaded."""
41def find_best_app(module: ModuleType) -> Flask:
42 """Given a module instance this tries to find the best possible
43 application in the module or raises an exception.
44 """
45 from . import Flask
47 # Search for the most common names first.
48 for attr_name in ("app", "application"):
49 app = getattr(module, attr_name, None)
51 if isinstance(app, Flask):
52 return app
54 # Otherwise find the only object that is a Flask instance.
55 matches = [v for v in module.__dict__.values() if isinstance(v, Flask)]
57 if len(matches) == 1:
58 return matches[0]
59 elif len(matches) > 1:
60 raise NoAppException(
61 "Detected multiple Flask applications in module"
62 f" '{module.__name__}'. Use '{module.__name__}:name'"
63 " to specify the correct one."
64 )
66 # Search for app factory functions.
67 for attr_name in ("create_app", "make_app"):
68 app_factory = getattr(module, attr_name, None)
70 if inspect.isfunction(app_factory):
71 try:
72 app = app_factory()
74 if isinstance(app, Flask):
75 return app
76 except TypeError as e:
77 if not _called_with_wrong_args(app_factory):
78 raise
80 raise NoAppException(
81 f"Detected factory '{attr_name}' in module '{module.__name__}',"
82 " but could not call it without arguments. Use"
83 f" '{module.__name__}:{attr_name}(args)'"
84 " to specify arguments."
85 ) from e
87 raise NoAppException(
88 "Failed to find Flask application or factory in module"
89 f" '{module.__name__}'. Use '{module.__name__}:name'"
90 " to specify one."
91 )
94def _called_with_wrong_args(f: t.Callable[..., Flask]) -> bool:
95 """Check whether calling a function raised a ``TypeError`` because
96 the call failed or because something in the factory raised the
97 error.
99 :param f: The function that was called.
100 :return: ``True`` if the call failed.
101 """
102 tb = sys.exc_info()[2]
104 try:
105 while tb is not None:
106 if tb.tb_frame.f_code is f.__code__:
107 # In the function, it was called successfully.
108 return False
110 tb = tb.tb_next
112 # Didn't reach the function.
113 return True
114 finally:
115 # Delete tb to break a circular reference.
116 # https://docs.python.org/2/library/sys.html#sys.exc_info
117 del tb
120def find_app_by_string(module: ModuleType, app_name: str) -> Flask:
121 """Check if the given string is a variable name or a function. Call
122 a function to get the app instance, or return the variable directly.
123 """
124 from . import Flask
126 # Parse app_name as a single expression to determine if it's a valid
127 # attribute name or function call.
128 try:
129 expr = ast.parse(app_name.strip(), mode="eval").body
130 except SyntaxError:
131 raise NoAppException(
132 f"Failed to parse {app_name!r} as an attribute name or function call."
133 ) from None
135 if isinstance(expr, ast.Name):
136 name = expr.id
137 args = []
138 kwargs = {}
139 elif isinstance(expr, ast.Call):
140 # Ensure the function name is an attribute name only.
141 if not isinstance(expr.func, ast.Name):
142 raise NoAppException(
143 f"Function reference must be a simple name: {app_name!r}."
144 )
146 name = expr.func.id
148 # Parse the positional and keyword arguments as literals.
149 try:
150 args = [ast.literal_eval(arg) for arg in expr.args]
151 kwargs = {
152 kw.arg: ast.literal_eval(kw.value)
153 for kw in expr.keywords
154 if kw.arg is not None
155 }
156 except ValueError:
157 # literal_eval gives cryptic error messages, show a generic
158 # message with the full expression instead.
159 raise NoAppException(
160 f"Failed to parse arguments as literal values: {app_name!r}."
161 ) from None
162 else:
163 raise NoAppException(
164 f"Failed to parse {app_name!r} as an attribute name or function call."
165 )
167 try:
168 attr = getattr(module, name)
169 except AttributeError as e:
170 raise NoAppException(
171 f"Failed to find attribute {name!r} in {module.__name__!r}."
172 ) from e
174 # If the attribute is a function, call it with any args and kwargs
175 # to get the real application.
176 if inspect.isfunction(attr):
177 try:
178 app = attr(*args, **kwargs)
179 except TypeError as e:
180 if not _called_with_wrong_args(attr):
181 raise
183 raise NoAppException(
184 f"The factory {app_name!r} in module"
185 f" {module.__name__!r} could not be called with the"
186 " specified arguments."
187 ) from e
188 else:
189 app = attr
191 if isinstance(app, Flask):
192 return app
194 raise NoAppException(
195 "A valid Flask application was not obtained from"
196 f" '{module.__name__}:{app_name}'."
197 )
200def prepare_import(path: str) -> str:
201 """Given a filename this will try to calculate the python path, add it
202 to the search path and return the actual module name that is expected.
203 """
204 path = os.path.realpath(path)
206 fname, ext = os.path.splitext(path)
207 if ext == ".py":
208 path = fname
210 if os.path.basename(path) == "__init__":
211 path = os.path.dirname(path)
213 module_name = []
215 # move up until outside package structure (no __init__.py)
216 while True:
217 path, name = os.path.split(path)
218 module_name.append(name)
220 if not os.path.exists(os.path.join(path, "__init__.py")):
221 break
223 if sys.path[0] != path:
224 sys.path.insert(0, path)
226 return ".".join(module_name[::-1])
229@t.overload
230def locate_app(
231 module_name: str, app_name: str | None, raise_if_not_found: t.Literal[True] = True
232) -> Flask:
233 ...
236@t.overload
237def locate_app(
238 module_name: str, app_name: str | None, raise_if_not_found: t.Literal[False] = ...
239) -> Flask | None:
240 ...
243def locate_app(
244 module_name: str, app_name: str | None, raise_if_not_found: bool = True
245) -> Flask | None:
246 try:
247 __import__(module_name)
248 except ImportError:
249 # Reraise the ImportError if it occurred within the imported module.
250 # Determine this by checking whether the trace has a depth > 1.
251 if sys.exc_info()[2].tb_next: # type: ignore[union-attr]
252 raise NoAppException(
253 f"While importing {module_name!r}, an ImportError was"
254 f" raised:\n\n{traceback.format_exc()}"
255 ) from None
256 elif raise_if_not_found:
257 raise NoAppException(f"Could not import {module_name!r}.") from None
258 else:
259 return None
261 module = sys.modules[module_name]
263 if app_name is None:
264 return find_best_app(module)
265 else:
266 return find_app_by_string(module, app_name)
269def get_version(ctx: click.Context, param: click.Parameter, value: t.Any) -> None:
270 if not value or ctx.resilient_parsing:
271 return
273 flask_version = importlib.metadata.version("flask")
274 werkzeug_version = importlib.metadata.version("werkzeug")
276 click.echo(
277 f"Python {platform.python_version()}\n"
278 f"Flask {flask_version}\n"
279 f"Werkzeug {werkzeug_version}",
280 color=ctx.color,
281 )
282 ctx.exit()
285version_option = click.Option(
286 ["--version"],
287 help="Show the Flask version.",
288 expose_value=False,
289 callback=get_version,
290 is_flag=True,
291 is_eager=True,
292)
295class ScriptInfo:
296 """Helper object to deal with Flask applications. This is usually not
297 necessary to interface with as it's used internally in the dispatching
298 to click. In future versions of Flask this object will most likely play
299 a bigger role. Typically it's created automatically by the
300 :class:`FlaskGroup` but you can also manually create it and pass it
301 onwards as click object.
302 """
304 def __init__(
305 self,
306 app_import_path: str | None = None,
307 create_app: t.Callable[..., Flask] | None = None,
308 set_debug_flag: bool = True,
309 ) -> None:
310 #: Optionally the import path for the Flask application.
311 self.app_import_path = app_import_path
312 #: Optionally a function that is passed the script info to create
313 #: the instance of the application.
314 self.create_app = create_app
315 #: A dictionary with arbitrary data that can be associated with
316 #: this script info.
317 self.data: dict[t.Any, t.Any] = {}
318 self.set_debug_flag = set_debug_flag
319 self._loaded_app: Flask | None = None
321 def load_app(self) -> Flask:
322 """Loads the Flask app (if not yet loaded) and returns it. Calling
323 this multiple times will just result in the already loaded app to
324 be returned.
325 """
326 if self._loaded_app is not None:
327 return self._loaded_app
329 if self.create_app is not None:
330 app: Flask | None = self.create_app()
331 else:
332 if self.app_import_path:
333 path, name = (
334 re.split(r":(?![\\/])", self.app_import_path, maxsplit=1) + [None]
335 )[:2]
336 import_name = prepare_import(path)
337 app = locate_app(import_name, name)
338 else:
339 for path in ("wsgi.py", "app.py"):
340 import_name = prepare_import(path)
341 app = locate_app(import_name, None, raise_if_not_found=False)
343 if app is not None:
344 break
346 if app is None:
347 raise NoAppException(
348 "Could not locate a Flask application. Use the"
349 " 'flask --app' option, 'FLASK_APP' environment"
350 " variable, or a 'wsgi.py' or 'app.py' file in the"
351 " current directory."
352 )
354 if self.set_debug_flag:
355 # Update the app's debug flag through the descriptor so that
356 # other values repopulate as well.
357 app.debug = get_debug_flag()
359 self._loaded_app = app
360 return app
363pass_script_info = click.make_pass_decorator(ScriptInfo, ensure=True)
365F = t.TypeVar("F", bound=t.Callable[..., t.Any])
368def with_appcontext(f: F) -> F:
369 """Wraps a callback so that it's guaranteed to be executed with the
370 script's application context.
372 Custom commands (and their options) registered under ``app.cli`` or
373 ``blueprint.cli`` will always have an app context available, this
374 decorator is not required in that case.
376 .. versionchanged:: 2.2
377 The app context is active for subcommands as well as the
378 decorated callback. The app context is always available to
379 ``app.cli`` command and parameter callbacks.
380 """
382 @click.pass_context
383 def decorator(ctx: click.Context, /, *args: t.Any, **kwargs: t.Any) -> t.Any:
384 if not current_app:
385 app = ctx.ensure_object(ScriptInfo).load_app()
386 ctx.with_resource(app.app_context())
388 return ctx.invoke(f, *args, **kwargs)
390 return update_wrapper(decorator, f) # type: ignore[return-value]
393class AppGroup(click.Group):
394 """This works similar to a regular click :class:`~click.Group` but it
395 changes the behavior of the :meth:`command` decorator so that it
396 automatically wraps the functions in :func:`with_appcontext`.
398 Not to be confused with :class:`FlaskGroup`.
399 """
401 def command( # type: ignore[override]
402 self, *args: t.Any, **kwargs: t.Any
403 ) -> t.Callable[[t.Callable[..., t.Any]], click.Command]:
404 """This works exactly like the method of the same name on a regular
405 :class:`click.Group` but it wraps callbacks in :func:`with_appcontext`
406 unless it's disabled by passing ``with_appcontext=False``.
407 """
408 wrap_for_ctx = kwargs.pop("with_appcontext", True)
410 def decorator(f: t.Callable[..., t.Any]) -> click.Command:
411 if wrap_for_ctx:
412 f = with_appcontext(f)
413 return super(AppGroup, self).command(*args, **kwargs)(f) # type: ignore[no-any-return]
415 return decorator
417 def group( # type: ignore[override]
418 self, *args: t.Any, **kwargs: t.Any
419 ) -> t.Callable[[t.Callable[..., t.Any]], click.Group]:
420 """This works exactly like the method of the same name on a regular
421 :class:`click.Group` but it defaults the group class to
422 :class:`AppGroup`.
423 """
424 kwargs.setdefault("cls", AppGroup)
425 return super().group(*args, **kwargs) # type: ignore[no-any-return]
428def _set_app(ctx: click.Context, param: click.Option, value: str | None) -> str | None:
429 if value is None:
430 return None
432 info = ctx.ensure_object(ScriptInfo)
433 info.app_import_path = value
434 return value
437# This option is eager so the app will be available if --help is given.
438# --help is also eager, so --app must be before it in the param list.
439# no_args_is_help bypasses eager processing, so this option must be
440# processed manually in that case to ensure FLASK_APP gets picked up.
441_app_option = click.Option(
442 ["-A", "--app"],
443 metavar="IMPORT",
444 help=(
445 "The Flask application or factory function to load, in the form 'module:name'."
446 " Module can be a dotted import or file path. Name is not required if it is"
447 " 'app', 'application', 'create_app', or 'make_app', and can be 'name(args)' to"
448 " pass arguments."
449 ),
450 is_eager=True,
451 expose_value=False,
452 callback=_set_app,
453)
456def _set_debug(ctx: click.Context, param: click.Option, value: bool) -> bool | None:
457 # If the flag isn't provided, it will default to False. Don't use
458 # that, let debug be set by env in that case.
459 source = ctx.get_parameter_source(param.name) # type: ignore[arg-type]
461 if source is not None and source in (
462 ParameterSource.DEFAULT,
463 ParameterSource.DEFAULT_MAP,
464 ):
465 return None
467 # Set with env var instead of ScriptInfo.load so that it can be
468 # accessed early during a factory function.
469 os.environ["FLASK_DEBUG"] = "1" if value else "0"
470 return value
473_debug_option = click.Option(
474 ["--debug/--no-debug"],
475 help="Set debug mode.",
476 expose_value=False,
477 callback=_set_debug,
478)
481def _env_file_callback(
482 ctx: click.Context, param: click.Option, value: str | None
483) -> str | None:
484 if value is None:
485 return None
487 import importlib
489 try:
490 importlib.import_module("dotenv")
491 except ImportError:
492 raise click.BadParameter(
493 "python-dotenv must be installed to load an env file.",
494 ctx=ctx,
495 param=param,
496 ) from None
498 # Don't check FLASK_SKIP_DOTENV, that only disables automatically
499 # loading .env and .flaskenv files.
500 load_dotenv(value)
501 return value
504# This option is eager so env vars are loaded as early as possible to be
505# used by other options.
506_env_file_option = click.Option(
507 ["-e", "--env-file"],
508 type=click.Path(exists=True, dir_okay=False),
509 help="Load environment variables from this file. python-dotenv must be installed.",
510 is_eager=True,
511 expose_value=False,
512 callback=_env_file_callback,
513)
516class FlaskGroup(AppGroup):
517 """Special subclass of the :class:`AppGroup` group that supports
518 loading more commands from the configured Flask app. Normally a
519 developer does not have to interface with this class but there are
520 some very advanced use cases for which it makes sense to create an
521 instance of this. see :ref:`custom-scripts`.
523 :param add_default_commands: if this is True then the default run and
524 shell commands will be added.
525 :param add_version_option: adds the ``--version`` option.
526 :param create_app: an optional callback that is passed the script info and
527 returns the loaded app.
528 :param load_dotenv: Load the nearest :file:`.env` and :file:`.flaskenv`
529 files to set environment variables. Will also change the working
530 directory to the directory containing the first file found.
531 :param set_debug_flag: Set the app's debug flag.
533 .. versionchanged:: 2.2
534 Added the ``-A/--app``, ``--debug/--no-debug``, ``-e/--env-file`` options.
536 .. versionchanged:: 2.2
537 An app context is pushed when running ``app.cli`` commands, so
538 ``@with_appcontext`` is no longer required for those commands.
540 .. versionchanged:: 1.0
541 If installed, python-dotenv will be used to load environment variables
542 from :file:`.env` and :file:`.flaskenv` files.
543 """
545 def __init__(
546 self,
547 add_default_commands: bool = True,
548 create_app: t.Callable[..., Flask] | None = None,
549 add_version_option: bool = True,
550 load_dotenv: bool = True,
551 set_debug_flag: bool = True,
552 **extra: t.Any,
553 ) -> None:
554 params = list(extra.pop("params", None) or ())
555 # Processing is done with option callbacks instead of a group
556 # callback. This allows users to make a custom group callback
557 # without losing the behavior. --env-file must come first so
558 # that it is eagerly evaluated before --app.
559 params.extend((_env_file_option, _app_option, _debug_option))
561 if add_version_option:
562 params.append(version_option)
564 if "context_settings" not in extra:
565 extra["context_settings"] = {}
567 extra["context_settings"].setdefault("auto_envvar_prefix", "FLASK")
569 super().__init__(params=params, **extra)
571 self.create_app = create_app
572 self.load_dotenv = load_dotenv
573 self.set_debug_flag = set_debug_flag
575 if add_default_commands:
576 self.add_command(run_command)
577 self.add_command(shell_command)
578 self.add_command(routes_command)
580 self._loaded_plugin_commands = False
582 def _load_plugin_commands(self) -> None:
583 if self._loaded_plugin_commands:
584 return
586 if sys.version_info >= (3, 10):
587 from importlib import metadata
588 else:
589 # Use a backport on Python < 3.10. We technically have
590 # importlib.metadata on 3.8+, but the API changed in 3.10,
591 # so use the backport for consistency.
592 import importlib_metadata as metadata
594 for ep in metadata.entry_points(group="flask.commands"):
595 self.add_command(ep.load(), ep.name)
597 self._loaded_plugin_commands = True
599 def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
600 self._load_plugin_commands()
601 # Look up built-in and plugin commands, which should be
602 # available even if the app fails to load.
603 rv = super().get_command(ctx, name)
605 if rv is not None:
606 return rv
608 info = ctx.ensure_object(ScriptInfo)
610 # Look up commands provided by the app, showing an error and
611 # continuing if the app couldn't be loaded.
612 try:
613 app = info.load_app()
614 except NoAppException as e:
615 click.secho(f"Error: {e.format_message()}\n", err=True, fg="red")
616 return None
618 # Push an app context for the loaded app unless it is already
619 # active somehow. This makes the context available to parameter
620 # and command callbacks without needing @with_appcontext.
621 if not current_app or current_app._get_current_object() is not app: # type: ignore[attr-defined]
622 ctx.with_resource(app.app_context())
624 return app.cli.get_command(ctx, name)
626 def list_commands(self, ctx: click.Context) -> list[str]:
627 self._load_plugin_commands()
628 # Start with the built-in and plugin commands.
629 rv = set(super().list_commands(ctx))
630 info = ctx.ensure_object(ScriptInfo)
632 # Add commands provided by the app, showing an error and
633 # continuing if the app couldn't be loaded.
634 try:
635 rv.update(info.load_app().cli.list_commands(ctx))
636 except NoAppException as e:
637 # When an app couldn't be loaded, show the error message
638 # without the traceback.
639 click.secho(f"Error: {e.format_message()}\n", err=True, fg="red")
640 except Exception:
641 # When any other errors occurred during loading, show the
642 # full traceback.
643 click.secho(f"{traceback.format_exc()}\n", err=True, fg="red")
645 return sorted(rv)
647 def make_context(
648 self,
649 info_name: str | None,
650 args: list[str],
651 parent: click.Context | None = None,
652 **extra: t.Any,
653 ) -> click.Context:
654 # Set a flag to tell app.run to become a no-op. If app.run was
655 # not in a __name__ == __main__ guard, it would start the server
656 # when importing, blocking whatever command is being called.
657 os.environ["FLASK_RUN_FROM_CLI"] = "true"
659 # Attempt to load .env and .flask env files. The --env-file
660 # option can cause another file to be loaded.
661 if get_load_dotenv(self.load_dotenv):
662 load_dotenv()
664 if "obj" not in extra and "obj" not in self.context_settings:
665 extra["obj"] = ScriptInfo(
666 create_app=self.create_app, set_debug_flag=self.set_debug_flag
667 )
669 return super().make_context(info_name, args, parent=parent, **extra)
671 def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
672 if not args and self.no_args_is_help:
673 # Attempt to load --env-file and --app early in case they
674 # were given as env vars. Otherwise no_args_is_help will not
675 # see commands from app.cli.
676 _env_file_option.handle_parse_result(ctx, {}, [])
677 _app_option.handle_parse_result(ctx, {}, [])
679 return super().parse_args(ctx, args)
682def _path_is_ancestor(path: str, other: str) -> bool:
683 """Take ``other`` and remove the length of ``path`` from it. Then join it
684 to ``path``. If it is the original value, ``path`` is an ancestor of
685 ``other``."""
686 return os.path.join(path, other[len(path) :].lstrip(os.sep)) == other
689def load_dotenv(path: str | os.PathLike[str] | None = None) -> bool:
690 """Load "dotenv" files in order of precedence to set environment variables.
692 If an env var is already set it is not overwritten, so earlier files in the
693 list are preferred over later files.
695 This is a no-op if `python-dotenv`_ is not installed.
697 .. _python-dotenv: https://github.com/theskumar/python-dotenv#readme
699 :param path: Load the file at this location instead of searching.
700 :return: ``True`` if a file was loaded.
702 .. versionchanged:: 2.0
703 The current directory is not changed to the location of the
704 loaded file.
706 .. versionchanged:: 2.0
707 When loading the env files, set the default encoding to UTF-8.
709 .. versionchanged:: 1.1.0
710 Returns ``False`` when python-dotenv is not installed, or when
711 the given path isn't a file.
713 .. versionadded:: 1.0
714 """
715 try:
716 import dotenv
717 except ImportError:
718 if path or os.path.isfile(".env") or os.path.isfile(".flaskenv"):
719 click.secho(
720 " * Tip: There are .env or .flaskenv files present."
721 ' Do "pip install python-dotenv" to use them.',
722 fg="yellow",
723 err=True,
724 )
726 return False
728 # Always return after attempting to load a given path, don't load
729 # the default files.
730 if path is not None:
731 if os.path.isfile(path):
732 return dotenv.load_dotenv(path, encoding="utf-8")
734 return False
736 loaded = False
738 for name in (".env", ".flaskenv"):
739 path = dotenv.find_dotenv(name, usecwd=True)
741 if not path:
742 continue
744 dotenv.load_dotenv(path, encoding="utf-8")
745 loaded = True
747 return loaded # True if at least one file was located and loaded.
750def show_server_banner(debug: bool, app_import_path: str | None) -> None:
751 """Show extra startup messages the first time the server is run,
752 ignoring the reloader.
753 """
754 if is_running_from_reloader():
755 return
757 if app_import_path is not None:
758 click.echo(f" * Serving Flask app '{app_import_path}'")
760 if debug is not None:
761 click.echo(f" * Debug mode: {'on' if debug else 'off'}")
764class CertParamType(click.ParamType):
765 """Click option type for the ``--cert`` option. Allows either an
766 existing file, the string ``'adhoc'``, or an import for a
767 :class:`~ssl.SSLContext` object.
768 """
770 name = "path"
772 def __init__(self) -> None:
773 self.path_type = click.Path(exists=True, dir_okay=False, resolve_path=True)
775 def convert(
776 self, value: t.Any, param: click.Parameter | None, ctx: click.Context | None
777 ) -> t.Any:
778 try:
779 import ssl
780 except ImportError:
781 raise click.BadParameter(
782 'Using "--cert" requires Python to be compiled with SSL support.',
783 ctx,
784 param,
785 ) from None
787 try:
788 return self.path_type(value, param, ctx)
789 except click.BadParameter:
790 value = click.STRING(value, param, ctx).lower()
792 if value == "adhoc":
793 try:
794 import cryptography # noqa: F401
795 except ImportError:
796 raise click.BadParameter(
797 "Using ad-hoc certificates requires the cryptography library.",
798 ctx,
799 param,
800 ) from None
802 return value
804 obj = import_string(value, silent=True)
806 if isinstance(obj, ssl.SSLContext):
807 return obj
809 raise
812def _validate_key(ctx: click.Context, param: click.Parameter, value: t.Any) -> t.Any:
813 """The ``--key`` option must be specified when ``--cert`` is a file.
814 Modifies the ``cert`` param to be a ``(cert, key)`` pair if needed.
815 """
816 cert = ctx.params.get("cert")
817 is_adhoc = cert == "adhoc"
819 try:
820 import ssl
821 except ImportError:
822 is_context = False
823 else:
824 is_context = isinstance(cert, ssl.SSLContext)
826 if value is not None:
827 if is_adhoc:
828 raise click.BadParameter(
829 'When "--cert" is "adhoc", "--key" is not used.', ctx, param
830 )
832 if is_context:
833 raise click.BadParameter(
834 'When "--cert" is an SSLContext object, "--key" is not used.',
835 ctx,
836 param,
837 )
839 if not cert:
840 raise click.BadParameter('"--cert" must also be specified.', ctx, param)
842 ctx.params["cert"] = cert, value
844 else:
845 if cert and not (is_adhoc or is_context):
846 raise click.BadParameter('Required when using "--cert".', ctx, param)
848 return value
851class SeparatedPathType(click.Path):
852 """Click option type that accepts a list of values separated by the
853 OS's path separator (``:``, ``;`` on Windows). Each value is
854 validated as a :class:`click.Path` type.
855 """
857 def convert(
858 self, value: t.Any, param: click.Parameter | None, ctx: click.Context | None
859 ) -> t.Any:
860 items = self.split_envvar_value(value)
861 return [super().convert(item, param, ctx) for item in items]
864@click.command("run", short_help="Run a development server.")
865@click.option("--host", "-h", default="127.0.0.1", help="The interface to bind to.")
866@click.option("--port", "-p", default=5000, help="The port to bind to.")
867@click.option(
868 "--cert",
869 type=CertParamType(),
870 help="Specify a certificate file to use HTTPS.",
871 is_eager=True,
872)
873@click.option(
874 "--key",
875 type=click.Path(exists=True, dir_okay=False, resolve_path=True),
876 callback=_validate_key,
877 expose_value=False,
878 help="The key file to use when specifying a certificate.",
879)
880@click.option(
881 "--reload/--no-reload",
882 default=None,
883 help="Enable or disable the reloader. By default the reloader "
884 "is active if debug is enabled.",
885)
886@click.option(
887 "--debugger/--no-debugger",
888 default=None,
889 help="Enable or disable the debugger. By default the debugger "
890 "is active if debug is enabled.",
891)
892@click.option(
893 "--with-threads/--without-threads",
894 default=True,
895 help="Enable or disable multithreading.",
896)
897@click.option(
898 "--extra-files",
899 default=None,
900 type=SeparatedPathType(),
901 help=(
902 "Extra files that trigger a reload on change. Multiple paths"
903 f" are separated by {os.path.pathsep!r}."
904 ),
905)
906@click.option(
907 "--exclude-patterns",
908 default=None,
909 type=SeparatedPathType(),
910 help=(
911 "Files matching these fnmatch patterns will not trigger a reload"
912 " on change. Multiple patterns are separated by"
913 f" {os.path.pathsep!r}."
914 ),
915)
916@pass_script_info
917def run_command(
918 info: ScriptInfo,
919 host: str,
920 port: int,
921 reload: bool,
922 debugger: bool,
923 with_threads: bool,
924 cert: ssl.SSLContext | tuple[str, str | None] | t.Literal["adhoc"] | None,
925 extra_files: list[str] | None,
926 exclude_patterns: list[str] | None,
927) -> None:
928 """Run a local development server.
930 This server is for development purposes only. It does not provide
931 the stability, security, or performance of production WSGI servers.
933 The reloader and debugger are enabled by default with the '--debug'
934 option.
935 """
936 try:
937 app: WSGIApplication = info.load_app()
938 except Exception as e:
939 if is_running_from_reloader():
940 # When reloading, print out the error immediately, but raise
941 # it later so the debugger or server can handle it.
942 traceback.print_exc()
943 err = e
945 def app(
946 environ: WSGIEnvironment, start_response: StartResponse
947 ) -> cabc.Iterable[bytes]:
948 raise err from None
950 else:
951 # When not reloading, raise the error immediately so the
952 # command fails.
953 raise e from None
955 debug = get_debug_flag()
957 if reload is None:
958 reload = debug
960 if debugger is None:
961 debugger = debug
963 show_server_banner(debug, info.app_import_path)
965 run_simple(
966 host,
967 port,
968 app,
969 use_reloader=reload,
970 use_debugger=debugger,
971 threaded=with_threads,
972 ssl_context=cert,
973 extra_files=extra_files,
974 exclude_patterns=exclude_patterns,
975 )
978run_command.params.insert(0, _debug_option)
981@click.command("shell", short_help="Run a shell in the app context.")
982@with_appcontext
983def shell_command() -> None:
984 """Run an interactive Python shell in the context of a given
985 Flask application. The application will populate the default
986 namespace of this shell according to its configuration.
988 This is useful for executing small snippets of management code
989 without having to manually configure the application.
990 """
991 import code
993 banner = (
994 f"Python {sys.version} on {sys.platform}\n"
995 f"App: {current_app.import_name}\n"
996 f"Instance: {current_app.instance_path}"
997 )
998 ctx: dict[str, t.Any] = {}
1000 # Support the regular Python interpreter startup script if someone
1001 # is using it.
1002 startup = os.environ.get("PYTHONSTARTUP")
1003 if startup and os.path.isfile(startup):
1004 with open(startup) as f:
1005 eval(compile(f.read(), startup, "exec"), ctx)
1007 ctx.update(current_app.make_shell_context())
1009 # Site, customize, or startup script can set a hook to call when
1010 # entering interactive mode. The default one sets up readline with
1011 # tab and history completion.
1012 interactive_hook = getattr(sys, "__interactivehook__", None)
1014 if interactive_hook is not None:
1015 try:
1016 import readline
1017 from rlcompleter import Completer
1018 except ImportError:
1019 pass
1020 else:
1021 # rlcompleter uses __main__.__dict__ by default, which is
1022 # flask.__main__. Use the shell context instead.
1023 readline.set_completer(Completer(ctx).complete)
1025 interactive_hook()
1027 code.interact(banner=banner, local=ctx)
1030@click.command("routes", short_help="Show the routes for the app.")
1031@click.option(
1032 "--sort",
1033 "-s",
1034 type=click.Choice(("endpoint", "methods", "domain", "rule", "match")),
1035 default="endpoint",
1036 help=(
1037 "Method to sort routes by. 'match' is the order that Flask will match routes"
1038 " when dispatching a request."
1039 ),
1040)
1041@click.option("--all-methods", is_flag=True, help="Show HEAD and OPTIONS methods.")
1042@with_appcontext
1043def routes_command(sort: str, all_methods: bool) -> None:
1044 """Show all registered routes with endpoints and methods."""
1045 rules = list(current_app.url_map.iter_rules())
1047 if not rules:
1048 click.echo("No routes were registered.")
1049 return
1051 ignored_methods = set() if all_methods else {"HEAD", "OPTIONS"}
1052 host_matching = current_app.url_map.host_matching
1053 has_domain = any(rule.host if host_matching else rule.subdomain for rule in rules)
1054 rows = []
1056 for rule in rules:
1057 row = [
1058 rule.endpoint,
1059 ", ".join(sorted((rule.methods or set()) - ignored_methods)),
1060 ]
1062 if has_domain:
1063 row.append((rule.host if host_matching else rule.subdomain) or "")
1065 row.append(rule.rule)
1066 rows.append(row)
1068 headers = ["Endpoint", "Methods"]
1069 sorts = ["endpoint", "methods"]
1071 if has_domain:
1072 headers.append("Host" if host_matching else "Subdomain")
1073 sorts.append("domain")
1075 headers.append("Rule")
1076 sorts.append("rule")
1078 try:
1079 rows.sort(key=itemgetter(sorts.index(sort)))
1080 except ValueError:
1081 pass
1083 rows.insert(0, headers)
1084 widths = [max(len(row[i]) for row in rows) for i in range(len(headers))]
1085 rows.insert(1, ["-" * w for w in widths])
1086 template = " ".join(f"{{{i}:<{w}}}" for i, w in enumerate(widths))
1088 for row in rows:
1089 click.echo(template.format(*row))
1092cli = FlaskGroup(
1093 name="flask",
1094 help="""\
1095A general utility script for Flask applications.
1097An application to load must be given with the '--app' option,
1098'FLASK_APP' environment variable, or with a 'wsgi.py' or 'app.py' file
1099in the current directory.
1100""",
1101)
1104def main() -> None:
1105 cli.main()
1108if __name__ == "__main__":
1109 main()