jazzoo 0.1.0__tar.gz

jazzoo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maarten Nieber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jazzoo-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+# Keep the full README out of the sdist until the launch (see readme in pyproject.toml)
+exclude README.md

jazzoo-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: jazzoo
+Version: 0.1.0
+Summary: A beast of a task-runner
+Author: Maarten Nieber
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# jazzoo
+
+A beast of a task-runner.
+
+Docs coming soon.

jazzoo-0.1.0/README.short.md

@@ -0,0 +1,5 @@
+# jazzoo
+
+A beast of a task-runner.
+
+Docs coming soon.

jazzoo-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "jazzoo"
+version = "0.1.0"
+description = "A beast of a task-runner"
+readme = "README.short.md"
+authors = [{ name = "Maarten Nieber" }]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+
+# Uncomment at launch, when the GitHub repo is public
+# [project.urls]
+# Homepage = "https://github.com/mnieber/jazzoo"
+# Issues = "https://github.com/mnieber/jazzoo/issues"
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+jazzoo = "jazzoo.runtime.entrypoints.jazzoo:main"
+jaz = "jazzoo.runtime.entrypoints.jazzoo:main"
+jaz-run = "jazzoo.commands.entrypoints.jaz_run:main"
+zoo = "jazzoo.runtime.entrypoints.zoo:main"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"jazzoo.config._vendor" = ["vendor.txt"]
+"jazzoo.config._vendor.yaml" = ["LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+# setuptools 77 is the first that understands license = "MIT"
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"

jazzoo-0.1.0/setup.cfg

@@ -0,0 +1,11 @@
+[isort]
+multi_line_output = 3
+include_trailing_comma = True
+force_grid_wrap = 0
+use_parentheses = True
+line_length = 88
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

jazzoo-0.1.0/setup.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+from setuptools import setup
+
+
+def create_placeholder():
+    this_directory = Path(__file__).parent
+    pkg_directory = this_directory / "src" / "jazzoo"
+
+    if not pkg_directory.exists():
+        pkg_directory.mkdir(parents=True)
+        with open(pkg_directory / "__init__.py", "w") as f:
+            f.write("# Placeholder for package")
+
+
+if __name__ == "__main__":
+    create_placeholder()
+    setup()

jazzoo-0.1.0/src/jazzoo/__init__.py

@@ -0,0 +1,57 @@
+from jazzoo.commands import (
+    CommandAbortedError,
+    CommandError,
+    CommandFailedError,
+    CommandNotFoundError,
+    CommandResult,
+    run,
+    run_docker,
+)
+from jazzoo.config import (
+    ConfigError,
+    ConfigExpansionError,
+    ConfigFileError,
+    ConfigKeyError,
+    get_config,
+    prepare_config,
+)
+from jazzoo.errors import (
+    ArgumentError,
+    ExecutionError,
+    JazzooError,
+    ModuleImportError,
+    ParseError,
+    ResolutionError,
+)
+from jazzoo.expressions.actions.evaluate import evaluate
+from jazzoo.functions.rules.get_function_by_path import get_function_by_path
+from jazzoo.functions.rules.get_targets import get_targets
+from jazzoo.modules.actions.parse_module import parse_module
+from jazzoo.modules.rules.get_module_by_path import get_module_by_path
+
+__all__ = [
+    "ArgumentError",
+    "CommandAbortedError",
+    "CommandError",
+    "CommandFailedError",
+    "CommandNotFoundError",
+    "CommandResult",
+    "ConfigError",
+    "ConfigExpansionError",
+    "ConfigFileError",
+    "ConfigKeyError",
+    "ExecutionError",
+    "JazzooError",
+    "ModuleImportError",
+    "ParseError",
+    "ResolutionError",
+    "evaluate",
+    "get_config",
+    "get_function_by_path",
+    "get_module_by_path",
+    "get_targets",
+    "parse_module",
+    "prepare_config",
+    "run",
+    "run_docker",
+]

jazzoo-0.1.0/src/jazzoo/aliases/errors.py

@@ -0,0 +1,5 @@
+from jazzoo.errors import JazzooError
+
+
+class AliasError(JazzooError):
+    pass

jazzoo-0.1.0/src/jazzoo/aliases/rules/expand_alias.py

@@ -0,0 +1,38 @@
+import shlex
+import typing as T
+
+from jazzoo.aliases.errors import AliasError
+from jazzoo.aliases.rules.get_alias_config_file import get_alias_config_file
+from jazzoo.aliases.rules.read_aliases import read_aliases
+
+# The options of jaz that an expansion may contain
+_ALLOWED_OPTIONS = ("--confirm", "--trace")
+
+
+def expand_alias(name: str) -> T.Optional[T.List[str]]:
+    config_file = get_alias_config_file()
+    expansion = read_aliases(config_file).get(name)
+    if expansion is None:
+        return None
+
+    try:
+        tokens = shlex.split(expansion)
+    except ValueError as error:
+        raise AliasError(
+            f'alias "{name}" has an invalid expansion: {error}', filename=config_file
+        )
+    if not tokens:
+        raise AliasError(f'alias "{name}" has an empty expansion', filename=config_file)
+
+    # Only the options that change how the target runs are allowed
+    for token in tokens:
+        option = token.partition("=")[0]
+        if option.startswith("-") and option not in _ALLOWED_OPTIONS:
+            raise AliasError(
+                f'alias "{name}" may not use the option {option}',
+                filename=config_file,
+            )
+    if all(token in _ALLOWED_OPTIONS for token in tokens):
+        raise AliasError(f'alias "{name}" names no target', filename=config_file)
+
+    return tokens

jazzoo-0.1.0/src/jazzoo/aliases/rules/get_alias_config_file.py

@@ -0,0 +1,7 @@
+import os
+
+from jazzoo.settings import get_zoo_config_dir
+
+
+def get_alias_config_file() -> str:
+    return os.path.join(get_zoo_config_dir(), "config")

jazzoo-0.1.0/src/jazzoo/aliases/rules/read_aliases.py

@@ -0,0 +1,36 @@
+import configparser
+import os
+import re
+import typing as T
+
+from jazzoo.aliases.errors import AliasError
+
+# A target path: names separated by dots
+_ALIAS_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*(\.[A-Za-z_][A-Za-z0-9_-]*)*$")
+
+
+def read_aliases(config_file: str) -> T.Dict[str, str]:
+    if not os.path.exists(config_file):
+        return {}
+
+    # No section is special: a section header cannot contain a newline, so the
+    # default section of configparser never occurs
+    parser = configparser.ConfigParser(
+        interpolation=None, strict=True, default_section="\n"
+    )
+    # Alias names are case-sensitive
+    parser.optionxform = str  # type: ignore[assignment]
+    try:
+        with open(config_file, encoding="utf-8") as f:
+            parser.read_file(f, source=config_file)
+    except (OSError, UnicodeDecodeError, configparser.Error) as error:
+        raise AliasError(f"invalid config file: {error}", filename=config_file)
+
+    if not parser.has_section("alias"):
+        return {}
+
+    aliases = dict(parser.items("alias"))
+    for name in aliases:
+        if not _ALIAS_NAME_RE.match(name):
+            raise AliasError(f'invalid alias name "{name}"', filename=config_file)
+    return aliases

jazzoo-0.1.0/src/jazzoo/blocks/actions/run_block.py

@@ -0,0 +1,80 @@
+import os
+import stat
+import subprocess
+import sys
+import tempfile
+import typing as T
+
+from jazzoo.errors import ExecutionError
+from jazzoo.settings import DEFAULT_SHEBANG
+
+
+def run_block(
+    shebang: T.Optional[str],
+    body: str,
+    filename: T.Optional[str] = None,
+    line: T.Optional[int] = None,
+    is_quiet: bool = False,
+    is_interactive: bool = False,
+) -> str:
+    """Run one block as a single subprocess and return its raw stdout.
+
+    The block is written to a temporary executable file so the shebang selects the
+    interpreter, exactly as it would for a script on disk.
+    """
+    shebang = shebang or DEFAULT_SHEBANG
+    script = shebang + "\n" + body
+    if not script.endswith("\n"):
+        script += "\n"
+
+    handle = tempfile.NamedTemporaryFile(
+        mode="w", suffix=".jaz-block", delete=False, encoding="utf-8"
+    )
+    try:
+        handle.write(script)
+        handle.close()
+        os.chmod(handle.name, os.stat(handle.name).st_mode | stat.S_IEXEC)
+
+        if is_interactive:
+            # Whatever was echoed must reach the console before the block's output
+            sys.stdout.flush()
+            sys.stderr.flush()
+            completed = subprocess.run([handle.name])
+        else:
+            completed = subprocess.run(
+                [handle.name],
+                capture_output=True,
+                text=True,
+            )
+    finally:
+        os.unlink(handle.name)
+
+    # An interactive block writes to the console itself, and Jazzoo never sees its
+    # output, not even in a quiet call.
+    if is_interactive:
+        if completed.returncode != 0:
+            raise ExecutionError(
+                f"recipe failed with exit code {completed.returncode}: "
+                f"command failed: {body.strip()}",
+                filename=filename,
+                line=line,
+            )
+        return ""
+
+    # The block's own output goes to the console as well as being captured for
+    # ⚙️.stdout, so a target behaves like the commands it runs. A quiet block keeps
+    # its stdout for the caller, but its stderr is always shown.
+    if completed.stdout and not is_quiet:
+        print(completed.stdout, end="")
+    if completed.stderr:
+        print(completed.stderr, end="", file=sys.stderr)
+
+    if completed.returncode != 0:
+        message = completed.stderr.strip() or f"command failed: {body.strip()}"
+        raise ExecutionError(
+            f"recipe failed with exit code {completed.returncode}: {message}",
+            filename=filename,
+            line=line,
+        )
+
+    return completed.stdout

jazzoo-0.1.0/src/jazzoo/blocks/models/block.py

@@ -0,0 +1,21 @@
+import typing as T
+
+from jazzoo.enums import BlockMode
+from jazzoo.utils.dataclass import dataclass
+
+
+@dataclass
+class BlockLine:
+    text: str
+    line: int
+    # Set by a leading `@`, which hides the echoed command but not its output.
+    is_quiet: bool = False
+
+
+@dataclass
+class Block:
+    mode: BlockMode
+    # The interpreter line, e.g. "#!/usr/bin/env python3". None in jazzoo mode.
+    shebang: T.Optional[str] = None
+    lines: T.List[BlockLine] = []
+    filename: T.Optional[str] = None

jazzoo-0.1.0/src/jazzoo/commands/__init__.py

@@ -0,0 +1,19 @@
+from .actions.run import run
+from .actions.run_docker import run_docker
+from .errors import (
+    CommandAbortedError,
+    CommandError,
+    CommandFailedError,
+    CommandNotFoundError,
+)
+from .models.command_result import CommandResult
+
+__all__ = [
+    "CommandAbortedError",
+    "CommandError",
+    "CommandFailedError",
+    "CommandNotFoundError",
+    "CommandResult",
+    "run",
+    "run_docker",
+]

jazzoo-0.1.0/src/jazzoo/commands/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .entrypoints.jaz_run import main
+
+sys.exit(main())

jazzoo-0.1.0/src/jazzoo/commands/actions/confirm_command.py

@@ -0,0 +1,36 @@
+import os
+import typing as T
+
+from ..errors import CommandAbortedError, CommandError
+from ..settings import CONFIRM_PROMPT, TERMINAL
+from ..utils.format_command import format_command
+
+
+def confirm_command(
+    command: T.Union[str, T.List[str]], cwd: T.Optional[str] = None
+) -> bool:
+    try:
+        reader = open(TERMINAL, "r", encoding="utf-8")
+        writer = open(TERMINAL, "w", encoding="utf-8")
+    except OSError:
+        raise CommandError("--confirm needs a terminal")
+
+    with reader, writer:
+        # Asks again until the answer is y, n, q or Enter
+        while True:
+            writer.write(format_command(command, cwd or os.getcwd()) + "\n")
+            writer.write(CONFIRM_PROMPT)
+            writer.flush()
+
+            line = reader.readline()
+            # An empty line has a newline; no newline means the end of input
+            if not line:
+                raise CommandAbortedError("aborted by the user")
+
+            answer = line.strip().lower()
+            if answer in ("", "y"):
+                return True
+            if answer == "n":
+                return False
+            if answer == "q":
+                raise CommandAbortedError("aborted by the user")

jazzoo-0.1.0/src/jazzoo/commands/actions/run.py

@@ -0,0 +1,100 @@
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import typing as T
+
+from ..errors import CommandFailedError
+from ..models.command_result import CommandResult
+from ..rules.find_executable import find_executable
+from ..rules.is_confirm_on import is_confirm_on
+from ..utils.format_command import format_command
+from ..utils.ignoring_sigint import ignoring_sigint
+from .confirm_command import confirm_command
+
+
+def run(
+    command: T.Union[str, T.List[str]],
+    cwd: T.Optional[str] = None,
+    env: T.Optional[T.Dict[str, str]] = None,
+    capture: bool = False,
+    check: bool = True,
+    echo: bool = False,
+) -> CommandResult:
+    # Check the arguments before anything runs
+    if isinstance(command, str):
+        if not command.strip():
+            raise ValueError("the command is empty")
+    elif not command:
+        raise ValueError("the command is empty")
+    if cwd is not None and not os.path.isdir(cwd):
+        raise ValueError(f"directory not found: {cwd}")
+
+    environ = {**os.environ, **(env or {})}
+
+    # A string runs in bash; a list runs directly
+    if isinstance(command, str):
+        args = ["bash", "-c", command]
+        executable = shutil.which("bash") or "/bin/bash"
+    else:
+        args = list(command)
+        executable = find_executable(args[0], environ)
+
+    # The prompt shows the command, so it replaces the echo
+    if is_confirm_on():
+        if not confirm_command(command, cwd):
+            skipped_output = "" if capture else None
+            return CommandResult(
+                command=command,
+                returncode=0,
+                stdout=skipped_output,
+                stderr=skipped_output,
+                skipped=True,
+            )
+    elif echo:
+        print(format_command(command, cwd))
+
+    # The command writes to the same file descriptors as the script, so what the
+    # script printed before must come first
+    sys.stdout.flush()
+    sys.stderr.flush()
+
+    output = subprocess.PIPE if capture else None
+    process = subprocess.Popen(
+        args,
+        executable=executable,
+        cwd=cwd,
+        env=environ,
+        stdout=output,
+        stderr=output,
+        text=True,
+    )
+
+    # SIGINT is ignored only after the command has started, because an ignored
+    # signal would be inherited by the command. A ctrl-c then reaches the command
+    # only.
+    with ignoring_sigint():
+        stdout, stderr = process.communicate()
+
+    if process.returncode == -signal.SIGINT:
+        raise KeyboardInterrupt
+
+    result = CommandResult(
+        command=command,
+        returncode=process.returncode,
+        stdout=stdout,
+        stderr=stderr,
+    )
+    if check and result.returncode != 0:
+        raise CommandFailedError(_failure_message(result, cwd), result)
+    return result
+
+
+def _failure_message(result: CommandResult, cwd: T.Optional[str]) -> str:
+    message = f"command failed with exit code {result.returncode}: " + format_command(
+        result.command, cwd
+    )
+    if result.stderr and result.stderr.strip():
+        message += "\n" + result.stderr.strip()
+    return message

jazzoo-0.1.0/src/jazzoo/commands/actions/run_docker.py

@@ -0,0 +1,67 @@
+import typing as T
+
+from ..models.command_result import CommandResult
+from ..rules.needs_tty import needs_tty
+
+Command = T.Union[str, T.List[str]]
+RunFunction = T.Callable[..., CommandResult]
+
+
+def run_docker(
+    container: str,
+    user: T.Optional[str] = None,
+    workdir: T.Optional[str] = None,
+    env: T.Optional[T.Dict[str, str]] = None,
+    shell: str = "bash",
+) -> T.Callable[[RunFunction], RunFunction]:
+    if not container or not container.strip():
+        raise ValueError("the container is empty")
+
+    container_env = dict(env or {})
+
+    def decorator(run: RunFunction) -> RunFunction:
+        def run_in_container(
+            command: Command,
+            cwd: T.Optional[str] = None,
+            env: T.Optional[T.Dict[str, str]] = None,
+            capture: bool = False,
+            check: bool = True,
+            echo: bool = False,
+        ) -> CommandResult:
+            # Check the command before the docker command hides it
+            if isinstance(command, str):
+                if not command.strip():
+                    raise ValueError("the command is empty")
+                command_args = [shell, "-c", command]
+            elif not command:
+                raise ValueError("the command is empty")
+            else:
+                command_args = list(command)
+
+            # The options come in a fixed order
+            docker_command = ["docker", "exec", "--interactive"]
+            if needs_tty(capture):
+                docker_command.append("--tty")
+            if user:
+                docker_command += ["--user", user]
+            # A cwd only replaces the workdir for this call
+            call_workdir = cwd or workdir
+            if call_workdir:
+                docker_command += ["--workdir", call_workdir]
+            for name, value in {**container_env, **(env or {})}.items():
+                docker_command += ["--env", f"{name}={value}"]
+            docker_command += [container, *command_args]
+
+            # The cwd and env belong to the container, not to the docker client
+            return run(
+                docker_command,
+                cwd=None,
+                env=None,
+                capture=capture,
+                check=check,
+                echo=echo,
+            )
+
+        return run_in_container
+
+    return decorator