API Reference¶

`optgroup`	A helper class to manage creating groups and group options via decorators
`GroupedOption`	Represents grouped (related) optional values
`OptionGroup`	Option group manages grouped (related) options
`RequiredAnyOptionGroup`	Option group with required any options of this group
`AllOptionGroup`	Option group with required all/none options of this group
`RequiredAllOptionGroup`	Option group with required all options of this group
`MutuallyExclusiveOptionGroup`	Option group with mutually exclusive behavior for grouped options
`RequiredMutuallyExclusiveOptionGroup`	Option group with required and mutually exclusive behavior for grouped options

class click_option_group.optgroup¶

A global instance of the helper class to manage creating groups and group options via decorators

The class provides two decorator-methods: group/__call__ and option. These decorators should be used for adding grouped options. The class have single global instance optgroup that should be used in most cases.

The example of usage:

from click_option_group import optgroup

...
@optgroup('Group 1', help='option group 1')
@optgroup.option('--foo')
@optgroup.option('--bar')
@optgroup.group('Group 2', help='option group 2')
@optgroup.option('--spam')
...

group(name, *, cls, help, **attrs)¶

The decorator creates a new group and collects its options

Creates the option group and registers all grouped options which were added by option() decorator.

Parameters:

name – Group name or None for deault name
cls – Option group class that should be inherited from OptionGroup class
help – Group help or None for empty help
attrs – Additional parameters of option group class

option(*param_decls, **attrs)¶

The decorator adds a new option to the group

The decorator is lazy. It adds option decls and attrs. All options will be registered by group() decorator.

Parameters:

param_decls – option declaration tuple
attrs – additional option attributes and parameters

class click_option_group.GroupedOption(param_decls: Optional[Sequence[str]] = None, *, group: OptionGroup, **attrs: Any)¶

Represents grouped (related) optional values

The class should be used only with OptionGroup class for creating grouped options.

Parameters:

param_decls – option declaration tuple
group – OptionGroup instance (the group for this option)
attrs – additional option attributes

property group: OptionGroup¶

Returns the reference to the group for this option

Returns:: OptionGroup the group instance for this option

class click_option_group.OptionGroup(name: Optional[str] = None, *, hidden: bool = False, help: Optional[str] = None)¶

Option group manages grouped (related) options

The class is used for creating the groups of options. The class can de used as based class to implement specific behavior for grouped options.

Parameters:

name – the group name. If it is not set the default group name will be used
help – the group help text or None

property name: str¶

Returns the group name or empty string if it was not set

Returns:: group name

property help: str¶

Returns the group help or empty string if it was not set

Returns:: group help

property name_extra: List[str]¶: Returns extra name attributes for the group

property forbidden_option_attrs: List[str]¶: Returns the list of forbidden option attributes for the group

get_help_record(ctx: Context) → Optional[Tuple[str, str]]¶

Returns the help record for the group

Parameters:: ctx – Click Context object
Returns:: the tuple of two fileds: (name, help)

option(*param_decls: str, **attrs: Any) → Callable¶

Decorator attaches a grouped option to the command

The decorator is used for adding options to the group and to the Click-command

get_options(ctx: Context) → Dict[str, GroupedOption]¶: Returns the dictionary with group options

get_option_names(ctx: Context) → List[str]¶: Returns the list with option names ordered by addition in the group

handle_parse_result(option: GroupedOption, ctx: Context, opts: Mapping[str, Any]) → None¶: The method should be used for adding specific behavior and relation for options in the group

class click_option_group.RequiredAnyOptionGroup(name: Optional[str] = None, *, hidden: bool = False, help: Optional[str] = None)¶

Option group with required any options of this group

RequiredAnyOptionGroup defines the behavior: At least one option from the group must be set.

property forbidden_option_attrs: List[str]¶: Returns the list of forbidden option attributes for the group

property name_extra: List[str]¶: Returns extra name attributes for the group

handle_parse_result(option: GroupedOption, ctx: Context, opts: Mapping[str, Any]) → None¶: The method should be used for adding specific behavior and relation for options in the group

class click_option_group.AllOptionGroup(name: Optional[str] = None, *, hidden: bool = False, help: Optional[str] = None)¶

Option group with required all/none options of this group

AllOptionGroup defines the behavior:

All options from the group must be set or None must be set

property forbidden_option_attrs: List[str]¶: Returns the list of forbidden option attributes for the group

property name_extra: List[str]¶: Returns extra name attributes for the group

handle_parse_result(option: GroupedOption, ctx: Context, opts: Mapping[str, Any]) → None¶: The method should be used for adding specific behavior and relation for options in the group

class click_option_group.RequiredAllOptionGroup(name: Optional[str] = None, *, hidden: bool = False, help: Optional[str] = None)¶

Option group with required all options of this group

RequiredAllOptionGroup defines the behavior: All options from the group must be set.

property forbidden_option_attrs: List[str]¶: Returns the list of forbidden option attributes for the group

property name_extra: List[str]¶: Returns extra name attributes for the group

handle_parse_result(option: GroupedOption, ctx: Context, opts: Mapping[str, Any]) → None¶: The method should be used for adding specific behavior and relation for options in the group

class click_option_group.MutuallyExclusiveOptionGroup(name: Optional[str] = None, *, hidden: bool = False, help: Optional[str] = None)¶

Option group with mutually exclusive behavior for grouped options

MutuallyExclusiveOptionGroup defines the behavior:

Only one or none option from the group must be set

property forbidden_option_attrs: List[str]¶: Returns the list of forbidden option attributes for the group

property name_extra: List[str]¶: Returns extra name attributes for the group

handle_parse_result(option: GroupedOption, ctx: Context, opts: Mapping[str, Any]) → None¶: The method should be used for adding specific behavior and relation for options in the group

class click_option_group.RequiredMutuallyExclusiveOptionGroup(name: Optional[str] = None, *, hidden: bool = False, help: Optional[str] = None)¶

Option group with required and mutually exclusive behavior for grouped options

RequiredMutuallyExclusiveOptionGroup defines the behavior:

Only one required option from the group must be set

property name_extra: List[str]¶: Returns extra name attributes for the group

handle_parse_result(option: GroupedOption, ctx: Context, opts: Mapping[str, Any]) → None¶: The method should be used for adding specific behavior and relation for options in the group

API Reference¶

Contents

Navigation