All Versions
Latest Version
Avg Release Cycle
149 days
Latest Release

Changelog History
Page 1

  • v8.2.0 Changes

    ๐Ÿš€ Unreleased

  • v8.1.3 Changes

    ๐Ÿš€ Released 2022-04-28

    • Use verbose form of typing.Callable for @command and @group. :issue:2255
    • Show error when attempting to create an option with multiple=True, is_flag=True. Use count instead. :issue:2246
  • v8.1.2 Changes

    ๐Ÿš€ Released 2022-03-31

    • Fix error message for readable path check that was mixed up with the executable check. :pr:2236
    • โช Restore parameter order for Path, placing the executable parameter at the end. It is recommended to use keyword arguments instead of positional arguments. :issue:2235
  • v8.1.1 Changes

    ๐Ÿš€ Released 2022-03-30

    • Fix an issue with decorator typing that caused type checking to report that a command was not callable. :issue:2227
  • v8.1.0 Changes

    ๐Ÿš€ Released 2022-03-28

    • ๐Ÿ‘ Drop support for Python 3.6. :pr:2129
    • ๐Ÿšš Remove previously deprecated code. :pr:2130

      • Group.resultcallback is renamed to result_callback.
      • autocompletion parameter to Command is renamed to shell_complete.
      • get_terminal_size is removed, use shutil.get_terminal_size instead.
      • get_os_args is removed, use sys.argv[1:] instead.
    • Rely on :pep:538 and :pep:540 to handle selecting UTF-8 encoding instead of ASCII. Click's locale encoding detection is removed. :issue:2198

    • 0๏ธโƒฃ Single options boolean flags with show_default=True only show the default if it is True. :issue:1971

    • The command and group decorators can be applied with or without parentheses. :issue:1359

    • The Path type can check whether the target is executable. :issue:1961

    • 0๏ธโƒฃ Command.show_default overrides Context.show_default, instead of the other way around. :issue:1963

    • Parameter decorators and @group handles cls=None the same as not passing cls. @option handles help=None the same as not passing help. :issue:#1959

    • A flag option with required=True requires that the flag is passed instead of choosing the implicit default value. :issue:1978

    • Indentation in help text passed to Option and Command is cleaned the same as using the @option and @command decorators does. A command's epilog and short_help are also processed. :issue:1985

    • Store unprocessed, epilog and short_help strings. Processing is only done when formatting help text for output. :issue:2149

    • Allow empty str input for prompt() when confirmation_prompt=True and default="". :issue:2157

    • ๐Ÿ Windows glob pattern expansion doesn't fail if a value is an invalid pattern. :issue:2195

    • It's possible to pass a list of params to @command. Any params defined with decorators are appended to the passed params. :issue:2131.

    • @command decorator is annotated as returning the correct type if a cls argument is used. :issue:2211

    • A Group with invoke_without_command=True and chain=False will invoke its result callback with the group function's return value. :issue:2124

    • to_info_dict will not fail if a ParamType doesn't define a name. :issue:2168

    • ๐Ÿ›  Shell completion prioritizes option values with option prefixes over new options. :issue:2040

    • Options that get an environment variable value using autoenvvar_prefix treat an empty value as None, consistent with a direct envvar. :issue:2146

  • v8.0.4 Changes

    ๐Ÿš€ Released 2022-02-18

    • open_file recognizes Path("-") as a standard stream, the same as the string "-". :issue:2106
    • The option and argument decorators preserve the type annotation of the decorated function. :pr:2155
    • 0๏ธโƒฃ A callable default value can customize its help text by overriding __str__ instead of always showing (dynamic). :issue:2099
    • Fix a typo in the Bash completion script that affected file and directory completion. If this script was generated by a previous version, it should be regenerated. :issue:2163
    • Fix typing for echo and secho file argument. :issue:2174, 2185
  • v8.0.3 Changes

    ๐Ÿš€ Released 2021-10-10

    • Fix issue with Path(resolve_path=True) type creating invalid paths. :issue:2088
    • Importing readline does not cause the confirm() prompt to disappear when pressing backspace. :issue:2092
    • 0๏ธโƒฃ Any default values injected by invoke() are cast to the corresponding parameter's type. :issue:2089, 2090
  • v8.0.2 Changes

    ๐Ÿš€ Released 2021-10-08

    • is_bool_flag is not set to True if is_flag is False. :issue:1925
    • Bash version detection is locale independent. :issue:1940
    • 0๏ธโƒฃ Empty default value is not shown for multiple=True. :issue:1969
    • Fix shell completion for arguments that start with a forward slash such as absolute file paths. :issue:1929
    • Path type with resolve_path=True resolves relative symlinks to be relative to the containing directory. :issue:1921
    • Completion does not skip Python's resource cleanup when exiting, avoiding some unexpected warning output. :issue:1738, 2017
    • Fix type annotation for type argument in prompt function. :issue:2062
    • ๐Ÿ’… Fix overline and italic styles, which were incorrectly added when adding underline. :pr:2058
    • An option with count=True will not show "[x>=0]" in help text. :issue:2072
    • 0๏ธโƒฃ Default values are not cast to the parameter type twice during processing. :issue:2085
    • Options with multiple and flag_value use the flag value instead of leaving an internal placeholder. :issue:2001
  • v8.0.1 Changes

    ๐Ÿš€ Released 2021-05-19

    • Mark top-level names as exported so type checking understand imports in user projects. :issue:1879
    • Annotate Context.obj as Any so type checking allows all operations on the arbitrary object. :issue:1885
    • Fix some types that weren't available in Python 3.6.0. :issue:1882
    • Fix type checking for iterating over ProgressBar object. :issue:1892
    • ๐Ÿ“‡ The importlib_metadata backport package is installed on Python < 3.8. :issue:1889
    • Arguments with nargs=-1 only use env var value if no command line values are given. :issue:1903
    • Flag options guess their type from flag_value if given, like regular options do from default. :issue:1886
    • ๐Ÿ“š Added documentation that custom parameter types may be passed already valid values in addition to strings. :issue:1898
    • Resolving commands returns the name that was given, not, fixing an unintended change to help text and default_map lookups. When using patterns like AliasedGroup, override resolve_command to change the name that is returned if needed. :issue:1895
    • 0๏ธโƒฃ If a default value is invalid, it does not prevent showing help text. :issue:1889
    • Pass windows_expand_args=False when calling the main command to disable pattern expansion on Windows. There is no way to escape patterns in CMD, so if the program needs to pass them on as-is then expansion must be disabled. :issue:1901
  • v8.0 Changes

    ๐Ÿš€ 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 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

    • ๐Ÿ’… 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