Allow the libraries input to take YAML-format lists of dependencies

As more library sources are added, it will be necessary to use data structures to fully define the dependencies. Since the workflow is already written in YAML, it makes sense to use it for this purpose as well.

Support for the old space-separated list format is retained, with the identical behavior, for backwards compatibility.

Author: per1234

README.md

@@ -18,7 +18,18 @@ For 3rd party boards, also specify the Boards Manager URL:
 
 ### `libraries`
 
-List of library dependencies to install (space separated). Default `""`.
+YAML-format list of library dependencies to install.
+
+Note: the original space-separated list format is also supported. When this syntax is used, the repository under test will always be installed as a library.
+
+#### Sources:
+
+##### Library Manager
+
+Keys:
+- `name` - name of the library.
+- `version` - version of the library to install. Default is the latest version.
+
 
 ### `sketch-paths`
 
@@ -106,6 +117,10 @@ Only compiling examples:
 - uses: arduino/actions/libraries/compile-examples@master
   with:
     fqbn: 'arduino:avr:uno'
+    libraries: |
+      - name: Servo
+      - name: Stepper
+        version: 1.1.3
 ```
 
 Storing the memory usage change report as a [workflow artifact](https://help.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts):

action.yml

@@ -8,8 +8,8 @@ inputs:
     description: 'Full qualified board name, with Boards Manager URL if needed'
     default: 'arduino:avr:uno'
   libraries:
-    description: 'List of library dependencies to install (space separated)'
     default: ''
+    description: 'YAML-format list of library dependencies to install'
   sketch-paths:
     description: 'List of paths containing sketches to compile.'
     default: 'examples'

compilesketches/compilesketches.py

@@ -14,6 +14,8 @@
 
 import git
 import github
+import yaml
+import yaml.parser
 
 import reportsizetrends
 
@@ -84,6 +86,11 @@ class RunCommandOutput(enum.Enum):
     report_previous_ram_key = "previous_ram"
     report_ram_delta_key = "ram_delta"
 
+    dependency_name_key = "name"
+    dependency_version_key = "version"
+
+    latest_release_indicator = "latest"
+
     def __init__(self, cli_version, fqbn_arg, libraries, sketch_paths, verbose, github_token, report_sketch,
                  enable_size_deltas_report, sketches_report_path, enable_size_trends_report, google_key_file,
                  size_trends_report_spreadsheet_id, size_trends_report_sheet_name):
@@ -225,6 +232,25 @@ def install_platforms(self):
         self.install_platforms_from_board_manager(platform_list=[fqbn_platform_name],
                                                   additional_url_list=additional_url_list)
 
+    def sort_dependency_list(self, dependency_list):
+        """Sort a list of sketch dependencies by source type
+
+        Keyword arguments:
+        dependency_list -- a list of dictionaries defining dependencies
+        """
+        sorted_dependencies = self.Dependencies()
+        for dependency in dependency_list:
+            if dependency is not None:
+                sorted_dependencies.manager.append(dependency)
+
+        return sorted_dependencies
+
+    class Dependencies:
+        """Container for sorted sketch dependencies"""
+
+        def __init__(self):
+            self.manager = []
+
     def install_platforms_from_board_manager(self, platform_list, additional_url_list):
         """Install platform dependencies from the Arduino Board Manager
 
@@ -250,6 +276,20 @@ def install_platforms_from_board_manager(self, platform_list, additional_url_lis
         # Install the platforms
         self.run_arduino_cli_command(command=core_install_command, enable_output=self.get_run_command_output_level())
 
+    def get_manager_dependency_name(self, dependency):
+        """Return the appropriate name value for a repository dependency
+
+        Keyword arguments:
+        dependency -- dictionary defining the Library/Board Manger dependency
+        """
+        name = dependency[self.dependency_name_key]
+        if self.dependency_version_key in dependency:
+            # If "latest" special version name is used, just don't add a version to cause LM to use the latest release
+            if dependency[self.dependency_version_key] != self.latest_release_indicator:
+                name = name + "@" + dependency[self.dependency_version_key]
+
+        return name
+
     def get_run_command_output_level(self):
         """Determine and return the appropriate output setting for the run_command function."""
         if self.verbose:
@@ -316,23 +356,38 @@ def install_libraries(self):
         """Install Arduino libraries."""
         self.libraries_path.mkdir(parents=True, exist_ok=True)
 
-        libraries_list = parse_list_input(self.libraries)
-        if len(libraries_list) > 0:
-            self.install_libraries_from_library_manager(library_name_list=libraries_list)
+        libraries = yaml.load(stream="", Loader=yaml.SafeLoader)
+        try:
+            libraries = yaml.load(stream=self.libraries, Loader=yaml.SafeLoader)
+        except yaml.parser.ParserError:
+            # This exception occurs when the space separated list items are individually quoted (e.g., '"Foo" "Bar"')
+            pass
+
+        library_list = self.Dependencies()
+        if type(libraries) is list:
+            # libraries input is YAML
+            library_list = self.sort_dependency_list(libraries)
+        else:
+            # libraries input uses the old space-separated list syntax
+            library_list.manager = [{self.dependency_name_key: library_name}
+                                    for library_name in parse_list_input(self.libraries)]
+
+        if len(library_list.manager) > 0:
+            self.install_libraries_from_library_manager(library_list=library_list.manager)
 
         # TODO: this is in anticipation of allowing arbitrary paths to be specified by the user, rather than assuming
         #       there is a library in the root of the repo (not the case when testing platforms and sketches)
         # Install the repository as a library by creating a symlink in the sketchbook
         self.install_libraries_from_path(library_path_list=[pathlib.Path(os.environ["GITHUB_WORKSPACE"])])
 
-    def install_libraries_from_library_manager(self, library_name_list):
+    def install_libraries_from_library_manager(self, library_list):
         """Install libraries using the Arduino Library Manager
 
         Keyword arguments:
-        library_name_list -- list of library names
+        library_list -- list of dictionaries defining the dependencies
         """
         lib_install_command = ["lib", "install"]
-        lib_install_command.extend(library_name_list)
+        lib_install_command.extend([self.get_manager_dependency_name(library) for library in library_list])
         self.run_arduino_cli_command(command=lib_install_command, enable_output=self.get_run_command_output_level())
 
     def install_libraries_from_path(self, library_path_list):

compilesketches/requirements.txt

@@ -2,3 +2,4 @@ gitpython==3.1.1
 PyGithub==1.47
 pytest==5.4.1
 pytest-mock==3.1.0
+pyyaml==5.3.1

compilesketches/tests/test_compilesketches.py

@@ -305,6 +305,21 @@ def test_install_platforms(mocker, fqbn_arg, expected_platform, expected_additio
     )
 
 
+@pytest.mark.parametrize(
+    "dependency_list, expected_dependency_type_list",
+    [([None], []),
+     ([{compilesketches.CompileSketches.dependency_name_key: "FooBar"}], ["manager"])]
+)
+def test_sort_dependency_list(monkeypatch, dependency_list, expected_dependency_type_list):
+    monkeypatch.setenv("GITHUB_WORKSPACE", "/foo/GitHubWorkspace")
+
+    compile_sketches = get_compilesketches_object()
+
+    for dependency, expected_dependency_type in zip(dependency_list, expected_dependency_type_list):
+        assert dependency in getattr(compile_sketches.sort_dependency_list(dependency_list=[dependency]),
+                                     expected_dependency_type)
+
+
 @pytest.mark.parametrize("additional_url_list",
                          [["https://example.com/package_foo_index.json", "https://example.com/package_bar_index.json"],
                           []])
@@ -427,11 +442,35 @@ class CommandData:
     subprocess.run.assert_called_once_with(command, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
 
 
-@pytest.mark.parametrize("libraries", ['"foo" "bar"', ""])
-def test_install_libraries(monkeypatch, mocker, libraries):
-    monkeypatch.setenv("GITHUB_WORKSPACE", "/foo/bar")
+@pytest.mark.parametrize(
+    "dependency, expected_name",
+    [({compilesketches.CompileSketches.dependency_name_key: "Foo",
+       compilesketches.CompileSketches.dependency_version_key: "1.2.3"}, "[email protected]"),
+     ({compilesketches.CompileSketches.dependency_name_key: "Foo",
+       compilesketches.CompileSketches.dependency_version_key: "latest"}, "Foo"),
+     ({compilesketches.CompileSketches.dependency_name_key: "[email protected]"}, "[email protected]"),
+     ({compilesketches.CompileSketches.dependency_name_key: "Foo"}, "Foo")])
+def test_get_manager_dependency_name(dependency, expected_name):
+    compile_sketches = get_compilesketches_object()
+    assert compile_sketches.get_manager_dependency_name(dependency=dependency) == expected_name
+
+
+@pytest.mark.parametrize("libraries, expected_manager",
+                         [("", []),
+                          ("foo bar", [{compilesketches.CompileSketches.dependency_name_key: "foo"},
+                                       {compilesketches.CompileSketches.dependency_name_key: "bar"}]),
+                          ("\"foo\" \"bar\"", [{compilesketches.CompileSketches.dependency_name_key: "foo"},
+                                               {compilesketches.CompileSketches.dependency_name_key: "bar"}]),
+                          ("-", []),
+                          ("- " + compilesketches.CompileSketches.dependency_name_key + ": foo",
+                           [{compilesketches.CompileSketches.dependency_name_key: "foo"}])])
+def test_install_libraries(monkeypatch, mocker, libraries, expected_manager):
+    libraries_path = pathlib.Path("/foo/LibrariesPath")
+
+    monkeypatch.setenv("GITHUB_WORKSPACE", "/foo/GitHubWorkspace")
 
     compile_sketches = get_compilesketches_object(libraries=libraries)
+    compile_sketches.libraries_path = libraries_path
 
     mocker.patch.object(pathlib.Path, "mkdir", autospec=True)
     mocker.patch("compilesketches.CompileSketches.install_libraries_from_library_manager", autospec=True)
@@ -440,35 +479,31 @@ def test_install_libraries(monkeypatch, mocker, libraries):
     compile_sketches.install_libraries()
 
     # noinspection PyUnresolvedReferences
-    pathlib.Path.mkdir.assert_called()
+    pathlib.Path.mkdir.assert_called_with(libraries_path, parents=True, exist_ok=True)
 
-    if len(compile_sketches.libraries) > 0:
+    if len(expected_manager) > 0:
         compile_sketches.install_libraries_from_library_manager.assert_called_once_with(
             compile_sketches,
-            library_name_list=compilesketches.parse_list_input(compile_sketches.libraries)
-        )
+            library_list=expected_manager)
     else:
         compile_sketches.install_libraries_from_library_manager.assert_not_called()
 
-    compile_sketches.install_libraries_from_path.assert_called_once_with(
-        compile_sketches,
-        library_path_list=[pathlib.Path(os.environ["GITHUB_WORKSPACE"])]
-    )
+    compile_sketches.install_libraries_from_path.assert_called_once()
 
 
 def test_install_libraries_from_library_manager(mocker):
     run_command_output_level = unittest.mock.sentinel.run_command_output_level
-    library_name_list = [unittest.mock.sentinel.library_name1, unittest.mock.sentinel.library_name2]
-
     compile_sketches = get_compilesketches_object()
 
+    library_list = [{compile_sketches.dependency_name_key: "foo"}, {compile_sketches.dependency_name_key: "bar"}]
+
     mocker.patch("compilesketches.CompileSketches.get_run_command_output_level", autospec=True,
                  return_value=run_command_output_level)
     mocker.patch("compilesketches.CompileSketches.run_arduino_cli_command", autospec=True)
 
-    compile_sketches.install_libraries_from_library_manager(library_name_list=library_name_list)
+    compile_sketches.install_libraries_from_library_manager(library_list=library_list)
 
-    lib_install_command = ["lib", "install"] + library_name_list
+    lib_install_command = ["lib", "install"] + [library["name"] for library in library_list]
     compile_sketches.run_arduino_cli_command.assert_called_once_with(compile_sketches,
                                                                      command=lib_install_command,
                                                                      enable_output=run_command_output_level)
@@ -1064,6 +1099,7 @@ def test_verbose_print(capsys, verbose):
 @pytest.mark.parametrize("list_argument, expected_list",
                          [("", []),
                           ("foobar", ["foobar"]),
+                          ("foo bar", ["foo", "bar"]),
                           ("\"foo bar\"", ["foo bar"]),
                           ("\'foo bar\'", ["foo bar"]),
                           ("\'\"foo bar\" \"baz\"\'", ["foo bar", "baz"]),