Changes¶
Version 8.2.1¶
Released 2025-05-20
Version 8.2.0¶
Released 2025-05-10
Use modern packaging metadata with
pyproject.tomlinstead ofsetup.cfg. #2438Use
flit_coreinstead ofsetuptoolsas build backend. #2543Deprecate the
__version__attribute. Use feature detection, orimportlib.metadata.version("click"), instead. #2598BaseCommandis deprecated.Commandis the base class for all commands. #2589MultiCommandis deprecated.Groupis the base class for all group commands. #2590The current parser and related classes and methods, are deprecated. #2205
OptionParserand theparsermodule, which is a modified copy ofoptparsein the standard library.Context.protected_argsis unneeded.Context.argscontains any remaining arguments while parsing.Parameter.add_to_parser(on bothArgumentandOption) is unneeded. Parsing works directly without building a separate parser.split_arg_stringis moved fromparsertoshell_completion.
Enable deferred evaluation of annotations with
from __future__ import annotations. #2270When generating a command’s name from a decorated function’s name, the suffixes
_command,_cmd,_group, and_grpare removed. #2322Show the
types.ParamType.namefortypes.Choiceoptions within--helpmessage ifshow_choices=Falseis specified. #2356Do not display default values in prompts when
Option.show_defaultisFalse. #2509Add
get_help_extramethod onOptionto fetch the generated extra items used inget_help_recordto render help text. #2516 #2517Keep stdout and stderr streams independent in
CliRunner. Always collect stderr output and never raise an exception. Add a new output stream to simulate what the user sees in its terminal. Removes themix_stderrparameter inCliRunner. #2522 #2523Option.show_envvarnow also shows environment variable in error messages. #2695 #2696Context.closewill be called on exit. This results in allContext.call_on_closecallbacks and context managers added viaContext.with_resourceto be closed on exit as well. #2680Add
ProgressBar(hidden: bool)to allow hiding the progressbar. #2609A
UserWarningwill be shown when multiple parameters attempt to use the same name. #2396When using
Option.envvarwithOption.flag_value, theflag_valuewill always be used instead of the value of the environment variable. #2746 #2788Add
Choice.get_invalid_choice_messagemethod for customizing the invalid choice message. #2621 #2622If help is shown because
no_args_is_helpis enabled (defaults toTruefor groups,Falsefor commands), the exit code is 2 instead of 0. #1489 #1489Contexts created during shell completion are closed properly, fixing a
ResourceWarningwhen usingclick.File. #2644 #2800 #2767click.edit(filename)now supports passing an iterable of filenames in case the editor supports editing multiple files at once. Its return type is now also typed:AnyStriftextis passed, otherwiseNone. #2067 #2068Specialized typing of
progressbar(length=...)asProgressBar[int]. #2630Improve
echo_via_pagerbehaviour in face of errors. #2674Terminate the pager in case a generator passed to
echo_via_pagerraises an exception.Ensure to always close the pipe to the pager process and wait for it to terminate.
echo_via_pagerwill not ignoreKeyboardInterruptanymore. This allows the user to search for future output of the generator when using less and then aborting the program using ctrl-c.
deprecated: bool | strcan now be used on options and arguments. This previously was only available forCommand. The message can now also be customised by using astrinstead of abool. #2263 #2271Command.deprecatedformatting in--helpchanged from(Deprecated) helptohelp (DEPRECATED).Parameters cannot be required nor prompted or an error is raised.
A warning will be printed when something deprecated is used.
Add a
catch_exceptionsparameter toCliRunner. Ifcatch_exceptionsis not passed toCliRunner.invoke, the value fromCliRunneris used. #2817 #2818Option.flag_valuewill no longer have a default value set based onOption.defaultifOption.is_flagisFalse. This results inOption.defaultnot needing to implement__bool__. #2829Incorrect
click.edittyping has been corrected. #2804Choiceis now generic and supports any iterable value. This allows you to use enums and other non-strvalues. #2796 #605Fix setup of help option’s defaults when using a custom class on its decorator. Removes
HelpOption. #2832 #2840
Version 8.1.8¶
Released 2024-12-19
Fix an issue with type hints for
click.open_file(). #2717Fix issue where error message for invalid
click.Pathdisplays on multiple lines. #2697Fixed issue that prevented a default value of
""from being displayed in the help for an option. #2500The test runner handles stripping color consistently on Windows. #2705
Show correct value for flag default when using
default_map. #2632Fix
click.echo(color=...)passingcolorto coloroma so it can be forced on Windows. #2606.More robust bash version check, fixing problem on Windows with git-bash. #2638
Cache the help option generated by the
help_option_namessetting to respect its eagerness. #2811Replace uses of
os.systemwithsubprocess.Popen. #1476Exceptions generated during a command will use the context’s
colorsetting when being displayed. #2193Error message when defining option with invalid name is more descriptive. #2452
Refactor code generating default
--helpoption to deduplicate code. #2563Test
CLIRunnerresets patched_compat.should_strip_ansi. #2732
Version 8.1.7¶
Released 2023-08-17
Version 8.1.6¶
Released 2023-07-18
Fix an issue with type hints for
@click.group(). #2558
Version 8.1.5¶
Released 2023-07-13
Fix an issue with type hints for
@click.command(),@click.option(), and other decorators. Introduce typing tests. #2558
Version 8.1.4¶
Released 2023-07-06
Replace all
typing.Dictoccurrences totyping.MutableMappingfor parameter hints. #2255Improve type hinting for decorators and give all generic types parameters. #2398
Fix return value and type signature of
shell_completion.add_completion_classfunction. #2421Bash version detection doesn’t fail on Windows. #2461
Completion works if there is a dot (
.) in the program name. #2166Improve type annotations for pyright type checker. #2268
Improve responsiveness of
click.clear(). #2284Improve command name detection when using Shiv or PEX. #2332
Avoid showing empty lines if command help text is empty. #2368
ZSH completion script works when loaded from
fpath. #2344.EOFErrorandKeyboardInterrupttracebacks are not suppressed whenstandalone_modeis disabled. #2380@group.commanddoes not fail if the group was created with a customcommand_class. #2416multiple=Trueis allowed for flag options again and does not require settingdefault=(). #2246, 2292, 2295Make the decorators returned by
@argument()and@option()reusable when theclsparameter is used. #2294Don’t fail when writing filenames to streams with strict errors. Replace invalid bytes with the replacement character (
�). #2395Remove unnecessary attempt to detect MSYS2 environment. #2355
Remove outdated and unnecessary detection of App Engine environment. #2554
echo()does not fail when no streams are attached, such as withpythonwon Windows. #2415Argument with
expose_value=Falsedo not cause completion to fail. #2336
Version 8.1.3¶
Released 2022-04-28
Version 8.1.2¶
Released 2022-03-31
Version 8.1.1¶
Released 2022-03-30
Fix an issue with decorator typing that caused type checking to report that a command was not callable. #2227
Version 8.1.0¶
Released 2022-03-28
Drop support for Python 3.6. #2129
Remove previously deprecated code. #2130
Group.resultcallbackis renamed toresult_callback.autocompletionparameter toCommandis renamed toshell_complete.get_terminal_sizeis removed, useshutil.get_terminal_sizeinstead.get_os_argsis removed, usesys.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. #2198
Single options boolean flags with
show_default=Trueonly show the default if it isTrue. #1971The
commandandgroupdecorators can be applied with or without parentheses. #1359The
Pathtype can check whether the target is executable. #1961Command.show_defaultoverridesContext.show_default, instead of the other way around. #1963Parameter decorators and
@grouphandlescls=Nonethe same as not passingcls.@optionhandleshelp=Nonethe same as not passinghelp. ##1959A flag option with
required=Truerequires that the flag is passed instead of choosing the implicit default value. #1978Indentation in help text passed to
OptionandCommandis cleaned the same as using the@optionand@commanddecorators does. A command’sepilogandshort_helpare also processed. #1985Store unprocessed
Command.help,epilogandshort_helpstrings. Processing is only done when formatting help text for output. #2149Allow empty str input for
prompt()whenconfirmation_prompt=Trueanddefault="". #2157Windows glob pattern expansion doesn’t fail if a value is an invalid pattern. #2195
It’s possible to pass a list of
paramsto@command. Any params defined with decorators are appended to the passed params. #2131.@commanddecorator is annotated as returning the correct type if aclsargument is used. #2211A
Groupwithinvoke_without_command=Trueandchain=Falsewill invoke its result callback with the group function’s return value. #2124to_info_dictwill not fail if aParamTypedoesn’t define aname. #2168Shell completion prioritizes option values with option prefixes over new options. #2040
Options that get an environment variable value using
autoenvvar_prefixtreat an empty value asNone, consistent with a directenvvar. #2146
Version 8.0.4¶
Released 2022-02-18
open_filerecognizesPath("-")as a standard stream, the same as the string"-". #2106The
optionandargumentdecorators preserve the type annotation of the decorated function. #2155A callable default value can customize its help text by overriding
__str__instead of always showing(dynamic). #2099Fix 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. #2163
Fix typing for
echoandsechofile argument. #2174, 2185
Version 8.0.3¶
Released 2021-10-10
Fix issue with
Path(resolve_path=True)type creating invalid paths. #2088Importing
readlinedoes not cause theconfirm()prompt to disappear when pressing backspace. #2092Any default values injected by
invoke()are cast to the corresponding parameter’s type. #2089, 2090
Version 8.0.2¶
Released 2021-10-08
is_bool_flagis not set toTrueifis_flagisFalse. #1925Bash version detection is locale independent. #1940
Empty
defaultvalue is not shown formultiple=True. #1969Fix shell completion for arguments that start with a forward slash such as absolute file paths. #1929
Pathtype withresolve_path=Trueresolves relative symlinks to be relative to the containing directory. #1921Completion does not skip Python’s resource cleanup when exiting, avoiding some unexpected warning output. #1738, 2017
Fix type annotation for
typeargument inpromptfunction. #2062Fix overline and italic styles, which were incorrectly added when adding underline. #2058
An option with
count=Truewill not show “[x>=0]” in help text. #2072Default values are not cast to the parameter type twice during processing. #2085
Options with
multipleandflag_valueuse the flag value instead of leaving an internal placeholder. #2001
Version 8.0.1¶
Released 2021-05-19
Mark top-level names as exported so type checking understand imports in user projects. #1879
Annotate
Context.objasAnyso type checking allows all operations on the arbitrary object. #1885Fix some types that weren’t available in Python 3.6.0. #1882
Fix type checking for iterating over
ProgressBarobject. #1892The
importlib_metadatabackport package is installed on Python < 3.8. #1889Arguments with
nargs=-1only use env var value if no command line values are given. #1903Flag options guess their type from
flag_valueif given, like regular options do fromdefault. #1886Added documentation that custom parameter types may be passed already valid values in addition to strings. #1898
Resolving commands returns the name that was given, not
command.name, fixing an unintended change to help text anddefault_maplookups. When using patterns likeAliasedGroup, overrideresolve_commandto change the name that is returned if needed. #1895If a default value is invalid, it does not prevent showing help text. #1889
Pass
windows_expand_args=Falsewhen 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. #1901
Version 8.0.0¶
Released 2021-05-11
Drop support for Python 2 and 3.5.
Colorama is always installed on Windows in order to provide style and color support. #1784
Adds a repr to Command, showing the command name for friendlier debugging. #1267, #1295
Add support for distinguishing the source of a command line parameter. #1264, #1329
Add an optional parameter to
ProgressBar.updateto set thecurrent_item. #1226, #1332version_optionusesimportlib.metadata(or theimportlib_metadatabackport) instead ofpkg_resources. The version is detected based on the package name, not the entry point name. The Python package name must match the installed package name, or be passed withpackage_name=. #1582If validation fails for a prompt with
hide_input=True, the value is not shown in the error message. #1460An
IntRangeorFloatRangeoption shows the accepted range in its help text. #1525, #1303IntRangeandFloatRangebounds can be open (<) instead of closed (<=) by settingmin_openandmax_open. Error messages have changed to reflect this. #1100An option defined with duplicate flag names (
"--foo/--foo") raises aValueError. #1465echo()will not fail when using pytest’scapsysfixture on Windows. #1590Resolving commands returns the canonical command name instead of the matched name. This makes behavior such as help text and
Context.invoked_subcommandconsistent when using patterns likeAliasedGroup. #1422The
BOOLtype accepts the values “on” and “off”. #1629A
Groupwithinvoke_without_command=Truewill always invoke its result callback. #1178nargs == -1andnargs > 1is parsed and validated for values from environment variables and defaults. #729Detect the program name when executing a module or package with
python -m name. #1603Include required parent arguments in help synopsis of subcommands. #1475
Help for boolean flags with
show_default=Trueshows the flag name instead ofTrueorFalse. #1538Non-string objects passed to
style()andsecho()will be converted to string. #1146edit(require_save=True)will detect saves for editors that exit very fast on filesystems with 1 second resolution. #1050New class attributes make it easier to use custom core objects throughout an entire application. #938
Command.context_classcontrols the context created when running the command.Context.invokecreates new contexts of the same type, so a custom type will persist to invoked subcommands.Context.formatter_classcontrols the formatter used to generate help and usage.Group.command_classchanges the default type for subcommands with@group.command().Group.group_classchanges the default type for subgroups with@group.group(). Setting it totypewill 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 awithstatement, allowing them to be used across subcommands and callbacks, then cleaned up when the context ends. #1191The result object returned by the test runner’s
invoke()method has areturn_valueattribute with the value returned by the invoked command. #1312Required arguments with the
Choicetype show the choices in curly braces to indicate that one is required ({a|b|c}). #1272If only a name is passed to
option(), Click suggests renaming it to--name. #1355A context’s
show_defaultparameter defaults to the value from the parent context. #1565click.style()can output 256 and RGB color codes. Most modern terminals support these codes. #1429When using
CliRunner.invoke(), the replacedstdinfile hasnameandmodeattributes. This letsFileoptions with the-value match non-testing behavior. #1064When creating a
Group, allow passing a list of commands instead of a dict. #1339When a long option name isn’t valid, use
difflibto make better suggestions for possible corrections. #1446Core 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, useContext(cli).to_info_dict(). #461Redesign the shell completion system. #1484, #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
autocompletionparameter for options and arguments is renamed toshell_complete. The function must takectx, param, incomplete, must do matching rather than return all values, and must return a list of strings or a list ofCompletionItem. 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}_sourcerather thansource_{shell}, and is always required.
Completion correctly parses command line strings with incomplete quoting or escape sequences. #1708
Extra context settings (
obj=..., etc.) are passed on to the completion system. #942Include
--helpoption in completion. #1504ParameterSourceis anenum.Enumsubclass. #1530Boolean and UUID types strip surrounding space before converting. #1605
Adjusted error message from parameter type validation to be more consistent. Quotes are used to distinguish the invalid value. #1605
The default value for a parameter with
nargs> 1 andmultiple=Truemust be a list of tuples. #1649When getting the value for a parameter, the default is tried in the same section as other sources to ensure consistent processing. #1649
All parameter types accept a value that is already the correct type. #1649
For shell completion, an argument is considered incomplete if its value did not come from the command line args. #1649
Added
ParameterSource.PROMPTto track parameter values that were prompted for. #1649Options with
nargs> 1 no longer raise an error if a default is not given. Parameters withnargs> 1 default toNone, and parameters withmultiple=Trueornargs=-1default to an empty tuple. #472Handle empty env vars as though the option were not passed. This extends the change introduced in 7.1 to be consistent in more cases. #1285
Parameter.get_default()checksContext.default_mapto handle overrides consistently in help text,invoke(), and prompts. #1548Add
prompt_requiredparam toOption. When set toFalse, the user will only be prompted for an input if no value was passed. #736Providing 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. #549, 736, 764, 921, 1015, 1618Fix formatting when
Command.options_metavaris empty. #1551Revert adding space between option help text that wraps. #1831
The default value passed to
promptwill be cast to the correct type like an input value would be. #1517Automatically generated short help messages will stop at the first ending of a phrase or double linebreak. #1082
Skip progress bar render steps for efficiency with very fast iterators by setting
update_min_steps. #676Respect
case_sensitive=Falsewhen doing shell completion forChoice#1692Use
mkstemp()instead ofmktemp()in pager implementation. #1752If
Option.show_defaultis a string, it is displayed even ifdefaultisNone. #1732click.get_terminal_size()is deprecated and will be removed in 8.1. Useshutil.get_terminal_size()instead. #1736Control the location of the temporary directory created by
CLIRunner.isolated_filesystemby passingtemp_dir. A custom directory will not be removed automatically. #395click.confirm()will prompt until input is given if called withdefault=None. #1381Option prompts validate the value with the option’s callback in addition to its type. #457
confirmation_promptcan be set to a custom string. #723Allow styled output in Jupyter on Windows. #1271
style()supports thestrikethrough,italic, andoverlinestyles. #805, 1821Multiline marker is removed from short help text. #1597
Restore progress bar behavior of echoing only the label if the file is not a TTY. #1138
Progress bar output is shown even if execution time is less than 0.5 seconds. #1648
Progress bar
item_show_funcshows the current item, not the previous item. #1353The
Pathparam type can be passedpath_type=pathlib.Pathto return a path object instead of a string. #405TypeErroris raised when parameter withmultiple=Trueornargs > 1has non-iterable default. #1749Add a
pass_meta_keydecorator for passing a key fromContext.meta. This is useful for extensions usingmetato store information. #1739Pathresolve_pathresolves symlinks on Windows Python < 3.8. #1813Command deprecation notice appears at the start of the help text, as well as in the short help. The notice is not in all caps. #1791
When taking arguments from
sys.argvon Windows, glob patterns, user dir, and env vars are expanded. #1096Marked messages shown by the CLI with
gettext()to allow applications to translate Click’s built-in strings. #303Writing invalid characters to
stderrwhen using the test runner does not raise aUnicodeEncodeError. #848Fix an issue where
readlinewould clear the entireprompt()line instead of only the input when pressing backspace. #665Add all kwargs passed to
Context.invoke()toctx.params. Fixes an inconsistency when nestingContext.forward()calls. #1568The
MultiCommand.resultcallbackdecorator is renamed toresult_callback. The old name is deprecated. #1160Fix issues with
CliRunneroutput when usingecho_stdin=True. #1101Fix a bug of
click.utils.make_default_short_helpfor which the returned string could be as long asmax_width + 3. #1849When defining a parameter,
defaultis validated withmultipleandnargs. More validation is done for values being processed as well. #1806HelpFormatter.write_textuses the full line width when wrapping text. #1871
Version 7.1.2¶
Released 2020-04-27
Revert applying shell quoting to commands for
echo_with_pagerandedit. This was intended to allows spaces in commands, but caused issues if the string was actually a command and arguments, or on Windows. Instead, the string must be quoted manually as it should appear on the command line. #1514
Version 7.1.1¶
Released 2020-03-09
Fix
ClickExceptionoutput going to stdout instead of stderr. #1495
Version 7.1¶
Released 2020-03-09
Fix PyPI package name, “click” is lowercase again.
Fix link in
unicode_literalserror message. #1151Add support for colored output on UNIX Jupyter notebooks. #1185
Operations that strip ANSI controls will strip the cursor hide/show sequences. #1216
Remove unused compat shim for
bytes. #1195Expand testing around termui, especially getchar on Windows. #1116
Fix output on Windows Python 2.7 built with MSVC 14. #1342
Fix
OSErrorwhen running in MSYS2. #1338Fix
OSErrorwhen redirecting toNULstream on Windows. #1065Fix memory leak when parsing Unicode arguments on Windows. #1136
Fix error in new AppEngine environments. #1462
Always return one of the passed choices for
click.Choice#1277, #1318Add
no_args_is_helpoption toclick.Command, defaults to False #1167Add
show_defaultparameter toContextto enable showing defaults globally. #1018Handle
env MYPATH=''as though the option were not passed. #1196It is once again possible to call
next(bar)on an active progress bar instance. #1125open_filewithatomic=Trueretains permissions of existing files and respects the current umask for new files. #1376When using the test
CliRunnerwithmix_stderr=False, ifresult.stderris empty it will not raise aValueError. #1193Remove the unused
mix_stderrparameter fromCliRunner.invoke. #1435Fix
TypeErrorraised when using bool flags and specifyingtype=bool. #1287Newlines in option help text are replaced with spaces before re-wrapping to avoid uneven line breaks. #834
MissingParameterexceptions are printable in the Python interpreter. #1139Fix how default values for file-type options are shown during prompts. #914
Fix environment variable automatic generation for commands containing
-. #1253Option help text replaces newlines with spaces when rewrapping, but preserves paragraph breaks, fixing multiline formatting. #834, 1066, 1397
Option help text that is wrapped adds an extra newline at the end to distinguish it from the next option. #1075
Consider
sensible-editorwhen determining the editor to use forclick.edit(). #1469Arguments to system calls such as the executable path passed to
click.editcan contains spaces. #1470Add ZSH completion autoloading and error handling. #1348
Add a repr to
Command,Group,Option, andArgument, showing the name for friendlier debugging. #1267Completion doesn’t consider option names if a value starts with
-after the--separator. #1247ZSH completion escapes special characters in values. #1418
Add completion support for Fish shell. #1423
Decoding bytes option values falls back to UTF-8 in more cases. #1468
Make the warning about old 2-arg parameter callbacks a deprecation warning, to be removed in 8.0. This has been a warning since Click 2.0. #1492
Adjust error messages to standardize the types of quotes used so they match error messages from Python.
Version 7.0¶
Released 2018-09-25
Drop support for Python 2.6 and 3.3. #967, 976
Document that ANSI color info isn’t parsed from bytearrays in Python 2. #334
Extract bar formatting to its own method. #414
Add
DateTimetype for converting input in given date time formats. #423secho’s first argument can now beNone, like inecho. #424Fixes a
ZeroDivisionErrorinProgressBar.make_step, when the arg passed to the first call ofProgressBar.updateis 0. #447, #1012Show progressbar only if total execution time is visible. #487
Added the ability to hide commands and options from help. #500
Non-standalone calls to
Context.exitreturn the exit code, rather than callingsys.exit. #667, #533, 1098click.getchar()returns Unicode in Python 3 on Windows, consistent with other platforms. #537, 821, 822, 1088, #1108Added
FloatRangetype. #538, 553Added support for bash completion of
type=click.ChoiceforOptionsandArguments. #535, #681Only allow one positional arg for
Argumentparameter declaration. #568, 574, #1014Add
case_sensitive=Falseas an option to Choice. #569click.getchar()correctly raisesKeyboardInterrupton “^C” andEOFErroron “^D” on Linux. #583, #1115Fix encoding issue with
click.getchar(echo=True)on Linux. #1115param_hintin errors now derived from param itself. #598, 704, #709Add a test that ensures that when an argument is formatted into a usage error, its metavar is used, not its name. #612
Allow setting
prog_nameas extra inCliRunner.invoke. #616, #999Help text taken from docstrings truncates at the
\fform feed character, useful for hiding Sphinx-style parameter documentation. #629, 1091launchnow works properly under Cygwin. #650CliRunner.invokenow may receiveargsas a string representing a Unix shell command. #664Make
Argument.make_metavar()default to type metavar. #675Add documentation for
ignore_unknown_options. #684Add bright colors support for
click.styleand fix the reset option for parametersfgandbg. #703, #809Add
show_envvarfor showing environment variables in help. #710Avoid
BrokenPipeErrorduring interpreter shutdown when stdout or stderr is a closed pipe. #712, #1106Disable
sys._getframes()on Python interpreters that don’t support it. #728Fix bug in test runner when calling
sys.exitwithNone. #739Fix crash on Windows console. #744
Fix bug that caused bash completion to give improper completions on chained commands. #754, #774
Added support for dynamic bash completion from a user-supplied callback. #755
Added support for bash completions containing spaces. #773
Allow autocompletion function to determine whether or not to return completions that start with the incomplete argument. #790, #806
Fix option naming routine to match documentation and be deterministic. #793, #794
Add test and documentation for
Optionnaming: functionality. #799Update doc to match arg name for
path_type. #801Raw strings added so correct escaping occurs. #807
Fix 16k character limit of
click.echoon Windows. #816, #819Overcome 64k character limit when writing to binary stream on Windows 7. #825, #830
Add bool conversion for “t” and “f”. #842
NoSuchOptionerrors takectxso that--helphint gets printed in error output. #860Fixed the behavior of Click error messages with regards to Unicode on 2.x and 3.x. Message is now always Unicode and the str and Unicode special methods work as you expect on that platform. #862
Progress bar now uses stderr by default. #863
Allow
CliRunnerto separate stdout and stderr. #868Fix invalid escape sequences. #877
Fix
ResourceWarningthat occurs during some tests. #878When detecting a misconfigured locale, don’t fail if the
localecommand fails. #880Add
case_sensitive=Falseas an option toChoicetypes. #887Force stdout/stderr writable. This works around issues with badly patched standard streams like those from Jupyter. #918
Fix completion of subcommand options after last argument #919, #930
_AtomicFilenow uses therealpathof the original filename so that changing the working directory does not affect it. #920Fix incorrect completions when defaults are present #925, #930
Add copy option attrs so that custom classes can be re-used. #926, #994
“x” and “a” file modes now use stdout when file is
"-". #929Fix missing comma in
__all__list. #935Stdout is now automatically set to non blocking. #954
Do not set options twice. #962
Move
fcntlimport. #965Fix Google App Engine
ImportError. #995Better handling of help text for dynamic default option values. #996
Fix
get_winter_size()so it correctly returns(0,0). #997Add test case checking for custom param type. #1001
Allow short width to address cmd formatting. #1002
Add details about Python version support. #1004
Added deprecation flag to commands. #1005
Fixed issues where
fdwas undefined. #1007Fix formatting for short help. #1008
Document how
auto_envvar_prefixworks with command groups. #1011Don’t add newlines by default for progress bars. #1013
Document that parameter names are converted to lowercase by default. #1055
Subcommands that are named by the function now automatically have the underscore replaced with a dash. If you register a function named
my_commandit becomesmy-commandin the command line interface.Hide hidden commands and options from completion. #1058, #1061
Fix absolute import blocking Click from being vendored into a project on Windows. #1068, #1069
Fix issue where a lowercase
auto_envvar_prefixwould not be converted to uppercase. #1105
Version 6.7¶
Released 2017-01-06
Version 6.6¶
Released 2016-04-04
Fix bug in
click.Pathwhere it would crash when passed a-. #551
Version 6.4¶
Released 2016-03-24
Fix bug in bash completion where click would discard one or more trailing arguments. #471
Version 6.3¶
Released 2016-02-22
Fix argument checks for interpreter invoke with
-mand-con Windows.Fixed a bug that cased locale detection to error out on Python 3.
Version 6.2¶
Released 2015-11-27
Correct fix for hidden progress bars.
Version 6.1¶
Released 2015-11-27
Resolved an issue with invisible progress bars no longer rendering.
Disable chain commands with subcommands as they were inherently broken.
Fix
MissingParameternot working without parameters passed.
Version 6.0¶
Released 2015-11-24, codename “pow pow”
Optimized the progressbar rendering to not render when it did not actually change.
Explicitly disallow
nargs=-1with a set default.The context is now closed before it’s popped from the stack.
Added support for short aliases for the false flag on toggles.
Click will now attempt to aid you with debugging locale errors better by listing with the help of the OS what locales are available.
Click used to return byte strings on Python 2 in some unit-testing situations. This has been fixed to correctly return unicode strings now.
For Windows users on Python 2, Click will now handle Unicode more correctly handle Unicode coming in from the system. This also has the disappointing side effect that filenames will now be always unicode by default in the
Pathtype which means that this can introduce small bugs for code not aware of this.Added a
typeparameter toPathto force a specific string type on the value.For users running Python on Windows the
echoandpromptfunctions now work with full unicode functionality in the Python windows console by emulating an output stream. This also applies to getting the virtual output and input streams viaclick.get_text_stream(...).Unittests now always force a certain virtual terminal width.
Added support for allowing dashes to indicate standard streams to the
Pathtype.Multi commands in chain mode no longer propagate arguments left over from parsing to the callbacks. It’s also now disallowed through an exception when optional arguments are attached to multi commands if chain mode is enabled.
Relaxed restriction that disallowed chained commands to have other chained commands as child commands.
Arguments with positive nargs can now have defaults implemented. Previously this configuration would often result in slightly unexpected values be returned.
Version 5.1¶
Released 2015-08-17
Fix a bug in
pass_objthat would accidentally pass the context too.
Version 5.0¶
Released 2015-08-16, codename “tok tok”
Removed various deprecated functionality.
Atomic files now only accept the
wmode.Change the usage part of help output for very long commands to wrap their arguments onto the next line, indented by 4 spaces.
Fix a bug where return code and error messages were incorrect when using
CliRunner.Added
get_current_context.Added a
metadictionary to the context which is shared across the linked list of contexts to allow click utilities to place state there.Introduced
Context.scope.The
echofunction is now threadsafe: It calls thewritemethod of the underlying object only once.prompt(hide_input=True)now prints a newline on^C.Click will now warn if users are using
unicode_literals.Click will now ignore the
PAGERenvironment variable if it is empty or contains only whitespace.The
click-contribGitHub organization was created.
Version 4.1¶
Released 2015-07-14
Fix a bug where error messages would include a trailing
Nonestring.Fix a bug where Click would crash on docstrings with trailing newlines.
Support streams with encoding set to
Noneon Python 3 by barfing with a better error.Handle ^C in less-pager properly.
Handle return value of
Nonefromsys.getfilesystemencodingFix crash when writing to unicode files with
click.echo.Fix type inference with multiple options.
Version 4.0¶
Released 2015-03-31, codename “zoom zoom”
Added
colorparameters to lots of interfaces that directly or indirectly call into echoing. This previously was always autodetection (with the exception of theecho_via_pagerfunction). Now you can forcefully enable or disable it, overriding the auto detection of Click.Added an
UNPROCESSEDtype which does not perform any type changes which simplifies text handling on 2.x / 3.x in some special advanced usecases.Added
NoSuchOptionandBadOptionUsageexceptions for more generic handling of errors.Added support for handling of unprocessed options which can be useful in situations where arguments are forwarded to underlying tools.
Added
max_content_widthparameter to the context which can be used to change the maximum width of help output. By default Click will not format content for more than 80 characters width.Added support for writing prompts to stderr.
Fix a bug when showing the default for multiple arguments.
Added support for custom subclasses to
optionandargument.Fix bug in
clear()on Windows when colorama is installed.Reject
nargs=-1for options properly. Options cannot be variadic.Fixed an issue with bash completion not working properly for commands with non ASCII characters or dashes.
Added a way to manually update the progressbar.
Changed the formatting of missing arguments. Previously the internal argument name was shown in error messages, now the metavar is shown if passed. In case an automated metavar is selected, it’s stripped of extra formatting first.
Version 3.3¶
Released 2014-09-08
Fixed an issue with error reporting on Python 3 for invalid forwarding of commands.
Version 3.2¶
Released 2014-08-22
Added missing
errparameter forwarding to thesechofunction.Fixed default parameters not being handled properly by the context invoke method. This is a backwards incompatible change if the function was used improperly.
Removed the
invoked_subcommandsattribute largely. It is not possible to provide it to work error free due to how the parsing works so this API has been deprecated.Restored the functionality of
invoked_subcommandwhich was broken as a regression in 3.1.
Version 3.1¶
Released 2014-08-13
Fixed a regression that caused contexts of subcommands to be created before the parent command was invoked which was a regression from earlier Click versions.
Version 3.0¶
Released 2014-08-12, codename “clonk clonk”
Formatter now no longer attempts to accommodate for terminals smaller than 50 characters. If that happens it just assumes a minimal width.
Added a way to not swallow exceptions in the test system.
Added better support for colors with pagers and ways to override the autodetection.
The CLI runner’s result object now has a traceback attached.
Improved automatic short help detection to work better with dots that do not terminate sentences.
When defining options without actual valid option strings now, Click will give an error message instead of silently passing. This should catch situations where users wanted to created arguments instead of options.
Restructured Click internally to support vendoring.
Added support for multi command chaining.
Added support for defaults on options with
multipleand options and arguments withnargs != 1.Label passed to
progressbaris no longer rendered with whitespace stripped.Added a way to disable the standalone mode of the
mainmethod on a Click command to be able to handle errors better.Added support for returning values from command callbacks.
Added simplifications for printing to stderr from
echo.Added result callbacks for groups.
Entering a context multiple times defers the cleanup until the last exit occurs.
Added
open_file.
Version 2.6¶
Released 2014-08-11
Fixed an issue where the wrapped streams on Python 3 would be reporting incorrect values for seekable.
Version 2.5¶
Released 2014-07-28
Fixed a bug with text wrapping on Python 3.
Version 2.4¶
Released 2014-07-04
Corrected a bug in the change of the help option in 2.3.
Version 2.3¶
Released 2014-07-03
Fixed an incorrectly formatted help record for count options.
Add support for ansi code stripping on Windows if colorama is not available.
Restored the Click 1.0 handling of the help parameter for certain edge cases.
Version 2.2¶
Released 2014-06-26
Fixed tty detection on PyPy.
Fixed an issue that progress bars were not rendered when the context manager was entered.
Version 2.1¶
Released 2014-06-14
Fixed the
launch()function on windows.Improved the colorama support on windows to try hard to not screw up the console if the application is interrupted.
Fixed windows terminals incorrectly being reported to be 80 characters wide instead of 79
Use colorama win32 bindings if available to get the correct dimensions of a windows terminal.
Fixed an issue with custom function types on Python 3.
Fixed an issue with unknown options being incorrectly reported in error messages.
Version 2.0¶
Released 2014-06-06, codename “tap tap tap”
Added support for opening stdin/stdout on Windows in binary mode correctly.
Added support for atomic writes to files by going through a temporary file.
Introduced
BadParameterwhich can be used to easily perform custom validation with the same error messages as in the type system.Added
progressbar(); a function to show progress bars.Added
get_app_dir(); a function to calculate the home folder for configs.Added transparent handling for ANSI codes into the
echo()function throughcolorama.Added
clear()function.Breaking change: parameter callbacks now get the parameter object passed as second argument. There is legacy support for old callbacks which will warn but still execute the script.
Added an
edit()function that invokes the default editor.Added an
launch()function that launches browsers and applications.Nargs of -1 for arguments can now be forced to be a single item through the required flag. It defaults to not required.
Setting a default for arguments now implicitly makes it non required.
Changed “yN” / “Yn” to “y/N” and “Y/n” in confirmation prompts.
Added basic support for bash completion.
Added
getchar()to fetch a single character from the terminal.Errors now go to stderr as intended.
Fixed various issues with more exotic parameter formats like DOS/Windows style arguments.
Added
pause()which works similar to the Windowspausecmd built-in but becomes an automatic noop if the application is not run through a terminal.Added a bit of extra information about missing choice parameters.
Changed how the help function is implemented to allow global overriding of the help option.
Added support for token normalization to implement case insensitive handling.
Added support for providing defaults for context settings.
Version 1.1¶
Released 2014-05-23
Fixed a bug that caused text files in Python 2 to not accept native strings.
Version 1.0¶
Released 2014-05-21
Initial release.