vest-build 0.0.1__tar.gz

vest_build-0.0.1/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.3
+Name: vest-build
+Version: 0.0.1
+Summary: A Python-based build system for bespoke use
+Author: ascpixi
+Author-email: ascpixi <ascpixi@proton.me>
+Requires-Dist: packaging>=26.0
+Requires-Dist: rich>=15.0.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# 🦺 Vest
+[![image](https://img.shields.io/pypi/v/vest-build.svg)](https://pypi.python.org/pypi/vest-build)
+[![image](https://img.shields.io/pypi/l/vest-build.svg)](https://github.com/ascpixi/vest/blob/main/LICENSE)
+[![image](https://img.shields.io/pypi/pyversions/vest-build.svg)](https://pypi.python.org/pypi/vest-build)
+[![Actions status](https://github.com/ascpixi/vest/workflows/CI/badge.svg)](https://github.com/ascpixi/vest/actions)
+
+Vest is a Python-based build system for bespoke use.
+
+## Getting started
+First, install Vest from PyPI:
+```
+pip install vest-build
+```
+
+Then, create a `build.vest` file! What this file will do depends on your project. Let's say you're building a C project. In this case, your `.vest` file might look like this:
+
+```py
+from vest import *
+
+component(
+    name = "my-c-project"
+)
+
+@task
+def build():
+    # Let's turn each C file to an object file...
+    for (src, dst) in build_list(
+        src = "./src/**/*.c",
+        dst = "./obj",
+        ext = ".o",
+        flatten = True
+    ):
+        run("gcc", ["-c", src, "-o", dst])
+
+    # ...then link em' all!
+    run("gcc", [
+        "-o", "./bin/final",
+        *glob("./obj/*.o")
+    ])
+
+    # Tasks should return all of their final artifacts. This can be a string, list of strings, or a dictionary of strings.
+    return "./bin/final"
+
+@task
+def run():
+    # "run" needs a build to execute!
+    artifact = self_dependency(build)
+
+    # Let's run what "build" gave us.
+    run(artifact)
+```
+
+In the directory you've created the `vest.build` file in, run `vest -t build`.
+
+## Extensions
+Vest doesn't assume what languages nor frameworks you're using it for. However, there's a couple of ready PyPI packages for known use-cases:
+- [`vest-build-dotnet`](https://github.com/ascpixi/vest-dotnet): support for the .NET SDK.

vest_build-0.0.1/README.md

@@ -0,0 +1,57 @@
+# 🦺 Vest
+[![image](https://img.shields.io/pypi/v/vest-build.svg)](https://pypi.python.org/pypi/vest-build)
+[![image](https://img.shields.io/pypi/l/vest-build.svg)](https://github.com/ascpixi/vest/blob/main/LICENSE)
+[![image](https://img.shields.io/pypi/pyversions/vest-build.svg)](https://pypi.python.org/pypi/vest-build)
+[![Actions status](https://github.com/ascpixi/vest/workflows/CI/badge.svg)](https://github.com/ascpixi/vest/actions)
+
+Vest is a Python-based build system for bespoke use.
+
+## Getting started
+First, install Vest from PyPI:
+```
+pip install vest-build
+```
+
+Then, create a `build.vest` file! What this file will do depends on your project. Let's say you're building a C project. In this case, your `.vest` file might look like this:
+
+```py
+from vest import *
+
+component(
+    name = "my-c-project"
+)
+
+@task
+def build():
+    # Let's turn each C file to an object file...
+    for (src, dst) in build_list(
+        src = "./src/**/*.c",
+        dst = "./obj",
+        ext = ".o",
+        flatten = True
+    ):
+        run("gcc", ["-c", src, "-o", dst])
+
+    # ...then link em' all!
+    run("gcc", [
+        "-o", "./bin/final",
+        *glob("./obj/*.o")
+    ])
+
+    # Tasks should return all of their final artifacts. This can be a string, list of strings, or a dictionary of strings.
+    return "./bin/final"
+
+@task
+def run():
+    # "run" needs a build to execute!
+    artifact = self_dependency(build)
+
+    # Let's run what "build" gave us.
+    run(artifact)
+```
+
+In the directory you've created the `vest.build` file in, run `vest -t build`.
+
+## Extensions
+Vest doesn't assume what languages nor frameworks you're using it for. However, there's a couple of ready PyPI packages for known use-cases:
+- [`vest-build-dotnet`](https://github.com/ascpixi/vest-dotnet): support for the .NET SDK.

vest_build-0.0.1/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "vest-build"
+version = "0.0.1"
+description = "A Python-based build system for bespoke use"
+readme = "README.md"
+authors = [
+    { name = "ascpixi", email = "ascpixi@proton.me" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "packaging>=26.0",
+    "rich>=15.0.0"
+]
+
+[project.scripts]
+vest = "vest.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "vest"

vest_build-0.0.1/src/vest/__init__.py

@@ -0,0 +1,55 @@
+"""
+This module defines parts of the component system specification that are recommended to be used in all Vest components.
+This module should only be imported from components, via `from vest import *`.
+"""
+
+from pkgutil import extend_path
+__path__ = extend_path(__path__, __name__)
+
+from vest.spec.core import (
+    artifact_dir,
+    artifact_dir_path_of,
+    clean_artifact_dir,
+    artifact_root,
+    artifact_root_path_of,
+    clean_artifact_root,
+    component,
+    dependency,
+    dependent_on,
+    host,
+    require_task,
+    self_dependency,
+    task,
+    run,
+    run_tool,
+    parameter
+)
+
+from vest.spec.externals import (
+    git_repo,
+    GitRepoResolver
+)
+
+from vest.spec.types import (
+    Component,
+    ComponentTask,
+    BuildError,
+    ExternalRepoResolver
+)
+
+from vest.spec.fs import (
+    build_list,
+    copy,
+    copy_many,
+    expand_path,
+    foreign_file,
+    glob,
+    make_unique_dir
+)
+
+from vest.common.collections import (
+    find,
+    maybe,
+    single,
+    flatten
+)

vest_build-0.0.1/src/vest/__main__.py

@@ -0,0 +1,221 @@
+import os
+import argparse
+import traceback
+import subprocess
+from rich import print
+from rich.console import Console
+import rich.traceback
+
+from vest.common.log import is_agent, log_warn, log_error_hdr, log_success_hdr
+from vest.spec.host import StandaloneHost
+from vest.spec.types import BuildError, UsageError
+
+def main():
+    console = Console()
+    rich.traceback.install()
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-t", "--task", help = "The task to run.", required = True)
+    parser.add_argument("-p", "--path", default = "./build.vest", help = "The path to the target component.")
+    parser.add_argument("-r", "--run", action = "store_true", help = "If set, the 'run_script' of the given task will be invoked.")
+    parser.add_argument("--no-cache", action = "store_true", help = "If set, the results of the previous build will be ignored.")
+    args, extra_args = parser.parse_known_args()
+
+    def parse_extra_args():
+        transformed: dict[str, str] = {}
+
+        prev_arg: str | None = None
+        expecting_key = True
+
+        for arg in extra_args:
+            is_key = arg.startswith("-")
+            if is_key != expecting_key:
+                if expecting_key:
+                    # Two keys right next to each other (e.g --type --arch)
+                    if prev_arg is not None:
+                        log_error_hdr(f"Two or more values specified for parameter {prev_arg}.")
+                        exit(1)
+                    else:
+                        log_error_hdr(f"Stray argument {arg} found.")
+                        exit(1)
+                else:
+                    # Two values right next to each other (e.g. --arch amd64 release)
+                    log_error_hdr(f"No value found for parameter {prev_arg}.")
+                    exit(1)
+
+            if not expecting_key:
+                # There isn't really a possibility where we don't have a previous arg here. We're looking for a value, thus we went over the first iteration
+                # (which was looking for a key).
+                assert prev_arg is not None
+
+                # This is value! "prev_arg" holds the key, while "arg" holds the value.
+                transformed[prev_arg] = arg
+
+            prev_arg = arg
+            expecting_key = not expecting_key
+
+        return transformed
+
+    host = StandaloneHost(
+        parameters = parse_extra_args(),
+        load_cache = not args.no_cache
+    )
+
+    try:
+        if os.path.isdir(args.path):
+            args.path = os.path.join(args.path, "build.vest")
+
+        component = host.eval_component(args.path)
+    except Exception as ex:
+        log_error_hdr("Could not evaluate the component")
+        print(f"[red]  ╰─> {ex}[/]")
+        print()
+
+        console.print_exception()
+        exit(1)
+
+    if not any(t.name == args.task for t in component.tasks):
+        log_error_hdr(f"No task named '{args.task}'.")
+        print("[red]  ╰─> The defined tasks are:[/]")
+
+        for task in component.tasks:
+            if task.description is not None:
+                print(f"[red]        - {task.name}: {task.description}[/]")
+            else:
+                print(f"[red]        - {task.name}[/]")
+
+        exit(1)
+
+    try:
+        task = next(x for x in component.tasks if x.name == args.task)
+        artifacts = host.run_task(task)
+    except Exception as ex:
+        if type(ex) is UsageError:
+            # A UsageError indicates that neither Vest or the components in question are at fault - the user might've e.g. not specified a
+            # required parameter. In this case, we don't print the stacktrace at all.
+            print(" │")
+            log_error_hdr(f"Could not build [bold]{component.name}:{args.task}[/]")
+            print(f"[red]  ╰─> {ex}[/]")
+            print()
+            exit(1)
+
+        # https://github.com/Textualize/rich/blob/master/rich/traceback.py#L234
+        rich.traceback.Traceback.LEXERS[".vest"] = "python"
+
+        # Skip the first two frames; which are this script and the component host
+        # respectively. We only want to show the faulting components.
+        if ex.__traceback__ is not None:
+            first = ex.__traceback__
+            for i in range(2):
+                if ex.__traceback__.tb_next is None:
+                    ex.__traceback__ = first # revert back to the previous state
+                    break
+
+                ex.__traceback__ = ex.__traceback__.tb_next
+
+            # A BuildError indicates that the cause of the error is incorrect usage of the
+            # component system (as opposed to e.g. a bug). In this case, we don't need to
+            # show the frames that belong to the component system.
+            if type(ex) is BuildError:
+                # Filter out stacktraces that are not .vest files (unless it's the last one)
+                prev = ex.__traceback__
+                current = prev.tb_next
+                while current is not None and current.tb_next is not None:
+                    if not current.tb_frame.f_code.co_filename.endswith(".vest"):
+                        prev.tb_next = current.tb_next
+                        current = prev.tb_next
+                    else:
+                        prev = current
+                        current = current.tb_next
+
+                # Don't show the last frame
+                current = ex.__traceback__
+                prev = None
+
+                while current.tb_next is not None:
+                    prev = current
+                    current = current.tb_next
+
+                if prev is not None:
+                    prev.tb_next = None
+
+        print(" │")
+        log_error_hdr(f"Could not build [bold]{component.name}:{args.task}[/]")
+        print(f"[red]  ╰─> {ex}[/]")
+        print()
+
+        if type(ex) is subprocess.CalledProcessError:
+            stdout = ex.stdout.decode("utf-8") if type(ex.stdout) is bytes else str(ex.stdout)
+            stderr = ex.stderr.decode("utf-8") if type(ex.stderr) is bytes else str(ex.stderr)
+
+            stdout = stdout.strip()
+            stderr = stderr.strip()
+    
+            if stdout:
+                print(f"[red]Standard output:[/]")
+                print(stdout)
+                print()
+
+            if stderr:
+                print(f"[red]Standard error:[/]")
+                print(stderr)
+                print()
+
+        if not is_agent():
+            console.print_exception()
+        else:
+            traceback.print_exc()
+
+        print()
+        exit(1)
+
+    print(" │")
+    log_success_hdr(f"Component [bold]{component.name}:{args.task}[/] built successfully")
+
+    if not args.run:
+        if type(artifacts) is str:
+            print(f"  ╰─> You may find the resulting artifact in [bold]{artifacts}[/].")
+        elif type(artifacts) is list:
+            print(f"  ╰─> The following artifacts have been created:")
+
+            for entry in artifacts:
+                print(f"        - {entry}")
+        elif type(artifacts) is dict:
+            print(f"  ╰─> The following named artifacts have been created:")
+
+            for (k, v) in artifacts.items():
+                print(f"        - [bold]{k}[/]: {v}")
+        else:
+            print(artifacts) # this should never happen...
+
+    print()
+
+    try:
+        host.write_cache()
+    except:
+        print()
+        print(" │")
+        log_warn(f"Could not write the build cache")
+        print(f"[yellow]  ╰─> An exception occured while storing the build cache file.[/]")
+        print(f"[yellow]      This might result in anomalous behavior in future build system invocations.[/]")
+        print(f"[yellow]      You may delete the 'artifacts' directory if this is the case.[/]")
+        print()
+        console.print_exception()
+
+    if args.run:
+        if task.run_script == None:
+            log_error_hdr(f"Cannot run/debug the artifacts of [bold]{component.name}:{task.name}[/]")
+            print(f"[red]  ╰─> The component does not define a 'run_script' to invoke.[/]")
+            exit(1)
+
+        run_args = task.run_script(artifacts)
+        assert len(run_args) > 0
+
+        console.show_cursor()
+
+        # Hand off control to the script, so that we don't mess stuff up with any
+        # e.g. signal handlers we may have installed
+        os.execvp(run_args[0], run_args)
+
+if __name__ == "__main__":
+    main()

vest_build-0.0.1/src/vest/common/collections.py

@@ -0,0 +1,83 @@
+from typing import Callable, Iterable, TypeVar, overload
+
+T = TypeVar("T")
+TKey = TypeVar("TKey")
+TValue = TypeVar("TValue")
+
+def find(collection: list[T], predicate: Callable[[T], bool]) -> T | None:
+    "Finds the first item in the given collection that meets the specified predicate."
+    for x in collection:
+        if predicate(x):
+            return x
+    
+    return None
+
+def single(collection: list[T], predicate: Callable[[T], bool]) -> T:
+    """
+    Picks the first item in the given collection that meets the specified predicate.
+    If no item meets the predicate, a `LookupError` is raised.
+    """
+    for x in collection:
+        if predicate(x):
+            return x
+        
+    raise LookupError("No value in the given collection matches the predicate.")
+
+@overload
+def maybe(value: dict[TKey, TValue], when: bool) -> dict[TKey, TValue]:
+    """
+    Returns the given `value` if `condition` is `True` - otherwise, returns an empty dictionary.
+
+    This function is useful when defining conditional collection elements:
+    ```
+    example = {
+        "key1": "always present",
+        *maybe({ "key2": "sometimes present" }, when = some_condition)
+    }
+    ```
+    """
+    ...
+
+@overload
+def maybe(value: T | list[T], when: bool) -> list[T]:
+    """
+    Returns a 1-element list of the given `value` if `condition` is `True` - otherwise,
+    returns an empty list. If `value` is a `list`, it is returned instead.
+
+    This function is useful when defining conditional collection elements:
+    ```
+    example = [
+        "always present",
+        *maybe("sometimes present", when = some_condition)
+    ]
+    ```
+
+    ...as opposed to:
+    ```
+    example = [
+        "always present",
+        *(["sometimes present"] if some_condition else [])
+    ]
+    ```
+    """
+    ...
+
+def maybe(value: T | list[T] | dict[TKey, TValue], when: bool) -> list[T] | dict[TKey, TValue]:
+    if isinstance(value, dict):
+        return value if when else {}
+   
+    if not isinstance(value, list):
+        return [value] if when else []
+    else:
+        return value if when else []
+    
+def flatten(value: Iterable[list[T]]) -> list[T]:
+    """
+    Flattens a collection of other, nested lists. For example, the sequence `[[1, 2], [3, 4], [5, 6]]`
+    becomes `[1, 2, 3, 4, 5, 6]`.
+    """
+    result: list[T] = []
+    for subarr in value:
+        result.extend(subarr)
+    
+    return result

vest_build-0.0.1/src/vest/common/fs.py

@@ -0,0 +1,28 @@
+import os
+
+def walk_down(start_path: str, end_path: str):
+    """
+    Returns the paths to traverse when walking down a directory tree, starting at
+    `start_path`, and ending with `end_path`.
+
+    @start_path: The path to being traversal in. Must be a child of `end_path`.
+    @end_path: The path to end traversing directories on. Must be a parent of `start_path`.
+    """
+
+    start_path = os.path.abspath(start_path)
+    end_path = os.path.abspath(end_path)
+
+    if not start_path.startswith(end_path):
+        raise ValueError(f"End path '{end_path}' is not a parent of start path '{start_path}'")
+
+    current_path = start_path
+    paths = [current_path]
+    
+    while current_path != end_path:
+        if current_path == os.path.dirname(current_path): # We've reached the root
+            raise ValueError(f"Reached root directory before finding end path '{end_path}'")
+        
+        current_path = os.path.dirname(current_path)
+        paths.append(current_path)
+    
+    return paths

vest_build-0.0.1/src/vest/common/log.py

@@ -0,0 +1,145 @@
+import os
+import atexit
+import shutil
+import rich
+from rich import print
+from rich.console import Console
+from rich.text import Text
+from rich.table import Table
+
+_current_log_indent = 0
+_task_stack: list[str] = []
+
+def is_github_actions():
+    return "GITHUB_RUN_ID" in os.environ
+
+def is_agent():
+    return "CLAUDECODE" in os.environ or "GEMINI_CLI" in os.environ or "CURSOR_AGENT" in os.environ
+
+def is_non_interactive():
+    return is_github_actions() or is_agent()
+
+def log_dedent(delta: int = 2):
+    global _current_log_indent
+    _current_log_indent -= delta
+    _task_stack.pop()
+
+def log_reset_terminal():
+    rich.reconfigure()
+    rich.console.Console().show_cursor()
+
+def log_deinit():
+    """Performs on-exit de-initialization of the logging sub-system."""
+    if not is_non_interactive():
+        log_reset_terminal()
+
+def log_get_effective_width():
+    return shutil.get_terminal_size().columns - _current_log_indent
+
+def log_dependency(full_name: str, fulfilled = False):
+    global _current_log_indent
+
+    if not fulfilled:
+        _current_log_indent += 2
+        _task_stack.append(full_name)
+
+    if is_agent():
+        print(f"{full_name} was built before - skipping because of cache." if fulfilled else f"Building {full_name}...")
+        return
+
+    formatted = (
+        f"◆ Dependency on [bold]{full_name}[/] [bright_black](fullfilled previously)[/]" if fulfilled else
+        f"◇ Building [bold]{full_name}[/]..."
+    )
+
+    if _current_log_indent == 0:
+        print(f"[white] {formatted}[/]")
+    else:
+        print(f"[white] {'├'.ljust(_current_log_indent, '─')} {formatted}[/]")
+
+def log(prefix: str, msg: str | Text):
+    """
+    Logs a message to the console. All arguments can be formatted using Rich markup.
+    If executing in a CI environment, no special formatting will be applied.
+    """
+
+    if not isinstance(msg, Text):
+        msg = Text.from_markup(msg)
+
+    if is_non_interactive():
+        print(prefix, msg)
+        return
+
+    def create_table(border: Text):
+        grid = Table.grid()
+        grid.add_column()
+        grid.add_column()
+        grid.add_column()
+        grid.add_column()
+
+        grid.add_row(
+            border,
+            Text.from_markup(prefix),
+            "  ",
+            msg
+        )
+
+        return grid
+
+    console = Console()
+    with console.capture() as capture:
+        console.print(create_table(Text(" │".ljust(_current_log_indent))))
+    
+    simulated = capture.get()
+    print(create_table(
+        Text((
+            # Make sure the first row, which holds the border, is as large as the table.
+            (" │".ljust(_current_log_indent + 2) + "\n") * simulated.count("\n")
+        ).rstrip("\n"))
+    ))
+
+def _get_agent_label(label: str):
+    if len(_task_stack) == 0:
+        return f"({label}) "
+    
+    return f"({label}@{_task_stack[-1]}) "
+
+def log_info(msg: str | Text):
+    """Logs an informational message to the console."""
+    log("[white bold]info[/]" if not is_non_interactive() else "(info)  " if is_github_actions() else _get_agent_label("info"), msg)
+
+def log_warn(msg: str | Text):
+    """Logs a warning message to the console."""
+    if isinstance(msg, Text):
+        msg.stylize("#ffffaf")
+    else:
+        msg = f"[#ffffaf]{msg}[/]"
+
+    log("[yellow bold]warn[/]" if not is_non_interactive() else "::warning::" if is_github_actions() else _get_agent_label("warning"), msg)
+
+def log_error(msg: str | Text):
+    """Logs an error message to the console."""
+    if isinstance(msg, Text):
+        msg.stylize("#ffcbd7")
+    else:
+        msg = f"[#ffcbd7]{msg}[/]"
+
+    log("[red bold]error[/]" if not is_non_interactive() else "::error::" if is_github_actions() else _get_agent_label("error"), msg)
+
+def log_error_hdr(msg: str):
+    "Prints an error header to the console."
+    if is_agent():
+        print(f"Failure: {msg}")
+        return
+
+    print(f"[black on red] × ERROR [/] [red]{msg}[/]")
+
+def log_success_hdr(msg: str):
+    "Prints a success header to the console."
+    if is_agent():
+        print(f"Success: {msg}")
+        return
+
+    print(f"[black on green] ❯ SUCCESS [/] [green]{msg}[/]")
+
+atexit.register(log_deinit)