all2md.cli.custom_actions

Custom argparse actions for improved CLI argument handling.

This module provides custom actions that enhance argparse functionality for better argument tracking, nested namespace handling, and environment variable support.

class all2md.cli.custom_actions.TrackingStoreAction

Bases: Action

Custom action that tracks whether an argument was explicitly provided.

This action stores both the value and metadata about whether the argument was provided by the user, making it easier to distinguish between default values and user-provided values that happen to match the default.

Also supports environment variable defaults using the pattern ALL2MD_DEST_NAME.

Initialize the tracking store action.

Parameters:

option_strings (Sequence[str]) – The option strings for this action
dest (str) – The attribute name to store the value
nargs (Optional[Union[int, str]]) – Number of arguments to consume
const (Optional[Any]) – Constant value for special cases
default (Optional[Any]) – Default value if not provided
type (Optional[Any]) – Type conversion function
choices (Optional[Sequence[Any]]) – Valid choices for the argument
required (bool) – Whether this argument is required
help (Optional[str]) – Help text for the argument
metavar (Optional[Union[str, tuple[str, ...]]]) – Display name for the argument value

Initialize the tracking store action.

Parameters:

option_strings (Sequence[str]) – The option strings for this action
dest (str) – The attribute name to store the value
nargs (Optional[Union[int, str]]) – Number of arguments to consume
const (Optional[Any]) – Constant value for special cases
default (Optional[Any]) – Default value if not provided
type (Optional[Any]) – Type conversion function
choices (Optional[Sequence[Any]]) – Valid choices for the argument
required (bool) – Whether this argument is required
help (Optional[str]) – Help text for the argument
metavar (Optional[Union[str, tuple[str, ...]]]) – Display name for the argument value

class all2md.cli.custom_actions.TrackingStoreTrueAction

Bases: Action

Custom store_true action that tracks whether the flag was explicitly provided.

Also supports environment variable defaults using the pattern ALL2MD_DEST_NAME.

Initialize the tracking store_true action.

Parameters:

option_strings (Sequence[str]) – The option strings for this action
dest (str) – The attribute name to store the value
default (bool) – Default value (should be False for store_true)
required (bool) – Whether this argument is required
help (Optional[str]) – Help text for the argument

__init__(option_strings: Sequence[str], dest: str, default: bool = False, required: bool = False, help: str | None = None) → None

Initialize the tracking store_true action.

Parameters:

option_strings (Sequence[str]) – The option strings for this action
dest (str) – The attribute name to store the value
default (bool) – Default value (should be False for store_true)
required (bool) – Whether this argument is required
help (Optional[str]) – Help text for the argument

class all2md.cli.custom_actions.TrackingStoreFalseAction

Bases: Action

Custom store_false action that tracks whether the flag was explicitly provided.

Also supports environment variable defaults using the pattern ALL2MD_DEST_NAME.

Initialize the tracking store_false action.

Parameters:

option_strings (Sequence[str]) – The option strings for this action
dest (str) – The attribute name to store the value
default (bool) – Default value (should be True for store_false)
required (bool) – Whether this argument is required
help (Optional[str]) – Help text for the argument

__init__(option_strings: Sequence[str], dest: str, default: bool = True, required: bool = False, help: str | None = None) → None

Initialize the tracking store_false action.

Parameters:

option_strings (Sequence[str]) – The option strings for this action
dest (str) – The attribute name to store the value
default (bool) – Default value (should be True for store_false)
required (bool) – Whether this argument is required
help (Optional[str]) – Help text for the argument

class all2md.cli.custom_actions.TrackingAppendAction

Bases: Action

Custom append action that tracks explicitly provided arguments.

Also supports environment variable defaults using the pattern ALL2MD_DEST_NAME. Environment values are split on commas.

Initialize the tracking append action.

Parameters:

option_strings (Sequence[str]) – The option strings for this action
dest (str) – The attribute name to store the value
nargs (Optional[Union[int, str]]) – Number of arguments to consume
const (Optional[Any]) – Constant value for special cases
default (Optional[list]) – Default value if not provided
type (Optional[Any]) – Type conversion function
choices (Optional[Sequence[Any]]) – Valid choices for the argument
required (bool) – Whether this argument is required
help (Optional[str]) – Help text for the argument
metavar (Optional[Union[str, tuple[str, ...]]]) – Display name for the argument value

Initialize the tracking append action.

Parameters:

option_strings (Sequence[str]) – The option strings for this action
dest (str) – The attribute name to store the value
nargs (Optional[Union[int, str]]) – Number of arguments to consume
const (Optional[Any]) – Constant value for special cases
default (Optional[list]) – Default value if not provided
type (Optional[Any]) – Type conversion function
choices (Optional[Sequence[Any]]) – Valid choices for the argument
required (bool) – Whether this argument is required
help (Optional[str]) – Help text for the argument
metavar (Optional[Union[str, tuple[str, ...]]]) – Display name for the argument value

class all2md.cli.custom_actions.TrackingPositiveIntAction

Bases: Action

Action that validates positive integers with tracking and environment variable support.

Initialize the tracking positive int action.

Parameters:

option_strings (Sequence[str]) – The option strings for this action
dest (str) – The attribute name to store the value
nargs (Optional[Union[int, str]]) – Number of arguments to consume
const (Optional[Any]) – Constant value for special cases
default (Optional[int]) – Default value if not provided
required (bool) – Whether this argument is required
help (Optional[str]) – Help text for the argument
metavar (Optional[Union[str, tuple[str, ...]]]) – Display name for the argument value

Initialize the tracking positive int action.

Parameters:

option_strings (Sequence[str]) – The option strings for this action
dest (str) – The attribute name to store the value
nargs (Optional[Union[int, str]]) – Number of arguments to consume
const (Optional[Any]) – Constant value for special cases
default (Optional[int]) – Default value if not provided
required (bool) – Whether this argument is required
help (Optional[str]) – Help text for the argument
metavar (Optional[Union[str, tuple[str, ...]]]) – Display name for the argument value

class all2md.cli.custom_actions.DynamicVersionAction

Bases: _VersionAction

Action that displays version information without requiring post-creation modification.

This replaces the need to modify parser._actions to update version strings.

Initialize with a callback to get version dynamically.

Parameters:

option_strings (Sequence[str]) – Option strings for this action
version_callback (callable, optional) – Function that returns the version string when called
**kwargs (Any) – Additional keyword arguments passed to parent action

__init__(option_strings: Sequence[str], version_callback: Callable[[], str] | None = None, **kwargs: Any) → None

Initialize with a callback to get version dynamically.

Parameters:

option_strings (Sequence[str]) – Option strings for this action
version_callback (callable, optional) – Function that returns the version string when called
**kwargs (Any) – Additional keyword arguments passed to parent action

all2md.cli.custom_actions.parse_dot_notation(dot_string: str, value: Any) → dict

Parse a dot notation string into a nested dictionary.

Parameters:

dot_string (str) – Dot notation string (e.g., “pdf.pages”)
value (Any) – The value to store at the nested location

Returns:

Nested dictionary with the value at the specified path

Return type:

dict

Examples

>>> parse_dot_notation("pdf.pages", [1, 2, 3])
{'pdf': {'pages': [1, 2, 3]}}
>>> parse_dot_notation("markdown.emphasis_symbol", "_")
{'markdown': {'emphasis_symbol': '_'}}

all2md.cli.custom_actions.merge_nested_dicts(base: dict, update: dict) → dict

Recursively merge nested dictionaries.

Parameters:

base (dict) – Base dictionary to merge into
update (dict) – Dictionary with updates to apply

Returns:

Merged dictionary with updates applied

Return type:

dict

Examples

>>> base = {'pdf': {'pages': [1, 2]}}
>>> update = {'pdf': {'password': 'secret'}}
>>> merge_nested_dicts(base, update)
{'pdf': {'pages': [1, 2], 'password': 'secret'}}

class all2md.cli.custom_actions.TieredHelpAction

Bases: Action

Custom help action that integrates the enhanced help formatter.

Initialize the tiered help action.

Parameters:

option_strings (list) – Option strings for this action
dest (str, optional) – Destination attribute, defaults to SUPPRESS
**kwargs (dict) – Additional argparse action keyword arguments

__init__(option_strings: list[str], dest: str = '==SUPPRESS==', **kwargs: Any) → None

Initialize the tiered help action.

Parameters:

option_strings (list) – Option strings for this action
dest (str, optional) – Destination attribute, defaults to SUPPRESS
**kwargs (dict) – Additional argparse action keyword arguments