feat(fw): eest utils - add docs, fix bugs, only rm venv on reset.

docs/getting_started/quick_start.md

@@ -1,37 +1,38 @@
 # Quick Start
 
 !!! info "Testing features under active development"
-    The EVM features under test must be implemented in the `evm` tool and `solc` executables that are used by the execution-spec-tests framework. The following guide installs stable versions of these tools.
+    The EVM features under test must be implemented in the `evm` tool used by the execution-spec-tests framework. The following guide installs stable versions of these tools.
 
     To test features under active development, start with this base configuration and then follow the steps in [executing tests for features under development](./executing_tests_dev_fork.md). 
 
 The following requires a Python 3.10, 3.11 or 3.12 installation.
 
-1. Ensure `go-ethereum`'s `evm` tool are in your path. Either build the required versions, or alternatively:
+1. Ensure `go-ethereum`'s `evm` tool is in your path. Either build the required versions, or alternatively:
 
     === "Ubuntu"
 
-          [geth Ubuntu installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#ubuntu-via-ppas).
+         - Install the geth evm using the [Ubuntu installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#ubuntu-via-ppas).
 
     === "macOS"
 
-          [geth macOS installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#macos-via-homebrew).
+         - Install the geth evm using the [macOS installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#macos-via-homebrew).
 
     === "Windows"
 
-          - [geth](https://geth.ethereum.org/downloads) (binary or installer).
-          - [geth Windows installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#windows).
+          - Execution-spec-tests doesn't fully support the Windows OS natively, however Windows Subsystem for Linux (WSL) can be used as a stable alternative.
+          - For those unfamiliar with WSL it's recommended to follow this [tutorial](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode) to develop from the WSL environment alongside VS code.
+          - Assuming Ubuntu is the Linux distribution within WSL please follow the geth [Ubuntu installation doc](https://geth.ethereum.org/docs/getting-started/installing-geth#ubuntu-via-ppas).
 
-2. Clone the [execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repo and install its dependencies (it's recommended to use a virtual environment for the installation):
+2. Clone the [execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repo and install its dependencies and additional entry points. Note the virtual environment is a requirement, as the `solc` dependency is self-contained.
 
     ```console
     git clone https://github.com/ethereum/execution-spec-tests
     cd execution-spec-tests
     python src/entry_points/eest_utils.py init
-    source venv/bin/activate # activate.csh or activate.fish the respective shell
+    source venv/bin/activate
     ```
 
-3. Verify installation:
+3. Verify the installation of the `fill` command:
     1. Explore test cases:
 
         ```console
@@ -62,9 +63,17 @@ The following requires a Python 3.10, 3.11 or 3.12 installation.
             head fixtures/blockchain_tests/berlin/eip2930_access_list/acl/access_list.json
             ```
 
+## Useful Commands
+
+After installing the execution-spec-tests (EEST) framework, our repo specific command line tool can be used for convenient utilities:
+
+- `eest reset`: Performs a clean up of the repo, by removing all generated files and folders, then re-initializes and installs all required packages & dependencies (removes the virtual environment).
+- `eest clean`: Cleans up and removes all generated folders and files (doesn't remove the virtual environment).
+- `eest init`: Initializes the repo by installing all the relevant packages & dependencies (equivalent to running `python src/entry_points/eest_utils.py init` as before).
+
 ## Next Steps
 
-1. Learn [useful command-line flags](./executing_tests_command_line.md).
+1. Learn [useful fill command-line flags](./executing_tests_command_line.md).
 2. [Execute tests for features under development](./executing_tests_dev_fork.md) via the `--fork` flag.
-3. _Optional:_ [Configure VS Code](./setup_vs_code.md) to auto-format Python code and [execute tests within VS Code](./executing_tests_vs_code.md#executing-and-debugging-test-cases).
+3. _Recommended:_ [Configure VS Code](./setup_vs_code.md) to auto-format Python code and [execute tests within VS Code](./executing_tests_vs_code.md#executing-and-debugging-test-cases).
 4. Implement a new test case, see [Writing Tests](../writing_tests/index.md).

setup.cfg

@@ -47,13 +47,13 @@ evm_transition_tool =
 console_scripts =
     fill = entry_points.fill:main
     tf = entry_points.tf:main
+    eest = entry_points.eest_utils:eest
     order_fixtures = entry_points.order_fixtures:main
     pyspelling_soft_fail = entry_points.pyspelling_soft_fail:main
     markdownlintcli2_soft_fail = entry_points.markdownlintcli2_soft_fail:main
     create_whitelist_for_flake8_spelling = entry_points.create_whitelist_for_flake8_spelling:main
     evm_bytes_to_python = entry_points.evm_bytes_to_python:main
     hasher = entry_points.hasher:main
-    eest = entry_points.eest_utils:eest
 
 [options.extras_require]
 test =

src/entry_points/eest_utils.py

@@ -11,7 +11,7 @@
 import click
 import colorlog
 
-# Required for forks <= Constantinople
+# Required for forks < Constantinople
 SOLC_PRE_CONSTANTINOPLE = "0.8.22"
 
 
@@ -49,14 +49,17 @@ def init():
     """
     Initializes and installs all required packages add dependencies for the repository:
     ```
-    python3 -m venv ./venv/
+    python -m venv ./venv/
     pip install --upgrade pip
-    pip install -e '.[docs,lint,test]'
+    pip install -e '.[docs,lint,test]' --force-reinstall
     solc-select install 0.8.22
     solc-select use latest --always-install
     ```
     """
-    venv_create = [sys.executable, "-m", "venv", os.path.join(".", "venv")]
+    if not (3, 10, 0) <= sys.version_info[:3] <= (3, 12, 2):
+        raise RuntimeError("EEST requires Python 3.10.0 up to 3.12.2.")
+    python_path = shutil.which("python")
+    venv_create = [python_path, "-m", "venv", os.path.join(".", "venv")]
 
     logger.info(f"Creating a virtual environment: `{' '.join(venv_create)}`")
     subprocess.run(venv_create, check=True)
@@ -67,14 +70,14 @@ def init():
     logger.info(f"Upgrading pip to the latest version: `{' '.join(pip_upgrade)}`")
     subprocess.run(pip_upgrade, check=True)
 
-    pip_install = [pip_path, "install", "-e", ".[docs,lint,test]"]
+    pip_install = [pip_path, "install", "-e", ".[docs,lint,test]", "--force-reinstall"]
     logger.info(f"Installing required packages: `{' '.join(pip_install)}`")
     subprocess.run(pip_install, check=True)
 
     solc_select_path = os.path.join(".", "venv", "bin", "solc-select")
     os.environ["VIRTUAL_ENV"] = os.environ.get("VIRTUAL_ENV")
 
-    # Required for forks <= Constantinople, see important note within release note:
+    # Required for forks < Constantinople, see important note within release note:
     # https://github.com/ethereum/solidity/releases/tag/v0.8.22
     solc_install_0_8_22 = [solc_select_path, "install", SOLC_PRE_CONSTANTINOPLE]
     logger.info(f"Installing solc 0.8.22 within venv:  `{' '.join(solc_install_0_8_22)}`")
@@ -88,27 +91,30 @@ def init():
 
 
 @eest.command()
-def clean():
+def clean(remove_venv: bool = False):
     """
     Cleans the repository of all generated files and directories:
     ```
-    rm -rf .tox .cache .pytest_cache .mypy_cache venv fixtures build
+    rm -rf .tox .cache .pytest_cache .mypy_cache fixtures build venv
     ```
+    By default, the virtual environment is not removed.
     """
-    items_to_remove = [".tox", ".pytest_cache", ".mypy_cache", "venv", "fixtures"]
+    items_to_remove = [".tox", ".pytest_cache", ".mypy_cache", "fixtures", "build", "site", "venv"]
     for item in items_to_remove:
         if os.path.exists(item):
+            if item == "venv" and not remove_venv:
+                continue
             shutil.rmtree(item, ignore_errors=True)
             logger.warning(f"Deleted `{item}`")
 
 
 @eest.command()
 def reset():
     """
-    Performs a clean and init on the repository.
+    Performs a clean and init on the repository (deletes the virtual env).
     """
     ctx = click.get_current_context()
-    ctx.invoke(clean)
+    ctx.invoke(clean, remove_venv=True)
     ctx.invoke(init)
 
 

whitelist.txt

@@ -47,6 +47,7 @@ changelog
 chfast
 classdict
 cli2
+cmd
 codeAddr
 codecopy
 codesize