chore: add cross-platform scripts for spelling and linting

This ensures that tox does not use any platform-specific commands.

.wordlist.txt

@@ -12,6 +12,7 @@ bytes8
 bytes20
 bytes32
 calc
+cli2
 coinbase
 crypto
 dao
@@ -205,6 +206,7 @@ prepend
 programmatically
 px
 py
+pyspelling
 pytest
 Pytest
 pytestArgs
@@ -252,6 +254,7 @@ visualstudio
 vscode
 vv
 wikipedia
+wordlist
 www
 xF
 xFA

setup.cfg

@@ -46,6 +46,9 @@ evm_block_builder =
 console_scripts =
     fill = entry_points.fill:main
     tf = entry_points.tf: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
 
 [options.extras_require]
 test =

src/entry_points/create_whitelist_for_flake8_spelling.py

@@ -0,0 +1,32 @@
+"""
+Create the whitelist.txt file used by the flake8-spellcheck plugin.
+
+We maintain our project dictionaries in separate files for convenience. This
+script simply concatenates them into a single file for use by the plugin.
+
+It's equivalent to the bash command:
+bash -c 'cat .wordlist.txt .wordlist_python_pytest.txt .wordlist_opcodes.txt > whitelist.txt'
+
+But is written in Python for use in tox to make it cross-platform.
+"""
+
+from pathlib import Path
+
+
+def main():
+    """
+    Create the whitelist.txt file used by the flake8-spellcheck plugin.
+    """
+    paths = [
+        Path(".wordlist.txt"),
+        Path(".wordlist_python_pytest.txt"),
+        Path(".wordlist_opcodes.txt"),
+    ]
+    with open("whitelist.txt", "w") as whitelist:
+        for path in paths:
+            with open(path) as wordlist:
+                whitelist.write(wordlist.read())
+
+
+if __name__ == "__main__":
+    main()

src/entry_points/markdownlintcli2_soft_fail.py

@@ -0,0 +1,34 @@
+"""
+Lint the markdown in ./README.md and ./docs/ using the external command
+markdownlint-cli2.
+
+This script's purpose is:
+
+1. Run the external command markdownlint-cli2 as a subprocess if it's
+    installed, if not fail silently. The aim is to avoid disruption to
+    external contributors who may not even be working on the docs.
+2. Keep tox cross-platform by not insisting on any external commands
+    (including bash).
+"""
+
+import shutil
+import subprocess
+import sys
+
+
+def main():
+    """
+    Run markdownlint-cli2 as a subprocess if it's installed, if not fail silently.
+    """
+    markdownlint = shutil.which("markdownlint-cli2")
+    if not markdownlint:
+        # Note: There's an additional step in test.yaml to run markdownlint-cli2 in github actions
+        print("*********  Install 'markdownlint-cli2' to enable markdown linting *********")
+        sys.exit(0)
+
+    command = ["node", str(markdownlint), "./docs/**/*.md", "./README.md"]
+    sys.exit(subprocess.run(command).returncode)
+
+
+if __name__ == "__main__":
+    main()

src/entry_points/pyspelling_soft_fail.py

@@ -0,0 +1,38 @@
+"""
+Spellcheck the markdown in ./README.md and ./docs/ using the pyspelling
+package.
+
+Pyspelling requires aspell as an external dependency. This script's purpose
+is to:
+
+1. Run pyspelling if aspell is installed, if not fail silently. The aim is to
+    avoid disruption to external contributors who may not even be working on
+    the docs.
+2. Keep tox cross-platform by not insisting on any external commands (including
+    bash).
+"""
+
+import os
+import shutil
+import sys
+
+from pyspelling import __main__ as pyspelling_main  # type: ignore
+
+
+def main():
+    """
+    Run pyspelling if aspell is installed, if not fail silently.
+    """
+    if not shutil.which("aspell"):
+        print("aspell not installed, skipping spellcheck.")
+        if os.environ.get("GITHUB_ACTIONS"):
+            sys.exit(1)
+        else:
+            print("*********  Install 'aspell' and 'aspell-en' to enable spellcheck *********")
+            sys.exit(0)
+
+    sys.exit(pyspelling_main.main())
+
+
+if __name__ == "__main__":
+    main()

tox.ini

@@ -4,11 +4,6 @@ env_list =
     tests
     docs
 
-[testenv]
-
-# flake8 insists the dictionary is called "whitelist.txt", we will create this below
-wordlists = .wordlist.txt .wordlist_python_pytest.txt .wordlist_opcodes.txt
-
 [testenv:framework]
 description = Run checks on helper libraries and test framework
 
@@ -18,13 +13,11 @@ extras =
 
 src = src setup.py
 
-allowlist_externals = bash
-
 commands =
     fname8 {[testenv:framework]src}
     isort {[testenv:framework]src} --check --diff
     black {[testenv:framework]src} --check --diff
-    bash -c 'cat {[testenv]wordlists} > whitelist.txt'
+    python -m src.entry_points.create_whitelist_for_flake8_spelling
     flake8 {[testenv:framework]src}
     mypy {[testenv:framework]src}
     pytest -c ./pytest-framework.ini -n auto
@@ -43,13 +36,11 @@ extras =
     test
     lint
 
-allowlist_externals = bash
-
 commands =
     fname8 tests
     isort tests --check --diff
     black tests --check --diff
-    bash -c 'cat {[testenv]wordlists} > whitelist.txt'
+    python -m src.entry_points.create_whitelist_for_flake8_spelling
     flake8 tests
     mypy tests
     pytest -n auto
@@ -66,15 +57,13 @@ setenv =
 
 src = setup.py docs/gen_test_case_reference.py
 
-allowlist_externals = bash
-
 commands =
     fname8 {[testenv:docs]src}
     isort {[testenv:docs]src} --check --diff
     black {[testenv:docs]src} --check --diff
-    bash -c 'cat {[testenv]wordlists} > whitelist.txt'
+    python -m src.entry_points.create_whitelist_for_flake8_spelling    
     flake8 {[testenv:docs]src}
     mypy {[testenv:docs]src}
     mkdocs build --strict
-    bash -c 'command -v aspell >/dev/null && (pyspelling || true) || { echo "INFO: *** install aspell and apsell-us to spell check markdown *** " 1>&2; exit 0; }'
-    bash -c 'command -v markdownlint-cli2 >/dev/null && (markdownlint-cli2 README.md "docs/**/*.md" || true) || { echo "INFO: *** install markdownlint-cli2 to lint markdown ***" 1>&2; exit 0; }'
+    python -m src.entry_points.pyspelling_soft_fail
+    python -m src.entry_points.markdownlintcli2_soft_fail