jazzoo 0.1.0__py3-none-any.whl

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/aliases/errors.py

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

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/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/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/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/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/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/commands/__main__.py

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

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/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/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

jazzoo/commands/entrypoints/jaz_run.py

@@ -0,0 +1,76 @@
+import argparse
+import sys
+import typing as T
+
+from ..actions.run import run as run_command
+from ..errors import (
+    CommandAbortedError,
+    CommandError,
+    CommandNotFoundError,
+    UsageError,
+)
+
+USAGE = (
+    "usage: jaz-run [--echo] [--] <executable> [<argument> ...]\n"
+    '       jaz-run [--echo] -c "<command>"'
+)
+
+
+class _ArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str):
+        raise UsageError(message)
+
+
+def _parse_args(argv: T.Optional[T.List[str]] = None):
+    parser = _ArgumentParser(prog="jaz-run", add_help=False)
+    parser.add_argument("--echo", dest="echo", action="store_true")
+    parser.add_argument("-c", dest="string_command", default=None)
+    parser.add_argument("--help", "-h", dest="help", action="store_true")
+    # The first argument that is not an option of jaz-run starts the command
+    parser.add_argument("command", nargs=argparse.REMAINDER)
+    return parser.parse_args(argv)
+
+
+def _get_command(args) -> T.Union[str, T.List[str]]:
+    command = list(args.command)
+    if command[:1] == ["--"]:
+        command = command[1:]
+
+    if args.string_command is not None:
+        if command:
+            raise UsageError("-c takes a single command")
+        return args.string_command
+
+    if not command:
+        raise UsageError("no command given")
+    return command
+
+
+def run(argv: T.Optional[T.List[str]] = None) -> int:
+    args = _parse_args(argv)
+    if args.help:
+        print(USAGE)
+        return 0
+
+    result = run_command(_get_command(args), check=False, echo=args.echo)
+    return result.returncode
+
+
+def main(argv: T.Optional[T.List[str]] = None) -> int:
+    try:
+        return run(argv)
+    except KeyboardInterrupt:
+        return 130
+    except CommandAbortedError as error:
+        print(f"jaz-run: {error}", file=sys.stderr)
+        return 130
+    except CommandNotFoundError as error:
+        print(f"jaz-run: {error}", file=sys.stderr)
+        return 127
+    except (CommandError, ValueError) as error:
+        print(f"jaz-run: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

jazzoo/commands/errors.py

@@ -0,0 +1,26 @@
+import typing as T
+
+if T.TYPE_CHECKING:
+    from .models.command_result import CommandResult
+
+
+class CommandError(Exception):
+    pass
+
+
+class CommandNotFoundError(CommandError):
+    pass
+
+
+class CommandAbortedError(CommandError):
+    pass
+
+
+class UsageError(CommandError):
+    pass
+
+
+class CommandFailedError(CommandError):
+    def __init__(self, message: str, result: "CommandResult"):
+        super().__init__(message)
+        self.result = result

jazzoo/commands/models/command_result.py

@@ -0,0 +1,15 @@
+import typing as T
+
+from ..utils.dataclass import dataclass
+
+
+@dataclass
+class CommandResult:
+    # The command, as it was given to run
+    command: T.Union[str, T.List[str]]
+    returncode: int
+    # None unless the output was captured
+    stdout: T.Optional[str] = None
+    stderr: T.Optional[str] = None
+    # True when the user skipped the command at the confirmation prompt
+    skipped: bool = False

jazzoo/commands/rules/find_executable.py

@@ -0,0 +1,18 @@
+import os
+import shutil
+import typing as T
+
+from ..errors import CommandNotFoundError
+
+
+def find_executable(name: str, environ: T.Dict[str, str]) -> str:
+    # A name with a slash is a path, as in a shell
+    if "/" in name:
+        if os.path.isfile(name) and os.access(name, os.X_OK):
+            return name
+        raise CommandNotFoundError(f"command not found: {name}")
+
+    path = shutil.which(name, path=environ.get("PATH", os.defpath))
+    if path is None:
+        raise CommandNotFoundError(f"command not found: {name}")
+    return path

jazzoo/commands/rules/has_terminal.py

@@ -0,0 +1,9 @@
+from ..settings import TERMINAL
+
+
+def has_terminal() -> bool:
+    try:
+        with open(TERMINAL, "w"):
+            return True
+    except OSError:
+        return False

jazzoo/commands/rules/is_confirm_on.py

@@ -0,0 +1,7 @@
+import os
+
+from ..settings import CONFIRM_ENV_VAR
+
+
+def is_confirm_on() -> bool:
+    return os.environ.get(CONFIRM_ENV_VAR) == "1"

jazzoo/commands/rules/needs_tty.py

@@ -0,0 +1,9 @@
+import sys
+
+
+def needs_tty(capture: bool) -> bool:
+    # A tty would mix stderr into captured output, and docker refuses one when the
+    # script has no terminal
+    if capture:
+        return False
+    return sys.stdin.isatty() and sys.stdout.isatty()