codekingpro/portable-devtools

1from __future__ import annotations2 3import ast4import collections.abc as cabc5import importlib.metadata6import inspect7import os8import platform9import re10import sys11import traceback12import typing as t13from functools import update_wrapper14from operator import itemgetter15from types import ModuleType16 17import click18from click.core import ParameterSource19from werkzeug import run_simple20from werkzeug.serving import is_running_from_reloader21from werkzeug.utils import import_string22 23from .globals import current_app24from .helpers import get_debug_flag25from .helpers import get_load_dotenv26 27if t.TYPE_CHECKING:28    import ssl29 30    from _typeshed.wsgi import StartResponse31    from _typeshed.wsgi import WSGIApplication32    from _typeshed.wsgi import WSGIEnvironment33 34    from .app import Flask35 36 37class NoAppException(click.UsageError):38    """Raised if an application cannot be found or loaded."""39 40 41def find_best_app(module: ModuleType) -> Flask:42    """Given a module instance this tries to find the best possible43    application in the module or raises an exception.44    """45    from . import Flask46 47    # Search for the most common names first.48    for attr_name in ("app", "application"):49        app = getattr(module, attr_name, None)50 51        if isinstance(app, Flask):52            return app53 54    # Otherwise find the only object that is a Flask instance.55    matches = [v for v in module.__dict__.values() if isinstance(v, Flask)]56 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        )65 66    # Search for app factory functions.67    for attr_name in ("create_app", "make_app"):68        app_factory = getattr(module, attr_name, None)69 70        if inspect.isfunction(app_factory):71            try:72                app = app_factory()73 74                if isinstance(app, Flask):75                    return app76            except TypeError as e:77                if not _called_with_wrong_args(app_factory):78                    raise79 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 e86 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    )92 93 94def _called_with_wrong_args(f: t.Callable[..., Flask]) -> bool:95    """Check whether calling a function raised a ``TypeError`` because96    the call failed or because something in the factory raised the97    error.98 99    :param f: The function that was called.100    :return: ``True`` if the call failed.101    """102    tb = sys.exc_info()[2]103 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 False109 110            tb = tb.tb_next111 112        # Didn't reach the function.113        return True114    finally:115        # Delete tb to break a circular reference.116        # https://docs.python.org/2/library/sys.html#sys.exc_info117        del tb118 119 120def find_app_by_string(module: ModuleType, app_name: str) -> Flask:121    """Check if the given string is a variable name or a function. Call122    a function to get the app instance, or return the variable directly.123    """124    from . import Flask125 126    # Parse app_name as a single expression to determine if it's a valid127    # attribute name or function call.128    try:129        expr = ast.parse(app_name.strip(), mode="eval").body130    except SyntaxError:131        raise NoAppException(132            f"Failed to parse {app_name!r} as an attribute name or function call."133        ) from None134 135    if isinstance(expr, ast.Name):136        name = expr.id137        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            )145 146        name = expr.func.id147 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.keywords154                if kw.arg is not None155            }156        except ValueError:157            # literal_eval gives cryptic error messages, show a generic158            # message with the full expression instead.159            raise NoAppException(160                f"Failed to parse arguments as literal values: {app_name!r}."161            ) from None162    else:163        raise NoAppException(164            f"Failed to parse {app_name!r} as an attribute name or function call."165        )166 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 e173 174    # If the attribute is a function, call it with any args and kwargs175    # 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                raise182 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 e188    else:189        app = attr190 191    if isinstance(app, Flask):192        return app193 194    raise NoAppException(195        "A valid Flask application was not obtained from"196        f" '{module.__name__}:{app_name}'."197    )198 199 200def prepare_import(path: str) -> str:201    """Given a filename this will try to calculate the python path, add it202    to the search path and return the actual module name that is expected.203    """204    path = os.path.realpath(path)205 206    fname, ext = os.path.splitext(path)207    if ext == ".py":208        path = fname209 210    if os.path.basename(path) == "__init__":211        path = os.path.dirname(path)212 213    module_name = []214 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)219 220        if not os.path.exists(os.path.join(path, "__init__.py")):221            break222 223    if sys.path[0] != path:224        sys.path.insert(0, path)225 226    return ".".join(module_name[::-1])227 228 229@t.overload230def locate_app(231    module_name: str, app_name: str | None, raise_if_not_found: t.Literal[True] = True232) -> Flask: ...233 234 235@t.overload236def locate_app(237    module_name: str, app_name: str | None, raise_if_not_found: t.Literal[False] = ...238) -> Flask | None: ...239 240 241def locate_app(242    module_name: str, app_name: str | None, raise_if_not_found: bool = True243) -> 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 None254        elif raise_if_not_found:255            raise NoAppException(f"Could not import {module_name!r}.") from None256        else:257            return None258 259    module = sys.modules[module_name]260 261    if app_name is None:262        return find_best_app(module)263    else:264        return find_app_by_string(module, app_name)265 266 267def get_version(ctx: click.Context, param: click.Parameter, value: t.Any) -> None:268    if not value or ctx.resilient_parsing:269        return270 271    flask_version = importlib.metadata.version("flask")272    werkzeug_version = importlib.metadata.version("werkzeug")273 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()281 282 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)291 292 293class ScriptInfo:294    """Helper object to deal with Flask applications.  This is usually not295    necessary to interface with as it's used internally in the dispatching296    to click.  In future versions of Flask this object will most likely play297    a bigger role.  Typically it's created automatically by the298    :class:`FlaskGroup` but you can also manually create it and pass it299    onwards as click object.300 301    .. versionchanged:: 3.1302        Added the ``load_dotenv_defaults`` parameter and attribute.303    """304 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_path314        #: Optionally a function that is passed the script info to create315        #: the instance of the application.316        self.create_app = create_app317        #: A dictionary with arbitrary data that can be associated with318        #: this script info.319        self.data: dict[t.Any, t.Any] = {}320        self.set_debug_flag = set_debug_flag321 322        self.load_dotenv_defaults = get_load_dotenv(load_dotenv_defaults)323        """Whether default ``.flaskenv`` and ``.env`` files should be loaded.324 325        ``ScriptInfo`` doesn't load anything, this is for reference when doing326        the load elsewhere during processing.327 328        .. versionadded:: 3.1329        """330 331        self._loaded_app: Flask | None = None332 333    def load_app(self) -> Flask:334        """Loads the Flask app (if not yet loaded) and returns it.  Calling335        this multiple times will just result in the already loaded app to336        be returned.337        """338        if self._loaded_app is not None:339            return self._loaded_app340        app: Flask | None = None341        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)354 355                    if app is not None:356                        break357 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            )365 366        if self.set_debug_flag:367            # Update the app's debug flag through the descriptor so that368            # other values repopulate as well.369            app.debug = get_debug_flag()370 371        self._loaded_app = app372        return app373 374 375pass_script_info = click.make_pass_decorator(ScriptInfo, ensure=True)376 377F = t.TypeVar("F", bound=t.Callable[..., t.Any])378 379 380def with_appcontext(f: F) -> F:381    """Wraps a callback so that it's guaranteed to be executed with the382    script's application context.383 384    Custom commands (and their options) registered under ``app.cli`` or385    ``blueprint.cli`` will always have an app context available, this386    decorator is not required in that case.387 388    .. versionchanged:: 2.2389        The app context is active for subcommands as well as the390        decorated callback. The app context is always available to391        ``app.cli`` command and parameter callbacks.392    """393 394    @click.pass_context395    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())399 400        return ctx.invoke(f, *args, **kwargs)401 402    return update_wrapper(decorator, f)  # type: ignore[return-value]403 404 405class AppGroup(click.Group):406    """This works similar to a regular click :class:`~click.Group` but it407    changes the behavior of the :meth:`command` decorator so that it408    automatically wraps the functions in :func:`with_appcontext`.409 410    Not to be confused with :class:`FlaskGroup`.411    """412 413    def command(  # type: ignore[override]414        self, *args: t.Any, **kwargs: t.Any415    ) -> t.Callable[[t.Callable[..., t.Any]], click.Command]:416        """This works exactly like the method of the same name on a regular417        :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)421 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]426 427        return decorator428 429    def group(  # type: ignore[override]430        self, *args: t.Any, **kwargs: t.Any431    ) -> t.Callable[[t.Callable[..., t.Any]], click.Group]:432        """This works exactly like the method of the same name on a regular433        :class:`click.Group` but it defaults the group class to434        :class:`AppGroup`.435        """436        kwargs.setdefault("cls", AppGroup)437        return super().group(*args, **kwargs)  # type: ignore[no-any-return]438 439 440def _set_app(ctx: click.Context, param: click.Option, value: str | None) -> str | None:441    if value is None:442        return None443 444    info = ctx.ensure_object(ScriptInfo)445    info.app_import_path = value446    return value447 448 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 be452# 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)466 467 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 use470    # that, let debug be set by env in that case.471    source = ctx.get_parameter_source(param.name)  # type: ignore[arg-type]472 473    if source is not None and source in (474        ParameterSource.DEFAULT,475        ParameterSource.DEFAULT_MAP,476    ):477        return None478 479    # Set with env var instead of ScriptInfo.load so that it can be480    # accessed early during a factory function.481    os.environ["FLASK_DEBUG"] = "1" if value else "0"482    return value483 484 485_debug_option = click.Option(486    ["--debug/--no-debug"],487    help="Set debug mode.",488    expose_value=False,489    callback=_set_debug,490)491 492 493def _env_file_callback(494    ctx: click.Context, param: click.Option, value: str | None495) -> str | None:496    try:497        import dotenv  # noqa: F401498    except ImportError:499        # Only show an error if a value was passed, otherwise we still want to500        # 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 None507 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)511 512    return value513 514 515# This option is eager so env vars are loaded as early as possible to be516# 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)529 530 531class FlaskGroup(AppGroup):532    """Special subclass of the :class:`AppGroup` group that supports533    loading more commands from the configured Flask app.  Normally a534    developer does not have to interface with this class but there are535    some very advanced use cases for which it makes sense to create an536    instance of this. see :ref:`custom-scripts`.537 538    :param add_default_commands: if this is True then the default run and539        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 and542        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 working545        directory to the directory containing the first file found.546    :param set_debug_flag: Set the app's debug flag.547 548    .. versionchanged:: 3.1549        ``-e path`` takes precedence over default ``.env`` and ``.flaskenv`` files.550 551    .. versionchanged:: 2.2552        Added the ``-A/--app``, ``--debug/--no-debug``, ``-e/--env-file`` options.553 554    .. versionchanged:: 2.2555        An app context is pushed when running ``app.cli`` commands, so556        ``@with_appcontext`` is no longer required for those commands.557 558    .. versionchanged:: 1.0559        If installed, python-dotenv will be used to load environment variables560        from :file:`.env` and :file:`.flaskenv` files.561    """562 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 group574        # callback. This allows users to make a custom group callback575        # without losing the behavior. --env-file must come first so576        # that it is eagerly evaluated before --app.577        params.extend((_env_file_option, _app_option, _debug_option))578 579        if add_version_option:580            params.append(version_option)581 582        if "context_settings" not in extra:583            extra["context_settings"] = {}584 585        extra["context_settings"].setdefault("auto_envvar_prefix", "FLASK")586 587        super().__init__(params=params, **extra)588 589        self.create_app = create_app590        self.load_dotenv = load_dotenv591        self.set_debug_flag = set_debug_flag592 593        if add_default_commands:594            self.add_command(run_command)595            self.add_command(shell_command)596            self.add_command(routes_command)597 598        self._loaded_plugin_commands = False599 600    def _load_plugin_commands(self) -> None:601        if self._loaded_plugin_commands:602            return603 604        if sys.version_info >= (3, 10):605            from importlib import metadata606        else:607            # Use a backport on Python < 3.10. We technically have608            # 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: ignore611 612        for ep in metadata.entry_points(group="flask.commands"):613            self.add_command(ep.load(), ep.name)614 615        self._loaded_plugin_commands = True616 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 be620        # available even if the app fails to load.621        rv = super().get_command(ctx, name)622 623        if rv is not None:624            return rv625 626        info = ctx.ensure_object(ScriptInfo)627 628        # Look up commands provided by the app, showing an error and629        # 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 None635 636        # Push an app context for the loaded app unless it is already637        # active somehow. This makes the context available to parameter638        # 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())641 642        return app.cli.get_command(ctx, name)643 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)649 650        # Add commands provided by the app, showing an error and651        # 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 message656            # 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 the660            # full traceback.661            click.secho(f"{traceback.format_exc()}\n", err=True, fg="red")662 663        return sorted(rv)664 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 was673        # not in a __name__ == __main__ guard, it would start the server674        # when importing, blocking whatever command is being called.675        os.environ["FLASK_RUN_FROM_CLI"] = "true"676 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            )683 684        return super().make_context(info_name, args, parent=parent, **extra)685 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 they691            # were given as env vars. Otherwise no_args_is_help will not692            # see commands from app.cli.693            _env_file_option.handle_parse_result(ctx, {}, [])694            _app_option.handle_parse_result(ctx, {}, [])695 696        return super().parse_args(ctx, args)697 698 699def _path_is_ancestor(path: str, other: str) -> bool:700    """Take ``other`` and remove the length of ``path`` from it. Then join it701    to ``path``. If it is the original value, ``path`` is an ancestor of702    ``other``."""703    return os.path.join(path, other[len(path) :].lstrip(os.sep)) == other704 705 706def load_dotenv(707    path: str | os.PathLike[str] | None = None, load_defaults: bool = True708) -> bool:709    """Load "dotenv" files to set environment variables. A given path takes710    precedence over ``.env``, which takes precedence over ``.flaskenv``. After711    loading and combining these files, values are only set if the key is not712    already set in ``os.environ``.713 714    This is a no-op if `python-dotenv`_ is not installed.715 716    .. _python-dotenv: https://github.com/theskumar/python-dotenv#readme717 718    :param path: Load the file at this location.719    :param load_defaults: Search for and load the default ``.flaskenv`` and720        ``.env`` files.721    :return: ``True`` if at least one env var was loaded.722 723    .. versionchanged:: 3.1724        Added the ``load_defaults`` parameter. A given path takes precedence725        over default files.726 727    .. versionchanged:: 2.0728        The current directory is not changed to the location of the729        loaded file.730 731    .. versionchanged:: 2.0732        When loading the env files, set the default encoding to UTF-8.733 734    .. versionchanged:: 1.1.0735        Returns ``False`` when python-dotenv is not installed, or when736        the given path isn't a file.737 738    .. versionadded:: 1.0739    """740    try:741        import dotenv742    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            )750 751        return False752 753    data: dict[str, str | None] = {}754 755    if load_defaults:756        for default_name in (".flaskenv", ".env"):757            if not (default_path := dotenv.find_dotenv(default_name, usecwd=True)):758                continue759 760            data |= dotenv.dotenv_values(default_path, encoding="utf-8")761 762    if path is not None and os.path.isfile(path):763        data |= dotenv.dotenv_values(path, encoding="utf-8")764 765    for key, value in data.items():766        if key in os.environ or value is None:767            continue768 769        os.environ[key] = value770 771    return bool(data)  # True if at least one env var was loaded.772 773 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        return780 781    if app_import_path is not None:782        click.echo(f" * Serving Flask app '{app_import_path}'")783 784    if debug is not None:785        click.echo(f" * Debug mode: {'on' if debug else 'off'}")786 787 788class CertParamType(click.ParamType):789    """Click option type for the ``--cert`` option. Allows either an790    existing file, the string ``'adhoc'``, or an import for a791    :class:`~ssl.SSLContext` object.792    """793 794    name = "path"795 796    def __init__(self) -> None:797        self.path_type = click.Path(exists=True, dir_okay=False, resolve_path=True)798 799    def convert(800        self, value: t.Any, param: click.Parameter | None, ctx: click.Context | None801    ) -> t.Any:802        try:803            import ssl804        except ImportError:805            raise click.BadParameter(806                'Using "--cert" requires Python to be compiled with SSL support.',807                ctx,808                param,809            ) from None810 811        try:812            return self.path_type(value, param, ctx)813        except click.BadParameter:814            value = click.STRING(value, param, ctx).lower()815 816            if value == "adhoc":817                try:818                    import cryptography  # noqa: F401819                except ImportError:820                    raise click.BadParameter(821                        "Using ad-hoc certificates requires the cryptography library.",822                        ctx,823                        param,824                    ) from None825 826                return value827 828            obj = import_string(value, silent=True)829 830            if isinstance(obj, ssl.SSLContext):831                return obj832 833            raise834 835 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"842 843    try:844        import ssl845    except ImportError:846        is_context = False847    else:848        is_context = isinstance(cert, ssl.SSLContext)849 850    if value is not None:851        if is_adhoc:852            raise click.BadParameter(853                'When "--cert" is "adhoc", "--key" is not used.', ctx, param854            )855 856        if is_context:857            raise click.BadParameter(858                'When "--cert" is an SSLContext object, "--key" is not used.',859                ctx,860                param,861            )862 863        if not cert:864            raise click.BadParameter('"--cert" must also be specified.', ctx, param)865 866        ctx.params["cert"] = cert, value867 868    else:869        if cert and not (is_adhoc or is_context):870            raise click.BadParameter('Required when using "--cert".', ctx, param)871 872    return value873 874 875class SeparatedPathType(click.Path):876    """Click option type that accepts a list of values separated by the877    OS's path separator (``:``, ``;`` on Windows). Each value is878    validated as a :class:`click.Path` type.879    """880 881    def convert(882        self, value: t.Any, param: click.Parameter | None, ctx: click.Context | None883    ) -> t.Any:884        items = self.split_envvar_value(value)885        # can't call no-arg super() inside list comprehension until Python 3.12886        super_convert = super().convert887        return [super_convert(item, param, ctx) for item in items]888 889 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_info943def 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.955 956    This server is for development purposes only. It does not provide957    the stability, security, or performance of production WSGI servers.958 959    The reloader and debugger are enabled by default with the '--debug'960    option.961    """962    try:963        app: WSGIApplication = info.load_app()  # pyright: ignore964    except Exception as e:965        if is_running_from_reloader():966            # When reloading, print out the error immediately, but raise967            # it later so the debugger or server can handle it.968            traceback.print_exc()969            err = e970 971            def app(972                environ: WSGIEnvironment, start_response: StartResponse973            ) -> cabc.Iterable[bytes]:974                raise err from None975 976        else:977            # When not reloading, raise the error immediately so the978            # command fails.979            raise e from None980 981    debug = get_debug_flag()982 983    if reload is None:984        reload = debug985 986    if debugger is None:987        debugger = debug988 989    show_server_banner(debug, info.app_import_path)990 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    )1002 1003 1004run_command.params.insert(0, _debug_option)1005 1006 1007@click.command("shell", short_help="Run a shell in the app context.")1008@with_appcontext1009def shell_command() -> None:1010    """Run an interactive Python shell in the context of a given1011    Flask application.  The application will populate the default1012    namespace of this shell according to its configuration.1013 1014    This is useful for executing small snippets of management code1015    without having to manually configure the application.1016    """1017    import code1018 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] = {}1025 1026    # Support the regular Python interpreter startup script if someone1027    # 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)1032 1033    ctx.update(current_app.make_shell_context())1034 1035    # Site, customize, or startup script can set a hook to call when1036    # entering interactive mode. The default one sets up readline with1037    # tab and history completion.1038    interactive_hook = getattr(sys, "__interactivehook__", None)1039 1040    if interactive_hook is not None:1041        try:1042            import readline1043            from rlcompleter import Completer1044        except ImportError:1045            pass1046        else:1047            # rlcompleter uses __main__.__dict__ by default, which is1048            # flask.__main__. Use the shell context instead.1049            readline.set_completer(Completer(ctx).complete)1050 1051        interactive_hook()1052 1053    code.interact(banner=banner, local=ctx)1054 1055 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_appcontext1069def 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())1072 1073    if not rules:1074        click.echo("No routes were registered.")1075        return1076 1077    ignored_methods = set() if all_methods else {"HEAD", "OPTIONS"}1078    host_matching = current_app.url_map.host_matching1079    has_domain = any(rule.host if host_matching else rule.subdomain for rule in rules)1080    rows = []1081 1082    for rule in rules:1083        row = [1084            rule.endpoint,1085            ", ".join(sorted((rule.methods or set()) - ignored_methods)),1086        ]1087 1088        if has_domain:1089            row.append((rule.host if host_matching else rule.subdomain) or "")1090 1091        row.append(rule.rule)1092        rows.append(row)1093 1094    headers = ["Endpoint", "Methods"]1095    sorts = ["endpoint", "methods"]1096 1097    if has_domain:1098        headers.append("Host" if host_matching else "Subdomain")1099        sorts.append("domain")1100 1101    headers.append("Rule")1102    sorts.append("rule")1103 1104    try:1105        rows.sort(key=itemgetter(sorts.index(sort)))1106    except ValueError:1107        pass1108 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))1113 1114    for row in rows:1115        click.echo(template.format(*row))1116 1117 1118cli = FlaskGroup(1119    name="flask",1120    help="""\1121A general utility script for Flask applications.1122 1123An application to load must be given with the '--app' option,1124'FLASK_APP' environment variable, or with a 'wsgi.py' or 'app.py' file1125in the current directory.1126""",1127)1128 1129 1130def main() -> None:1131    cli.main()1132 1133 1134if __name__ == "__main__":1135    main()1136