all2md.cli.builder

Dynamic CLI argument builder for all2md.

This module provides a system for automatically generating CLI arguments from dataclass options using field metadata.

class all2md.cli.builder.DynamicCLIBuilder

Bases: object

Builds CLI arguments dynamically from options dataclasses.

This class introspects converter options dataclasses and their metadata to automatically generate argparse arguments, eliminating the need for hard-coded CLI argument definitions.

Initialize the CLI builder.

__init__() → None

Initialize the CLI builder.

get_options_class_map() → Dict[str, Type[Any]]

Expose cached options classes for external introspection.

snake_to_kebab(name: str) → str

Convert snake_case to kebab-case.

Parameters:

name (str) – Snake case field name

Returns:

Kebab case CLI name

Return type:

str

infer_cli_name(field_name: str, format_prefix: str | None = None, is_boolean_with_true_default: bool = False) → str

Infer CLI argument name from field name.

Parameters:

  • field_name (str) – Dataclass field name

  • format_prefix (str, optional) – Format prefix (e.g., ‘pdf’, ‘html’)

  • is_boolean_with_true_default (bool) – Whether this is a boolean field with default=True

Returns:

CLI argument name with – prefix

Return type:

str

get_argument_kwargs(field: Any, metadata: Dict[str, Any], cli_name: str, options_class: Type) → Dict[str, Any]

Build argparse kwargs from field metadata using robust type resolution.

This method replaces brittle string matching with proper type introspection using typing.get_type_hints and helper methods.

Parameters:

  • field (Field) – Dataclass field

  • metadata (dict) – Field metadata

  • cli_name (str) – CLI argument name

  • options_class (Type) – The dataclass containing the field

Returns:

Kwargs for argparse.add_argument()

Return type:

dict

add_options_class_arguments(parser: ArgumentParser, options_class: Type, format_prefix: str | None = None, group_name: str | None = None) → None

Add arguments for an options dataclass.

Parameters:

  • parser (ArgumentParser) – Parser to add arguments to

  • options_class (Type) – Options dataclass type

  • format_prefix (str, optional) – Prefix for argument names (e.g., ‘pdf’)

  • group_name (str, optional) – Name for argument group

add_format_specific_options(parser: ArgumentParser, options_class: Type, format_prefix: str | None = None, group_name: str | None = None) → None

Add arguments for format-specific options, excluding BaseOptions fields.

Parameters:

  • parser (ArgumentParser) – Parser to add arguments to

  • options_class (Type) – Options dataclass type

  • format_prefix (str, optional) – Prefix for argument names (e.g., ‘pdf’)

  • group_name (str, optional) – Name for argument group

add_renderer_options(parser: ArgumentParser, options_class: Type, format_name: str) → None

Add renderer options for a given format with dedicated prefixes.

add_transform_arguments(parser: ArgumentParser) → None

Add transform-related CLI arguments.

Adds –transform flag and dynamic transform parameter arguments based on discovered transforms and their metadata.

Parameters:

parser (ArgumentParser) – Parser to add transform arguments to

add_global_attachment_arguments(parser: ArgumentParser) → None

Add global attachment handling arguments that apply to all formats.

These arguments are extracted from AttachmentOptionsMixin and apply to all formats unless overridden by format-specific arguments.

Parameters:

parser (ArgumentParser) – Parser to add arguments to

build_parser() → ArgumentParser

Build the complete argument parser with dynamic arguments.

Returns:

Configured parser

Return type:

ArgumentParser

resolve_option_field(dest: str) → tuple[Any, Dict[str, Any]] | None

Return the dataclass field and metadata for a CLI destination.

map_args_to_options(parsed_args: Namespace, json_options: dict | None = None) → dict

Map CLI arguments to options using dot notation parsing.

This simplified version uses dot notation in argument destinations to directly map to the nested structure of options.

Parameters:

  • parsed_args (argparse.Namespace) – Parsed command line arguments

  • json_options (dict or None) – Options loaded from JSON file

Returns:

Mapped options dictionary ready for to_markdown()

Return type:

dict

all2md.cli.builder.validate_pygments_theme(theme_name: str) → str

Validate that a Pygments theme name is valid.

Parameters:

theme_name (str) – Theme name to validate

Returns:

The validated theme name

Return type:

str

Raises:

argparse.ArgumentTypeError – If theme name is not valid

all2md.cli.builder.create_parser() → ArgumentParser

Create and configure the argument parser using dynamic generation.

all2md.cli.builder.get_exit_code_for_exception(exception: Exception) → int

Map an exception to an appropriate CLI exit code.

Parameters:

exception (Exception) – The exception to map to an exit code

Returns:

The appropriate exit code for the exception type

Return type:

int