chore: misc fixes

Signed-off-by: Ben Selwyn-Smith <[email protected]>

Author: benmss

src/macaron/build_spec_generator/build_command_patcher.py

@@ -99,10 +99,10 @@ def patch_commands(
 
     For each command in this command sequence:
 
-    - If the command is not a build command or the build tool is not supported by us, it will be leave intact.
+    - If the command is not a build command, or it's a tool we do not support, it will be left intact.
 
-    - If the command is a build command supported by us, it will be patch if a patch value is provided to ``patches``.
-      If no patch value is provided for a build command, it will be leave intact.
+    - If the command is a build command we support, it will be patched, if a patch value is provided in ``patches``.
+      If no patch value is provided for a build command, it will be left intact.
 
     `patches` is a mapping with:
 
@@ -113,7 +113,7 @@ def patch_commands(
       For example: :class:`macaron.cli_command_parser.maven_cli_parser.MavenCLICommandParser.apply_patch`,
       :class:`macaron.cli_command_parser.gradle_cli_parser.GradleCLICommandParser.apply_patch`.
 
-    This means that all commands that matches a BuildTool will be apply by the same patch value.
+    This means that all commands that match a BuildTool will be applied by the same patch value.
 
     Returns
     -------

src/macaron/build_spec_generator/build_spec_generator.py

@@ -20,7 +20,7 @@
 
 
 class BuildSpecFormat(str, Enum):
-    """The build spec format that we supports."""
+    """The build spec formats that we support."""
 
     REPRODUCIBLE_CENTRAL = "rc-buildspec"
 
@@ -87,7 +87,7 @@ def gen_build_spec_for_purl(
     int
         The exit code for this function. ``os.EX_OK`` if everything is fine, ``os.EX_OSERR`` if the
         buildspec file cannot be created in the local filesystem, ``os.EX_DATAERR`` if there was an
-        error in generate the content for the buildspec file.
+        error generating the content for the buildspec file.
     """
     db_engine = create_engine(f"sqlite+pysqlite:///{database_path}", echo=False)
 
@@ -102,7 +102,7 @@ def gen_build_spec_for_purl(
                 )
 
         if not build_spec_content:
-            logger.error("Error while generate reproducible central build spec.")
+            logger.error("Error while generating reproducible central build spec.")
             return os.EX_DATAERR
 
         logger.debug("Build spec content: \n%s", build_spec_content)
@@ -133,7 +133,7 @@ def gen_build_spec_for_purl(
                 file.write(build_spec_content)
         except OSError as error:
             logger.error(
-                "Could not generate the Buildspec to %s. Error: %s",
+                "Could not create the build spec at %s. Error: %s",
                 os.path.relpath(build_spec_filepath, os.getcwd()),
                 error,
             )

src/macaron/build_spec_generator/cli_command_parser/__init__.py

@@ -17,7 +17,7 @@ def is_list_of_strs(value: Any) -> TypeGuard[list[str]]:
 
 
 def is_dict_of_str_to_str_or_none(value: Any) -> TypeGuard[dict[str, str | None]]:
-    """Type guard for a dictionary with keys are string and values are strings or None."""
+    """Type guard for a dictionary where the keys are string and values are strings or None."""
     if not isinstance(value, dict):
         return False
 
@@ -37,7 +37,7 @@ def patch_mapping(
 ) -> dict[str, str]:
     """Patch a mapping.
 
-    A key with value in patch set to None will be removed from the original.
+    A key with a value in the patch set to None will be removed from the original.
 
     Parameters
     ----------
@@ -79,7 +79,7 @@ class OptionDef(Generic[P]):
 
     @abstractmethod
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[P]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         raise NotImplementedError()
 
     @abstractmethod
@@ -162,4 +162,4 @@ def apply_patch(
         cli_command: T,
         options_patch: Mapping[str, Y_contra | None],
     ) -> T:
-        """Return the a new CLICommand object with its option patched, while persisting the executable path."""
+        """Return a new CLICommand object with its option patched, while persisting the executable path."""

src/macaron/build_spec_generator/cli_command_parser/gradle_cli_command.py

@@ -139,17 +139,17 @@ def from_parsed_arg(
     def parse_properties(props: list[str]) -> dict[str, str]:
         """Return a dictionary that maps between a property and its value.
 
-        Each property definition value in `props` can have either of these format:
+        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 is of type string.
+        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 properties definition provided in the cli command.
+            The list of property definitions provided in the cli command.
             This is the list parsed by argparse.
 
         Returns

src/macaron/build_spec_generator/cli_command_parser/gradle_cli_parser.py

@@ -47,7 +47,7 @@ class GradleOptionalFlag(OptionDef[bool]):
     dest: str | None = field(default=None)
 
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[bool]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         return isinstance(patch, bool)
 
     def add_itself_to_arg_parser(self, arg_parse: argparse.ArgumentParser) -> None:
@@ -76,7 +76,7 @@ def get_patch_type_str(self) -> str:
 
 @dataclass
 class GradleOptionalNegateableFlag(OptionDef[bool]):
-    """This option represents an optional negateable flag in Gradle CLI command.
+    """This option represents an optional negatable flag in Gradle CLI command.
 
     For example: --build-cache/--no-build-cache
     """
@@ -119,12 +119,12 @@ def get_patch_type_str(self) -> str:
 
 @dataclass
 class GradleSingleValue(OptionDef[str]):
-    """This option represents an option that takes a value in Grale CLI command."""
+    """This option represents an option that takes a value in Gradle CLI command."""
 
     short_name: str | None
 
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[str]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         return isinstance(patch, str)
 
     def add_itself_to_arg_parser(self, arg_parse: argparse.ArgumentParser) -> None:
@@ -145,10 +145,10 @@ def get_patch_type_str(self) -> str:
 
 @dataclass
 class GradlePropeties(OptionDef[dict[str, str | None]]):
-    """This option represents an option used to define properties values of a Gradle CLI command.
+    """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 to its value.
+    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
@@ -158,7 +158,7 @@ class GradlePropeties(OptionDef[dict[str, str | None]]):
     short_name: str
 
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[dict[str, str | None]]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         return is_dict_of_str_to_str_or_none(patch)
 
     def add_itself_to_arg_parser(self, arg_parse: argparse.ArgumentParser) -> None:
@@ -181,7 +181,7 @@ class GradleTask(OptionDef[list[str]]):
     """
 
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[list[str]]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         return is_list_of_strs(patch)
 
     def add_itself_to_arg_parser(self, arg_parse: argparse.ArgumentParser) -> None:
@@ -199,16 +199,17 @@ def get_patch_type_str(self) -> str:
 
 @dataclass
 class GradleAppendedList(OptionDef[list[str]]):
-    """This option represents an option that can be specify multiple times and they all appended to a list.
+    """This option represents an option that can be specified multiple times.
 
-    For example, one can exclude multiple tasks with
-        gradle <task_to_run> --exclude-task taskA --exclude-task taskB
+    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
 
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[list[str]]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         return is_list_of_strs(patch)
 
     def add_itself_to_arg_parser(self, arg_parse: argparse.ArgumentParser) -> None:
@@ -223,7 +224,7 @@ def get_patch_type_str(self) -> str:
         return "list[str]"
 
 
-# TODO: some value option only allows you to provide certain values
+# TODO: some value options only allow you to provide certain values.
 # For example: --console allows "plain", "auto", "rich" or "verbose".
 # They are right now not enforced. We need to think whether we want to enforce them.
 GRADLE_OPTION_DEF: list[OptionDef] = [
@@ -368,7 +369,7 @@ def get_patch_type_str(self) -> str:
         short_name="-x",
         long_name="--exclude-task",
     ),
-    # TODO: determine which of these options can be provided multiple times
+    # TODO: determine which of these options can be provided multiple times.
     GradleSingleValue(
         short_name="-b",
         long_name="--build-file",
@@ -583,7 +584,7 @@ def apply_patch(
 
         `options_patch` is a mapping with:
 
-        - **Key**: the long name of an Gradle CLI option as string. For example: ``--continue``, ``--build-cache``.
+        - **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
@@ -660,7 +661,7 @@ def apply_option_patch(
         if not self.validate_patch(patch):
             raise PatchBuildCommandError("The patch is invalid.")
 
-        # Copy the Maven CLI Options for patching
+        # Copy the Maven CLI Options for patching.
         new_gradle_cli_options = deepcopy(gradle_cli_options)
 
         for option_long_name, patch_value in patch.items():

src/macaron/build_spec_generator/cli_command_parser/maven_cli_command.py

@@ -60,7 +60,7 @@ def from_parsed_arg(
         cls,
         parsed_arg: argparse.Namespace,
     ) -> "MavenCLIOptions":
-        """Initialize the instance from the the argparse.Namespace object.
+        """Initialize the instance from the argparse.Namespace object.
 
         Parameters
         ----------
@@ -142,8 +142,8 @@ def parse_system_properties(props: list[str]) -> dict[str, str]:
         system_props = {}
         for ele in props:
             prop_name, _, prop_val = ele.partition("=")
-            # Allow the subsequent definition override the previous one.
-            # This follows the way Maven is resolving system property.
+            # Allow subsequent definitions to override previous ones.
+            # This follows the way Maven resolves system properties.
             # For example:
             #   mvn help:evaluate -Da=foo -Da=bar -Dexpression=a -q -DforceStdout
             # => result for `a` is bar

src/macaron/build_spec_generator/cli_command_parser/maven_cli_parser.py

@@ -33,7 +33,7 @@ class MavenOptionalFlag(OptionDef[bool]):
 
     For example: --debug/-X
 
-    A short form for the option is rquired.
+    A short form for the option is required.
     """
 
     short_name: str
@@ -43,7 +43,7 @@ class MavenOptionalFlag(OptionDef[bool]):
     dest: str | None = field(default=None)
 
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[bool]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         return isinstance(patch, bool)
 
     def add_itself_to_arg_parser(self, arg_parse: argparse.ArgumentParser) -> None:
@@ -77,7 +77,7 @@ class MavenSingleValue(OptionDef[str]):
     short_name: str
 
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[str]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         return isinstance(patch, str)
 
     def add_itself_to_arg_parser(self, arg_parse: argparse.ArgumentParser) -> None:
@@ -96,19 +96,19 @@ class MavenCommaDelimList(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 spliting its original value 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 store as ["profile1", "profile2", "profile3"]
+    will be stored as ["profile1", "profile2", "profile3"]
 
     A short form for the option is required.
     """
 
     short_name: str
 
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[list[str]]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         return is_list_of_strs(patch)
 
     def add_itself_to_arg_parser(self, arg_parse: argparse.ArgumentParser) -> None:
@@ -138,7 +138,7 @@ class MavenSystemPropeties(OptionDef[dict[str, str | None]]):
     short_name: str
 
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[dict[str, str | None]]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         return is_dict_of_str_to_str_or_none(patch)
 
     def add_itself_to_arg_parser(self, arg_parse: argparse.ArgumentParser) -> None:
@@ -161,7 +161,7 @@ class MavenGoalPhase(OptionDef[list[str]]):
     """
 
     def is_valid_patch_option(self, patch: Any) -> TypeGuard[list[str]]:
-        """Return True if the provide patch value is compatible with the internal type of this option."""
+        """Return True if the provided patch value is compatible with the internal type of this option."""
         return is_list_of_strs(patch)
 
     def add_itself_to_arg_parser(self, arg_parse: argparse.ArgumentParser) -> None:
@@ -280,7 +280,7 @@ def get_patch_type_str(self) -> str:
         long_name="goals",
     ),
     # TODO: we need to confirm whether one can provide
-    # -P or -pl multiple times and the values will be aggregate into a list of string
+    # -P or -pl multiple times and the values will be aggregate into a list of string.
     # The current implementation only consider one instance of -P or -pl.
     # Where to begin:
     # https://github.com/apache/maven/blob/maven-3.9.x/maven-embedder/src/main/java/org/apache/maven/cli/CLIManager.java
@@ -360,7 +360,7 @@ def __init__(self) -> None:
             exit_on_error=False,
         )
 
-        # A mapping between the long name to its option definition.
+        # A mapping between the long name and its option definition.
         self.option_defs: dict[str, OptionDef] = {}
 
         for opt_def in MAVEN_OPTION_DEF:
@@ -452,7 +452,7 @@ def parse(self, cmd_list: list[str]) -> "MavenCLICommand":
             #   mvn --help
             #   mvn --version
             # Note that we don't allow mvn -V or mvn --show-version as this command will
-            #   failed for mvn
+            #   fail for mvn.
             if not parsed_opts.help_ and not parsed_opts.version:
                 raise CommandLineParseError(f"No goal detected for {' '.join(options)}.")
 
@@ -491,10 +491,9 @@ def apply_patch(
         `options_patch` 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 value being a list of string.
+          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 you want to
-          patch.
+        - **Value**: The value to patch. The type of this value depends on the type of option to be patched.
 
         The types of patch values:
 

src/macaron/build_spec_generator/cli_command_parser/unparsed_cli_command.py

@@ -8,9 +8,9 @@
 
 @dataclass
 class UnparsedCLICommand:
-    """This class represents a CLICommand that we don't support parsing.
+    """This class represents a CLICommand that we support the parsing of.
 
-    Therefore, it only stores the original command as is.
+    It is stored in its original form.
     """
 
     original_cmds: list[str]