macaron.build_spec_generator.cli_command_parser package

This module contain the base classes cli command parsers related.

macaron.build_spec_generator.cli_command_parser.is_list_of_strs(value)

Type guard for a list of strings.

Return type:: TypeGuard[list[str]]

macaron.build_spec_generator.cli_command_parser.is_dict_of_str_to_str_or_none(value)

Type guard for a dictionary where the keys are string and values are strings or None.

Return type:: TypeGuard[dict[str, str | None]]

macaron.build_spec_generator.cli_command_parser.patch_mapping(original, patch)

Patch a mapping.

A key with a value in the patch set to None will be removed from the original.

Parameters:

original (Mapping[str, str]) – The original mapping.
patch (Mapping[str, str | None]) – The patch.

Returns:

The new dictionary after applying the patch.

Return type:

dict[str, str]

class macaron.build_spec_generator.cli_command_parser.OptionDef(long_name)

Bases: Generic[P]

This class represents a definition of a CLI option for argparse.ArgumentParser.

This class also contains the information for validating a patch value. The generic type P is the patch expected type (if it’s not None).

long_name: str

abstractmethod is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[TypeVar(P)]

abstractmethod add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

abstractmethod get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name)

class macaron.build_spec_generator.cli_command_parser.PatchCommandBuildTool(value)

Bases: str, Enum

Build tool supported for CLICommand patching.

MAVEN = 'maven'

GRADLE = 'gradle'

class macaron.build_spec_generator.cli_command_parser.CLIOptions(*args, **kwargs)

Bases: Protocol

Interface of the options part of a CLICommand.

to_option_cmds()

Return the options as a list of strings.

Return type:: list[str]

__init__(*args, **kwargs)

class macaron.build_spec_generator.cli_command_parser.CLICommand(*args, **kwargs)

Bases: Protocol

Interface of a CLI Command.

to_cmds()

Return the CLI Command as a list of strings.

Return type:: list[str]

__init__(*args, **kwargs)

class macaron.build_spec_generator.cli_command_parser.CLICommandParser(*args, **kwargs)

Bases: Protocol[T, Y_contra]

Interface of a CLI Command Parser.

property build_tool: PatchCommandBuildTool: Return the BuildTool enum corresponding to this CLICommand.

parse(cmd_list)

Parse the CLI Command.

Parameters:: cmd_list (list[str]) – The CLI Command as list of strings.
Returns:: The CLICommand instance.
Return type:: CLICommand
Raises:: CommandLineParseError – If an error happens when parsing the CLI Command.

is_build_tool(executable_path)

Return True if executable_path ends the accepted executable for this build tool.

Parameters:: executable_path (str) – The executable component of a CLI command.
Return type:: bool

apply_patch(cli_command, patch_options)

Return a new CLICommand object with its option patched, while persisting the executable path.

Return type:: TypeVar(T, bound= CLICommand)

__init__(*args, **kwargs)

Submodules

macaron.build_spec_generator.cli_command_parser.gradle_cli_command module

This module contains the classes that represent components of a Gradle CLI Command.

class macaron.build_spec_generator.cli_command_parser.gradle_cli_command.GradleCLIOptions(continue_, help_, no_rebuild, debug, export_keys, foreground, info, offline, profile, quiet, refresh_dependencies, refresh_keys, rerun_tasks, full_stacktrace, stacktrace, status, stop, continuous, version, warn, write_locks, build_cache, configuration_cache, configure_on_demand, daemon, parallel, scan, watch_fs, build_file, settings_file, configuration_cache_problems, gradle_user_home, init_script, include_build, write_verification_metadata, max_workers, project_dir, priority, project_cache_dir, update_locks, warning_mode, exclude_task, system_prop, project_prop, tasks)

Bases: object

The class that stores the values of options parsed from a Gradle CLI Command.

continue_: bool | None

help_: bool | None

no_rebuild: bool | None

debug: bool | None

export_keys: bool | None

foreground: bool | None

info: bool | None

offline: bool | None

profile: bool | None

quiet: bool | None

refresh_dependencies: bool | None

refresh_keys: bool | None

rerun_tasks: bool | None

full_stacktrace: bool | None

stacktrace: bool | None

status: bool | None

stop: bool | None

continuous: bool | None

version: bool | None

warn: bool | None

write_locks: bool | None

build_cache: bool | None

configuration_cache: bool | None

configure_on_demand: bool | None

daemon: bool | None

parallel: bool | None

scan: bool | None

watch_fs: bool | None

build_file: str | None

settings_file: str | None

configuration_cache_problems: str | None

gradle_user_home: str | None

init_script: str | None

include_build: str | None

write_verification_metadata: str | None

max_workers: str | None

project_dir: str | None

priority: str | None

project_cache_dir: str | None

update_locks: str | None

warning_mode: str | None

exclude_task: list[str] | None

system_prop: dict[str, str] | None

project_prop: dict[str, str] | None

tasks: list[str] | None

classmethod from_parsed_arg(parsed_arg)

Initialize the instance from an argparse.Namespace object.

Parameters:: parsed_arg (argparse.Namespace) – The argparse.Namespace object obtained from parsing the CLI Command.
Returns:: The intialized GradleCLIOptions object instance.
Return type:: GradleCLIOptions

static parse_properties(props)

Return a dictionary that maps between a property and its value.

Each property definition value in props can have either of these formats: - property=value (e.g. property=value from -Dproperty=value): this will be parsed into a dictionary mapping of “property”: “value”. Both the key and value of this mapping are of type string. - property (e.g. property from -Dproperty): this will be parsed into a dictionary mapping of “property”: <empty_string>.

Parameters:: props (list[str]) – The list of property definitions provided in the cli command. This is the list parsed by argparse.
Returns:: The properties dictionary.
Return type:: dict[str, str]

Examples

>>> GradleCLIOptions.parse_properties(["boo=true", "foo=1", "bar"])
{'boo': 'true', 'foo': '1', 'bar': ''}

to_option_cmds()

Return the options as a list of strings.

Return type:: list[str]

to_cmd_no_tasks()

Return the options only as a list of string.

Only enabled options are returned.

Returns:: The enabled options.
Return type:: list[str]

__init__(continue_, help_, no_rebuild, debug, export_keys, foreground, info, offline, profile, quiet, refresh_dependencies, refresh_keys, rerun_tasks, full_stacktrace, stacktrace, status, stop, continuous, version, warn, write_locks, build_cache, configuration_cache, configure_on_demand, daemon, parallel, scan, watch_fs, build_file, settings_file, configuration_cache_problems, gradle_user_home, init_script, include_build, write_verification_metadata, max_workers, project_dir, priority, project_cache_dir, update_locks, warning_mode, exclude_task, system_prop, project_prop, tasks)

class macaron.build_spec_generator.cli_command_parser.gradle_cli_command.GradleCLICommand(executable, options)

Bases: object

The class that stores the values of a Gradle CLI Command.

executable: str

options: GradleCLIOptions

to_cmds()

Return the CLI Command as a list of strings.

Return type:: list[str]

__init__(executable, options)

macaron.build_spec_generator.cli_command_parser.gradle_cli_parser module

This module contains the Gradle CLI Command parser.

class macaron.build_spec_generator.cli_command_parser.gradle_cli_parser.GradleOptionalFlag(long_name, short_names, dest=None)

Bases: OptionDef[bool]

This option represents an optional flag in Gradle CLI command.

For example:

Has one short name -d/–debug
Has no short name –continue
Has multiple short names -?/-h/–help

This option can have multiple values, and it’s not required.

short_names: list[str] | None

dest: str | None = None

is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[bool]

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name, short_names, dest=None)

class macaron.build_spec_generator.cli_command_parser.gradle_cli_parser.GradleOptionalNegatableFlag(long_name)

Bases: OptionDef[bool]

This option represents an optional negatable flag in Gradle CLI command.

For example: –build-cache/–no-build-cache

is_valid_patch_option(patch)

Return True if the provide patch value is compatible with the internal type of this option.

Return type:: TypeGuard[bool]

static get_negated_long_name(long_name)

Return the negated version of a long option name.

Return type:: str

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name)

class macaron.build_spec_generator.cli_command_parser.gradle_cli_parser.GradleSingleValue(long_name, short_name)

Bases: OptionDef[str]

This option represents an option that takes a value in Gradle CLI command.

short_name: str | None

is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[str]

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name, short_name)

class macaron.build_spec_generator.cli_command_parser.gradle_cli_parser.GradleProperties(long_name, short_name)

Bases: OptionDef[dict[str, str | None]]

This option represents an option used to define property values of a Gradle CLI command.

This option can be defined multiple times and the values are appended into a list of string in argparse. However, it’s stored internally as a dictionary mapping between the system property name and its value.

In Gradle there are 2 options of this type:

-D/–system-prop
-P/–project-prop

short_name: str

is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[dict[str, str | None]]

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name, short_name)

class macaron.build_spec_generator.cli_command_parser.gradle_cli_parser.GradleTask(long_name)

Bases: OptionDef[list[str]]

This option represents the positional task option in Gradle CLI command.

argparse.Namespace stores this as a list of string. This is stored internally as a list of string.

is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[list[str]]

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name)

class macaron.build_spec_generator.cli_command_parser.gradle_cli_parser.GradleAppendedList(long_name, short_name)

Bases: OptionDef[list[str]]

This option represents an option that can be specified multiple times.

Each instance of the option will be appended to a list. For example, one can exclude multiple tasks with: gradle <task_to_run> –exclude-task taskA –exclude-task taskB

short_name: str

is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[list[str]]

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name, short_name)

class macaron.build_spec_generator.cli_command_parser.gradle_cli_parser.GradleCLICommandParser

Bases: object

A Gradle CLI Command Parser.

ACCEPTABLE_EXECUTABLE = {'gradle', 'gradlew'}

__init__(): Initialize the instance.

is_build_tool(executable_path)

Return True if executable_path ends the accepted executable for this build tool.

Parameters:: executable_path (str) – The executable component of a CLI command.
Return type:: bool

validate_patch(patch)

Return True if the patch conforms to the expected format.

Return type:: bool

parse(cmd_list)

Parse the Gradle CLI Command.

Parameters:: cmd_list (list[str]) – The Gradle CLI Command as list of strings.
Returns:: The GradleCLICommand instance.
Return type:: GradleCLICommand
Raises:: CommandLineParseError – If an error happens when parsing the Gradle CLI Command.

apply_patch(cli_command, patch_options)

Patch the options of a Gradle CLI command, while persisting the executable path.

patch_options is a mapping with:

Key: the long name of a Gradle CLI option as string. For example: --continue, --build-cache. For patching tasks, use the key tasks.
Value: The value to patch for an option referred to by the key. The type of this value depends on the type of option you want to patch. Please see the details below.

The types of patch values:

For optional flag (e.g -d/--debug) that doesn’t take in a value, it is boolean. True if you want to set it, and False if you want to unset it.
For -D/--system-prop and -P/--project-prop ONLY, it is a a mapping between the property name and its value. A value of type None can be provided to “unset” the property.
For -x/--exclude-task option, a list of string is required.
For options that have a negated form (e.g. --build-cache/--no-build-cache), the key must be the normal long name (--build-cache) and the value is of type boolean. True if you want to set --build-cache and False if you want to set --no-build-cache.
For other option that expects a value (e.g -c/–setting-file <path/to/settings/file>`), a string is expected.

None can be provided to ANY type of option to forcefully remove it from the original build command.

Parameters:

cli_command (GradleCLICommand) – The original Gradle command, as a GradleCLICommand object from GradleCLICommandParser.parse(...)
patch_options (Mapping[str, GradleOptionPatchValueType | None]) – The patch values.

Returns:

The patched command as a new GradleCLICommand object.

Return type:

GradleCLICommand

Raises:

PatchBuildCommandError – If an error happens during the patching process.

apply_option_patch(gradle_cli_options, patch)

Patch the Gradle CLI Options and return a new copy.

Parameters:

gradle_cli_options (GradleCLIOptions) – The Gradle CLI Options to patch.
patch (Mapping[str, GradleOptionPatchValueType | None]) – A mapping between the name of the attribute in GradleCLIOptions and its patch value

Returns:

The new patched gradle cli options.

Return type:

GradleCLIOptions

Raises:

PatchBuildCommandError – If an error happens during the patching process.

macaron.build_spec_generator.cli_command_parser.maven_cli_command module

This module contains the classes that represent components of a Maven CLI Command.

class macaron.build_spec_generator.cli_command_parser.maven_cli_command.MavenCLIOptions(also_make, also_make_dependents, batch_mode, strict_checksums, lax_checksums, errors, fail_at_end, fail_fast, fail_never, help_, non_recursive, no_snapshot_updates, no_transfer_progress, quiet, version, show_version, debug, offline, update_snapshots, builder, encrypt_master_password, encrypt_password, file, global_settings, global_toolchains, log_file, resume_from, settings, toolchains, threads, activate_profiles, projects, define, goals)

Bases: object

The class that stores the values of options parsed from a Maven CLI Command.

also_make: bool | None

also_make_dependents: bool | None

batch_mode: bool | None

strict_checksums: bool | None

lax_checksums: bool | None

errors: bool | None

fail_at_end: bool | None

fail_fast: bool | None

fail_never: bool | None

help_: bool | None

non_recursive: bool | None

no_snapshot_updates: bool | None

no_transfer_progress: bool | None

quiet: bool | None

version: bool | None

show_version: bool | None

debug: bool | None

offline: bool | None

update_snapshots: bool | None

builder: str | None

encrypt_master_password: str | None

encrypt_password: str | None

file: str | None

global_settings: str | None

global_toolchains: str | None

log_file: str | None

resume_from: str | None

settings: str | None

toolchains: str | None

threads: str | None

activate_profiles: list[str] | None

projects: list[str] | None

define: dict[str, str] | None

goals: list[str] | None

classmethod from_parsed_arg(parsed_arg)

Initialize the instance from the argparse.Namespace object.

Parameters:: parsed_arg (argparse.Namespace) – The argparse.Namespace object obtained from parsing the CLI Command.
Returns:: The MavenCLIOptions object.
Return type:: MavenCLIOptions

static parse_system_properties(props)

Return a dictionary that maps between a system propertie and its value.

Each property definition value in props can have either of these format: - property=value (e.g. -Dproperty=value): this will be parsed into a dictionary mapping of “property”: “value”. Both the key and value of this mapping is of type string. - property (e.g. -Dproperty): this will be parsed into a dictionary mapping of “property”: “true”.

Parameters:: props (list[str]) – The list of values provided to -D/–define in the cli command. This is the list parsed by argparse.
Returns:: The system properties dictionary.
Return type:: dict[str, str]

Examples

>>> MavenCLIOptions.parse_system_properties(["boo=true", "foo=1", "bar"])
{'boo': 'true', 'foo': '1', 'bar': 'true'}

static parse_comma_sep_list(input_val)

Split a comma delimited string and return a list of string elements.

Parameters:: input_val (str) – The comma delimited string.
Returns:: The list of string elements.
Return type:: list[str]

Examples

>>> MavenCLIOptions.parse_comma_sep_list("examples,release")
['examples', 'release']

to_option_cmds()

Return the options as a list of strings.

Return type:: list[str]

to_cmd_no_goals()

Return the options only as a list of string.

Only enabled options are returned.

Returns:: The enabled options.
Return type:: list[str]

__init__(also_make, also_make_dependents, batch_mode, strict_checksums, lax_checksums, errors, fail_at_end, fail_fast, fail_never, help_, non_recursive, no_snapshot_updates, no_transfer_progress, quiet, version, show_version, debug, offline, update_snapshots, builder, encrypt_master_password, encrypt_password, file, global_settings, global_toolchains, log_file, resume_from, settings, toolchains, threads, activate_profiles, projects, define, goals)

class macaron.build_spec_generator.cli_command_parser.maven_cli_command.MavenCLICommand(executable, options)

Bases: object

The class that stores the values of a Maven CLI Command.

executable: str

options: MavenCLIOptions

to_cmds()

Return the CLI Command as a list of strings.

Return type:: list[str]

__init__(executable, options)

macaron.build_spec_generator.cli_command_parser.maven_cli_parser module

This module contains the Maven CLI Command parser.

class macaron.build_spec_generator.cli_command_parser.maven_cli_parser.MavenOptionalFlag(long_name, short_name, dest=None)

Bases: OptionDef[bool]

This option represents an optional flag in Maven CLI command.

For example: –debug/-X

A short form for the option is required.

short_name: str

dest: str | None = None

is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[bool]

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name, short_name, dest=None)

class macaron.build_spec_generator.cli_command_parser.maven_cli_parser.MavenSingleValue(long_name, short_name)

Bases: OptionDef[str]

This option represents an option that takes a value in Maven CLI command.

For example: “–settings ./path/to/pom.xml”

A short form for the option is required.

short_name: str

is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[str]

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name, short_name)

class macaron.build_spec_generator.cli_command_parser.maven_cli_parser.MavenCommaDelimList(long_name, short_name)

Bases: OptionDef[list[str]]

This option represents an option that takes a comma delimited value in Maven CLI command.

This option can be defined one time only and the value is stored as a string in argparse. However, it’s stored internally as list of strings obtained by splitting its original value in argparse using comma as the delimiter.

For example: “-P profile1,profile2,profile3” will be stored as [“profile1”, “profile2”, “profile3”]

A short form for the option is required.

short_name: str

is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[list[str]]

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name, short_name)

class macaron.build_spec_generator.cli_command_parser.maven_cli_parser.MavenSystemProperties(long_name, short_name)

Bases: OptionDef[dict[str, str | None]]

This option represents the -D/–define option of a Maven CLI command.

This option can be defined multiple times and the values are appended into a list of string in argparse. However, it’s stored internally as a dictionary mapping between the system property name to its value.

For example: -Dmaven.skip.test=true -Drat.skip=true will be stored as {"maven.skip.test": "true", "rat.skip": "true"}

A short form for the option is required.

short_name: str

is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[dict[str, str | None]]

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name, short_name)

class macaron.build_spec_generator.cli_command_parser.maven_cli_parser.MavenGoalPhase(long_name)

Bases: OptionDef[list[str]]

This option represents the positional goal/plugin-phase option in Maven CLI command.

argparse.Namespace stores this as a list of string. This is stored internally as a list of string.

is_valid_patch_option(patch)

Return True if the provided patch value is compatible with the internal type of this option.

Return type:: TypeGuard[list[str]]

add_to_arg_parser(arg_parse)

Add a new argument to argparser.ArgumentParser representing this option.

Return type:: None

get_patch_type_str()

Return the expected type for the patch value as string.

Return type:: str

__init__(long_name)

class macaron.build_spec_generator.cli_command_parser.maven_cli_parser.MavenCLICommandParser

Bases: object

A Maven CLI Command Parser.

ACCEPTABLE_EXECUTABLE = {'mvn', 'mvnw'}

__init__(): Initialize the instance.

is_build_tool(executable_path)

Return True if executable_path ends the accepted executable for this build tool.

Parameters:: executable_path (str) – The executable component of a CLI command.
Return type:: bool

validate_patch(patch)

Return True if the patch conforms to the expected format.

Return type:: bool

parse(cmd_list)

Parse the Maven CLI Command.

Parameters:: cmd_list (list[str]) – The Maven CLI Command as list of strings.
Returns:: The MavenCLICommand instance.
Return type:: MavenCLICommand
Raises:: MavenCLICommandParseError – If an error happens when parsing the Maven CLI Command.

apply_patch(cli_command, patch_options)

Patch the options of a Gradle CLI command, while persisting the executable path.

patch_options is a mapping with:

Key: the long name of a Maven CLI option as a string. For example: --define, --settings. For patching goals or plugin phases, use the key goals with the value being a list of strings.
Value: The value to patch. The type of this value depends on the type of option to be patched.

The types of patch values:

For optional flag (e.g -X/--debug) it is boolean. True to set it and False to unset it.
For -D/--define ONLY, it will be a mapping between the system property name and its value.
For options that expects a comma delimited list of string (e.g. -P/--activate-profiles and -pl/--projects), a list of string is expected.
For other value option (e.g -s/--settings), a string is expected.

None can be provided to any type of option to remove it from the original build command.

Parameters:

cli_command (MavenCLICommand) – The original Maven command, as a MavenCLICommand object from MavenCLICommand.parse(...)
patch_options (Mapping[str, MavenOptionPatchValueType | None]) – The patch values.

Returns:

The patched command as a new MavenCLICommand object.

Return type:

MavenCLICommand

Raises:

PatchBuildCommandError – If an error happens during the patching process.

apply_option_patch(maven_cli_options, patch)

Patch the Maven CLI Options and return a new copy.

Parameters:

maven_cli_options (MavenCLIOptions) – The Maven CLI Options to patch.
patch (Mapping[str, PatchValueType | None]) – A mapping between the name of the attribute in MavenCLIOptions and its patch value. The value can be None to disable an option.

Returns:

The new patched maven cli options.

Return type:

MavenCLIOptions

Raises:

PatchBuildCommandError – If an error happens during the patching process.

macaron.build_spec_generator.cli_command_parser.unparsed_cli_command module

This module contains the class definition for a CLICommand that we don’t support parsing for it.

class macaron.build_spec_generator.cli_command_parser.unparsed_cli_command.UnparsedCLICommand(original_cmds)

Bases: object

This class represents a CLICommand that we support the parsing of.

It is stored in its original form.

original_cmds: list[str]

to_cmds()

Return the CLI Command as a list of strings.

Return type:: list[str]

__init__(original_cmds)