Skip to main content

Using Specialized Parameter Types

Leverage specialized Click parameter types in the Flask CLI to handle complex configurations like SSL certificates and multi-path lists. These types, found in flask.cli, provide built-in validation and transformation for common development server options.

Handling SSL Certificates with CertParamType​

Use CertParamType to allow users to specify SSL certificates in three different ways: a file path, the string 'adhoc', or an import path to an ssl.SSLContext object.

In src/flask/cli.py, this is implemented for the run command as follows:

import click
from flask.cli import CertParamType, _validate_key

@click.command("run")
@click.option(
    "--cert",
    type=CertParamType(),
    help="Specify a certificate file to use HTTPS.",
    is_eager=True,
)
@click.option(
    "--key",
    type=click.Path(exists=True, dir_okay=False, resolve_path=True),
    callback=_validate_key,
    expose_value=False,
    help="The key file to use when specifying a certificate.",
)
def run_command(cert, **kwargs):
    # cert will be a path string, 'adhoc', or an SSLContext object
    # If a path was provided, _validate_key converts it to (cert_path, key_path)
    pass

Supported Certificate Modes​

  1. File Path: If a valid file path is provided, CertParamType returns the resolved path. You must also provide a --key file. The _validate_key callback ensures that if a file is used for --cert, a corresponding --key is present, and it combines them into a tuple (cert_path, key_path).
  2. Ad-hoc Certificates: Passing --cert adhoc generates a temporary certificate. This requires the cryptography library to be installed.
  3. SSLContext Import: You can provide a dotted import path to an existing ssl.SSLContext object (e.g., --cert myapp.ssl.context). CertParamType uses werkzeug.utils.import_string to load the object.

Handling Multiple Paths with SeparatedPathType​

Use SeparatedPathType when an option needs to accept multiple file paths or patterns in a single string, separated by the operating system's path separator (: on Linux/macOS, ; on Windows).

This is used in src/flask/cli.py for the --extra-files and --exclude-patterns options:

import os
from flask.cli import SeparatedPathType

@click.command("run")
@click.option(
    "--extra-files",
    default=None,
    type=SeparatedPathType(),
    help=(
        "Extra files that trigger a reload on change. Multiple paths"
        f" are separated by {os.path.pathsep!r}."
    ),
)
def run_command(extra_files, **kwargs):
    # extra_files is a list of resolved path strings
    if extra_files:
        for path in extra_files:
            print(f"Watching: {path}")

SeparatedPathType automatically splits the input string using os.path.pathsep and runs each individual path through the standard click.Path validation.

Troubleshooting and Requirements​

  • Missing Cryptography: If you use --cert adhoc without the cryptography library installed, CertParamType will raise a click.BadParameter error: "Using ad-hoc certificates requires the cryptography library."
  • SSL Support: The ssl module must be available in your Python installation. If not, using --cert will result in: "Using \"--cert\" requires Python to be compiled with SSL support."
  • Key Validation: When using a file path for --cert, you must provide --key. Conversely, if you use 'adhoc' or an SSLContext object, providing --key will trigger a validation error from _validate_key.
  • Path Separators: SeparatedPathType is OS-dependent. Ensure you use the correct separator for your environment (e.g., export FLASK_RUN_EXTRA_FILES=file1.txt:file2.txt on Linux).