Context Module

The parsing Context used internally for tracking parsed arguments and configuration overrides.

author:

Doug Skrypa

class cli_command_parser.context.Context(argv: Argv = None, command_cls: CommandType | None = None, *, parent: Context | None = None, config: AnyConfig = None, terminal_width: int = None, allow_argv_prog: Bool = None, command: CommandObj | None = None, **kwargs)

Bases: AbstractContextManager

The parsing context.

Holds user input while parsing, and holds the parsed values. Handles config overrides / hierarchy for settings that affect parser behavior.

prog: OptStr = None

config: CommandConfig

allow_argv_prog: Bool = True

classmethod for_prog(prog: PathLike, *args, **kwargs) → Context

property terminal_width: int

Returns the current terminal width as the number of characters that fit on a single line.

get_parsed(command: Command = None, *, exclude: Collection[Parameter] = (), recursive: Bool = True, default: Any = None, include_defaults: Bool = True) → dict[str, Any]

Returns all of the parsed arguments as a dictionary.

The get_parsed() helper function provides an easier way to access this functionality.

Parameters:

• command – An initialized Command object for which arguments were already parsed.

• exclude – Parameter objects that should be excluded from the returned results

• recursive – Whether parsed arguments should be recursively gathered from parent Commands

• default – The default value to use for parameters that raise MissingArgument when attempting to obtain their result values.

• include_defaults – Whether default values should be included in the returned results. If False, only user-provided values will be included.

Returns:

A dictionary containing all of the arguments that were parsed. The keys in the returned dict match the names assigned to the Parameters in the Command associated with this Context.

property params: CommandParameters | None

The CommandParameters object that contains the categorized Parameters from the Command associated with this Context.

get_error_handler() → ErrorHandler | NullErrorHandler

Returns the ErrorHandler configured to be used.

has_parsed_value(param: Parameter) → bool

get_parsed_value(param: Parameter, default=<object object>)

Not intended to be called by users. Used by Parameters to access their parsed values.

set_parsed_value(param: Parameter, value: Any)

Not intended to be called by users. Used by Parameters during parsing to store parsed values.

pop_parsed_value(param: Parameter)

Not intended to be called by users. Used by Parameters during parsing if backtracking is necessary.

roll_back_parsed_values(param: Parameter, count: int)

Not intended to be called by users. Used during parsing as part of backtracking.

record_action(param: ParamOrGroup, val_count: int = 1)

Not intended to be called by users. Used by Parameters during parsing to indicate that they were provided.

num_provided(param: ParamOrGroup) → int

Not intended to be called by users. Used by Parameters during parsing to handle nargs.

get_missing() → list[Parameter]

Not intended to be called by users. Used during parsing to determine if any Parameters are missing.

missing_options_with_env_var() → Iterator[Option]

Yields Option parameters that have an environment variable configured, and did not have any CLI values.

property action_flag_count: int

Not intended to be accessed by users. Returns the count of parsed action flags.

property all_action_flags: list[ActionFlag]

Not intended to be accessed by users. Returns all parsed action flags.

property categorized_action_flags: dict[ActionPhase, Sequence[ActionFlag]]

Not intended to be accessed by users. Returns a dict of parsed action flags, categorized by the ActionPhase during which they will run.

iter_action_flags(phase: ActionPhase) → Iterator[ActionFlag]

Not intended to be called by users. Iterator that yields action flags to be executed during the specified phase while incrementing the counter of actions taken.

Parameters:

phase – The current ActionPhase

class cli_command_parser.context.ActionPhase(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

PRE_INIT = 0

BEFORE_MAIN = 1

AFTER_MAIN = 2

class cli_command_parser.context.ContextProxy

Bases: object

Proxy for the currently active Context object. Allows usage similar to the request object in Flask.

This class should not be instantiated by users - use the common ctx instance.

has_parsed_value(param: Parameter) → bool

get_parsed_value(param: Parameter)

set_parsed_value(param: Parameter, value: Any)

record_action(param: ParamOrGroup, val_count: int = 1)

num_provided(param: ParamOrGroup) → int

property terminal_width: int

property config: CommandConfig

cli_command_parser.context.get_current_context(silent: bool = False) → Context | None

Get the currently active parsing context.

Parameters:

silent – If True, allow this function to return None if there is no active Context

Returns:

The active Context object

Raises:

NoActiveContext if there is no active Context and silent=False (default)

cli_command_parser.context.get_or_create_context(command_cls: CommandType, argv: Argv = None, *, command: CommandObj = None, **kwargs) → Context

Used internally by Commands to re-use an existing user-activated Context, or to create a new Context if there was no active Context.

cli_command_parser.context.get_context(command: Command) → Context

Parameters:

command – An initialized Command object

Returns:

The Context associated with the given Command

cli_command_parser.context.get_parsed(command: Command, to_call: Callable = None, default: Any = None, include_defaults: Bool = True) → dict[str, Any]

Provides a way to obtain all of the arguments that were parsed for the given Command as a dictionary.

If the parsed arguments are intended to be used to call a particular function/method, or to initialize a particular class, then that callable can be provided as the to_call parameter to filter the parsed arguments to only the ones that would be accepted by it. It will not be called by this function.

If the callable accepts any VAR_KEYWORD parameters (i.e., **kwargs), then those param names will not be used for filtering. That is, if the command has a Parameter named kwargs and the callable accepts **kwargs, the kwargs key will not be included in the argument dict returned by this function. If any of the parameters of the given callable cannot be passed as a keyword argument (i.e., POSITIONAL_ONLY or VAR_POSITIONAL), then they must be handled after calling this function. They will be included in the returned dict.

Parameters:

• command – An initialized Command object for which arguments were already parsed.

• to_call – A callable (function, method, class, etc.) that should be used to filter the parsed arguments. If provided, then only the keys that match the callable’s signature will be included in the returned dictionary of parsed arguments.

• default – The default value to use for parameters that raise MissingArgument when attempting to obtain their result values.

• include_defaults – Whether default values should be included in the returned results. If False, only user-provided values will be included.

Returns:

A dictionary containing all of the (optionally filtered) arguments that were parsed. The keys in the returned dict match the names assigned to the Parameters in the given Command.

cli_command_parser.context.get_raw_arg(command: Command, parameter: Parameter) → Any

Retrieve the raw parsed argument value(s) provided for the given Parameter