album-solution-api 0.7.2__tar.gz → 0.7.3__tar.gz

{album_solution_api-0.7.2 → album_solution_api-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: album-solution-api
-Version: 0.7.2
+Version: 0.7.3
 Summary: Album is a framework for unifying computational tools across frameworks, languages, and environments.
 Author-email: Jan Philipp Albrecht <album@jpalbrecht.de>, Kyle Harrington <album@kyleharrington.com>, Deborah Schmidt <mail@frauzufall.de>
 Maintainer-email: Jan Philipp Albrecht <album@jpalbrecht.de>, Kyle Harrington <album@kyleharrington.com>, Deborah Schmidt <mail@frauzufall.de>
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Utilities
 Requires-Python: >=3.6

{album_solution_api-0.7.2 → album_solution_api-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "album-solution-api"
-version = "0.7.2"
+version = "0.7.3"
 authors = [
     {name = "Jan Philipp Albrecht", email = "album@jpalbrecht.de"},
     {name = "Kyle Harrington", email = "album@kyleharrington.com"},
@@ -33,6 +33,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: Implementation :: PyPy",
     "Topic :: Utilities"
 ]

{album_solution_api-0.7.2 → album_solution_api-0.7.3}/src/album/runner/api.py

@@ -1,10 +1,11 @@
 """This module provides the API for the album runner."""
+import hashlib
 import json
 import os
 import sys
 import tarfile
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Tuple, Union
 from urllib.request import urlretrieve
 
 from album.runner.album_logging import configure_logging, get_active_logger, to_loglevel
@@ -17,6 +18,8 @@ from album.runner.core.model.solution_script import SolutionScript
 def download_if_not_exists(url, file_name):
     """Download resource if not already cached and returns local resource path.
 
+    Its content is not checked, download_verified checks it against a known hash.
+
     Args:
         url: The URL of the download.
         file_name: The local filename of the download.
@@ -40,6 +43,76 @@ def download_if_not_exists(url, file_name):
     return download_path
 
 
+def download_verified(url: str, file_name: Union[str, Path], known_hash: str) -> Path:
+    """Download a file into the cache of the solution if it is not there, and check its content.
+
+    The content has to have the hash known_hash, written as in the resource file of a solution:
+    ``"sha256:<hex digest>"``, another algorithm of hashlib instead of sha256 (e.g. ``"md5:<hex digest>"``), or the
+    hex digest alone for sha256. A file in the cache with another content is downloaded again; a download with
+    another content is removed.
+
+    Args:
+        url: The URL of the download.
+        file_name: The local filename of the download, in the cache of the solution.
+        known_hash: The hash of the content.
+
+    Returns: The path to the file.
+
+    Raises:
+        ValueError: If known_hash names an algorithm hashlib does not know, or the download has another hash.
+
+    """
+    algorithm, digest = _split_hash(known_hash)
+    download_path = get_cache_path().joinpath(file_name)
+
+    if download_path.exists():
+        if _file_hash(download_path, algorithm) == digest:
+            get_active_logger().info(f"Found cache of {url}: {download_path}...")
+            return download_path
+        get_active_logger().info(
+            f"The cache of {url} has another content: {download_path}..."
+        )
+    download_path.parent.mkdir(parents=True, exist_ok=True)
+
+    get_active_logger().info(f"Downloading {url} to {download_path}...")
+
+    # downloaded next to the file, which it replaces only with the right content
+    part_path = download_path.with_name(download_path.name + ".part")
+    try:
+        urlretrieve(url, part_path)
+        download_hash = _file_hash(part_path, algorithm)
+        if download_hash == digest:
+            os.replace(part_path, download_path)
+            return download_path
+    finally:
+        if part_path.exists():
+            part_path.unlink()
+    raise ValueError(
+        f"The download of {url} has the {algorithm} hash {download_hash}, not {digest}."
+    )
+
+
+def _split_hash(known_hash: str) -> Tuple[str, str]:
+    """Return the algorithm and the hex digest of a hash, sha256 if it names no algorithm."""
+    algorithm, _, digest = known_hash.rpartition(":")
+    algorithm = (algorithm or "sha256").lower()
+    # a shake algorithm needs the length of its digest
+    if algorithm not in hashlib.algorithms_guaranteed or algorithm.startswith("shake_"):
+        raise ValueError(
+            f'The hash "{known_hash}" names an algorithm hashlib does not know.'
+        )
+    return algorithm, digest.lower()
+
+
+def _file_hash(path: Path, algorithm: str) -> str:
+    """Return the hex digest of the content of a file."""
+    file_hash = hashlib.new(algorithm)
+    with open(path, "rb") as file:
+        for chunk in iter(lambda: file.read(1024 * 1024), b""):
+            file_hash.update(chunk)
+    return file_hash.hexdigest()
+
+
 def extract_tar(in_tar, out_dir):
     """Extract a TAR file to a directory.
 
@@ -103,11 +176,14 @@ def get_cache_path() -> Path:
 
 
 def get_resources_dict(os_specific: bool = False) -> Dict[str, Any]:
-    """Return the resource files from a json as a dictionary and adds the download paths to the dictionary.
+    """Return the resources of the solution, as declared in its resource file, with the path of each file.
+
+    The dictionary has the form ``{"resources": {<key>: {"name": ..., "path": ..., ...}}}``. A resource
+    meant for another OS is not downloaded, its path is None.
 
     Args:
-        os_specific: If True, all resources are returned, otherwise only the installed resources
-        meant for the current OS are returned.
+        os_specific: If True, only the resources meant for the current OS are returned, otherwise all
+        resources are returned.
     """
     resources_dict = {}
     active_solution = get_active_solution()

{album_solution_api-0.7.2 → album_solution_api-0.7.3}/src/album/runner/core/model/solution_script.py

@@ -33,9 +33,24 @@ class SolutionScript:
         SolutionScript.api_access(solution, package_path, installation_base_path, environment_path)
         parser = None
         if solution.setup().args:
-            append_arguments = (goal == Solution.Action.RUN) or (goal == Solution.Action.TEST)
-            if append_arguments:
+            if goal == Solution.Action.RUN:
                 parser = SolutionScript.append_arguments(solution)
+            elif goal == Solution.Action.TEST:
+                # For the test goal the arguments come from the command line and from
+                # pre_test(), which has not run at this point. Enforcing `required` here
+                # made argparse exit with "the following arguments are required: ..." for
+                # every solution that marks an argument required -- before pre_test() had
+                # any chance to provide it. Solutions worked around this by declaring
+                # required=False and writing "(required)" into the description, which hid
+                # the requirement from every consumer of the metadata. So parse the command
+                # line without enforcing `required`: pre_test() can read get_args() and
+                # adapt what the caller passed, and an invalid command line still fails
+                # before pre_test() runs. The parse that enforces `required` happens below,
+                # after pre_test()'s values are on the command line.
+                parser = SolutionScript.build_parser(solution)
+                if parser is not None:
+                    lenient_parser = SolutionScript.build_parser(solution, enforce_required=False)
+                    solution.set_args(lenient_parser.parse_args())
         if goal == Solution.Action.INSTALL:
             solution.setup().install()
         if goal == Solution.Action.UNINSTALL:
@@ -51,8 +66,10 @@ class SolutionScript:
                 d = {}
             sys.argv = sys.argv + ["=".join([c, d[c]]) for c in d]
 
-            # parse args again after pre_test() routine if necessary.
-            if parser and "args" in solution.setup().keys():
+            # The parse that counts for the test goal: pre_test()'s arguments now follow
+            # the caller's, so they win, and a required argument pre_test() supplies is
+            # satisfied rather than fatal.
+            if parser is not None:
                 args = parser.parse_args()
                 solution.set_args(args)
 
@@ -111,16 +128,32 @@ class SolutionScript:
             raise ArgumentError(argument=args, message=message)
 
     @staticmethod
-    def _handle_args_list(solution: ISolution):
+    def build_parser(solution: ISolution, enforce_required=True):
+        """The argument parser for a solution's declared arguments, built but not yet parsed.
+
+        Returns None when the solution declares its arguments as a string ('pass-through'),
+        which is validated the same way append_arguments() validates it. Separated from the
+        parse so that the test goal can enforce required arguments only after pre_test() has
+        run. With enforce_required=False, no argument is marked required: the test goal parses
+        the command line that way for pre_test(), which may still supply them.
+        """
+        if isinstance(solution.setup().args, str):
+            SolutionScript._handle_args_string(solution.setup().args)
+            return None
         parser = argparse.ArgumentParser(description='album run %s' % solution.setup().name)
         for arg in solution.setup().args:
-            SolutionScript._add_parser_argument(solution, parser, arg)
+            SolutionScript._add_parser_argument(solution, parser, arg, enforce_required)
+        return parser
+
+    @staticmethod
+    def _handle_args_list(solution: ISolution):
+        parser = SolutionScript.build_parser(solution)
         args = parser.parse_args()
         solution.set_args(args)
         return parser
 
     @staticmethod
-    def _add_parser_argument(solution, parser, arg):
+    def _add_parser_argument(solution, parser, arg, enforce_required=True):
         keys = arg.keys()
 
         if 'default' in keys and 'action' in keys:
@@ -135,8 +168,8 @@ class SolutionScript:
         if 'description' in keys:
             args['help'] = arg['description']
         if 'type' in keys:
-            args['type'] = SolutionScript._parse_type(arg['type'])
-        if 'required' in keys:
+            args['type'] = SolutionScript._parse_type(arg['type'], arg['name'])
+        if 'required' in keys and enforce_required:
             args['required'] = arg['required']
         parser.add_argument('--%s' % arg['name'], **args)
 
@@ -156,16 +189,22 @@ class SolutionScript:
             raise ValueError("invalid truth value %r" % (val,))
 
     @staticmethod
-    def _parse_type(type_str):
-        if type_str == 'string':
+    def _parse_type(type_str, arg_name):
+        # str, int and bool are the Python names of string, integer and boolean
+        if type_str in ('string', 'str'):
             return str
         if type_str == 'file':
             return Path
         if type_str == 'directory':
             return Path
-        if type_str == 'integer':
+        if type_str in ('integer', 'int'):
             return int
         if type_str == 'float':
             return float
-        if type_str == 'boolean':
+        if type_str in ('boolean', 'bool'):
             return SolutionScript.strtobool
+        # without a type function argparse would pass the value on as text
+        raise ValueError(
+            'The argument %s has the unknown type %r. Known types are str, int, float, bool, file and directory, '
+            'and string, integer and boolean.' % (arg_name, type_str)
+        )

{album_solution_api-0.7.2 → album_solution_api-0.7.3}/src/album/runner/core/schema/solution_schema.json

@@ -64,7 +64,7 @@
                 "type": {
                     "title": "type",
                     "type": "string",
-                    "enum": ["string", "file", "directory", "boolean", "integer", "float"]
+                    "enum": ["string", "file", "directory", "boolean", "integer", "float", "str", "bool", "int"]
                 },
                 "default": {
                     "title": "default"

{album_solution_api-0.7.2 → album_solution_api-0.7.3}/src/album_solution_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: album-solution-api
-Version: 0.7.2
+Version: 0.7.3
 Summary: Album is a framework for unifying computational tools across frameworks, languages, and environments.
 Author-email: Jan Philipp Albrecht <album@jpalbrecht.de>, Kyle Harrington <album@kyleharrington.com>, Deborah Schmidt <mail@frauzufall.de>
 Maintainer-email: Jan Philipp Albrecht <album@jpalbrecht.de>, Kyle Harrington <album@kyleharrington.com>, Deborah Schmidt <mail@frauzufall.de>
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Utilities
 Requires-Python: >=3.6