recp 0.1.1__py3-none-any.whl

recp/cli/main.py

@@ -0,0 +1,141 @@
+import os
+import sys
+import argparse
+from datetime import datetime
+from importlib.metadata import version
+from ..utils.recipe import Recipe
+from ..utils.config import PackageConfig
+
+
+def get_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="run command line tools recp",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        allow_abbrev=False
+    )
+    subparser = parser.add_subparsers(dest="action")
+
+    # Run parser
+    run_parser = subparser.add_parser(
+        "run",
+        description="run recipes in .yaml format",
+        help="run recipes in .yaml format",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        allow_abbrev=False
+    )
+    run_parser.add_argument(
+        "recipe",
+        type=str,
+        help="recipe .yaml file"
+    )
+    run_parser.add_argument(
+        "-t", "--tag",
+        nargs="*",
+        type=str,
+        help="include only steps matching a specific tag"
+    )
+    run_parser.add_argument(
+        "-d", "--dry-run",
+        action="store_true",
+        help="show the sequence of commands to be run without running them"
+    )
+    run_parser.add_argument(
+        "--ignore-errors",
+        action="store_true",
+        help="ignore and skip steps that resulted in errors"
+    )
+    run_parser.add_argument(
+        "--unsafe",
+        action="store_true",
+        help="enable unsafe !expr constructor in recipe files"
+    )
+
+    # Config parser
+    config_parser = subparser.add_parser(
+        "config", # Show available recipes too
+        description="configure recp",
+        help="configure recp",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+        allow_abbrev=False
+    )
+    config_parser_option_group = config_parser.add_mutually_exclusive_group()
+    config_parser_option_group.add_argument(
+        "--set",
+        type=str,
+        nargs=2,
+        help="set parameter",
+    )
+    config_parser_option_group.add_argument(
+        "--add",
+        type=str,
+        help="add a recipe",
+    )
+    return parser
+
+
+def main() -> None:
+    # Version print
+    if (
+        len(sys.argv) == 1
+        or (len(sys.argv) == 2 and sys.argv[1] in ("-v", "--version"))
+    ):
+        print(
+            f"recp version {version('recp')} developed by Esteban Gómez 2025-"
+            f"{datetime.now().year} (Speech Interaction Technology, Aalto "
+            "University)"
+        )
+        sys.exit(0)
+    
+    # Parse args
+    parser = get_parser()
+    args = parser.parse_args()
+
+    match args.action:
+        case "config":
+            config = PackageConfig(app_name="recp", app_author="Esteban Gómez")
+
+            if args.set:
+                config.set_param(param=args.set[0], value=args.set[1])
+            
+            elif args.add:
+                config.add_recipe(args.add)
+
+            else:
+                config.print_params()
+        
+        case "run":
+            # Check if recipe is a preset
+            if not args.recipe.endswith(".yaml"):
+                config = PackageConfig(
+                    app_name="recp",
+                    app_author="Esteban Gómez"
+                )
+
+                if os.path.isfile(
+                    os.path.join(config.recipes_dir, args.recipe + ".yaml")
+                ):
+                    args.recipe = os.path.join(
+                        config.recipes_dir,
+                        args.recipe + ".yaml"
+                    )
+                
+                else:
+                    raise FileNotFoundError(
+                        f"Recipe {args.recipe!r} not found in recipes folder "
+                        f"{config.recipes_dir!r}"
+                    )
+
+            # Create and run recipe
+            recipe = Recipe(file=args.recipe, allow_expr=args.unsafe)
+            recipe.run(
+                tag=args.tag,
+                ignore_errors=args.ignore_errors,
+                dry_run=args.dry_run
+            )
+        
+        case _:
+            raise AssertionError
+
+
+if __name__ == "__main__":
+    main()

recp/utils/apply.py

@@ -0,0 +1,275 @@
+import os
+import random
+from datetime import datetime
+from typing import List
+from .io import get_dir_files
+from .exceptions import LenghtError
+
+
+def apply_date(
+        cmd_list: List[str],
+        token: str,
+        format: str = "%Y-%m-%d"
+) -> List[str]:
+    """Replaces a given token by a date.
+
+    Args:
+        cmd_list (List[str]): Input commands.
+        token (str): The token within the command strings to be replaced.
+        format (str): Date format to use.
+    
+    Returns:
+        List[str]: List of modified commands.
+    """
+    for cmd_idx, cmd in enumerate(cmd_list):
+        cmd_list[cmd_idx] = cmd.replace(token, datetime.now().strftime(format))
+    
+    return cmd_list
+
+
+def apply_dir_files(
+        cmd_list: List[str],
+        token: str,
+        dir: str,
+        ext: str | List[str] = "*",
+        recursive: bool = True
+) -> List[str]:
+    """Replaces a given token by the path to each file in a foleder.
+
+    Args:
+        cmd_list (List[str]): Input commands.
+        token (str): The token within the command strings to be replaced.
+        dir (str): Path to the folder to be searched.
+        ext (str | List[str]): The file extension(s) used to filter files. Only
+            files matching these extension(s) will be considered.
+        recursive (bool): If `True`, the search is done recursively. 
+    
+    Returns:
+        List[str]: List of modified commands.
+    """
+    for cmd in cmd_list:
+        files = get_dir_files(dir=dir, ext=ext, recursive=recursive)
+        cmd_expanded_list = []
+
+        for file in files:
+            cmd_expanded_list.append(cmd.replace(token, file))
+ 
+    return cmd_expanded_list
+
+
+def apply_index(
+        cmd_list: List[str],
+        token: str,
+        offset: int = 0,
+        zfill: int = 0
+) -> List[str]:
+    """Replaces a given token by the command index value.
+    
+    Args:
+        cmd_list (List[str]): Input commands.
+        token (str): Token to be replaced.
+        offset (int): Offset applied to all values.
+        zfill (int | None): Minimum width of the number, padded with leading
+            zeros if needed.
+    
+    Returns:
+        List[str]: List of modified commands.
+    """
+    for cmd_idx, cmd in enumerate(cmd_list):
+        cmd_list[cmd_idx] = cmd.replace(
+            token,
+            str(cmd_idx + offset).zfill(zfill)
+        )
+    
+    return cmd_list
+
+
+def apply_parent_dir(
+        cmd_list: List[str],
+        token: str,
+        path: str
+) -> List[str]:
+    """Replaces a given token by the parent path of a given path.
+
+    Args:
+        cmd_list (List[str]): Input commands.
+        token (str): The token within the command strings to be replaced.
+        path (str): The file system path from which the parent directory will
+            be extracted.
+    
+    Returns:
+        List[str]: List of modified commands.
+    """
+    for cmd_idx, cmd in enumerate(cmd_list):
+        cmd_list[cmd_idx] = cmd.replace(
+            token,
+            os.path.dirname(os.path.normpath(path))
+        )
+    
+    return cmd_list
+
+
+def apply_randchoice(
+        cmd_list: List[str],
+        token: str,
+        choices: List[str],
+        seed: int | None = None
+) -> List[str]:
+    """Replace a token by a random choice from a list of choices.
+    
+    Args:
+        cmd_list (List[str]): Input commands.
+        token (str): Token to be replaced.
+        choices (List[str]): List of choices.
+        seed (int | None): Random seed.
+    """
+    generator = random.Random(seed)
+
+    for cmd_idx, cmd in enumerate(cmd_list):
+        value = generator.choice(choices)
+        cmd_list[cmd_idx] = cmd.replace(token, str(value))
+    
+    return cmd_list
+
+
+def apply_randint(
+        cmd_list: List[str],
+        token: str,
+        min: int,
+        max: int,
+        seed: int | None = None
+) -> List[str]:
+    """Replace a token by a random integer number within a range, including
+    both `min` and `max` within this range.
+    
+    Args:
+        cmd_list (List[str]): Input commands.
+        token (str): Token to be replaced.
+        min (int): Minimum `int` value to be generated.
+        max (int): Maximum `int` value to be generated.
+        seed (int | None): Random seed.
+    """
+    generator = random.Random(seed)
+
+    for cmd_idx, cmd in enumerate(cmd_list):
+        value = generator.randint(min, max)
+        cmd_list[cmd_idx] = cmd.replace(token, str(value))
+    
+    return cmd_list
+
+
+def apply_randfloat(
+        cmd_list: List[str],
+        token: str,
+        min: float,
+        max: float,
+        seed: int | None = None
+) -> List[str]:
+    """Replace a token by a random floating-point number within the
+    `[min, max)` range.
+    
+    Args:
+        cmd_list (List[str]): Input commands.
+        token (str): Token to be replaced.
+        min (float): Minimum `float` value to be generated (inclusive).
+        max (float): Maximum `float` value to be generated (exclusive).
+        seed (int | None): Random seed.
+    """
+    generator = random.Random(seed)
+
+    for cmd_idx, cmd in enumerate(cmd_list):
+        value = generator.uniform(min, max)
+        cmd_list[cmd_idx] = cmd.replace(token, str(value))
+    
+    return cmd_list
+
+
+def apply_replace(cmd_list: List[str], **kwargs) -> List[str]:
+    """Replace placeholders by specified values.
+    
+    Args:
+        cmd_list (List[str]): Input commands.
+        **kwargs: Each subsequent argument corresponds to the value to be
+            replaced, and the value is the updated value it will take.
+    
+    Returns:
+        List[str]: List of modified commands.
+    """
+    for cmd_idx, cmd in enumerate(cmd_list):
+        for k, v in kwargs.items():
+            cmd = cmd.replace(k, v)
+        
+        cmd_list[cmd_idx] = cmd
+
+    return cmd_list
+
+
+def apply_repeat(cmd_list: List[str], n: int) -> List[str]:
+    """Repeat a command or command list `n` times.
+    
+    Args:
+        cmd_list (List[str]): Input commands.
+        n (int): Number of repetitions.
+    
+    Returns:
+        List[str]: List of modified commands.
+    """
+    return cmd_list * n
+
+
+def apply_match(
+        cmd_list: List[str],
+        var: str,
+        token: str,
+        choices: List[str],
+        values: List[str],
+) -> List[str]:
+    """Matches a variable value against multiple choices and replaces a token
+    in the command based on the matching value.
+
+    Args:
+        cmd_list (List[str]): Input commands.
+        var (str): Variable to match.
+        token (str): Token to replace.
+        choices (List[str]): Possible values for `var`.
+        values (List[str]): Values used to replace `token` based on the
+            matching value from `choices`.
+
+    Returns:
+        List[str]: List of modified commands.
+    """
+    # Assertions
+    if len(choices) != len(values):
+        raise LenghtError(
+            "case and value lists must have the same number of elements, but "
+            f"case has {len(choices)} elements and value has {len(values)} "
+            "elements"
+        )
+
+    # Turn into sets to filter out repeated values
+    choice = list(dict.fromkeys(choices))  # Preserves order
+    value = list(dict.fromkeys(values))
+
+    for cmd_idx, cmd in enumerate(cmd_list):
+        value_idx = choice.index(var)
+        cmd_list[cmd_idx] = cmd.replace(token, value[value_idx])
+    
+    return cmd_list
+
+
+def get_apply_registy() -> dict:
+    """Returns the registry of all functions that can be used withing the `run`
+    key of a recipe `.yaml` file.
+    """
+    return {
+        "date": apply_date,
+        "dir_files": apply_dir_files,
+        "index": apply_index,
+        "match": apply_match,
+        "parent_dir": apply_parent_dir,
+        "randchoice": apply_randchoice,
+        "randint": apply_randint,
+        "randfloat": apply_randfloat,
+        "replace": apply_replace,
+        "repeat": apply_repeat
+    }

recp/utils/collections.py

@@ -0,0 +1,43 @@
+import os
+from contextlib import contextmanager
+from typing import (
+    Any,
+    List
+)
+
+
+def make_list(x: Any) -> List[Any]:
+    """If `x` is a single element, turns it into a `list` of one element.
+
+    Args:
+        x (Any): Element(s) to be returned as a `list`.
+
+    Returns:
+        (list): `x` as a `list`.
+    """
+    return [x] if not isinstance(x, list) and x is not None else x
+
+
+@contextmanager
+def temp_env(merge: dict = {}):
+    """Temporarily modify the environment variables.
+
+    This context manager allows temporary modification of the
+    environment variables for the duration of the context. Once the
+    context is exited, the environment variables are restored to their
+    original state.
+
+    Args:
+        merge (dict): A dictionary of environment variables to be
+            temporarily added or updated. The keys are the variable
+            names and the values are their corresponding values.
+    """
+    old_env = os.environ.copy()
+    
+    try:
+        os.environ.update({k: str(v) for k, v in merge.items()})
+        yield
+    
+    finally:
+        os.environ.clear()
+        os.environ.update(old_env)

recp/utils/config.py

@@ -0,0 +1,114 @@
+import os
+import json
+import shutil
+from typing import Any
+from platformdirs import PlatformDirs
+from .exceptions import (
+    FileExtensionError,
+    FolderNotFoundError
+)
+
+
+class PackageConfig:
+    """Package configuration parameters.
+
+    Args:
+        app_name (str): Application name.
+        app_author (str): Application author name.
+    """
+    def __init__(
+            self,
+            app_name: str,
+            app_author: str
+    ) -> None:
+        super().__init__()
+
+        # Params
+        self._platform = PlatformDirs(appname=app_name, appauthor=app_author)
+        self.maybe_reset_default_config()
+        self.config_file = os.path.join(
+            self._platform.user_data_dir,
+            "settings.json"
+        )
+        
+        with open(self.config_file, "r") as f:
+            self.config = json.load(f)
+        
+    @property
+    def recipes_dir(self) -> str:
+        """Returns the folder where user recipes are stored.
+
+        Returns:
+            (str): Folder where user recipes are stored.
+        """
+        return self.config["recipes.dir"]
+
+    def maybe_reset_default_config(self) -> None:
+        """Restores the default package configuration if it does not exist."""
+        BASE_DIR = self._platform.user_data_dir
+        RECIPES_DIR = os.path.join(BASE_DIR, "recipes")
+        BASE_SETTINGS_FILE = os.path.join(BASE_DIR, "settings.json")
+        BASE_SETTINGS = {"recipes.dir": RECIPES_DIR}
+
+        os.makedirs(BASE_DIR, exist_ok=True)
+        os.makedirs(RECIPES_DIR, exist_ok=True)
+
+        if not os.path.isfile(BASE_SETTINGS_FILE):
+            with open(BASE_SETTINGS_FILE, "w") as f:
+                json.dump(obj=BASE_SETTINGS, fp=f, indent=2)
+    
+    def save_config(self) -> None:
+        """Saves the `settings.json` configuration file with the update
+        configuration parameters.
+        """
+        with open(self.config_file, "w", encoding="utf-8") as f:
+            json.dump(self.config, f)
+ 
+    def set_param(self, param: str, value: Any) -> None:
+        """Sets a parameter value in the user configuration file.
+        
+        Args:
+            param (str): Parameter name.
+            value (Any): Parameter value.
+        """
+        if param not in self.config:
+            raise ValueError(
+                f"Invalid parameter {param!r}. Run 'recp config' to list "
+                "existing parameters"
+            )
+        
+        match param:
+            case "recipes.dir":
+                if not os.path.isdir(value):
+                    raise FolderNotFoundError(f"Invalid folder {value!r}")
+                
+                self.config[param] = value
+            
+            case _:
+                raise AssertionError
+        
+        self.save_config()
+    
+    def add_recipe(self, file: str) -> None:
+        """Adds a new recipe to the user recipes folder.
+        
+        Args:
+            file (str): `.yaml` recipe file to add.
+        """
+        if not os.path.isfile(file):
+            raise FileNotFoundError(f"File {file!r} not found")
+        
+        if not file.endswith(".yaml"):
+            raise FileExtensionError(
+                "Only .yaml files can be added as recipes"
+            )
+        
+        shutil.copy(file, self.recipes_dir)
+        print(f"Recipe {file!r} successfully added to recipes folder")
+
+    def print_params(self) -> None:
+        """Prints user parameters to the terminal. """
+        print(f"file: {self.config_file!r}")
+
+        for k, v in self.config.items():
+            print(f"{k}: {v!r}")

recp/utils/exceptions.py

@@ -0,0 +1,19 @@
+
+class RequiredValueNotFoundError(Exception):
+    pass
+
+
+class MinimumVersionRequirementError(Exception):
+    pass
+
+
+class FolderNotFoundError(Exception):
+    pass
+
+
+class FileExtensionError(Exception):
+    pass
+
+
+class LenghtError(Exception):
+    pass

recp/utils/io.py

@@ -0,0 +1,75 @@
+import os
+from glob import glob
+from typing import (
+    Callable,
+    List
+)
+from .collections import make_list
+
+
+def get_dir_files(
+        dir: str | List[str],
+        ext: str | List[str] = "*",
+        recursive: bool = True,
+        key: Callable | None = None
+) -> List[str]:
+    """Returns a `list` with all the files inside folder with extension `ext`.
+    It supports a recursive search and searching in more than one root folder
+    at a time if `recursive=True` and `dir` is a `list` of `str`,
+    respectively.
+
+    Args:
+        dir (str | List[str]): Folder(s) to be searched.
+        ext (str | Tuple[str]): File extensions to be considered. Accepts `.*`
+            as a wild card.
+        recursive (bool): If `True`, the search inside each folder will be
+            recursive.
+        key (Callable | None): Key function to sort the results. If it is not
+            provided, files will be sorted alphabetically.
+
+    Returns:
+        `list` of `str` with the path to each retrieved file.
+
+    Raises:
+        FileNotFoundError: If one of the folder(s) cannot be found.
+    """
+    dir = make_list(dir)
+    ext = make_list(ext)
+
+    # Expand user and vars
+    for idx, dir_ in enumerate(dir):
+        dir[idx] = dir_
+
+    # Check dirs exist before fetching content
+    for dir_ in dir:
+        if not os.path.isdir(dir_):
+            raise FileNotFoundError(f"Folder not found: '{dir_}'")
+
+    all_files = []
+
+    # Search dirs
+    for dir_ in dir:
+        for ext_ in ext:
+            if recursive:
+                all_files.extend(
+                    list(
+                        glob(
+                            os.path.join(dir_, "**", f"*{ext_}"),
+                            recursive=True
+                        )
+                    )
+                )
+            else:
+                all_files.extend(list(glob(os.path.join(dir_, f"*{ext_}"))))
+    
+    # Filter out folders with file-like names (e.g. ending in .wav extension)
+    flagged_files = []
+
+    for file in all_files:
+        if not os.path.isfile(file):
+            flagged_files.append(file)
+    
+    for flagged_file in flagged_files:
+        all_files.remove(flagged_file)
+
+    return sorted(all_files, key=key)