feat: add script runner (#78)

* feat: add script runner

* test: add test for scripts

* refactor: process scripts in a nicer way

* refactor: move `__init__.py` to `_cli.py` for `ape_run`

* refactor: move config to top import (now that loading is differed)

* refactor: empty list check can just be not

* refactor: no need to handle return values

* refactor: `--interactive` was not a flag

* feat: run script using network

* feat: run console on interactive

* refactor: use importlib instead

* fix: exception traceback

* fix: use absolute paths for executing scripts (resolve to relative)

* feat: add ability to display error info

* test: actually do something in the script

* fix: add script to sys.path temporarily to discover it

* chore: ignore cache folder

* test: clean up fixtures

* test: fix issue with how isolated filesystem worked

the function we were using created a *new* temp directory at the base
of the project folder, which was not intended behavior (the intention
was to leverage the project folder as the base directly)

Author: fubuloubu

.gitignore

@@ -116,3 +116,6 @@ dmypy.json
 
 # setuptools-scm
 version.py
+
+# Ape stuff
+.build/

pyproject.toml

@@ -23,6 +23,6 @@ line_length = 100
 force_grid_wrap = 0
 include_trailing_comma = true
 known_third_party = ["IPython", "click", "dataclassy", "eth_abi", "eth_account", "eth_utils", "github", "hexbytes", "hypothesis", "hypothesis_jsonschema", "importlib_metadata", "pluggy", "pytest", "requests", "setuptools", "web3", "yaml"]
-known_first_party = ["ape_accounts", "ape"]
+known_first_party = ["ape_accounts", "ape_console", "ape"]
 multi_line_output = 3
 use_parentheses = true

setup.py

@@ -79,6 +79,7 @@
             "ape_compile=ape_compile._cli:cli",
             "ape_console=ape_console._cli:cli",
             "ape_plugins=ape_plugins._cli:cli",
+            "ape_run=ape_run._cli:cli",
             "ape_networks=ape_networks._cli:cli",
         ],
     },
@@ -94,6 +95,7 @@
         "ape_infura",
         "ape_networks",
         "ape_plugins",
+        "ape_run",
         "ape_test",
         "ape_pm",
     ],
@@ -109,6 +111,7 @@
         "ape_ethereum": ["py.typed"],
         "ape_etherscan": ["py.typed"],
         "ape_infura": ["py.typed"],
+        "ape_run": ["py.typed"],
         "ape_test": ["py.typed"],
         "ape_pm": ["py.typed"],
     },

src/ape/utils.py

@@ -27,6 +27,39 @@ def get_distributions():
     return packages_distributions()
 
 
+def is_relative_to(path: Path, target: Path) -> bool:
+    if hasattr(path, "is_relative_to"):
+        # NOTE: Only available `>=3.9`
+        return target.is_relative_to(path)  # type: ignore
+
+    else:
+        try:
+            return target.relative_to(path) is not None
+        except ValueError:
+            return False
+
+
+def get_relative_path(target: Path, anchor: Path) -> Path:
+    """
+    Compute the relative path of `target` relative to `anchor`,
+    which may or may not share a common ancestor.
+    NOTE: Both paths must be absolute
+    """
+    assert anchor.is_absolute()
+    assert target.is_absolute()
+
+    anchor_copy = Path(str(anchor))
+    levels_deep = 0
+    while not is_relative_to(anchor_copy, target):
+        levels_deep += 1
+        assert anchor_copy != anchor_copy.parent
+        anchor_copy = anchor_copy.parent
+
+    return Path("/".join(".." for _ in range(levels_deep))).joinpath(
+        str(target.relative_to(anchor_copy))
+    )
+
+
 def get_package_version(obj: Any) -> str:
     # If value is already cached/static
     if hasattr(obj, "__version__"):

src/ape_run/__init__.py

@@ -0,0 +1,112 @@
+import sys
+from importlib import import_module
+from pathlib import Path
+
+import click
+
+from ape import config, networks
+from ape.utils import Abort, get_relative_path
+from ape_console._cli import NetworkChoice, console
+
+# TODO: Migrate this to a CLI toolkit under `ape`
+
+
+def _run_script(script_path, interactive=False, verbose=False):
+    script_path = get_relative_path(script_path, Path.cwd())
+    script_parts = script_path.parts[:-1]
+
+    if any(p == ".." for p in script_parts):
+        raise Abort("Cannot execute script from outside current directory")
+
+    # Add to Python path so we can search for the given script to import
+    sys.path.append(str(script_path.parent.resolve()))
+
+    # Load the python module to find our hook functions
+    try:
+        py_module = import_module(script_path.stem)
+
+    except Exception as e:
+        if verbose:
+            raise e
+
+        else:
+            raise Abort(f"Exception while executing script: {script_path}") from e
+
+    finally:
+        # Undo adding the path to make sure it's not permanent
+        sys.path.remove(str(script_path.parent.resolve()))
+
+    # Execute the hooks
+    if hasattr(py_module, "cli"):
+        # TODO: Pass context to `cli` before calling it
+        py_module.cli()
+
+    elif hasattr(py_module, "main"):
+        # NOTE: `main()` accepts no arguments
+        py_module.main()
+
+    else:
+        raise Abort("No `main` or `cli` method detected")
+
+    if interactive:
+        return console()
+
+
+@click.command(short_help="Run scripts from the `scripts` folder")
+@click.argument("scripts", nargs=-1)
+@click.option(
+    "-v",
+    "--verbose",
+    is_flag=True,
+    default=False,
+    help="Display errors from scripts",
+)
+@click.option(
+    "-i",
+    "--interactive",
+    is_flag=True,
+    default=False,
+    help="Drop into interactive console session after running",
+)
+@click.option(
+    "--network",
+    type=NetworkChoice(case_sensitive=False),
+    default=networks.default_ecosystem.name,
+    help="Override the default network and provider. (see `ape networks list` for options)",
+    show_default=True,
+    show_choices=False,
+)
+def cli(scripts, verbose, interactive, network):
+    """
+    NAME - Path or script name (from `scripts/` folder)
+
+    Run scripts from the `scripts` folder. A script must either define a `main()` method,
+    or define an import named `cli` that is a `click.Command` or `click.Group` object.
+    `click.Group` and `click.Command` objects will be provided with additional context, which
+    will be injected dynamically during script execution. The dynamically injected objects are
+    the exports from the `ape` top-level package (similar to how the console works)
+    """
+    if not scripts:
+        raise Abort("Must provide at least one script name or path")
+
+    scripts_folder = config.PROJECT_FOLDER / "scripts"
+
+    # Generate the lookup based on all the scripts defined in the project's `scripts/` folderi
+    # NOTE: If folder does not exist, this will be empty (same as if there are no files)
+    available_scripts = {p.stem: p.resolve() for p in scripts_folder.glob("*.py")}
+
+    with networks.parse_network_choice(network):
+        for name in scripts:
+            if Path(name).exists():
+                script_file = Path(name).resolve()
+
+            elif not scripts_folder.exists():
+                raise Abort("No `scripts/` directory detected to run script")
+
+            elif name not in available_scripts:
+                raise Abort(f"No script named '{name}' detected in scripts folder")
+
+            else:
+                script_file = available_scripts[name]
+
+            _run_script(script_file, interactive, verbose)

src/ape_run/_cli.py

@@ -4,55 +4,47 @@
 import pytest  # type: ignore
 
 import ape
-from ape import Project
-from ape import config as ape_config
 
-TEMP_FOLDER = Path(mkdtemp())
-# NOTE: Don't change this setting
-ape_config.DATA_FOLDER = TEMP_FOLDER / ".ape"
-# NOTE: Ensure that a temp path is used by default (avoids `.build` appearing in src)
-ape_config.PROJECT_FOLDER = TEMP_FOLDER
-ape.project = Project(TEMP_FOLDER)
+# NOTE: Ensure that we don't use local paths for these
+ape.config.DATA_FOLDER = Path(mkdtemp())
+ape.config.PROJECT_FOLDER = Path(mkdtemp())
 
 
 @pytest.fixture(scope="session")
 def config():
-    yield ape_config
+    yield ape.config
 
 
 @pytest.fixture(scope="session")
-def plugin_manager():
-    from ape import plugin_manager
+def data_folder(config):
+    yield config.DATA_FOLDER
 
-    yield plugin_manager
+
+@pytest.fixture(scope="session")
+def plugin_manager():
+    yield ape.plugin_manager
 
 
 @pytest.fixture(scope="session")
 def accounts():
-    from ape import accounts
-
-    yield accounts
+    yield ape.accounts
 
 
 @pytest.fixture(scope="session")
 def compilers():
-    from ape import compilers
-
-    yield compilers
+    yield ape.compilers
 
 
 @pytest.fixture(scope="session")
 def networks():
-    from ape import networks
-
-    yield networks
+    yield ape.networks
 
 
 @pytest.fixture(scope="session")
-def project():
-    yield ape.project
+def project_folder(config):
+    yield config.PROJECT_FOLDER
 
 
 @pytest.fixture(scope="session")
-def data_folder(config):
-    yield config.DATA_FOLDER
+def project(config):
+    yield ape.Project(config.PROJECT_FOLDER)

src/ape_run/py.typed

@@ -1,3 +1,4 @@
+import os
 from distutils.dir_util import copy_tree
 from pathlib import Path
 
@@ -30,11 +31,13 @@ def project(project_folder):
     ape.project = previous_project
 
 
-@pytest.fixture(scope="session")
-def runner(config):
+@pytest.fixture
+def runner(project_folder):
+    previous_cwd = str(Path.cwd())
+    os.chdir(str(project_folder))
     runner = CliRunner()
-    with runner.isolated_filesystem(temp_dir=config.PROJECT_FOLDER):
-        yield runner
+    yield runner
+    os.chdir(previous_cwd)
 
 
 @pytest.fixture(scope="session")

tests/conftest.py

@@ -0,0 +1,6 @@
+from ape import networks
+
+
+def main():
+    assert networks.active_provider.name == "test"
+    print("Script ran!")