Decorators¶

click.command(name:Callable[[...],Any])→Command¶

click.command(name:str|None,cls:type[CmdType],**attrs:Any)→Callable[[Callable[[...],Any]],CmdType]

click.command(name:None=None,*,cls:type[CmdType],**attrs:Any)→Callable[[Callable[[...],Any]],CmdType]

click.command(name:str|None=None,cls:None=None,**attrs:Any)→Callable[[Callable[[...],Any]],Command]

Creates a newCommand and uses the decorated function ascallback. This will also automatically attach all decoratedoption()s andargument()s as parameters to the command.

The name of the command defaults to the name of the function, converted tolowercase, with underscores_ replaced by dashes-, and the suffixes_command,_cmd,_group, and_grp are removed. For example,init_data_command becomesinit-data.

All keyword arguments are forwarded to the underlying command class.For theparams argument, any decorated params are appended tothe end of the list.

Once decorated the function turns into aCommand instancethat can be invoked as a command line utility or be attached to acommandGroup.

Parameters:

• name – The name of the command. Defaults to modifying the function’sname as described above.

• cls – The command class to create. Defaults toCommand.

Changelog

Changed in version 8.2:The suffixes_command,_cmd,_group, and_grp areremoved when generating the name.

Changed in version 8.1:This decorator can be applied without parentheses.

Changed in version 8.1:Theparams argument can be used. Decorated params areappended to the end of the list.

click.group(name:Callable[[...],Any])→Group¶

click.group(name:str|None,cls:type[GrpType],**attrs:Any)→Callable[[Callable[[...],Any]],GrpType]

click.group(name:None=None,*,cls:type[GrpType],**attrs:Any)→Callable[[Callable[[...],Any]],GrpType]

click.group(name:str|None=None,cls:None=None,**attrs:Any)→Callable[[Callable[[...],Any]],Group]

Creates a newGroup with a function as callback. Thisworks otherwise the same ascommand() just that theclsparameter is set toGroup.

Changelog

Changed in version 8.1:This decorator can be applied without parentheses.

click.argument(*param_decls,cls=None,**attrs)¶

Attaches an argument to the command. All positional arguments arepassed as parameter declarations toArgument; all keywordarguments are forwarded unchanged (exceptcls).This is equivalent to creating anArgument instance manuallyand attaching it to theCommand.params list.

For the default argument class, refer toArgument andParameter for descriptions of parameters.

Parameters:

• cls (type[Argument]|None) – the argument class to instantiate. This defaults toArgument.

• param_decls (str) – Passed as positional arguments to the constructor ofcls.

• attrs (Any) – Passed as keyword arguments to the constructor ofcls.

Return type:

Callable[[FC],FC]

click.option(*param_decls,cls=None,**attrs)¶

Attaches an option to the command. All positional arguments arepassed as parameter declarations toOption; all keywordarguments are forwarded unchanged (exceptcls).This is equivalent to creating anOption instance manuallyand attaching it to theCommand.params list.

For the default option class, refer toOption andParameter for descriptions of parameters.

Parameters:

• cls (type[Option]|None) – the option class to instantiate. This defaults toOption.

• param_decls (str) – Passed as positional arguments to the constructor ofcls.

• attrs (Any) – Passed as keyword arguments to the constructor ofcls.

Return type:

Callable[[FC],FC]

click.password_option(*param_decls,**kwargs)¶

Add a--password option which prompts for a password, hidinginput and asking to enter the value again for confirmation.

Parameters:

• param_decls (str) – One or more option names. Defaults to the singlevalue"--password".

• kwargs (Any) – Extra arguments are passed tooption().

Return type:

Callable[[FC],FC]

click.confirmation_option(*param_decls,**kwargs)¶

Add a--yes option which shows a prompt before continuing ifnot passed. If the prompt is declined, the program will exit.

Parameters:

• param_decls (str) – One or more option names. Defaults to the singlevalue"--yes".

• kwargs (Any) – Extra arguments are passed tooption().

Return type:

Callable[[FC],FC]

click.version_option(version=None,*param_decls,package_name=None,prog_name=None,message=None,**kwargs)¶

Add a--version option which immediately prints the versionnumber and exits the program.

Ifversion is not provided, Click will try to detect it usingimportlib.metadata.version() to get the version for thepackage_name.

Ifpackage_name is not provided, Click will try to detect it byinspecting the stack frames. This will be used to detect theversion, so it must match the name of the installed package.

Parameters:

• version (str |None) – The version number to show. If not provided, Clickwill try to detect it.

• param_decls (str) – One or more option names. Defaults to the singlevalue"--version".

• package_name (str |None) – The package name to detect the version from. Ifnot provided, Click will try to detect it.

• prog_name (str |None) – The name of the CLI to show in the message. If notprovided, it will be detected from the command.

• message (str |None) – The message to show. The values%(prog)s,%(package)s, and%(version)s are available. Defaults to"%(prog)s,version%(version)s".

• kwargs (Any) – Extra arguments are passed tooption().

Raises:

RuntimeError –version could not be detected.

Return type:

Callable[[FC],FC]

Changelog

Changed in version 8.0:Add thepackage_name parameter, and the%(package)svalue for messages.

Changed in version 8.0:Useimportlib.metadata instead ofpkg_resources. Theversion is detected based on the package name, not the entrypoint name. The Python package name must match the installedpackage name, or be passed withpackage_name=.

click.help_option(*param_decls,**kwargs)¶

Pre-configured--help option which immediately prints the help pageand exits the program.

Parameters:

• param_decls (str) – One or more option names. Defaults to the singlevalue"--help".

• kwargs (Any) – Extra arguments are passed tooption().

Return type:

Callable[[FC],FC]

click.pass_context(f)¶

Marks a callback as wanting to receive the current contextobject as first argument.

Parameters:

f (t.Callable[te.Concatenate[Context,P],R])

Return type:

t.Callable[P, R]

click.pass_obj(f)¶

Similar topass_context(), but only pass the object on thecontext onwards (Context.obj). This is useful if that objectrepresents the state of a nested system.

Parameters:

f (t.Callable[te.Concatenate[T,P],R])

Return type:

t.Callable[P, R]

click.make_pass_decorator(object_type,ensure=False)¶

Given an object type this creates a decorator that will worksimilar topass_obj() but instead of passing the object of thecurrent context, it will find the innermost context of typeobject_type().

This generates a decorator that works roughly like this:

fromfunctoolsimportupdate_wrapperdefdecorator(f):@pass_contextdefnew_func(ctx,*args,**kwargs):obj=ctx.find_object(object_type)returnctx.invoke(f,obj,*args,**kwargs)returnupdate_wrapper(new_func,f)returndecorator

Parameters:

• object_type (type[T]) – the type of the object to pass.

• ensure (bool) – if set toTrue, a new object will be created andremembered on the context if it’s not there yet.

Return type:

t.Callable[[t.Callable[te.Concatenate[T, P], R]], t.Callable[P, R]]

click.decorators.pass_meta_key(key,*,doc_description=None)¶

Create a decorator that passes a key fromclick.Context.meta as the first argument to the decoratedfunction.

Parameters:

• key (str) – Key inContext.meta to pass.

• doc_description (str |None) – Description of the object being passed,inserted into the decorator’s docstring. Defaults to “the ‘key’key from Context.meta”.

Return type:

t.Callable[[t.Callable[te.Concatenate[T, P], R]], t.Callable[P, R]]

Changelog

Added in version 8.0.

Utilities¶

click.echo(message=None,file=None,nl=True,err=False,color=None)¶

Print a message and newline to stdout or a file. This should beused instead ofprint() because it provides better supportfor different data, files, and environments.

Compared toprint(), this does the following:

• Ensures that the output encoding is not misconfigured on Linux.

• Supports Unicode in the Windows console.

• Supports writing to binary outputs, and supports writing bytesto text outputs.

• Supports colors and styles on Windows.

• Removes ANSI color and style codes if the output does not looklike an interactive terminal.

• Always flushes the output.

Parameters:

• message (Any |None) – The string or bytes to output. Other objects areconverted to strings.

• file (IO[Any]|None) – The file to write to. Defaults tostdout.

• err (bool) – Write tostderr instead ofstdout.

• nl (bool) – Print a newline after the message. Enabled by default.

• color (bool |None) – Force showing or hiding colors and other styles. Bydefault Click will remove color if the output does not look likean interactive terminal.

Return type:

None

Changelog

Changed in version 6.0:Support Unicode output on the Windows console. Click does notmodifysys.stdout, sosys.stdout.write() andprint()will still not support Unicode.

Changed in version 4.0:Added thecolor parameter.

Added in version 3.0:Added theerr parameter.

Changed in version 2.0:Support colors on Windows if colorama is installed.

click.echo_via_pager(text_or_generator,color=None)¶

This function takes a text and shows it via an environment specificpager on stdout.

Changelog

Changed in version 3.0:Added thecolor flag.

Parameters:

• text_or_generator (Iterable[str]|Callable[[],Iterable[str]]|str) – the text to page, or alternatively, agenerator emitting the text to page.

• color (bool |None) – controls if the pager supports ANSI colors or not. Thedefault is autodetection.

Return type:

None

click.prompt(text,default=None,hide_input=False,confirmation_prompt=False,type=None,value_proc=None,prompt_suffix=':',show_default=True,err=False,show_choices=True)¶

Prompts a user for input. This is a convenience function that canbe used to prompt a user for input later.

If the user aborts the input by sending an interrupt signal, thisfunction will catch it and raise aAbort exception.

Parameters:

• text (str) – the text to show for the prompt.

• default (Any |None) – the default value to use if no input happens. If thisis not given it will prompt until it’s aborted.

• hide_input (bool) – if this is set to true then the input value willbe hidden.

• confirmation_prompt (bool |str) – Prompt a second time to confirm thevalue. Can be set to a string instead ofTrue to customizethe message.

• type (ParamType |Any |None) – the type to use to check the value against.

• value_proc (Callable[[str],Any]|None) – if this parameter is provided it’s a function thatis invoked instead of the type conversion toconvert a value.

• prompt_suffix (str) – a suffix that should be added to the prompt.

• show_default (bool) – shows or hides the default value in the prompt.

• err (bool) – if set to true the file defaults tostderr instead ofstdout, the same as with echo.

• show_choices (bool) – Show or hide choices if the passed type is a Choice.For example if type is a Choice of either day or week,show_choices is true and text is “Group by” then theprompt will be “Group by (day, week): “.

Return type:

Any

Changed in version 8.3.1:A space is no longer appended to the prompt.

Changelog

Added in version 8.0:confirmation_prompt can be a custom string.

Added in version 7.0:Added theshow_choices parameter.

Added in version 6.0:Added unicode support for cmd.exe on Windows.

Added in version 4.0:Added theerr parameter.

click.confirm(text,default=False,abort=False,prompt_suffix=':',show_default=True,err=False)¶

Prompts for confirmation (yes/no question).

If the user aborts the input by sending a interrupt signal thisfunction will catch it and raise aAbort exception.

Parameters:

• text (str) – the question to ask.

• default (bool |None) – The default value to use when no input is given. IfNone, repeat until input is given.

• abort (bool) – if this is set toTrue a negative answer aborts theexception by raisingAbort.

• prompt_suffix (str) – a suffix that should be added to the prompt.

• show_default (bool) – shows or hides the default value in the prompt.

• err (bool) – if set to true the file defaults tostderr instead ofstdout, the same as with echo.

Return type:

bool

Changed in version 8.3.1:A space is no longer appended to the prompt.

Changelog

Changed in version 8.0:Repeat until input is given ifdefault isNone.

Added in version 4.0:Added theerr parameter.

click.progressbar(*,length:int,label:str|None=None,hidden:bool=False,show_eta:bool=True,show_percent:bool|None=None,show_pos:bool=False,fill_char:str='#',empty_char:str='-',bar_template:str='%(label)s [%(bar)s] %(info)s',info_sep:str=' ',width:int=36,file:TextIO|None=None,color:bool|None=None,update_min_steps:int=1)→ProgressBar[int]¶

click.progressbar(iterable:Iterable[V]|None=None,length:int|None=None,label:str|None=None,hidden:bool=False,show_eta:bool=True,show_percent:bool|None=None,show_pos:bool=False,item_show_func:Callable[[V|None],str|None]|None=None,fill_char:str='#',empty_char:str='-',bar_template:str='%(label)s [%(bar)s] %(info)s',info_sep:str=' ',width:int=36,file:TextIO|None=None,color:bool|None=None,update_min_steps:int=1)→ProgressBar[V]

This function creates an iterable context manager that can be usedto iterate over something while showing a progress bar. It willeither iterate over theiterable orlength items (that are countedup). While iteration happens, this function will print a renderedprogress bar to the givenfile (defaults to stdout) and will attemptto calculate remaining time and more. By default, this progress barwill not be rendered if the file is not a terminal.

The context manager creates the progress bar. When the contextmanager is entered the progress bar is already created. With everyiteration over the progress bar, the iterable passed to the bar isadvanced and the bar is updated. When the context manager exits,a newline is printed and the progress bar is finalized on screen.

Note: The progress bar is currently designed for use cases where thetotal progress can be expected to take at least several seconds.Because of this, the ProgressBar class object won’t displayprogress that is considered too fast, and progress where the timebetween steps is less than a second.

No printing must happen or the progress bar will be unintentionallydestroyed.

Example usage:

withprogressbar(items)asbar:foriteminbar:do_something_with(item)

Alternatively, if no iterable is specified, one can manually update theprogress bar through theupdate() method instead of directlyiterating over the progress bar. The update method accepts the numberof steps to increment the bar with:

withprogressbar(length=chunks.total_bytes)asbar:forchunkinchunks:process_chunk(chunk)bar.update(chunks.bytes)

Theupdate() method also takes an optional value specifying thecurrent_item at the new position. This is useful when usedtogether withitem_show_func to customize the output for eachmanual step:

withclick.progressbar(length=total_size,label='Unzipping archive',item_show_func=lambdaa:a.filename)asbar:forarchiveinzip_file:archive.extract()bar.update(archive.size,archive)

Parameters:

• iterable – an iterable to iterate over. If not provided the lengthis required.

• length – the number of items to iterate over. By default theprogressbar will attempt to ask the iterator about itslength, which might or might not work. If an iterable isalso provided this parameter can be used to override thelength. If an iterable is not provided the progress barwill iterate over a range of that length.

• label – the label to show next to the progress bar.

• hidden – hide the progressbar. Defaults toFalse. When no tty isdetected, it will only print the progressbar label. Setting this toFalse also disables that.

• show_eta – enables or disables the estimated time display. This isautomatically disabled if the length cannot bedetermined.

• show_percent – enables or disables the percentage display. Thedefault isTrue if the iterable has a length orFalse if not.

• show_pos – enables or disables the absolute position display. Thedefault isFalse.

• item_show_func – A function called with the current item whichcan return a string to show next to the progress bar. If thefunction returnsNone nothing is shown. The current item canbeNone, such as when entering and exiting the bar.

• fill_char – the character to use to show the filled part of theprogress bar.

• empty_char – the character to use to show the non-filled part ofthe progress bar.

• bar_template – the format string to use as template for the bar.The parameters in it arelabel for the label,bar for the progress bar andinfo for theinfo section.

• info_sep – the separator between multiple info items (eta etc.)

• width – the width of the progress bar in characters, 0 means fullterminal width

• file – The file to write to. If this is not a terminal thenonly the label is printed.

• color – controls if the terminal supports ANSI colors or not. Thedefault is autodetection. This is only needed if ANSIcodes are included anywhere in the progress bar outputwhich is not the case by default.

• update_min_steps – Render only when this many updates havecompleted. This allows tuning for very fast iterators.

Changelog

Added in version 8.2:Thehidden argument.

Changed in version 8.0:Output is shown even if execution time is less than 0.5 seconds.

Changed in version 8.0:item_show_func shows the current item, not the previous one.

Changed in version 8.0:Labels are echoed if the output is not a TTY. Reverts a changein 7.0 that removed all output.

Added in version 8.0:Theupdate_min_steps parameter.

Added in version 4.0:Thecolor parameter andupdate method.

Added in version 2.0.

click.clear()¶

Clears the terminal screen. This will have the effect of clearingthe whole visible space of the terminal and moving the cursor to thetop left. This does not do anything if not connected to a terminal.

Changelog

Added in version 2.0.

Return type:

None

click.style(text,fg=None,bg=None,bold=None,dim=None,underline=None,overline=None,italic=None,blink=None,reverse=None,strikethrough=None,reset=True)¶

Styles a text with ANSI styles and returns the new string. Bydefault the styling is self contained which means that at the endof the string a reset code is issued. This can be prevented bypassingreset=False.

Examples:

click.echo(click.style('Hello World!',fg='green'))click.echo(click.style('ATTENTION!',blink=True))click.echo(click.style('Some things',reverse=True,fg='cyan'))click.echo(click.style('More colors',fg=(255,12,128),bg=117))

Supported color names:

• black (might be a gray)

• red

• green

• yellow (might be an orange)

• blue

• magenta

• cyan

• white (might be light gray)

• bright_black

• bright_red

• bright_green

• bright_yellow

• bright_blue

• bright_magenta

• bright_cyan

• bright_white

• reset (reset the color code only)

If the terminal supports it, color may also be specified as:

• An integer in the interval [0, 255]. The terminal must support8-bit/256-color mode.

• An RGB tuple of three integers in [0, 255]. The terminal mustsupport 24-bit/true-color mode.

Seehttps://en.wikipedia.org/wiki/ANSI_color andhttps://gist.github.com/XVilka/8346728 for more information.

Parameters:

• text (Any) – the string to style with ansi codes.

• fg (int |tuple[int,int,int]|str |None) – if provided this will become the foreground color.

• bg (int |tuple[int,int,int]|str |None) – if provided this will become the background color.

• bold (bool |None) – if provided this will enable or disable bold mode.

• dim (bool |None) – if provided this will enable or disable dim mode. This isbadly supported.

• underline (bool |None) – if provided this will enable or disable underline.

• overline (bool |None) – if provided this will enable or disable overline.

• italic (bool |None) – if provided this will enable or disable italic.

• blink (bool |None) – if provided this will enable or disable blinking.

• reverse (bool |None) – if provided this will enable or disable inverserendering (foreground becomes background and theother way round).

• strikethrough (bool |None) – if provided this will enable or disablestriking through text.

• reset (bool) – by default a reset-all code is added at the end of thestring which means that styles do not carry over. Thiscan be disabled to compose styles.

Return type:

str

Changelog

Changed in version 8.0:A non-stringmessage is converted to a string.

Changed in version 8.0:Added support for 256 and RGB color codes.

Changed in version 8.0:Added thestrikethrough,italic, andoverlineparameters.

Changed in version 7.0:Added support for bright colors.

Added in version 2.0.

click.unstyle(text)¶

Removes ANSI styling information from a string. Usually it’s notnecessary to use this function as Click’s echo function willautomatically remove styling if necessary.

Changelog

Added in version 2.0.

Parameters:

text (str) – the text to remove style information from.

Return type:

str

click.secho(message=None,file=None,nl=True,err=False,color=None,**styles)¶

This function combinesecho() andstyle() into onecall. As such the following two calls are the same:

click.secho('Hello World!',fg='green')click.echo(click.style('Hello World!',fg='green'))

All keyword arguments are forwarded to the underlying functionsdepending on which one they go with.

Non-string types will be converted tostr. However,bytes are passed directly toecho() without applyingstyle. If you want to style bytes that represent text, callbytes.decode() first.

Changelog

Changed in version 8.0:A non-stringmessage is converted to a string. Bytes arepassed through without style applied.

Added in version 2.0.

Parameters:

• message (Any |None)

• file (IO |None)

• nl (bool)

• err (bool)

• color (bool |None)

• styles (Any)

Return type:

None

click.edit(text:bytes|bytearray,editor:str|None=None,env:Mapping[str,str]|None=None,require_save:bool=False,extension:str='.txt')→bytes|None¶

click.edit(text:str,editor:str|None=None,env:Mapping[str,str]|None=None,require_save:bool=True,extension:str='.txt')→str|None

click.edit(text:None=None,editor:str|None=None,env:Mapping[str,str]|None=None,require_save:bool=True,extension:str='.txt',filename:str|Iterable[str]|None=None)→None

Edits the given text in the defined editor. If an editor is given(should be the full path to the executable but the regular operatingsystem search path is used for finding the executable) it overridesthe detected editor. Optionally, some environment variables can beused. If the editor is closed without changes,None is returned. Incase a file is edited directly the return value is alwaysNone andrequire_save andextension are ignored.

If the editor cannot be opened aUsageError is raised.

Note for Windows: to simplify cross-platform usage, the newlines areautomatically converted from POSIX to Windows and vice versa. As such,the message here will have\n as newline markers.

Parameters:

• text – the text to edit.

• editor – optionally the editor to use. Defaults to automaticdetection.

• env – environment variables to forward to the editor.

• require_save – if this is true, then not saving in the editorwill make the return value becomeNone.

• extension – the extension to tell the editor about. This defaultsto.txt but changing this might change syntaxhighlighting.

• filename – if provided it will edit this file instead of theprovided text contents. It will not use a temporaryfile as an indirection in that case. If the editor supportsediting multiple files at once, a sequence of files may bepassed as well. Invokeclick.file once per file insteadif multiple files cannot be managed at once or editing thefiles serially is desired.

Changelog

Changed in version 8.2.0:filename now accepts anyIterable[str] in addition to astrif theeditor supports editing multiple files at once.

click.launch(url,wait=False,locate=False)¶

This function launches the given URL (or filename) in the defaultviewer application for this file type. If this is an executable, itmight launch the executable in a new session. The return value isthe exit code of the launched application. Usually,0 indicatessuccess.

Examples:

click.launch('https://click.palletsprojects.com/')click.launch('/my/downloaded/file',locate=True)

Changelog

Added in version 2.0.

Parameters:

• url (str) – URL or filename of the thing to launch.

• wait (bool) – Wait for the program to exit before returning. Thisonly works if the launched program blocks. In particular,xdg-open on Linux does not block.

• locate (bool) – if this is set toTrue then instead of launching theapplication associated with the URL it will attempt tolaunch a file manager with the file located. Thismight have weird effects if the URL does not point tothe filesystem.

Return type:

int

click.getchar(echo=False)¶

Fetches a single character from the terminal and returns it. Thiswill always return a unicode character and under certain rarecircumstances this might return more than one character. Thesituations which more than one character is returned is when forwhatever reason multiple characters end up in the terminal buffer orstandard input was not actually a terminal.

Note that this will always read from the terminal, even if somethingis piped into the standard input.

Note for Windows: in rare cases when typing non-ASCII characters, thisfunction might wait for a second character and then return both at once.This is because certain Unicode characters look like special-key markers.

Changelog

Added in version 2.0.

Parameters:

echo (bool) – if set toTrue, the character read will also show up onthe terminal. The default is to not show it.

Return type:

str

click.pause(info=None,err=False)¶

This command stops execution and waits for the user to press anykey to continue. This is similar to the Windows batch “pause”command. If the program is not run through a terminal, this commandwill instead do nothing.

Changelog

Added in version 4.0:Added theerr parameter.

Added in version 2.0.

Parameters:

• info (str |None) – The message to print before pausing. Defaults to"Pressanykeytocontinue...".

• err (bool) – if set to message goes tostderr instead ofstdout, the same as with echo.

Return type:

None

click.get_binary_stream(name)¶

Returns a system stream for byte processing.

Parameters:

name (Literal['stdin','stdout','stderr']) – the name of the stream to open. Valid names are'stdin','stdout' and'stderr'

Return type:

BinaryIO

click.get_text_stream(name,encoding=None,errors='strict')¶

Returns a system stream for text processing. This usually returnsa wrapped stream around a binary stream returned fromget_binary_stream() but it also can take shortcuts for alreadycorrectly configured streams.

Parameters:

• name (Literal['stdin','stdout','stderr']) – the name of the stream to open. Valid names are'stdin','stdout' and'stderr'

• encoding (str |None) – overrides the detected default encoding.

• errors (str |None) – overrides the default error mode.

Return type:

TextIO

click.open_file(filename,mode='r',encoding=None,errors='strict',lazy=False,atomic=False)¶

Open a file, with extra behavior to handle'-' to indicatea standard stream, lazy open on write, and atomic write. Similar tothe behavior of theFile param type.

If'-' is given to openstdout orstdin, the stream iswrapped so that using it in a context manager will not close it.This makes it possible to use the function without accidentallyclosing a standard stream:

withopen_file(filename)asf:...

Parameters:

• filename (str |PathLike[str]) – The name or Path of the file to open, or'-' forstdin/stdout.

• mode (str) – The mode in which to open the file.

• encoding (str |None) – The encoding to decode or encode a file opened intext mode.

• errors (str |None) – The error handling mode.

• lazy (bool) – Wait to open the file until it is accessed. For readmode, the file is temporarily opened to raise access errorsearly, then closed until it is read again.

• atomic (bool) – Write to a temporary file and replace the given fileon close.

Return type:

IO[Any]

Changelog

Added in version 3.0.

click.get_app_dir(app_name,roaming=True,force_posix=False)¶

Returns the config folder for the application. The default behavioris to return whatever is most appropriate for the operating system.

To give you an idea, for an app called"FooBar", something likethe following folders could be returned:

Mac OS X:

~/Library/ApplicationSupport/FooBar

Mac OS X (POSIX):

~/.foo-bar

Unix:

~/.config/foo-bar

Unix (POSIX):

~/.foo-bar

Windows (roaming):

C:\Users\<user>\AppData\Roaming\FooBar

Windows (not roaming):

C:\Users\<user>\AppData\Local\FooBar

Changelog

Added in version 2.0.

Parameters:

• app_name (str) – the application name. This should be properly capitalizedand can contain whitespace.

• roaming (bool) – controls if the folder should be roaming or not on Windows.Has no effect otherwise.

• force_posix (bool) – if this is set toTrue then on any POSIX system thefolder will be stored in the home folder with a leadingdot instead of the XDG config home or darwin’sapplication support folder.

Return type:

str

click.format_filename(filename,shorten=False)¶

Format a filename as a string for display. Ensures the filename can bedisplayed by replacing any invalid bytes or surrogate escapes in the namewith the replacement character�.

Invalid bytes or surrogate escapes will raise an error when written to astream witherrors="strict". This will typically happen withstdoutwhen the locale is something likeen_GB.UTF-8.

Many scenariosare safe to write surrogates though, due to PEP 538 andPEP 540, including:

• Writing tostderr, which useserrors="backslashreplace".

• The system hasLANG=C.UTF-8,C, orPOSIX. Python opensstdout and stderr witherrors="surrogateescape".

• None ofLANG/LC_* are set. Python assumesLANG=C.UTF-8.

• Python is started in UTF-8 mode withPYTHONUTF8=1 or-Xutf8.Python opens stdout and stderr witherrors="surrogateescape".

Parameters:

• filename (str |bytes |PathLike[str]|PathLike[bytes]) – formats a filename for UI display. This will also convertthe filename into unicode without failing.

• shorten (bool) – this optionally shortens the filename to strip of thepath that leads up to it.

Return type:

str

Commands¶

click.BaseCommand¶

alias of_BaseCommand

classclick.Command(name,context_settings=None,callback=None,params=None,help=None,epilog=None,short_help=None,options_metavar='[OPTIONS]',add_help_option=True,no_args_is_help=False,hidden=False,deprecated=False)¶

Commands are the basic building block of command line interfaces inClick. A basic command handles command line parsing and might dispatchmore parsing to commands nested below it.

Parameters:

• name (str |None) – the name of the command to use unless a group overrides it.

• context_settings (cabc.MutableMapping[str,t.Any]|None) – an optional dictionary with defaults that arepassed to the context object.

• callback (t.Callable[...,t.Any]|None) – the callback to invoke. This is optional.

• params (list[Parameter]|None) – the parameters to register with this command. This canbe eitherOption orArgument objects.

• help (str |None) – the help string to use for this command.

• epilog (str |None) – like the help string but it’s printed at the end of thehelp page after everything else.

• short_help (str |None) – the short help to use for this command. This isshown on the command listing of the parent command.

• add_help_option (bool) – by default each command registers a--helpoption. This can be disabled by this parameter.

• no_args_is_help (bool) – this controls what happens if no arguments areprovided. This option is disabled by default.If enabled this will add--help as argumentif no arguments are passed

• hidden (bool) – hide this command from help outputs.

• deprecated (bool |str) – IfTrue or non-empty string, issues a messageindicating that the command is deprecated and highlightsits deprecation in –help. The message can be customizedby using a string as the value.

• options_metavar (str |None)

Changelog

Changed in version 8.2:This is the base class for all commands, notBaseCommand.deprecated can be set to a string as well to customize thedeprecation message.

Changed in version 8.1:help,epilog, andshort_help are stored unprocessed,all formatting is done when outputting help text, not at init,and is done even if not using the@command decorator.

Changed in version 8.0:Added arepr showing the command name.

Changed in version 7.1:Added theno_args_is_help parameter.

Changed in version 2.0:Added thecontext_settings parameter.

context_class¶

alias ofContext

allow_extra_args=False¶

the default for theContext.allow_extra_args flag.

allow_interspersed_args=True¶

the default for theContext.allow_interspersed_args flag.

ignore_unknown_options=False¶

the default for theContext.ignore_unknown_options flag.

name¶

the name the command thinks it has. Upon registering a commandon aGroup the group will default the command namewith this information. You should instead use theContext'sinfo_name attribute.

context_settings:MutableMapping[str,Any]¶

an optional dictionary with defaults passed to the context.

callback¶

the callback to execute when the command fires. This might beNone in which case nothing happens.

params:list[Parameter]¶

the list of parameters for this command in the order theyshould show up in the help page and execute. Eager parameterswill automatically be handled before non eager ones.

get_usage(ctx)¶

Formats the usage line into a string and returns it.

Callsformat_usage() internally.

Parameters:

ctx (Context)

Return type:

str

format_usage(ctx,formatter)¶

Writes the usage line into the formatter.

This is a low-level method called byget_usage().

Parameters:

• ctx (Context)

• formatter (HelpFormatter)

Return type:

None

collect_usage_pieces(ctx)¶

Returns all the pieces that go into the usage line and returnsit as a list of strings.

Parameters:

ctx (Context)

Return type:

list[str]

get_help_option_names(ctx)¶

Returns the names for the help option.

Parameters:

ctx (Context)

Return type:

list[str]

get_help_option(ctx)¶

Returns the help option object.

Skipped ifadd_help_option isFalse.

Changelog

Changed in version 8.1.8:The help option is now cached to avoid creating it multiple times.

Parameters:

ctx (Context)

Return type:

Option | None

make_parser(ctx)¶

Creates the underlying option parser for this command.

Parameters:

ctx (Context)

Return type:

_OptionParser

get_help(ctx)¶

Formats the help into a string and returns it.

Callsformat_help() internally.

Parameters:

ctx (Context)

Return type:

str

get_short_help_str(limit=45)¶

Gets short help for the command or makes it by shortening thelong help string.

Parameters:

limit (int)

Return type:

str

format_help(ctx,formatter)¶

Writes the help into the formatter if it exists.

This is a low-level method called byget_help().

This calls the following methods:

• format_usage()

• format_help_text()

• format_options()

• format_epilog()

Parameters:

• ctx (Context)

• formatter (HelpFormatter)

Return type:

None

format_help_text(ctx,formatter)¶

Writes the help text to the formatter if it exists.

Parameters:

• ctx (Context)

• formatter (HelpFormatter)

Return type:

None

format_options(ctx,formatter)¶

Writes all the options into the formatter if they exist.

Parameters:

• ctx (Context)

• formatter (HelpFormatter)

Return type:

None

format_epilog(ctx,formatter)¶

Writes the epilog into the formatter if it exists.

Parameters:

• ctx (Context)

• formatter (HelpFormatter)

Return type:

None

make_context(info_name,args,parent=None,**extra)¶

This function when given an info name and arguments will kickoff the parsing and create a newContext. It does notinvoke the actual command callback though.

To quickly customize the context class used without overridingthis method, set thecontext_class attribute.

Parameters:

• info_name (str |None) – the info name for this invocation. Generally thisis the most descriptive name for the script orcommand. For the toplevel script it’s usuallythe name of the script, for commands below it’sthe name of the command.

• args (list[str]) – the arguments to parse as list of strings.

• parent (Context |None) – the parent context if available.

• extra (Any) – extra keyword arguments forwarded to the contextconstructor.

Return type:

Context

Changelog

Changed in version 8.0:Added thecontext_class attribute.

invoke(ctx)¶

Given a context, this invokes the attached callback (if it exists)in the right way.

Parameters:

ctx (Context)

Return type:

Any

shell_complete(ctx,incomplete)¶

Return a list of completions for the incomplete value. Looksat the names of options and chained multi-commands.

Any command could be part of a chained multi-command, so siblingcommands are valid at any point during command completion.

Parameters:

• ctx (Context) – Invocation context for this command.

• incomplete (str) – Value being completed. May be empty.

Return type:

list[CompletionItem]

Changelog

Added in version 8.0.

main(args:Sequence[str]|None=None,prog_name:str|None=None,complete_var:str|None=None,standalone_mode:Literal[True]=True,**extra:Any)→NoReturn¶

main(args:Sequence[str]|None=None,prog_name:str|None=None,complete_var:str|None=None,standalone_mode:bool=True,**extra:Any)→Any

This is the way to invoke a script with all the bells andwhistles as a command line application. This will always terminatethe application after a call. If this is not wanted,SystemExitneeds to be caught.

This method is also available by directly calling the instance ofaCommand.

Parameters:

• args – the arguments that should be used for parsing. If notprovided,sys.argv[1:] is used.

• prog_name – the program name that should be used. By defaultthe program name is constructed by taking the filename fromsys.argv[0].

• complete_var – the environment variable that controls thebash completion support. The default is"_<prog_name>_COMPLETE" with prog_name inuppercase.

• standalone_mode – the default behavior is to invoke the scriptin standalone mode. Click will thenhandle exceptions and convert them intoerror messages and the function will neverreturn but shut down the interpreter. Ifthis is set toFalse they will bepropagated to the caller and the returnvalue of this function is the return valueofinvoke().

• windows_expand_args – Expand glob patterns, user dir, andenv vars in command line args on Windows.

• extra – extra keyword arguments are forwarded to the contextconstructor. SeeContext for more information.

Changelog

Changed in version 8.0.1:Added thewindows_expand_args parameter to allowdisabling command line arg expansion on Windows.

Changed in version 8.0:When taking arguments fromsys.argv on Windows, globpatterns, user dir, and env vars are expanded.

Changed in version 3.0:Added thestandalone_mode parameter.

click.MultiCommand¶

alias of_MultiCommand

classclick.Group(name=None,commands=None,invoke_without_command=False,no_args_is_help=None,subcommand_metavar=None,chain=False,result_callback=None,**kwargs)¶

A group is a command that nests other commands (or more groups).

Parameters:

• name (str |None) – The name of the group command.

• commands (cabc.MutableMapping[str,Command]|cabc.Sequence[Command]|None) – Map names toCommand objects. Can be a list, whichwill useCommand.name as the keys.

• invoke_without_command (bool) – Invoke the group’s callback even if asubcommand is not given.

• no_args_is_help (bool |None) – If no arguments are given, show the group’s help andexit. Defaults to the opposite ofinvoke_without_command.

• subcommand_metavar (str |None) – How to represent the subcommand argument in help.The default will represent whetherchain is set or not.

• chain (bool) – Allow passing more than one subcommand argument. After parsinga command’s arguments, if any arguments remain another command will bematched, and so on.

• result_callback (t.Callable[...,t.Any]|None) – A function to call after the group’s andsubcommand’s callbacks. The value returned by the subcommand is passed.Ifchain is enabled, the value will be a list of values returned byall the commands. Ifinvoke_without_command is enabled, the valuewill be the value returned by the group’s callback, or an empty list ifchain is enabled.

• kwargs (t.Any) – Other arguments passed toCommand.

Changelog

Changed in version 8.2:Merged with and replaces theMultiCommand base class.

Changed in version 8.0:Thecommands argument can be a list of command objects.

allow_extra_args=True¶

the default for theContext.allow_extra_args flag.

allow_interspersed_args=False¶

the default for theContext.allow_interspersed_args flag.

command_class:type[Command]|None=None¶

If set, this is used by the group’scommand() decoratoras the defaultCommand class. This is useful to make allsubcommands use a custom command class.

Changelog

Added in version 8.0.

group_class:type[Group]|type[type]|None=None¶

If set, this is used by the group’sgroup() decoratoras the defaultGroup class. This is useful to make allsubgroups use a custom group class.

If set to the special valuetype (literallygroup_class=type), this group’s class will be used as thedefault class. This makes a custom group class continue to makecustom groups.

Changelog

Added in version 8.0.

commands:MutableMapping[str,Command]¶

The registered subcommands by their exported names.

add_command(cmd,name=None)¶

Registers anotherCommand with this group. If the nameis not provided, the name of the command is used.

Parameters:

• cmd (Command)

• name (str |None)

Return type:

None

command(__func:Callable[[...],Any])→Command¶

command(*args:Any,**kwargs:Any)→Callable[[Callable[[...],Any]],Command]

A shortcut decorator for declaring and attaching a command tothe group. This takes the same arguments ascommand() andimmediately registers the created command with this group bycallingadd_command().

To customize the command class used, set thecommand_class attribute.

Changelog

Changed in version 8.1:This decorator can be applied without parentheses.

Changed in version 8.0:Added thecommand_class attribute.

group(__func:Callable[[...],Any])→Group¶

group(*args:Any,**kwargs:Any)→Callable[[Callable[[...],Any]],Group]

A shortcut decorator for declaring and attaching a group tothe group. This takes the same arguments asgroup() andimmediately registers the created group with this group bycallingadd_command().

To customize the group class used, set thegroup_classattribute.

Changelog

Changed in version 8.1:This decorator can be applied without parentheses.

Changed in version 8.0:Added thegroup_class attribute.

result_callback(replace=False)¶

Adds a result callback to the command. By default if aresult callback is already registered this will chain them butthis can be disabled with thereplace parameter. The resultcallback is invoked with the return value of the subcommand(or the list of return values from all subcommands if chainingis enabled) as well as the parameters as they would be passedto the main callback.

Example:

@click.group()@click.option('-i','--input',default=23)defcli(input):return42@cli.result_callback()defprocess_result(result,input):returnresult+input

Parameters:

replace (bool) – if set toTrue an already existing resultcallback will be removed.

Return type:

Callable[[F],F]

Changelog

Changed in version 8.0:Renamed fromresultcallback.

Added in version 3.0.

get_command(ctx,cmd_name)¶

Given a context and a command name, this returns aCommandobject if it exists or returnsNone.

Parameters:

• ctx (Context)

• cmd_name (str)

Return type:

Command | None

list_commands(ctx)¶

Returns a list of subcommand names in the order they should appear.

Parameters:

ctx (Context)

Return type:

list[str]

collect_usage_pieces(ctx)¶

Returns all the pieces that go into the usage line and returnsit as a list of strings.

Parameters:

ctx (Context)

Return type:

list[str]

format_options(ctx,formatter)¶

Writes all the options into the formatter if they exist.

Parameters:

• ctx (Context)

• formatter (HelpFormatter)

Return type:

None

format_commands(ctx,formatter)¶

Extra format methods for multi methods that adds all the commandsafter the options.

Parameters:

• ctx (Context)

• formatter (HelpFormatter)

Return type:

None

invoke(ctx)¶

Given a context, this invokes the attached callback (if it exists)in the right way.

Parameters:

ctx (Context)

Return type:

Any

shell_complete(ctx,incomplete)¶

Return a list of completions for the incomplete value. Looksat the names of options, subcommands, and chainedmulti-commands.

Parameters:

• ctx (Context) – Invocation context for this command.

• incomplete (str) – Value being completed. May be empty.

Return type:

list[CompletionItem]

Changelog

Added in version 8.0.

classclick.CommandCollection(name=None,sources=None,**kwargs)¶

AGroup that looks up subcommands on other groups. If a commandis not found on this group, each registered source is checked in order.Parameters on a source are not added to this group, and a source’s callbackis not invoked when invoking its commands. In other words, this “flattens”commands in many groups into this one group.

Parameters:

• name (str |None) – The name of the group command.

• sources (list[Group]|None) – A list ofGroup objects to look up commands from.

• kwargs (t.Any) – Other arguments passed toGroup.

Changelog

Changed in version 8.2:This is a subclass ofGroup. Commands are looked up first on thisgroup, then each of its sources.

sources:list[Group]¶

The list of registered groups.

add_source(group)¶

Add a group as a source of commands.

Parameters:

group (Group)

Return type:

None

get_command(ctx,cmd_name)¶

Given a context and a command name, this returns aCommandobject if it exists or returnsNone.

Parameters:

• ctx (Context)

• cmd_name (str)

Return type:

Command | None

list_commands(ctx)¶

Returns a list of subcommand names in the order they should appear.

Parameters:

ctx (Context)

Return type:

list[str]

Parameters¶

classclick.Parameter(param_decls=None,type=None,required=False,default=UNSET,callback=None,nargs=None,multiple=False,metavar=None,expose_value=True,is_eager=False,envvar=None,shell_complete=None,deprecated=False)¶

A parameter to a command comes in two versions: they are eitherOptions orArguments. Other subclasses are currentlynot supported by design as some of the internals for parsing areintentionally not finalized.

Some settings are supported by both options and arguments.

Parameters:

• param_decls (cabc.Sequence[str]|None) – the parameter declarations for this option orargument. This is a list of flags or argumentnames.

• type (types.ParamType |t.Any |None) – the type that should be used. Either aParamTypeor a Python type. The latter is converted into the formerautomatically if supported.

• required (bool) – controls if this is optional or not.

• default (t.Any |t.Callable[[],t.Any]|None) – the default value if omitted. This can also be a callable,in which case it’s invoked when the default is neededwithout any arguments.

• callback (t.Callable[[Context,Parameter,t.Any],t.Any]|None) – A function to further process or validate the valueafter type conversion. It is called asf(ctx,param,value)and must return the value. It is called for all sources,including prompts.

• nargs (int |None) – the number of arguments to match. If not1 the returnvalue is a tuple instead of single value. The default fornargs is1 (except if the type is a tuple, then it’sthe arity of the tuple). Ifnargs=-1, all remainingparameters are collected.

• metavar (str |None) – how the value is represented in the help page.

• expose_value (bool) – if this isTrue then the value is passed onwardsto the command callback and stored on the context,otherwise it’s skipped.

• is_eager (bool) – eager values are processed before non eager ones. Thisshould not be set for arguments or it will inverse theorder of processing.

• envvar (str |cabc.Sequence[str]|None) – environment variable(s) that are used to provide a default value forthis parameter. This can be a string or a sequence of strings. If a sequence isgiven, only the first non-empty environment variable is used for the parameter.

• shell_complete (t.Callable[[Context,Parameter,str],list[CompletionItem]|list[str]]|None) – A function that returns custom shellcompletions. Used instead of the param’s type completion ifgiven. Takesctx,param,incomplete and must return a listofCompletionItem or a list ofstrings.

• deprecated (bool |str) – IfTrue or non-empty string, issues a messageindicating that the argument is deprecated and highlightsits deprecation in –help. The message can be customizedby using a string as the value. A deprecated parametercannot be required, a ValueError will be raised otherwise.

• multiple (bool)

Changelog

Changed in version 8.2.0:Introduction ofdeprecated.

Changed in version 8.2:Adding duplicate parameter names to aCommand willresult in aUserWarning being shown.

Changed in version 8.2:Adding duplicate parameter names to aCommand willresult in aUserWarning being shown.

Changed in version 8.0:process_value validates required parameters and boundednargs, and invokes the parameter callback before returningthe value. This allows the callback to validate prompts.full_process_value is removed.

Changed in version 8.0:autocompletion is renamed toshell_complete and has newsemantics described above. The old name is deprecated and willbe removed in 8.1, until then it will be wrapped to match thenew requirements.

Changed in version 8.0:Formultiple=True,nargs>1, the default must be a list oftuples.

Changed in version 8.0:Setting a default is no longer required fornargs>1, it willdefault toNone.multiple=True ornargs=-1 willdefault to().

Changed in version 7.1:Empty environment variables are ignored rather than taking theempty string value. This makes it possible for scripts to clearvariables if they can’t unset them.

Changed in version 2.0:Changed signature for parameter callback to also be passed theparameter. The old callback format will still work, but it willraise a warning to give you a chance to migrate the code easier.

to_info_dict()¶

Gather information that could be useful for a tool generatinguser-facing documentation.

Useclick.Context.to_info_dict() to traverse the entireCLI structure.

Changed in version 8.3.0:ReturnsNone for thedefault if it was not set.

Changelog

Added in version 8.0.

Return type:

dict[str,Any]

propertyhuman_readable_name:str¶

Returns the human readable name of this parameter. This is thesame as the name for options, but the metavar for arguments.

get_default(ctx:Context,call:Literal[True]=True)→Any|None¶

get_default(ctx:Context,call:bool=True)→Any|Callable[[],Any]|None

Get the default for the parameter. TriesContext.lookup_default() first, then the local default.

Parameters:

• ctx – Current context.

• call – If the default is a callable, call it. Disable toreturn the callable instead.

Changelog

Changed in version 8.0.2:Type casting is no longer performed when getting a default.

Changed in version 8.0.1:Type casting can fail in resilient parsing mode. Invaliddefaults will not prevent showing help text.

Changed in version 8.0:Looks atctx.default_map first.

Changed in version 8.0:Added thecall parameter.

type_cast_value(ctx,value)¶

Convert and validate a value against the parameter’stype,multiple, andnargs.

Parameters:

• ctx (Context)

• value (Any)

Return type:

Any

get_error_hint(ctx)¶

Get a stringified version of the param for use in error messages toindicate which param caused the error.

Parameters:

ctx (Context)

Return type:

str

shell_complete(ctx,incomplete)¶

Return a list of completions for the incomplete value. If ashell_complete function was given during init, it is used.Otherwise, thetypeshell_complete() function is used.

Parameters:

• ctx (Context) – Invocation context for this command.

• incomplete (str) – Value being completed. May be empty.

Return type:

list[CompletionItem]

Changelog

Added in version 8.0.

classclick.Option(param_decls=None,show_default=None,prompt=False,confirmation_prompt=False,prompt_required=True,hide_input=False,is_flag=None,flag_value=UNSET,multiple=False,count=False,allow_from_autoenv=True,type=None,help=None,hidden=False,show_choices=True,show_envvar=False,deprecated=False,**attrs)¶

Options are usually optional values on the command line andhave some extra features that arguments don’t have.

All other parameters are passed onwards to the parameter constructor.

Parameters:

• show_default (bool |str |None) – Show the default value for this option in itshelp text. Values are not shown by default, unlessContext.show_default isTrue. If this value is astring, it shows that string in parentheses instead of theactual value. This is particularly useful for dynamic options.For single option boolean flags, the default remains hidden ifits value isFalse.

• show_envvar (bool) – Controls if an environment variable should beshown on the help page and error messages.Normally, environment variables are not shown.

• prompt (bool |str) – If set toTrue or a non empty string then theuser will be prompted for input. If set toTrue the promptwill be the option name capitalized. A deprecated option cannot beprompted.

• confirmation_prompt (bool |str) – Prompt a second time to confirm thevalue if it was prompted for. Can be set to a string instead ofTrue to customize the message.

• prompt_required (bool) – If set toFalse, the user will beprompted for input only when the option was specified as a flagwithout a value.

• hide_input (bool) – If this isTrue then the input on the promptwill be hidden from the user. This is useful for password input.

• is_flag (bool |None) – forces this option to act as a flag. The default isauto detection.

• flag_value (t.Any) – which value should be used for this flag if it’senabled. This is set to a boolean automatically ifthe option string contains a slash to mark two options.

• multiple (bool) – if this is set toTrue then the argument is acceptedmultiple times and recorded. This is similar tonargsin how it works but supports arbitrary number ofarguments.

• count (bool) – this flag makes an option increment an integer.

• allow_from_autoenv (bool) – if this is enabled then the value of thisparameter will be pulled from an environmentvariable in case a prefix is defined on thecontext.

• help (str |None) – the help string.

• hidden (bool) – hide this option from help outputs.

• attrs (t.Any) – Other command arguments described inParameter.

• param_decls (cabc.Sequence[str]|None)

• type (types.ParamType |t.Any |None)

• show_choices (bool)

• deprecated (bool |str)

Changelog

Changed in version 8.2:envvar used withflag_value will always use theflag_value,previously it would use the value of the environment variable.

Changed in version 8.1:Help text indentation is cleaned here instead of only in the@option decorator.

Changed in version 8.1:Theshow_default parameter overridesContext.show_default.

Changed in version 8.1:The default of a single option boolean flag is not shown if thedefault value isFalse.

Changed in version 8.0.1:type is detected fromflag_value if given.

classclick.Argument(param_decls,required=None,**attrs)¶

Arguments are positional parameters to a command. They generallyprovide fewer features than options but can have infinitenargsand are required by default.

All parameters are passed onwards to the constructor ofParameter.

Parameters:

• param_decls (cabc.Sequence[str])

• required (bool |None)

• attrs (t.Any)

Context¶

classclick.Context(command,parent=None,info_name=None,obj=None,auto_envvar_prefix=None,default_map=None,terminal_width=None,max_content_width=None,resilient_parsing=False,allow_extra_args=None,allow_interspersed_args=None,ignore_unknown_options=None,help_option_names=None,token_normalize_func=None,color=None,show_default=None)¶

The context is a special internal object that holds state relevantfor the script execution at every single level. It’s normally invisibleto commands unless they opt-in to getting access to it.

The context is useful as it can pass internal objects around and cancontrol special execution features such as reading data fromenvironment variables.

A context can be used as context manager in which case it will callclose() on teardown.

Parameters:

• command (Command) – the command class for this context.

• parent (Context |None) – the parent context.

• info_name (str |None) – the info name for this invocation. Generally thisis the most descriptive name for the script orcommand. For the toplevel script it is usuallythe name of the script, for commands below it it’sthe name of the script.

• obj (t.Any |None) – an arbitrary object of user data.

• auto_envvar_prefix (str |None) – the prefix to use for automatic environmentvariables. If this isNone then readingfrom environment variables is disabled. Thisdoes not affect manually set environmentvariables which are always read.

• default_map (cabc.MutableMapping[str,t.Any]|None) – a dictionary (like object) with default valuesfor parameters.

• terminal_width (int |None) – the width of the terminal. The default isinherit from parent context. If no contextdefines the terminal width then autodetection will be applied.

• max_content_width (int |None) – the maximum width for content rendered byClick (this currently only affects helppages). This defaults to 80 characters ifnot overridden. In other words: even if theterminal is larger than that, Click will notformat things wider than 80 characters bydefault. In addition to that, formatters mightadd some safety mapping on the right.

• resilient_parsing (bool) – if this flag is enabled then Click willparse without any interactivity or callbackinvocation. Default values will also beignored. This is useful for implementingthings such as completion support.

• allow_extra_args (bool |None) – if this is set toTrue then extra argumentsat the end will not raise an error and will bekept on the context. The default is to inheritfrom the command.

• allow_interspersed_args (bool |None) – if this is set toFalse then optionsand arguments cannot be mixed. Thedefault is to inherit from the command.

• ignore_unknown_options (bool |None) – instructs click to ignore options it doesnot know and keeps them for laterprocessing.

• help_option_names (list[str]|None) – optionally a list of strings that define howthe default help parameter is named. Thedefault is['--help'].

• token_normalize_func (t.Callable[[str],str]|None) – an optional function that is used tonormalize tokens (options, choices,etc.). This for instance can be used toimplement case insensitive behavior.

• color (bool |None) – controls if the terminal supports ANSI colors or not. Thedefault is autodetection. This is only needed if ANSIcodes are used in texts that Click prints which is bydefault not the case. This for instance would affecthelp output.

• show_default (bool |None) – Show the default value for commands. If thisvalue is not set, it defaults to the value from the parentcontext.Command.show_default overrides this default for thespecific command.

Changelog

Changed in version 8.2:Theprotected_args attribute is deprecated and will be removed inClick 9.0.args will contain remaining unparsed tokens.

Changed in version 8.1:Theshow_default parameter is overridden byCommand.show_default, instead of the other way around.

Changed in version 8.0:Theshow_default parameter defaults to the value from theparent context.

Changed in version 7.1:Added theshow_default parameter.

Changed in version 4.0:Added thecolor,ignore_unknown_options, andmax_content_width parameters.

Changed in version 3.0:Added theallow_extra_args andallow_interspersed_argsparameters.

Changed in version 2.0:Added theresilient_parsing,help_option_names, andtoken_normalize_func parameters.

formatter_class¶

alias ofHelpFormatter

parent¶

the parent context orNone if none exists.

command¶

theCommand for this context.

info_name¶

the descriptive information name

params:dict[str,Any]¶

Map of parameter names to their parsed values. Parameterswithexpose_value=False are not stored.

args:list[str]¶

the leftover arguments.

obj:Any¶

the user object stored.

invoked_subcommand:str|None¶

This flag indicates if a subcommand is going to be executed. Agroup callback can use this information to figure out if it’sbeing executed directly or because the execution flow passesonwards to a subcommand. By default it’s None, but it can bethe name of the subcommand to execute.

If chaining is enabled this will be set to'*' in caseany commands are executed. It is however not possible tofigure out which ones. If you require this knowledge youshould use aresult_callback().

terminal_width:int|None¶

The width of the terminal (None is autodetection).

max_content_width:int|None¶

The maximum width of formatted content (None implies a sensibledefault which is 80 for most things).

allow_extra_args¶

Indicates if the context allows extra args or if it shouldfail on parsing.

Changelog

Added in version 3.0.

allow_interspersed_args:bool¶

Indicates if the context allows mixing of arguments andoptions or not.

Changelog

Added in version 3.0.

ignore_unknown_options:bool¶

Instructs click to ignore options that a command does notunderstand and will store it on the context for laterprocessing. This is primarily useful for situations where youwant to call into external programs. Generally this pattern isstrongly discouraged because it’s not possibly to losslesslyforward all arguments.

Changelog

Added in version 4.0.

help_option_names:list[str]¶

The names for the help options.

token_normalize_func:Callable[[str],str]|None¶

An optional normalization function for tokens. This isoptions, choices, commands etc.

resilient_parsing:bool¶

Indicates if resilient parsing is enabled. In that case Clickwill do its best to not cause any failures and default valueswill be ignored. Useful for completion.

color:bool|None¶

Controls if styling output is wanted or not.

show_default:bool|None¶

Show option default values when formatting help text.

to_info_dict()¶

Gather information that could be useful for a tool generatinguser-facing documentation. This traverses the entire CLIstructure.

withContext(cli)asctx:info=ctx.to_info_dict()

Changelog

Added in version 8.0.

Return type:

dict[str,Any]

scope(cleanup=True)¶

This helper method can be used with the context object to promoteit to the current thread local (seeget_current_context()).The default behavior of this is to invoke the cleanup functions whichcan be disabled by settingcleanup toFalse. The cleanupfunctions are typically used for things such as closing file handles.

If the cleanup is intended the context object can also be directlyused as a context manager.

Example usage:

withctx.scope():assertget_current_context()isctx

This is equivalent:

withctx:assertget_current_context()isctx

Changelog

Added in version 5.0.

Parameters:

cleanup (bool) – controls if the cleanup functions should be run ornot. The default is to run these functions. Insome situations the context only wants to betemporarily pushed in which case this can be disabled.Nested pushes automatically defer the cleanup.

Return type:

Iterator[Context]

propertymeta:dict[str,Any]¶

This is a dictionary which is shared with all the contextsthat are nested. It exists so that click utilities can store somestate here if they need to. It is however the responsibility ofthat code to manage this dictionary well.

The keys are supposed to be unique dotted strings. For instancemodule paths are a good choice for it. What is stored in there isirrelevant for the operation of click. However what is important isthat code that places data here adheres to the general semantics ofthe system.

Example usage:

LANG_KEY=f'{__name__}.lang'defset_language(value):ctx=get_current_context()ctx.meta[LANG_KEY]=valuedefget_language():returnget_current_context().meta.get(LANG_KEY,'en_US')

Changelog

Added in version 5.0.

make_formatter()¶

Creates theHelpFormatter for the help andusage output.

To quickly customize the formatter class used without overridingthis method, set theformatter_class attribute.

Changelog

Changed in version 8.0:Added theformatter_class attribute.

Return type:

HelpFormatter

with_resource(context_manager)¶

Register a resource as if it were used in awithstatement. The resource will be cleaned up when the context ispopped.

Usescontextlib.ExitStack.enter_context(). It calls theresource’s__enter__() method and returns the result. Whenthe context is popped, it closes the stack, which calls theresource’s__exit__() method.

To register a cleanup function for something that isn’t acontext manager, usecall_on_close(). Or use somethingfromcontextlib to turn it into a context manager first.

@click.group()@click.option("--name")@click.pass_contextdefcli(ctx):ctx.obj=ctx.with_resource(connect_db(name))

Parameters:

context_manager (AbstractContextManager[V]) – The context manager to enter.

Returns:

Whatevercontext_manager.__enter__() returns.

Return type:

V

Changelog

Added in version 8.0.

call_on_close(f)¶

Register a function to be called when the context tears down.

This can be used to close resources opened during the scriptexecution. Resources that support Python’s context managerprotocol which would be used in awith statement should beregistered withwith_resource() instead.

Parameters:

f (Callable[[...],Any]) – The function to execute on teardown.

Return type:

Callable[[…],Any]

close()¶

Invoke all close callbacks registered withcall_on_close(), and exit all context managers enteredwithwith_resource().

Return type:

None

propertycommand_path:str¶

The computed command path. This is used for theusageinformation on the help page. It’s automatically created bycombining the info names of the chain of contexts to the root.

find_root()¶

Finds the outermost context.

Return type:

Context

find_object(object_type)¶

Finds the closest object of a given type.

Parameters:

object_type (type[V])

Return type:

V | None

ensure_object(object_type)¶

Likefind_object() but sets the innermost object to anew instance ofobject_type if it does not exist.

Parameters:

object_type (type[V])

Return type:

V

lookup_default(name:str,call:Literal[True]=True)→Any|None¶

lookup_default(name:str,call:Literal[False]=True)→Any|Callable[[],Any]|None

Get the default for a parameter fromdefault_map.

Parameters:

• name – Name of the parameter.

• call – If the default is a callable, call it. Disable toreturn the callable instead.

Changelog

Changed in version 8.0:Added thecall parameter.

fail(message)¶

Aborts the execution of the program with a specific errormessage.

Parameters:

message (str) – the error message to fail with.

Return type:

NoReturn

abort()¶

Aborts the script.

Return type:

NoReturn

exit(code=0)¶

Exits the application with a given exit code.

Changelog

Changed in version 8.2:Callbacks and context managers registered withcall_on_close()andwith_resource() are closed before exiting.

Parameters:

code (int)

Return type:

NoReturn

get_usage()¶

Helper method to get formatted usage string for the currentcontext and command.

Return type:

str

get_help()¶

Helper method to get formatted help page for the currentcontext and command.

Return type:

str

invoke(callback:Callable[[...],V],/,*args:Any,**kwargs:Any)→V¶

invoke(callback:Command,/,*args:Any,**kwargs:Any)→Any

Invokes a command callback in exactly the way it expects. Thereare two ways to invoke this method:

1. the first argument can be a callback and all other arguments andkeyword arguments are forwarded directly to the function.

2. the first argument is a click command object. In that case allarguments are forwarded as well but proper click parameters(options and click arguments) must be keyword arguments and Clickwill fill in defaults.

Changelog

Changed in version 8.0:Allkwargs are tracked inparams so they will bepassed ifforward() is called at multiple levels.

Changed in version 3.2:A new context is created, and missing arguments use default values.

forward(cmd,/,*args,**kwargs)¶

Similar toinvoke() but fills in default keywordarguments from the current context if the other command expectsit. This cannot invoke callbacks directly, only other commands.

Changelog

Changed in version 8.0:Allkwargs are tracked inparams so they will bepassed ifforward is called at multiple levels.

Parameters:

• cmd (Command)

• args (Any)

• kwargs (Any)

Return type:

Any

set_parameter_source(name,source)¶

Set the source of a parameter. This indicates the locationfrom which the value of the parameter was obtained.

Parameters:

• name (str) – The name of the parameter.

• source (ParameterSource) – A member ofParameterSource.

Return type:

None

get_parameter_source(name)¶

Get the source of a parameter. This indicates the locationfrom which the value of the parameter was obtained.

This can be useful for determining when a user specified a valueon the command line that is the same as the default value. Itwill beDEFAULT only if thevalue was actually taken from the default.

Parameters:

name (str) – The name of the parameter.

Return type:

ParameterSource

Changelog

Changed in version 8.0:ReturnsNone if the parameter was not provided from anysource.