The Decorator API

Click’s decorator API turns a Python callback into a command-line object and lets nearby decorators describe that command’s parameters. The main entry point is command, while option and argument prepare parameter objects for it.

This arrangement exists so command declarations remain compact: parameter decorators register metadata first, and command later combines that metadata with the callback into a Command. Helper decorators then adapt callback arguments or install common options without requiring each application to repeat the underlying plumbing.

Sources: src/click/decorators.py:168-255, src/click/decorators.py:352-377, src/click/decorators.py:324-349, src/click/decorators.py:314-321, src/click/decorators.py:28-36

Core concepts

Command construction

A command is the object created around the decorated function, with the function retained as its callback and its decorated parameters passed into the command constructor.

The public decorator is command; its overloads allow either a callable directly or a later decorator call, with an optional custom cls and additional attributes.

Sources: src/click/decorators.py:217-250, src/click/decorators.py:138, src/click/decorators.py:144-148, src/click/decorators.py:163-165

Parameter memoization

Parameter memoization is the temporary registration step that stores an Option or Argument until command builds the future Command.

The helper _param_memo appends directly to an existing Command, or otherwise stores parameters on the function’s __click_params__ attribute.

Sources: src/click/decorators.py:314-321, src/click/decorators.py:352-377, src/click/decorators.py:324-349

Context-passing wrappers

A context-passing wrapper is a replacement function that obtains the current Context at invocation time and supplies context-derived data to the original callback.

pass_context supplies the current context itself, pass_obj supplies Context.obj, and make_pass_decorator can find or create an object of a requested type.

Sources: src/click/decorators.py:28-36, src/click/decorators.py:39-48, src/click/decorators.py:51-97

Shortcut options

A shortcut option is a preconfigured decorator that ultimately delegates to option with fixed defaults and, when needed, a callback.

Sources: src/click/decorators.py:380-401, src/click/decorators.py:404-418, src/click/decorators.py:421-558, src/click/decorators.py:603-627

How a function becomes a command

When command receives a callable directly, it saves that callable as func, rejects conflicting class or attribute arguments, and otherwise returns a decorator for the later form.

The inner decorator rejects an object that is already a Command, reads any __click_params__ collected on the function, reverses those collected parameters into the command parameter list, and uses the function docstring as help when no explicit help was supplied.

If no explicit name is provided, the command name comes from the function name after lowercasing, replacing underscores with dashes, and removing a trailing command, cmd, group, or grp suffix.

Finally, command constructs cls with the computed name, the original function as callback, the collected params, and the remaining attributes; it copies the function docstring to cmd.__doc__ and returns the command object.

The workflow shows the important boundary: option and argument leave the function callable intact, while command is the decorator that replaces the decorated function with a Command.

Sources: src/click/decorators.py:206-217, src/click/decorators.py:217-234, src/click/decorators.py:239-247, src/click/decorators.py:248-250, src/click/decorators.py:352-377, src/click/decorators.py:324-349

How options and arguments register parameters

option defaults its class to Option, constructs that class from positional parameter declarations and keyword attributes, passes the resulting object to _param_memo, and returns the original function.

argument follows the same pattern with Argument: it defaults the class, constructs it from declarations and attributes, memoizes it, and returns the original function.

These decorators are therefore equivalent to manually creating the corresponding parameter object and attaching it to the command’s Command.params list, except that the attachment may be deferred through function metadata.

The eventual command decorator removes __click_params__ from the function and extends its parameter list with the collected declarations before constructing the command.

Sources: src/click/decorators.py:352-375, src/click/decorators.py:324-349, src/click/decorators.py:352-377, src/click/decorators.py:314-321, src/click/decorators.py:221-230

How helper decorators supply context and common flags

pass_context wraps a callback so invocation calls the original function with get_current_context() as its first argument, then preserves the original wrapper metadata with update_wrapper.

pass_obj performs the same style of wrapping but passes get_current_context().obj, which is intended for state stored on the context rather than the entire context object.

make_pass_decorator generalizes this behavior: its generated wrapper obtains the current context, chooses ensure_object or find_object according to ensure, raises RuntimeError if no object is available, and invokes the callback through ctx.invoke.

pass_meta_key is another generated wrapper; it reads ctx.meta[key] and supplies that value to the callback through ctx.invoke.

The same wrapper shape explains the helper family: lookup happens only when the callback is invoked, not when the decorator is declared.

The common option helpers configure option rather than creating a separate parameter mechanism. confirmation_option defaults to --yes, makes it a flag that does not expose a value, prompts when needed, and aborts through its callback when the value is false.

password_option defaults to --password, enables prompting and confirmation, hides input, and returns option with those defaults.

help_option creates an eager flag whose callback prints ctx.get_help() and exits when parsing is not resilient.

version_option creates an eager option whose callback resolves or detects a version, prints a formatted message, and exits; custom_version_option instead invokes a supplied callback to produce the complete output before exiting.

Sources: src/click/decorators.py:28-36, src/click/decorators.py:39-48, src/click/decorators.py:51-97, src/click/decorators.py:76-95, src/click/decorators.py:115-121, src/click/decorators.py:380-401, src/click/decorators.py:404-418, src/click/decorators.py:603-627, src/click/decorators.py:421-558, src/click/decorators.py:501-548, src/click/decorators.py:585-590

How it connects

The decorator functions are exported from click.__init__, so callers can use names such as option, pass_context, pass_obj, version_option, and custom_version_option through the Click package surface. This page’s object-building behavior feeds into Commands and Groups, while the resulting Option, Argument, and Parameter objects are explained in The Parameter Model.

The current context used by the helper wrappers is provided by Click’s context machinery, covered in Context and Execution. The parser consumes the command and parameter model later; its own role is described in The Low-Level Parser.

Sources: src/click/init.py:21-29, src/click/decorators.py:352-377, src/click/decorators.py:324-349, src/click/decorators.py:28-36, src/click/globals.py:21-33

Key takeaways

• command turns the decorated function into a Command whose callback is the original function.
• option and argument construct parameter objects and memoize them before command construction.
• _param_memo stores pending parameters on __click_params__ or appends them directly to a Command.
• pass_context, pass_obj, make_pass_decorator, and pass_meta_key inject context-derived values at invocation time.
• Shortcut decorators configure option with standard flags, callbacks, prompts, output, and exit behavior.