« Changelog History


click v8.0 Release Notes

  • 🚀 Unreleased

    • 👍 Drop support for Python 2 and 3.5.
    • 💅 Colorama is always installed on Windows in order to provide style and color support. :pr:1784
    • Adds a repr to Command, showing the command name for friendlier debugging. :issue:1267, :pr:1295
    • 👍 Add support for distinguishing the source of a command line parameter. :issue:1264, :pr:1329
    • ⚡️ Add an optional parameter to ProgressBar.update to set the current_item. :issue:1226, :pr:1332
    • 📇 version_option uses importlib.metadata (or the importlib_metadata backport) instead of pkg_resources. :issue:1582
    • If validation fails for a prompt with hide_input=True, the value is not shown in the error message. :issue:1460
    • An IntRange or FloatRange option shows the accepted range in its help text. :issue:1525, :pr:1303
    • IntRange and FloatRange bounds can be open (<) instead of closed (<=) by setting min_open and max_open. Error messages have changed to reflect this. :issue:1100
    • An option defined with duplicate flag names ("--foo/--foo") raises a ValueError. :issue:1465
    • ✅ echo() will not fail when using pytest's capsys fixture on Windows. :issue:1590
    • Resolving commands returns the canonical command name instead of the matched name. This makes behavior such as help text and Context.invoked_subcommand consistent when using patterns like AliasedGroup. :issue:1422
    • The BOOL type accepts the values "on" and "off". :issue:1629
    • A Group with invoke_without_command=True will always invoke its result callback. :issue:1178
    • 📜 nargs == -1 and nargs > 1 is parsed and validated for values from environment variables and defaults. :issue:729
    • 📦 Detect the program name when executing a module or package with python -m name. :issue:1603
    • Include required parent arguments in help synopsis of subcommands. :issue:1475
    • 0️⃣ Help for boolean flags with show_default=True shows the flag name instead of True or False. :issue:1538
    • 💅 Non-string objects passed to style() and secho() will be converted to string. :pr:1146
    • edit(require_save=True) will detect saves for editors that exit very fast on filesystems with 1 second resolution. :pr:1050

    • New class attributes make it easier to use custom core objects throughout an entire application. :pr:938

      • Command.context_class controls the context created when running the command.
      • Context.invoke creates new contexts of the same type, so a custom type will persist to invoked subcommands.
      • Context.formatter_class controls the formatter used to generate help and usage.
      • Group.command_class changes the default type for subcommands with @group.command().
      • Group.group_class changes the default type for subgroups with @group.group(). Setting it to type will create subgroups of the same type as the group itself.
      • Core objects use super() consistently for better support of subclassing.

    • Use Context.with_resource() to manage resources that would normally be used in a with statement, allowing them to be used across subcommands and callbacks, then cleaned up when the context ends. :pr:1191

    • ✅ The result object returned by the test runner's invoke() method has a return_value attribute with the value returned by the invoked command. :pr:1312

    • Required arguments with the Choice type show the choices in curly braces to indicate that one is required ({a|b|c}). :issue:1272

    • If only a name is passed to option(), Click suggests renaming it to --name. :pr:1355

    • 0️⃣ A context's show_default parameter defaults to the value from the parent context. :issue:1565

    • 💅 click.style() can output 256 and RGB color codes. Most modern terminals support these codes. :pr:1429

    • When using CliRunner.invoke(), the replaced stdin file has name and mode attributes. This lets File options with the - value match non-testing behavior. :issue:1064

    • When creating a Group, allow passing a list of commands instead of a dict. :issue:1339

    • 👍 When a long option name isn't valid, use difflib to make better suggestions for possible corrections. :issue:1446

    • Core objects have a to_info_dict() method. This gathers information about the object's structure that could be useful for a tool generating user-facing documentation. To get the structure of an entire CLI, use Context(cli).to_info_dict(). :issue:461

    • Redesign the shell completion system. :issue:1484, :pr:1622

      • Support Bash >= 4.4, Zsh, and Fish, with the ability for extensions to add support for other shells.
      • Allow commands, groups, parameters, and types to override their completions suggestions.
      • Groups complete the names commands were registered with, which can differ from the name they were created with.
      • The autocompletion parameter for options and arguments is renamed to shell_complete. The function must take ctx, param, incomplete, must do matching rather than return all values, and must return a list of strings or a list of ShellComplete. The old name and behavior is deprecated and will be removed in 8.1.
      • The env var values used to start completion have changed order. The shell now comes first, such as {shell}_source rather than source_{shell}, and is always required.

    • 📜 Completion correctly parses command line strings with incomplete quoting or escape sequences. :issue:1708

    • Extra context settings (obj=..., etc.) are passed on to the completion system. :issue:942

    • Include --help option in completion. :pr:1504

    • ParameterSource is an enum.Enum subclass. :issue:1530

    • Boolean and UUID types strip surrounding space before converting. :issue:1605

    • Adjusted error message from parameter type validation to be more consistent. Quotes are used to distinguish the invalid value. :issue:1605

    • 0️⃣ The default value for a parameter with nargs > 1 and multiple=True must be a list of tuples. :issue:1649

    • 0️⃣ When getting the value for a parameter, the default is tried in the same section as other sources to ensure consistent processing. :issue:1649

    • All parameter types accept a value that is already the correct type. :issue:1649

    • For shell completion, an argument is considered incomplete if its value did not come from the command line args. :issue:1649

    • Added ParameterSource.PROMPT to track parameter values that were prompted for. :issue:1649

    • 0️⃣ Options with nargs > 1 no longer raise an error if a default is not given. Parameters with nargs > 1 default to None, and parameters with multiple=True or nargs=-1 default to an empty tuple. :issue:472

    • Handle empty env vars as though the option were not passed. This extends the change introduced in 7.1 to be consistent in more cases. :issue:1285

    • 0️⃣ Parameter.get_default() checks Context.default_map to handle overrides consistently in help text, invoke(), and prompts. :issue:1548

    • Add prompt_required param to Option. When set to False, the user will only be prompted for an input if no value was passed. :issue:736

    • Providing the value to an option can be made optional through is_flag=False, and the value can instead be prompted for or passed in as a default value. :issue:549, 736, 764, 921, 1015, 1618

    • Fix formatting when Command.options_metavar is empty. :pr:1551

    • ⏪ Revert adding space between option help text that wraps. :issue:1831

    • 0️⃣ The default value passed to prompt will be cast to the correct type like an input value would be. :pr:1517

    • Automatically generated short help messages will stop at the first ending of a phrase or double linebreak. :issue:1082

    • Skip progress bar render steps for efficiency with very fast iterators by setting update_min_steps. :issue:676

    • Respect case_sensitive=False when doing shell completion for Choice :issue:1692

    • Use mkstemp() instead of mktemp() in pager implementation. :issue:1752

    • 0️⃣ If Option.show_default is a string, it is displayed even if default is None. :issue:1732

    • click.get_terminal_size() is deprecated and will be removed in 8.1. Use :func:shutil.get_terminal_size instead. :issue:1736

    • Control the location of the temporary directory created by CLIRunner.isolated_filesystem by passing temp_dir. A custom directory will not be removed automatically. :issue:395

    • click.confirm() will prompt until input is given if called with default=None. :issue:1381

    • Option prompts validate the value with the option's callback in addition to its type. :issue:457

    • confirmation_prompt can be set to a custom string. :issue:723

    • 💅 Allow styled output in Jupyter on Windows. :issue:1271

    • 💅 style() supports the strikethrough, italic, and overline styles. :issue:805, 1821

    • 🚚 Multiline marker is removed from short help text. :issue:1597

    • ⏪ Restore progress bar behavior of echoing only the label if the file is not a TTY. :issue:1138

    • Progress bar output is shown even if execution time is less than 0.5 seconds. :issue:1648

    • 👉 Progress bar item_show_func shows the current item, not the previous item. :issue:1353

    • The Path param type can be passed path_type=pathlib.Path to return a path object instead of a string. :issue:405

    • TypeError is raised when parameter with multiple=True or nargs > 1 has non-iterable default. :issue:1749

    • Add a pass_meta_key decorator for passing a key from Context.meta. This is useful for extensions using meta to store information. :issue:1739

    • 🏁 Path resolve_path resolves symlinks on Windows Python < 3.8. :issue:1813

    • 🗄 Command deprecation notice appears at the start of the help text, as well as in the short help. The notice is not in all caps. :issue:1791

    • 🏁 When taking arguments from sys.argv on Windows, glob patterns, user dir, and env vars are expanded. :issue:1096

    • Marked messages shown by the CLI with gettext() to allow applications to translate Click's built-in strings. :issue:303

    • ✅ Writing invalid characters to stderr when using the test runner does not raise a UnicodeEncodeError. :issue:848

    • Fix an issue where readline would clear the entire prompt() line instead of only the input when pressing backspace. :issue:665

    • Add all kwargs passed to Context.invoke() to ctx.params. Fixes an inconsistency when nesting Context.forward() calls. :issue:1568

    • The MultiCommand.resultcallback decorator is renamed to result_callback. The old name is deprecated. :issue:1160

    • Fix issues with CliRunner output when using echo_stdin=True. :issue:1101

    • 0️⃣ Fix a bug of click.utils.make_default_short_help for which the returned string could be as long as max_width + 3. :issue:1849

    • 0️⃣ When defining a parameter, default is validated with multiple and nargs. More validation is done for values being processed as well. :issue:1806