Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/flask/cli.py: 25%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
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: ...
235@t.overload
236def locate_app(
237 module_name: str, app_name: str | None, raise_if_not_found: t.Literal[False] = ...
238) -> Flask | None: ...
241def locate_app(
242 module_name: str, app_name: str | None, raise_if_not_found: bool = True
243) -> Flask | None:
244 try:
245 __import__(module_name)
246 except ImportError:
247 # Reraise the ImportError if it occurred within the imported module.
248 # Determine this by checking whether the trace has a depth > 1.
249 if sys.exc_info()[2].tb_next: # type: ignore[union-attr]
250 raise NoAppException(
251 f"While importing {module_name!r}, an ImportError was"
252 f" raised:\n\n{traceback.format_exc()}"
253 ) from None
254 elif raise_if_not_found:
255 raise NoAppException(f"Could not import {module_name!r}.") from None
256 else:
257 return None
259 module = sys.modules[module_name]
261 if app_name is None:
262 return find_best_app(module)
263 else:
264 return find_app_by_string(module, app_name)
267def get_version(ctx: click.Context, param: click.Parameter, value: t.Any) -> None:
268 if not value or ctx.resilient_parsing:
269 return
271 flask_version = importlib.metadata.version("flask")
272 werkzeug_version = importlib.metadata.version("werkzeug")
274 click.echo(
275 f"Python {platform.python_version()}\n"
276 f"Flask {flask_version}\n"
277 f"Werkzeug {werkzeug_version}",
278 color=ctx.color,
279 )
280 ctx.exit()
283version_option = click.Option(
284 ["--version"],
285 help="Show the Flask version.",
286 expose_value=False,
287 callback=get_version,
288 is_flag=True,
289 is_eager=True,
290)
293class ScriptInfo:
294 """Helper object to deal with Flask applications. This is usually not
295 necessary to interface with as it's used internally in the dispatching
296 to click. In future versions of Flask this object will most likely play
297 a bigger role. Typically it's created automatically by the
298 :class:`FlaskGroup` but you can also manually create it and pass it
299 onwards as click object.
301 .. versionchanged:: 3.1
302 Added the ``load_dotenv_defaults`` parameter and attribute.
303 """
305 def __init__(
306 self,
307 app_import_path: str | None = None,
308 create_app: t.Callable[..., Flask] | None = None,
309 set_debug_flag: bool = True,
310 load_dotenv_defaults: bool = True,
311 ) -> None:
312 #: Optionally the import path for the Flask application.
313 self.app_import_path = app_import_path
314 #: Optionally a function that is passed the script info to create
315 #: the instance of the application.
316 self.create_app = create_app
317 #: A dictionary with arbitrary data that can be associated with
318 #: this script info.
319 self.data: dict[t.Any, t.Any] = {}
320 self.set_debug_flag = set_debug_flag
322 self.load_dotenv_defaults = get_load_dotenv(load_dotenv_defaults)
323 """Whether default ``.flaskenv`` and ``.env`` files should be loaded.
325 ``ScriptInfo`` doesn't load anything, this is for reference when doing
326 the load elsewhere during processing.
328 .. versionadded:: 3.1
329 """
331 self._loaded_app: Flask | None = None
333 def load_app(self) -> Flask:
334 """Loads the Flask app (if not yet loaded) and returns it. Calling
335 this multiple times will just result in the already loaded app to
336 be returned.
337 """
338 if self._loaded_app is not None:
339 return self._loaded_app
340 app: Flask | None = None
341 if self.create_app is not None:
342 app = self.create_app()
343 else:
344 if self.app_import_path:
345 path, name = (
346 re.split(r":(?![\\/])", self.app_import_path, maxsplit=1) + [None]
347 )[:2]
348 import_name = prepare_import(path)
349 app = locate_app(import_name, name)
350 else:
351 for path in ("wsgi.py", "app.py"):
352 import_name = prepare_import(path)
353 app = locate_app(import_name, None, raise_if_not_found=False)
355 if app is not None:
356 break
358 if app is None:
359 raise NoAppException(
360 "Could not locate a Flask application. Use the"
361 " 'flask --app' option, 'FLASK_APP' environment"
362 " variable, or a 'wsgi.py' or 'app.py' file in the"
363 " current directory."
364 )
366 if self.set_debug_flag:
367 # Update the app's debug flag through the descriptor so that
368 # other values repopulate as well.
369 app.debug = get_debug_flag()
371 self._loaded_app = app
372 return app
375pass_script_info = click.make_pass_decorator(ScriptInfo, ensure=True)
377F = t.TypeVar("F", bound=t.Callable[..., t.Any])
380def with_appcontext(f: F) -> F:
381 """Wraps a callback so that it's guaranteed to be executed with the
382 script's application context.
384 Custom commands (and their options) registered under ``app.cli`` or
385 ``blueprint.cli`` will always have an app context available, this
386 decorator is not required in that case.
388 .. versionchanged:: 2.2
389 The app context is active for subcommands as well as the
390 decorated callback. The app context is always available to
391 ``app.cli`` command and parameter callbacks.
392 """
394 @click.pass_context
395 def decorator(ctx: click.Context, /, *args: t.Any, **kwargs: t.Any) -> t.Any:
396 if not current_app:
397 app = ctx.ensure_object(ScriptInfo).load_app()
398 ctx.with_resource(app.app_context())
400 return ctx.invoke(f, *args, **kwargs)
402 return update_wrapper(decorator, f) # type: ignore[return-value]
405class AppGroup(click.Group):
406 """This works similar to a regular click :class:`~click.Group` but it
407 changes the behavior of the :meth:`command` decorator so that it
408 automatically wraps the functions in :func:`with_appcontext`.
410 Not to be confused with :class:`FlaskGroup`.
411 """
413 def command( # type: ignore[override]
414 self, *args: t.Any, **kwargs: t.Any
415 ) -> t.Callable[[t.Callable[..., t.Any]], click.Command]:
416 """This works exactly like the method of the same name on a regular
417 :class:`click.Group` but it wraps callbacks in :func:`with_appcontext`
418 unless it's disabled by passing ``with_appcontext=False``.
419 """
420 wrap_for_ctx = kwargs.pop("with_appcontext", True)
422 def decorator(f: t.Callable[..., t.Any]) -> click.Command:
423 if wrap_for_ctx:
424 f = with_appcontext(f)
425 return super(AppGroup, self).command(*args, **kwargs)(f) # type: ignore[no-any-return]
427 return decorator
429 def group( # type: ignore[override]
430 self, *args: t.Any, **kwargs: t.Any
431 ) -> t.Callable[[t.Callable[..., t.Any]], click.Group]:
432 """This works exactly like the method of the same name on a regular
433 :class:`click.Group` but it defaults the group class to
434 :class:`AppGroup`.
435 """
436 kwargs.setdefault("cls", AppGroup)
437 return super().group(*args, **kwargs) # type: ignore[no-any-return]
440def _set_app(ctx: click.Context, param: click.Option, value: str | None) -> str | None:
441 if value is None:
442 return None
444 info = ctx.ensure_object(ScriptInfo)
445 info.app_import_path = value
446 return value
449# This option is eager so the app will be available if --help is given.
450# --help is also eager, so --app must be before it in the param list.
451# no_args_is_help bypasses eager processing, so this option must be
452# processed manually in that case to ensure FLASK_APP gets picked up.
453_app_option = click.Option(
454 ["-A", "--app"],
455 metavar="IMPORT",
456 help=(
457 "The Flask application or factory function to load, in the form 'module:name'."
458 " Module can be a dotted import or file path. Name is not required if it is"
459 " 'app', 'application', 'create_app', or 'make_app', and can be 'name(args)' to"
460 " pass arguments."
461 ),
462 is_eager=True,
463 expose_value=False,
464 callback=_set_app,
465)
468def _set_debug(ctx: click.Context, param: click.Option, value: bool) -> bool | None:
469 # If the flag isn't provided, it will default to False. Don't use
470 # that, let debug be set by env in that case.
471 source = ctx.get_parameter_source(param.name) # type: ignore[arg-type]
473 if source is not None and source in (
474 ParameterSource.DEFAULT,
475 ParameterSource.DEFAULT_MAP,
476 ):
477 return None
479 # Set with env var instead of ScriptInfo.load so that it can be
480 # accessed early during a factory function.
481 os.environ["FLASK_DEBUG"] = "1" if value else "0"
482 return value
485_debug_option = click.Option(
486 ["--debug/--no-debug"],
487 help="Set debug mode.",
488 expose_value=False,
489 callback=_set_debug,
490)
493def _env_file_callback(
494 ctx: click.Context, param: click.Option, value: str | None
495) -> str | None:
496 try:
497 import dotenv # noqa: F401
498 except ImportError:
499 # Only show an error if a value was passed, otherwise we still want to
500 # call load_dotenv and show a message without exiting.
501 if value is not None:
502 raise click.BadParameter(
503 "python-dotenv must be installed to load an env file.",
504 ctx=ctx,
505 param=param,
506 ) from None
508 # Load if a value was passed, or we want to load default files, or both.
509 if value is not None or ctx.obj.load_dotenv_defaults:
510 load_dotenv(value, load_defaults=ctx.obj.load_dotenv_defaults)
512 return value
515# This option is eager so env vars are loaded as early as possible to be
516# used by other options.
517_env_file_option = click.Option(
518 ["-e", "--env-file"],
519 type=click.Path(exists=True, dir_okay=False),
520 help=(
521 "Load environment variables from this file, taking precedence over"
522 " those set by '.env' and '.flaskenv'. Variables set directly in the"
523 " environment take highest precedence. python-dotenv must be installed."
524 ),
525 is_eager=True,
526 expose_value=False,
527 callback=_env_file_callback,
528)
531class FlaskGroup(AppGroup):
532 """Special subclass of the :class:`AppGroup` group that supports
533 loading more commands from the configured Flask app. Normally a
534 developer does not have to interface with this class but there are
535 some very advanced use cases for which it makes sense to create an
536 instance of this. see :ref:`custom-scripts`.
538 :param add_default_commands: if this is True then the default run and
539 shell commands will be added.
540 :param add_version_option: adds the ``--version`` option.
541 :param create_app: an optional callback that is passed the script info and
542 returns the loaded app.
543 :param load_dotenv: Load the nearest :file:`.env` and :file:`.flaskenv`
544 files to set environment variables. Will also change the working
545 directory to the directory containing the first file found.
546 :param set_debug_flag: Set the app's debug flag.
548 .. versionchanged:: 3.1
549 ``-e path`` takes precedence over default ``.env`` and ``.flaskenv`` files.
551 .. versionchanged:: 2.2
552 Added the ``-A/--app``, ``--debug/--no-debug``, ``-e/--env-file`` options.
554 .. versionchanged:: 2.2
555 An app context is pushed when running ``app.cli`` commands, so
556 ``@with_appcontext`` is no longer required for those commands.
558 .. versionchanged:: 1.0
559 If installed, python-dotenv will be used to load environment variables
560 from :file:`.env` and :file:`.flaskenv` files.
561 """
563 def __init__(
564 self,
565 add_default_commands: bool = True,
566 create_app: t.Callable[..., Flask] | None = None,
567 add_version_option: bool = True,
568 load_dotenv: bool = True,
569 set_debug_flag: bool = True,
570 **extra: t.Any,
571 ) -> None:
572 params: list[click.Parameter] = list(extra.pop("params", None) or ())
573 # Processing is done with option callbacks instead of a group
574 # callback. This allows users to make a custom group callback
575 # without losing the behavior. --env-file must come first so
576 # that it is eagerly evaluated before --app.
577 params.extend((_env_file_option, _app_option, _debug_option))
579 if add_version_option:
580 params.append(version_option)
582 if "context_settings" not in extra:
583 extra["context_settings"] = {}
585 extra["context_settings"].setdefault("auto_envvar_prefix", "FLASK")
587 super().__init__(params=params, **extra)
589 self.create_app = create_app
590 self.load_dotenv = load_dotenv
591 self.set_debug_flag = set_debug_flag
593 if add_default_commands:
594 self.add_command(run_command)
595 self.add_command(shell_command)
596 self.add_command(routes_command)
598 self._loaded_plugin_commands = False
600 def _load_plugin_commands(self) -> None:
601 if self._loaded_plugin_commands:
602 return
604 if sys.version_info >= (3, 10):
605 from importlib import metadata
606 else:
607 # Use a backport on Python < 3.10. We technically have
608 # importlib.metadata on 3.8+, but the API changed in 3.10,
609 # so use the backport for consistency.
610 import importlib_metadata as metadata # pyright: ignore
612 for ep in metadata.entry_points(group="flask.commands"):
613 self.add_command(ep.load(), ep.name)
615 self._loaded_plugin_commands = True
617 def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
618 self._load_plugin_commands()
619 # Look up built-in and plugin commands, which should be
620 # available even if the app fails to load.
621 rv = super().get_command(ctx, name)
623 if rv is not None:
624 return rv
626 info = ctx.ensure_object(ScriptInfo)
628 # Look up commands provided by the app, showing an error and
629 # continuing if the app couldn't be loaded.
630 try:
631 app = info.load_app()
632 except NoAppException as e:
633 click.secho(f"Error: {e.format_message()}\n", err=True, fg="red")
634 return None
636 # Push an app context for the loaded app unless it is already
637 # active somehow. This makes the context available to parameter
638 # and command callbacks without needing @with_appcontext.
639 if not current_app or current_app._get_current_object() is not app: # type: ignore[attr-defined]
640 ctx.with_resource(app.app_context())
642 return app.cli.get_command(ctx, name)
644 def list_commands(self, ctx: click.Context) -> list[str]:
645 self._load_plugin_commands()
646 # Start with the built-in and plugin commands.
647 rv = set(super().list_commands(ctx))
648 info = ctx.ensure_object(ScriptInfo)
650 # Add commands provided by the app, showing an error and
651 # continuing if the app couldn't be loaded.
652 try:
653 rv.update(info.load_app().cli.list_commands(ctx))
654 except NoAppException as e:
655 # When an app couldn't be loaded, show the error message
656 # without the traceback.
657 click.secho(f"Error: {e.format_message()}\n", err=True, fg="red")
658 except Exception:
659 # When any other errors occurred during loading, show the
660 # full traceback.
661 click.secho(f"{traceback.format_exc()}\n", err=True, fg="red")
663 return sorted(rv)
665 def make_context(
666 self,
667 info_name: str | None,
668 args: list[str],
669 parent: click.Context | None = None,
670 **extra: t.Any,
671 ) -> click.Context:
672 # Set a flag to tell app.run to become a no-op. If app.run was
673 # not in a __name__ == __main__ guard, it would start the server
674 # when importing, blocking whatever command is being called.
675 os.environ["FLASK_RUN_FROM_CLI"] = "true"
677 if "obj" not in extra and "obj" not in self.context_settings:
678 extra["obj"] = ScriptInfo(
679 create_app=self.create_app,
680 set_debug_flag=self.set_debug_flag,
681 load_dotenv_defaults=self.load_dotenv,
682 )
684 return super().make_context(info_name, args, parent=parent, **extra)
686 def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
687 if (not args and self.no_args_is_help) or (
688 len(args) == 1 and args[0] in self.get_help_option_names(ctx)
689 ):
690 # Attempt to load --env-file and --app early in case they
691 # were given as env vars. Otherwise no_args_is_help will not
692 # see commands from app.cli.
693 _env_file_option.handle_parse_result(ctx, {}, [])
694 _app_option.handle_parse_result(ctx, {}, [])
696 return super().parse_args(ctx, args)
699def _path_is_ancestor(path: str, other: str) -> bool:
700 """Take ``other`` and remove the length of ``path`` from it. Then join it
701 to ``path``. If it is the original value, ``path`` is an ancestor of
702 ``other``."""
703 return os.path.join(path, other[len(path) :].lstrip(os.sep)) == other
706def load_dotenv(
707 path: str | os.PathLike[str] | None = None, load_defaults: bool = True
708) -> bool:
709 """Load "dotenv" files to set environment variables. A given path takes
710 precedence over ``.env``, which takes precedence over ``.flaskenv``. After
711 loading and combining these files, values are only set if the key is not
712 already set in ``os.environ``.
714 This is a no-op if `python-dotenv`_ is not installed.
716 .. _python-dotenv: https://github.com/theskumar/python-dotenv#readme
718 :param path: Load the file at this location.
719 :param load_defaults: Search for and load the default ``.flaskenv`` and
720 ``.env`` files.
721 :return: ``True`` if at least one env var was loaded.
723 .. versionchanged:: 3.1
724 Added the ``load_defaults`` parameter. A given path takes precedence
725 over default files.
727 .. versionchanged:: 2.0
728 The current directory is not changed to the location of the
729 loaded file.
731 .. versionchanged:: 2.0
732 When loading the env files, set the default encoding to UTF-8.
734 .. versionchanged:: 1.1.0
735 Returns ``False`` when python-dotenv is not installed, or when
736 the given path isn't a file.
738 .. versionadded:: 1.0
739 """
740 try:
741 import dotenv
742 except ImportError:
743 if path or os.path.isfile(".env") or os.path.isfile(".flaskenv"):
744 click.secho(
745 " * Tip: There are .env files present. Install python-dotenv"
746 " to use them.",
747 fg="yellow",
748 err=True,
749 )
751 return False
753 data: dict[str, str | None] = {}
755 if load_defaults:
756 for default_name in (".flaskenv", ".env"):
757 if not (default_path := dotenv.find_dotenv(default_name, usecwd=True)):
758 continue
760 data |= dotenv.dotenv_values(default_path, encoding="utf-8")
762 if path is not None and os.path.isfile(path):
763 data |= dotenv.dotenv_values(path, encoding="utf-8")
765 for key, value in data.items():
766 if key in os.environ or value is None:
767 continue
769 os.environ[key] = value
771 return bool(data) # True if at least one env var was loaded.
774def show_server_banner(debug: bool, app_import_path: str | None) -> None:
775 """Show extra startup messages the first time the server is run,
776 ignoring the reloader.
777 """
778 if is_running_from_reloader():
779 return
781 if app_import_path is not None:
782 click.echo(f" * Serving Flask app '{app_import_path}'")
784 if debug is not None:
785 click.echo(f" * Debug mode: {'on' if debug else 'off'}")
788class CertParamType(click.ParamType):
789 """Click option type for the ``--cert`` option. Allows either an
790 existing file, the string ``'adhoc'``, or an import for a
791 :class:`~ssl.SSLContext` object.
792 """
794 name = "path"
796 def __init__(self) -> None:
797 self.path_type = click.Path(exists=True, dir_okay=False, resolve_path=True)
799 def convert(
800 self, value: t.Any, param: click.Parameter | None, ctx: click.Context | None
801 ) -> t.Any:
802 try:
803 import ssl
804 except ImportError:
805 raise click.BadParameter(
806 'Using "--cert" requires Python to be compiled with SSL support.',
807 ctx,
808 param,
809 ) from None
811 try:
812 return self.path_type(value, param, ctx)
813 except click.BadParameter:
814 value = click.STRING(value, param, ctx).lower()
816 if value == "adhoc":
817 try:
818 import cryptography # noqa: F401
819 except ImportError:
820 raise click.BadParameter(
821 "Using ad-hoc certificates requires the cryptography library.",
822 ctx,
823 param,
824 ) from None
826 return value
828 obj = import_string(value, silent=True)
830 if isinstance(obj, ssl.SSLContext):
831 return obj
833 raise
836def _validate_key(ctx: click.Context, param: click.Parameter, value: t.Any) -> t.Any:
837 """The ``--key`` option must be specified when ``--cert`` is a file.
838 Modifies the ``cert`` param to be a ``(cert, key)`` pair if needed.
839 """
840 cert = ctx.params.get("cert")
841 is_adhoc = cert == "adhoc"
843 try:
844 import ssl
845 except ImportError:
846 is_context = False
847 else:
848 is_context = isinstance(cert, ssl.SSLContext)
850 if value is not None:
851 if is_adhoc:
852 raise click.BadParameter(
853 'When "--cert" is "adhoc", "--key" is not used.', ctx, param
854 )
856 if is_context:
857 raise click.BadParameter(
858 'When "--cert" is an SSLContext object, "--key" is not used.',
859 ctx,
860 param,
861 )
863 if not cert:
864 raise click.BadParameter('"--cert" must also be specified.', ctx, param)
866 ctx.params["cert"] = cert, value
868 else:
869 if cert and not (is_adhoc or is_context):
870 raise click.BadParameter('Required when using "--cert".', ctx, param)
872 return value
875class SeparatedPathType(click.Path):
876 """Click option type that accepts a list of values separated by the
877 OS's path separator (``:``, ``;`` on Windows). Each value is
878 validated as a :class:`click.Path` type.
879 """
881 def convert(
882 self, value: t.Any, param: click.Parameter | None, ctx: click.Context | None
883 ) -> t.Any:
884 items = self.split_envvar_value(value)
885 # can't call no-arg super() inside list comprehension until Python 3.12
886 super_convert = super().convert
887 return [super_convert(item, param, ctx) for item in items]
890@click.command("run", short_help="Run a development server.")
891@click.option("--host", "-h", default="127.0.0.1", help="The interface to bind to.")
892@click.option("--port", "-p", default=5000, help="The port to bind to.")
893@click.option(
894 "--cert",
895 type=CertParamType(),
896 help="Specify a certificate file to use HTTPS.",
897 is_eager=True,
898)
899@click.option(
900 "--key",
901 type=click.Path(exists=True, dir_okay=False, resolve_path=True),
902 callback=_validate_key,
903 expose_value=False,
904 help="The key file to use when specifying a certificate.",
905)
906@click.option(
907 "--reload/--no-reload",
908 default=None,
909 help="Enable or disable the reloader. By default the reloader "
910 "is active if debug is enabled.",
911)
912@click.option(
913 "--debugger/--no-debugger",
914 default=None,
915 help="Enable or disable the debugger. By default the debugger "
916 "is active if debug is enabled.",
917)
918@click.option(
919 "--with-threads/--without-threads",
920 default=True,
921 help="Enable or disable multithreading.",
922)
923@click.option(
924 "--extra-files",
925 default=None,
926 type=SeparatedPathType(),
927 help=(
928 "Extra files that trigger a reload on change. Multiple paths"
929 f" are separated by {os.path.pathsep!r}."
930 ),
931)
932@click.option(
933 "--exclude-patterns",
934 default=None,
935 type=SeparatedPathType(),
936 help=(
937 "Files matching these fnmatch patterns will not trigger a reload"
938 " on change. Multiple patterns are separated by"
939 f" {os.path.pathsep!r}."
940 ),
941)
942@pass_script_info
943def run_command(
944 info: ScriptInfo,
945 host: str,
946 port: int,
947 reload: bool,
948 debugger: bool,
949 with_threads: bool,
950 cert: ssl.SSLContext | tuple[str, str | None] | t.Literal["adhoc"] | None,
951 extra_files: list[str] | None,
952 exclude_patterns: list[str] | None,
953) -> None:
954 """Run a local development server.
956 This server is for development purposes only. It does not provide
957 the stability, security, or performance of production WSGI servers.
959 The reloader and debugger are enabled by default with the '--debug'
960 option.
961 """
962 try:
963 app: WSGIApplication = info.load_app() # pyright: ignore
964 except Exception as e:
965 if is_running_from_reloader():
966 # When reloading, print out the error immediately, but raise
967 # it later so the debugger or server can handle it.
968 traceback.print_exc()
969 err = e
971 def app(
972 environ: WSGIEnvironment, start_response: StartResponse
973 ) -> cabc.Iterable[bytes]:
974 raise err from None
976 else:
977 # When not reloading, raise the error immediately so the
978 # command fails.
979 raise e from None
981 debug = get_debug_flag()
983 if reload is None:
984 reload = debug
986 if debugger is None:
987 debugger = debug
989 show_server_banner(debug, info.app_import_path)
991 run_simple(
992 host,
993 port,
994 app,
995 use_reloader=reload,
996 use_debugger=debugger,
997 threaded=with_threads,
998 ssl_context=cert,
999 extra_files=extra_files,
1000 exclude_patterns=exclude_patterns,
1001 )
1004run_command.params.insert(0, _debug_option)
1007@click.command("shell", short_help="Run a shell in the app context.")
1008@with_appcontext
1009def shell_command() -> None:
1010 """Run an interactive Python shell in the context of a given
1011 Flask application. The application will populate the default
1012 namespace of this shell according to its configuration.
1014 This is useful for executing small snippets of management code
1015 without having to manually configure the application.
1016 """
1017 import code
1019 banner = (
1020 f"Python {sys.version} on {sys.platform}\n"
1021 f"App: {current_app.import_name}\n"
1022 f"Instance: {current_app.instance_path}"
1023 )
1024 ctx: dict[str, t.Any] = {}
1026 # Support the regular Python interpreter startup script if someone
1027 # is using it.
1028 startup = os.environ.get("PYTHONSTARTUP")
1029 if startup and os.path.isfile(startup):
1030 with open(startup) as f:
1031 eval(compile(f.read(), startup, "exec"), ctx)
1033 ctx.update(current_app.make_shell_context())
1035 # Site, customize, or startup script can set a hook to call when
1036 # entering interactive mode. The default one sets up readline with
1037 # tab and history completion.
1038 interactive_hook = getattr(sys, "__interactivehook__", None)
1040 if interactive_hook is not None:
1041 try:
1042 import readline
1043 from rlcompleter import Completer
1044 except ImportError:
1045 pass
1046 else:
1047 # rlcompleter uses __main__.__dict__ by default, which is
1048 # flask.__main__. Use the shell context instead.
1049 readline.set_completer(Completer(ctx).complete)
1051 interactive_hook()
1053 code.interact(banner=banner, local=ctx)
1056@click.command("routes", short_help="Show the routes for the app.")
1057@click.option(
1058 "--sort",
1059 "-s",
1060 type=click.Choice(("endpoint", "methods", "domain", "rule", "match")),
1061 default="endpoint",
1062 help=(
1063 "Method to sort routes by. 'match' is the order that Flask will match routes"
1064 " when dispatching a request."
1065 ),
1066)
1067@click.option("--all-methods", is_flag=True, help="Show HEAD and OPTIONS methods.")
1068@with_appcontext
1069def routes_command(sort: str, all_methods: bool) -> None:
1070 """Show all registered routes with endpoints and methods."""
1071 rules = list(current_app.url_map.iter_rules())
1073 if not rules:
1074 click.echo("No routes were registered.")
1075 return
1077 ignored_methods = set() if all_methods else {"HEAD", "OPTIONS"}
1078 host_matching = current_app.url_map.host_matching
1079 has_domain = any(rule.host if host_matching else rule.subdomain for rule in rules)
1080 rows = []
1082 for rule in rules:
1083 row = [
1084 rule.endpoint,
1085 ", ".join(sorted((rule.methods or set()) - ignored_methods)),
1086 ]
1088 if has_domain:
1089 row.append((rule.host if host_matching else rule.subdomain) or "")
1091 row.append(rule.rule)
1092 rows.append(row)
1094 headers = ["Endpoint", "Methods"]
1095 sorts = ["endpoint", "methods"]
1097 if has_domain:
1098 headers.append("Host" if host_matching else "Subdomain")
1099 sorts.append("domain")
1101 headers.append("Rule")
1102 sorts.append("rule")
1104 try:
1105 rows.sort(key=itemgetter(sorts.index(sort)))
1106 except ValueError:
1107 pass
1109 rows.insert(0, headers)
1110 widths = [max(len(row[i]) for row in rows) for i in range(len(headers))]
1111 rows.insert(1, ["-" * w for w in widths])
1112 template = " ".join(f"{{{i}:<{w}}}" for i, w in enumerate(widths))
1114 for row in rows:
1115 click.echo(template.format(*row))
1118cli = FlaskGroup(
1119 name="flask",
1120 help="""\
1121A general utility script for Flask applications.
1123An application to load must be given with the '--app' option,
1124'FLASK_APP' environment variable, or with a 'wsgi.py' or 'app.py' file
1125in the current directory.
1126""",
1127)
1130def main() -> None:
1131 cli.main()
1134if __name__ == "__main__":
1135 main()